@manny-est/node-red-flowpilot 0.5.2 → 0.6.0

package/lib/core/modes.js

@@ -155,7 +155,9 @@
                 context: context,
                 history: historyPayload.messages,
                 historyTruncated: historyPayload.truncated,
-                conversationId: conversationId
+                conversationId: conversationId,
+                strategy: "classic",
+                entry: "chat"
             };
 
             function handleSendResult(data) {
@@ -271,6 +273,65 @@
         dispatch();
     }
 
+    function summarizeConversationHistory() {
+        if (isPopoutContext) {
+            addMessage("assistant", "`/summarize` only runs in the main FlowPilot panel.");
+            return;
+        }
+
+        var totalMessages = conversationHistory.length;
+        if (totalMessages <= 4) {
+            addMessage("assistant", "Nothing much to summarize yet — only " + totalMessages +
+                " message(s) so far.");
+            return;
+        }
+
+        var recentTail = conversationHistory.slice(-4);
+        var olderSlice = conversationHistory.slice(0, -4);
+        var beforeTokens = estimateTokens(olderSlice);
+        var prompt = "Summarize the earlier conversation history provided here. " +
+            "Keep it concise and factual. Preserve decisions, constraints, important context, " +
+            "and unresolved questions. Return plain text only.";
+        var payload = {
+            prompt: prompt,
+            context: null,
+            history: olderSlice.slice(),
+            historyTruncated: false,
+            conversationId: conversationId,
+            strategy: "classic",
+            entry: "chat"
+        };
+
+        setBusy(true);
+        showPending(false);
+
+        ajaxJson("POST", "flowpilot/chat", payload, function (data) {
+            hidePending();
+            var summaryText = String(data && data.message ? data.message : "").trim();
+            if (!summaryText) {
+                addMessage("error", "Summarize failed: no summary text returned.");
+                setBusy(false);
+                updateSelectionStatus();
+                return;
+            }
+
+            var summaryMessage = {
+                role: "assistant",
+                content: "[Summary of earlier conversation]\n" + summaryText
+            };
+            conversationHistory = [summaryMessage].concat(recentTail);
+            addMessage("assistant", "Compacted " + olderSlice.length + " earlier message(s) into a summary (~" +
+                beforeTokens.toLocaleString() + " → ~" + estimateTokens(summaryMessage).toLocaleString() + " tokens).");
+            setBusy(false);
+            updateSelectionStatus();
+        }, function (msg) {
+            hidePending();
+            addMessage("error", "Summarize failed: " + msg);
+            setBusy(false);
+            updateSelectionStatus();
+        });
+    }
+
     // ---------------------------------------------------------------------
     // Bounded read-tool loop, shared by chat and
     // generate/document/modify ("explore-then-propose"). Sends the
@@ -299,14 +360,150 @@
     // than erroring out.
     // ---------------------------------------------------------------------
     var AGENT_LOOP_MAX_STEPS = 8;
-    var AGENT_LOOP_TOKEN_CEILING = 50000;
+    // W7 §16 point 5: ask_user round-trips get their own small budget,
+    // separate from AGENT_LOOP_MAX_STEPS, so a couple of clarifying
+    // questions don't eat the real step budget.
+    var AGENT_ASK_USER_MAX_ROUNDTRIPS = 3;
 
     var fpAgentStopRequested = false;
-
-    function runAgentLoop(firstEndpoint, payload, stepExtra, onDone, onError) {
+    // CLAUDE-022: the in-flight jqXHR for this run's current ajaxJson call
+    // (first request / postNextStep / fallbackToPlain), so the Stop button
+    // can actually abort it instead of only setting the flag above. Cleared
+    // back to null the moment that call's own success/error callback runs,
+    // so a stale reference never lingers into the next step.
+    var fpCurrentAgentRequest = null;
+
+    // P10-D1 (ADR-001 R5): monotonic suffix so two runs minted in the same
+    // millisecond (Date.now() collision) still get distinct runIds.
+    var runIdCounter = 0;
+
+    function runAgentLoop(firstEndpoint, payload, stepExtra, realOnDone, realOnError) {
+        if (!payload || !payload.strategy || !payload.entry) {
+            throw new Error("runAgentLoop requires strategy and entry in the initial payload.");
+        }
+        var AGENT_LOOP_TOKEN_CEILING = (Number(currentSettings.agentLoopTokenCeiling) > 0)
+            ? Number(currentSettings.agentLoopTokenCeiling) : 50000;
+        var runStrategy = payload.strategy;
+        var runEntry = payload.entry;
+        // P10-D1 follow-up (sr-dev review): captured once, like
+        // runStrategy/runEntry/runId — using the free-variable
+        // conversationId instead would let a stale run's dedup lookup land
+        // in the wrong conversation's bucket if the user switches
+        // conversations mid-run.
+        var runConversationId = payload.conversationId;
+        // P10-D1: minted once per run, included in every step payload so
+        // the server can echo it into logs beside strategy/entry. Also the
+        // namespace for this run's WRITE tool opIds (opId = runId + ":" +
+        // call.id, ADR-001 R5).
+        var runId = "run-" + Date.now().toString(36) + "-" + (++runIdCounter);
+        // CLAUDE-013: accumulates placeholder->real-id mappings across every
+        // WRITE-tool call resolved THIS run, so a later call in the same run
+        // (e.g. group_nodes) can resolve a placeholder id (e.g. "fp-new-2")
+        // that an earlier call (e.g. apply_step) minted via applyInsertions —
+        // each WRITE executor's call-local idMap only covers ids it created
+        // itself, not ids from a prior call in the same agent loop.
+        var runIdMap = {};
+        // CLAUDE-027: accumulates the individual RED.history event(s) each
+        // WRITE-tool call this run would otherwise have pushed on its own
+        // (apply_step/remove_step/rename_node/group_nodes — see
+        // applyInsertions/applyModifications in apply-review.js and
+        // executeGroupNodesTool in main.js, all of which push into this
+        // array instead of RED.history directly whenever it's passed
+        // through). Flushed as ONE RED.history entry — via RED.history's own
+        // t:"multi" wrapper, confirmed against @node-red/editor-client's
+        // red.js (e.g. its deleteSelection(), which collapses a mixed
+        // delete+move into one push the exact same way) when there's more
+        // than one, or pushed unwrapped when there's exactly one, matching
+        // that same core convention — the moment this run actually ends, by
+        // flushRunHistory()/onDone/onError below. A run that never calls a
+        // WRITE tool (e.g. a pure ask_user round-trip, or read-only chat)
+        // leaves this empty, so flush is a no-op and no spurious entry is
+        // pushed.
+        var runHistoryEvents = [];
         var step = 0;
         var totalTokens = 0;
+        var askUserRounds = 0;
         fpAgentStopRequested = false;
+        fpCurrentAgentRequest = null;
+        // W7: one entry per WRITE tool call resolved THIS runAgentLoop
+        // invocation, in order (proceed-and-pass / proceed-and-fail /
+        // user-declined all count, read-tool calls don't) — gives
+        // handleModifyResult a real 1:1 todo-item correlation instead of
+        // the CLAUDE-005 all-together fallback. Attached to the final
+        // data as _agentWriteResults right before onDone(data); untouched
+        // (empty) whenever no WRITE tool call was made this turn, which
+        // keeps the existing all-together path completely unchanged.
+        var agentWriteResults = [];
+        // CLAUDE-014: plain-language note for the decision that triggered the
+        // NEXT agent-step round trip (consent-gate Proceed/Skip, ask_user
+        // answer) — set right before the decision resumes the loop, read and
+        // cleared by postNextStep so CODEX-012's debug.log can show what the
+        // user actually decided instead of only raw tool-result JSON. Only
+        // populated when settings.debugLogging is on.
+        var pendingDebugNote = null;
+
+        // CLAUDE-027: pushes this run's accumulated WRITE-tool history
+        // event(s) (runHistoryEvents above) to RED.history as ONE entry —
+        // coalesced via t:"multi" when more than one WRITE-tool call
+        // mutated this run, unwrapped when exactly one did, a no-op when
+        // none did. MUST run at every single point this run can end, not
+        // just the "clean" success path — a run that errors out (step
+        // budget/token ceiling exceeded, user Stop, a failed request) after
+        // ALREADY applying one or more WRITE tool calls still needs its
+        // partial progress to land in undo history, or Ctrl+Z would be
+        // unable to remove mutations that are visibly sitting on the
+        // canvas. Rather than call this at each of those call sites
+        // individually (easy to miss one), onDone/onError below shadow the
+        // real callback params so EVERY exit from this closure flushes
+        // first automatically.
+        function flushRunHistory() {
+            if (!runHistoryEvents.length) { return; }
+            if (runHistoryEvents.length === 1) {
+                RED.history.push(runHistoryEvents[0]);
+            } else {
+                RED.history.push({ t: "multi", events: runHistoryEvents.slice() });
+            }
+            runHistoryEvents = [];
+        }
+        function onDone(data) { flushRunHistory(); realOnDone(data); }
+        function onError(err, xhr) { flushRunHistory(); realOnError(err, xhr); }
+
+        // P10-D2 (ADR-001 R5): run events on the record store. runRec is
+        // created LAZILY, the first time something WRITE-tool/ask_user-
+        // worthy happens — never for a plain chat/read-only turn, so this
+        // is a no-op for every mode/strategy that never offers WRITE tools
+        // (chat, document, build, classic Modify — agentToolsFor only
+        // offers WRITE_TOOLS for strategy:"agent" + mode:"modify"). Once
+        // created, it's a "todo" record (the same W4 machinery that
+        // already survives /refresh via rerenderRecord) so a mid-run
+        // refresh finds it; handleModifyResult upgrades it in place with
+        // real Plan: items via data._agentRunRecord instead of creating a
+        // second record, once the final turn's explanation arrives.
+        var runEvents = [];
+        var runRec = null;
+
+        function syncRunMarker(reason) {
+            if (!runRec) { return; }
+            writeRunMarker({
+                runId: runId,
+                action: runEntry,
+                appliedCount: runEvents.filter(function (e) { return e.t === "applied"; }).length,
+                conversationId: runConversationId
+            }, reason || "syncRunMarker");
+        }
+
+        function recordRunEvent(t, extra) {
+            if (!runRec) {
+                runRec = addRecord("todo", { action: runEntry, items: [], events: runEvents });
+            }
+            runEvents.push(Object.assign({ t: t, at: Date.now() }, extra || {}));
+            runRec.events = runEvents;
+            if (t === "done") {
+                clearRunMarker("run done: " + runId);
+            } else {
+                syncRunMarker("run event: " + t);
+            }
+        }
 
         function addUsage(usage) {
             if (usage && typeof usage.total_tokens === "number") {
@@ -316,14 +513,184 @@
 
         function fallbackToPlain() {
             setAgentNarration("Continuing without tools…");
-            ajaxJson("POST", firstEndpoint, payload, onDone, onError);
+            fpCurrentAgentRequest = ajaxJson("POST", firstEndpoint, payload, function (data) {
+                fpCurrentAgentRequest = null;
+                if (runRec) { recordRunEvent("done", {}); data._agentRunRecord = runRec; }
+                onDone(data);
+            }, function (err, xhr) {
+                fpCurrentAgentRequest = null;
+                if (fpAgentStopRequested) {
+                    if (runRec) { recordRunEvent("interrupted", { detail: "stopped by user" }); rerenderTodoRecord(runRec); }
+                    onError("Stopped after " + Math.max(0, step - 1) + " tool call step(s) at your request.");
+                    return;
+                }
+                if (runRec) { recordRunEvent("interrupted", { detail: "fallback request failed" }); rerenderTodoRecord(runRec); }
+                // CLAUDE-023: forward xhr so a genuine parse error's raw
+                // response survives to handleExecuteError (via onModifyError)
+                // instead of being dropped here — ajaxJson's error callback
+                // is (msg, xhr), and onError expects the same shape.
+                onError(err, xhr);
+            });
+        }
+
+        function postNextStep(nextMessages) {
+            setAgentNarration("Thinking… (step " + step + "/" + AGENT_LOOP_MAX_STEPS + ")");
+            var stepPayload = Object.assign({
+                messages: nextMessages,
+                conversationId: payload.conversationId
+            }, stepExtra, {
+                strategy: runStrategy,
+                entry: runEntry,
+                runId: runId,
+                events: runEvents.slice()
+            });
+            if (pendingDebugNote) {
+                stepPayload.debugNote = pendingDebugNote;
+                pendingDebugNote = null;
+            }
+            fpCurrentAgentRequest = ajaxJson("POST", "flowpilot/agent-step", stepPayload,
+                function (stepData) { fpCurrentAgentRequest = null; handleStep(stepData, nextMessages); },
+                function (err, xhr) {
+                    fpCurrentAgentRequest = null;
+                    if (fpAgentStopRequested) {
+                        if (runRec) { recordRunEvent("interrupted", { detail: "stopped by user" }); rerenderTodoRecord(runRec); }
+                        onError("Stopped after " + Math.max(0, step - 1) + " tool call step(s) at your request.");
+                        return;
+                    }
+                    if (runRec) { recordRunEvent("interrupted", { detail: "agent-step request failed" }); rerenderTodoRecord(runRec); }
+                    // CLAUDE-023: forward xhr — see fallbackToPlain's error
+                    // callback above for why this must not be dropped.
+                    onError(err, xhr);
+                });
+        }
+
+        // Processes calls[idx..] one at a time. A WRITE-gated call (per
+        // toolTiers, classified against SAFE_NODE_TYPES) or an ask_user
+        // call PAUSES here — rendering a chip/question and waiting for a
+        // user action — instead of executing synchronously like the
+        // existing 6 READ tools still do. Once the whole batch is
+        // resolved, posts the next step exactly as before.
+        function processToolCallsFrom(calls, idx, nextMessages, toolTiers) {
+            if (idx >= calls.length) { postNextStep(nextMessages); return; }
+
+            var call = calls[idx];
+            var name = call.function.name;
+            var args = parseToolCallArgs(call);
+            if (name === "redirect_mode") {
+                var redirectResult = executeAgentToolCall(call, runIdMap, runHistoryEvents);
+                nextMessages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(redirectResult) });
+                if (runRec) {
+                    recordRunEvent("redirect", { detail: (redirectResult && redirectResult.suggestedAction && redirectResult.suggestedAction.mode) || args.mode || "unknown" });
+                    recordRunEvent("done", {});
+                }
+                onDone({
+                    explanation: (redirectResult && redirectResult.explanation) || "",
+                    prose: true,
+                    flow: null,
+                    suggestedAction: redirectResult && redirectResult.suggestedAction ? redirectResult.suggestedAction : null
+                });
+                return;
+            }
+            var isWriteTool = name === "apply_step" || name === "remove_step" || name === "rename_node" || name === "group_nodes";
+            // P10-D1: only WRITE tool calls get an opId — idempotency is
+            // about preventing double MUTATION, not about read tools.
+            var opId = isWriteTool ? (runId + ":" + call.id) : null;
+
+            // P10-D1: a repeat opId (duplicate delivery, a retry, or the
+            // model repeating a call) returns the SAME result without
+            // re-invoking the executor — the graph is mutated at most once
+            // per opId, checked against the per-conversation applied-ops
+            // map before mutating (main.js).
+            function runExecutorIdempotent() {
+                if (opId) {
+                    var recorded = getAppliedOp(runConversationId, opId);
+                    if (recorded) { return recorded; }
+                }
+                var result = executeAgentToolCall(call, runIdMap, runHistoryEvents);
+                // CLAUDE-013: merge this call's own new placeholder->real-id
+                // mappings (e.g. apply_step's newNodes) into the run-scoped
+                // map so a LATER call this run can resolve the same ids.
+                if (result && result.idMap) { Object.assign(runIdMap, result.idMap); }
+                if (opId) { recordAppliedOp(runConversationId, opId, result); }
+                return result;
+            }
+
+            function continueWithResult(resultObj) {
+                var _reason = null;
+                if (resultObj && !resultObj.allPass) {
+                    _reason = resultObj.error || resultObj.reason || null;
+                }
+                if (isWriteTool) { agentWriteResults.push({ allPass: !!(resultObj && resultObj.allPass), reason: _reason }); }
+                nextMessages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(resultObj) });
+                processToolCallsFrom(calls, idx + 1, nextMessages, toolTiers);
+            }
+
+            if (name === "ask_user") {
+                if (askUserRounds >= AGENT_ASK_USER_MAX_ROUNDTRIPS) {
+                    continueWithResult({ error: "ask_user budget (" + AGENT_ASK_USER_MAX_ROUNDTRIPS +
+                        ") exhausted for this turn — proceed with your best judgment or give a final answer." });
+                    return;
+                }
+                askUserRounds++;
+                setAgentNarration(describeAgentToolCall(name, args));
+                recordRunEvent("asked", { detail: args.question });
+                renderAskUserQuestion({ question: args.question, options: args.options,
+                    onAnswer: function (answerText) {
+                        recordRunEvent("answered", { detail: answerText });
+                        if (currentSettings.debugLogging) { pendingDebugNote = "user answered: " + answerText; }
+                        continueWithResult({ answer: answerText });
+                    } });
+                return; // PAUSES here until the question is answered
+            }
+
+            if (isWriteTool) { recordRunEvent("step", { opId: opId, detail: name }); }
+
+            var tier = toolTiers && toolTiers[call.id];
+            if (writeToolCallNeedsConsent(tier, name, args)) {
+                if (isWriteTool) { recordRunEvent("consent", { opId: opId, detail: name }); }
+                renderAgentToolConsentGate({
+                    name: name, args: args,
+                    onResume: function (granted) {
+                        if (currentSettings.debugLogging) {
+                            pendingDebugNote = granted ? "user clicked Proceed" : "user clicked Skip this step";
+                        }
+                        if (!granted) {
+                            continueWithResult({ skipped: true, reason: "user declined — this call was not applied" });
+                            return;
+                        }
+                        setAgentNarration(describeAgentToolCall(name, args) + " (step " + step + "/" + AGENT_LOOP_MAX_STEPS + ")");
+                        var result = runExecutorIdempotent();
+                        if (isWriteTool) {
+                            recordRunEvent("applied", { opId: opId });
+                            recordRunEvent("verified", { opId: opId, detail: !!(result && result.allPass) });
+                        }
+                        continueWithResult(result);
+                    }
+                });
+                return; // PAUSES here until Proceed/Skip is clicked
+            }
+
+            setAgentNarration(describeAgentToolCall(name, args) + " (step " + step + "/" + AGENT_LOOP_MAX_STEPS + ")");
+            var autoResult = runExecutorIdempotent();
+            if (isWriteTool) {
+                recordRunEvent("applied", { opId: opId });
+                recordRunEvent("verified", { opId: opId, detail: !!(autoResult && autoResult.allPass) });
+            }
+            continueWithResult(autoResult);
         }
 
         function handleStep(data, messages) {
             addUsage(data.usage);
 
+            if (data.fallbackToClassic) {
+                fallbackToPlain();
+                return;
+            }
+
             if (!data.toolCalls || !data.toolCalls.length) {
                 if (step > 0) { addAgentStatsNote(step, totalTokens); }
+                if (agentWriteResults.length) { data._agentWriteResults = agentWriteResults.slice(); }
+                if (runRec) { recordRunEvent("done", {}); data._agentRunRecord = runRec; }
                 onDone(data);
                 return;
             }
@@ -336,50 +703,76 @@
                 return;
             }
 
-            step++;
-            if (step > AGENT_LOOP_MAX_STEPS) {
-                onError("FlowPilot stopped after " + AGENT_LOOP_MAX_STEPS +
-                    " tool call(s) without a final answer. Try breaking your " +
-                    "request into smaller steps, or be more specific about " +
-                    "which node(s) or flow you mean.");
-                return;
+            // An ask_user-ONLY batch doesn't consume the real step budget —
+            // see AGENT_ASK_USER_MAX_ROUNDTRIPS above. A batch mixing
+            // ask_user with any other tool call counts normally, since real
+            // work happened in it too.
+            var isAskUserOnlyBatch = data.toolCalls.every(function (c) { return c.function.name === "ask_user"; });
+            if (!isAskUserOnlyBatch) {
+                step++;
+                if (step > AGENT_LOOP_MAX_STEPS) {
+                    if (runRec) { recordRunEvent("interrupted", { detail: "step budget exceeded" }); rerenderTodoRecord(runRec); }
+                    onError("FlowPilot stopped after " + AGENT_LOOP_MAX_STEPS +
+                        " tool call(s) without a final answer. Try breaking your " +
+                        "request into smaller steps, or be more specific about " +
+                        "which node(s) or flow you mean.");
+                    return;
+                }
             }
             if (totalTokens > AGENT_LOOP_TOKEN_CEILING) {
+                if (runRec) { recordRunEvent("interrupted", { detail: "token ceiling exceeded" }); rerenderTodoRecord(runRec); }
                 onError("FlowPilot stopped after using " + totalTokens +
-                    " tokens on this turn without a final answer. Try " +
-                    "selecting fewer nodes, or asking a more specific " +
-                    "question so fewer tool calls are needed.");
+                    " tokens on this turn (limit: " + AGENT_LOOP_TOKEN_CEILING +
+                    ") without a final answer. Try selecting fewer nodes, asking a " +
+                    "more specific question, or raising \"Max total tokens per " +
+                    "agent turn\" in Settings → Behavior.");
                 return;
             }
             if (fpAgentStopRequested) {
+                if (runRec) { recordRunEvent("interrupted", { detail: "stopped by user" }); rerenderTodoRecord(runRec); }
                 onError("Stopped after " + (step - 1) + " tool call step(s) at your request.");
                 return;
             }
 
             var nextMessages = (messages || data.messages || []).slice();
             nextMessages.push({ role: "assistant", content: data.content || null, tool_calls: data.toolCalls });
-            data.toolCalls.forEach(function (call) {
-                setAgentNarration(describeAgentToolCall(call.function.name, parseToolCallArgs(call)) +
-                    " (step " + step + "/" + AGENT_LOOP_MAX_STEPS + ")");
-                nextMessages.push({
-                    role: "tool",
-                    tool_call_id: call.id,
-                    content: JSON.stringify(executeAgentToolCall(call))
-                });
-            });
-            setAgentNarration("Thinking… (step " + step + "/" + AGENT_LOOP_MAX_STEPS + ")");
-            var stepPayload = Object.assign({
-                messages: nextMessages,
-                conversationId: payload.conversationId
-            }, stepExtra);
-            ajaxJson("POST", "flowpilot/agent-step", stepPayload,
-                function (stepData) { handleStep(stepData, nextMessages); }, onError);
+            processToolCallsFrom(data.toolCalls, 0, nextMessages, data.toolTiers);
         }
 
-        var firstPayload = Object.assign({}, payload, { tools: true });
-        ajaxJson("POST", firstEndpoint, firstPayload, function (data) {
+        var firstPayload = Object.assign({}, payload, { tools: true, runId: runId });
+        fpCurrentAgentRequest = ajaxJson("POST", firstEndpoint, firstPayload, function (data) {
+            fpCurrentAgentRequest = null;
             handleStep(data, null);
-        }, function () {
+        }, function (err, xhr) {
+            fpCurrentAgentRequest = null;
+            if (fpAgentStopRequested) {
+                // CLAUDE-022: an abort of the FIRST request must actually
+                // stop, not fallbackToPlain() — falling back would ignore
+                // the stop and keep going without tools instead.
+                if (runRec) { recordRunEvent("interrupted", { detail: "stopped by user" }); rerenderTodoRecord(runRec); }
+                onError("Stopped after " + Math.max(0, step - 1) + " tool call step(s) at your request.");
+                return;
+            }
+            // CLAUDE-023: fallbackToPlain() must only fire for failures that
+            // actually look like "the provider doesn't support tools" — a
+            // genuine parse/validation failure from processGenerationContent
+            // (flowpilot.js) always comes back as HTTP 422 with a .raw
+            // payload attached (see err.status = 422 / err.raw = content
+            // there). A provider-level failure of the tools:true call itself
+            // (unrecognized "tools" field, model swapped since the last
+            // probe, etc.) never goes through that parser, so it always
+            // reaches here as some other status with no .raw. Only the
+            // latter should be silently retried without tools; the former is
+            // a real failure and must surface as one so handleExecuteError
+            // (via onModifyError) gets a chance to show it — including its
+            // raw JSON in Debug mode.
+            var raw = xhr && xhr.responseJSON && xhr.responseJSON.raw;
+            var looksLikeParseFailure = !!raw || (xhr && xhr.status === 422);
+            if (looksLikeParseFailure) {
+                if (runRec) { recordRunEvent("interrupted", { detail: "first agentic request failed" }); rerenderTodoRecord(runRec); }
+                onError(err, xhr);
+                return;
+            }
             // The provider was probed as
             // supportsTools, but the very first tools:true request failed
             // outright — e.g. the model was swapped since the last probe, or
@@ -622,8 +1015,14 @@
     // flow; show the raw so the user can see what happened.
     function handleExecuteError(msg, raw) {
         popDanglingUserHistory();
-        addMessage("error", msg);
-        if (raw) { addGeneratedJson(raw, true); }
+        if (raw && currentSettings.debugLogging) {
+            addMessage("error", msg);
+            addGeneratedJson(raw, true);
+        } else if (raw) {
+            addMessage("error", msg + " Enable Debug mode in Settings to see the full response next time.");
+        } else {
+            addMessage("error", msg);
+        }
         setBusy(false);
     }
 
@@ -632,6 +1031,28 @@
     function applySuggestedAction(suggestedAction) {
         if (!suggestedAction || !suggestedAction.mode || !suggestedAction.prompt) { return; }
         armExecuteAction(suggestedAction.mode);
+        // CLAUDE-015: the model already identified which nodes this action
+        // targets (including "the whole flow" as a valid identification,
+        // not an exemption) — override whatever armExecuteAction's own
+        // pinCurrentSelection() pinned from the live canvas selection, the
+        // same pinnedSelectionIds every downstream consumer (Document,
+        // Modify, their guards, their context builders) already reads via
+        // activeSelectionIds(). Absent targetNodeIds: unchanged, today's
+        // behavior. Mirrors pinCurrentSelection()'s own rule of only
+        // overwriting on a non-empty result, so a bad/empty resolution
+        // doesn't blow away a legitimate live-selection pin.
+        if (suggestedAction.targetNodeIds === "all") {
+            var allTabIds = allActiveTabNodeIds();
+            if (allTabIds.length) { pinnedSelectionIds = allTabIds; }
+        } else if (suggestedAction.targetNodeIds === "instance") {
+            var allInstanceIds = allInstanceNodeIds();
+            if (allInstanceIds.length) { pinnedSelectionIds = allInstanceIds; }
+        } else if (Array.isArray(suggestedAction.targetNodeIds)) {
+            var resolvedIds = suggestedAction.targetNodeIds.filter(function (id) {
+                return !!findLiveNode(id);
+            });
+            if (resolvedIds.length) { pinnedSelectionIds = resolvedIds; }
+        }
         var $promptBox = el("#fp-prompt");
         if ($promptBox.length) {
             $promptBox.val(suggestedAction.prompt);
@@ -660,11 +1081,23 @@
         var isChatMode = suggestedAction.mode === "chat";
         var titleText = suggestedAction.customTitle || (isChatMode ? "Switch to Chat" : "Cleared for takeoff — " + modeLabel);
 
+        // CLAUDE-028: the record must exist before the button does, so the
+        // button can carry data-fp-record-id/-action — the same relay
+        // markers renderAskUserQuestion's quick-reply buttons use to
+        // survive the pop-out's innerHTML clone (bindRecordActionButtons
+        // in init.js rebinds by these attributes and relays the click back
+        // to this window via resolveRecordAction; this window is the only
+        // one with live suggestedAction data to act on). The direct click
+        // handler below still fires normally for the un-popped-out sidebar.
+        var rec = addRecord("chip", { chipType: "suggestedAction", suggestedAction: suggestedAction });
+
         var $row = $("<div>").addClass("fp-chip-row");
         var $card = $("<button>")
             .addClass("fp-chip fp-chip-card")
             .attr("type", "button")
             .attr("title", suggestedAction.prompt)
+            .attr("data-fp-record-id", rec.id)
+            .attr("data-fp-record-action", "apply-suggested-action")
             .on("click", function () { applySuggestedAction(suggestedAction); });
         $("<span>").addClass("fp-chip-icon")
             .append($("<i>").addClass(isChatMode ? "fa fa-comment" : "fa fa-paper-plane"))
@@ -675,12 +1108,28 @@
         $("<span>").addClass("fp-chip-go").html("&rsaquo;").appendTo($card);
         $card.appendTo($row);
 
-        if (suggestedAction.selectionHint) {
-            $("<div>").addClass("fp-chip-hint").text("Tip: " + suggestedAction.selectionHint).appendTo($row);
+        // CLAUDE-030: Document mode always requires a real, non-empty
+        // selection at Send time (server-side: describeSelectionContext
+        // returns null and /flowpilot/document 400s on "Select the node(s)
+        // you want documented first" whenever nothing is actually selected)
+        // — but the model has occasionally generated a selectionHint
+        // implying otherwise (e.g. "leave nothing selected to document...
+        // general Node-RED info") when it had no concrete node to name.
+        // Rather than re-word the model's already-fragile mode-mismatch
+        // prompt guidance under time pressure, override deterministically
+        // here: if this chip targets Document and doesn't carry a real
+        // resolved target, always show the one hint that's actually true.
+        var targetResolved = suggestedAction.targetNodeIds === "all" ||
+            suggestedAction.targetNodeIds === "instance" ||
+            (Array.isArray(suggestedAction.targetNodeIds) && suggestedAction.targetNodeIds.length > 0);
+        var hintText = (suggestedAction.mode === "document" && !targetResolved)
+            ? "Select the node(s) you want documented first."
+            : suggestedAction.selectionHint;
+        if (hintText) {
+            $("<div>").addClass("fp-chip-hint").text("Tip: " + hintText).appendTo($row);
         }
 
         $box.append($row);
-        addRecord("chip", { chipType: "suggestedAction", suggestedAction: suggestedAction });
         scrollMessagesToBottom();
     }
 
@@ -772,6 +1221,28 @@
         scrollMessagesToBottom();
     }
 
+    // Detects the model's own tool-call envelope leaking through as
+    // "prose" — e.g. a vague first-turn Modify reply the server marked
+    // prose:true but whose explanation is actually the raw
+    // {"explanation":...,"changes":[...]} JSON as literal text. Starting
+    // with "{" alone doesn't make text suspect (real prose can open with
+    // a brace), so this also requires it to parse as an object carrying
+    // one of FlowPilot's own envelope keys.
+    function looksLikeToolEnvelope(text) {
+        if (typeof text !== "string") { return false; }
+        var trimmed = text.trim();
+        if (trimmed.charAt(0) !== "{") { return false; }
+        var parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        } catch (e) {
+            return false;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) { return false; }
+        return ["changes", "newNodes", "newWires", "removeNodes", "newGroups", "explanation"]
+            .some(function (key) { return Object.prototype.hasOwnProperty.call(parsed, key); });
+    }
+
     // Shared by Generate/Document/Modify result handlers: renders the model's
     // clarifying-question or prose-only envelope as a normal assistant
     // message and leaves the action armed for a follow-up. Returns true if it
@@ -789,6 +1260,11 @@
             return true;
         }
         if (data.prose) {
+            if (looksLikeToolEnvelope(data.explanation)) {
+                handleExecuteError("FlowPilot's reply didn't come through as expected.", data.explanation);
+                updateSelectionStatus();
+                return true;
+            }
             addMessage("assistant", data.explanation || "(no content returned)");
             pushHistory("assistant", data.explanation || "");
             renderActionChip(data.suggestedAction);
@@ -810,7 +1286,34 @@
 
         // Lay nodes out before review/import — see layoutGeneratedFlow for why.
         var flow = Array.isArray(data.flow) ? layoutGeneratedFlow(data.flow) : data.flow;
-        addMessage("assistant", data.explanation || "(no explanation returned)");
+        var planItems = parseTodoPlan(data.explanation || "");
+        var todoRec = null;
+        var writeResults = Array.isArray(data._agentWriteResults) ? data._agentWriteResults : [];
+        if (writeResults.length) {
+            if (!planItems.length) {
+                planItems = [{ text: goalPrompt || "Generate flow", status: "pending" }];
+            }
+            planItems.forEach(function (item, i) {
+                item.status = (i < writeResults.length)
+                    ? (writeResults[i].allPass ? "done" : "failed")
+                    : "active";
+            });
+            if (data._agentRunRecord) {
+                todoRec = data._agentRunRecord;
+                todoRec.action = "generate";
+                todoRec.items = planItems;
+            } else {
+                todoRec = addRecord("todo", { action: "generate", items: planItems });
+            }
+            rerenderTodoRecord(todoRec);
+            var deterministicSummary = buildDeterministicRunSummary(planItems, writeResults);
+            addMessage("assistant", deterministicSummary || "(no explanation returned)");
+            if (shouldShowSecondaryExplanation(deterministicSummary, data.explanation)) {
+                addMessage("fp-notice", data.explanation);
+            }
+        } else {
+            addMessage("assistant", data.explanation || "(no explanation returned)");
+        }
         pushHistory("assistant", data.explanation || "(no explanation returned)");
         // B1: bake the deploy-verify option into the review panel as the
         // primary chip rather than a separate chip below it. Only for
@@ -821,7 +1324,9 @@
         var _buildOnImported = (goalPrompt && !activeBuildLoop && _hasDeployable)
             ? function (importResult) { startBuildLoop(goalPrompt, flow, importResult); }
             : null;
-        addGeneratedReview(flow, _buildOnImported, _buildOnImported ? goalPrompt : null);
+        if (!writeResults.length) {
+            addGeneratedReview(flow, _buildOnImported, _buildOnImported ? goalPrompt : null);
+        }
         // Suppress a server-suggested build chip when deploy-verify is already
         // the primary action inside the review panel — it would be a duplicate.
         renderActionChip(_buildOnImported && data.suggestedAction && data.suggestedAction.mode === "build"
@@ -839,17 +1344,69 @@
         // W4: parse and surface the Plan: block if present.
         var planItems = parseTodoPlan(data.explanation || "");
         var todoRec = null;
+        // W7: real per-item correlation, and (CLAUDE-011) the signal that
+        // real mutations already happened this turn via WRITE tool calls
+        // (apply_step/remove_step/rename_node/group_nodes) — each already
+        // consent-gated (or, for group_nodes' write-safe tier, always
+        // auto-applied) and applied through its own review chip. Hoisted
+        // above the planItems.length check (rather than declared inside
+        // it) so it's always defined below even on a turn with no Plan:
+        // block, e.g. a wrap-up-only final response after tool calls.
+        var writeResults = Array.isArray(data._agentWriteResults) ? data._agentWriteResults : [];
         if (planItems.length) {
-            // Verification only produces one aggregate pass/fail result for
-            // the whole Modify response — mark every item active up front so
-            // they all resolve together instead of leaving items 2+ stuck at
-            // "pending" forever (only item 1 would ever flip otherwise).
-            planItems.forEach(function (item) { item.status = "active"; });
-            todoRec = addRecord("todo", { action: "modify", items: planItems });
+            // Each WRITE tool call this turn resolves ONE plan item, in
+            // order (§16 point 2 — "one WRITE tool call = one plan/todo
+            // item"). This is the deferred half of CLAUDE-005 (c6c2e84),
+            // now unblocked: that fix could only mark the WHOLE plan
+            // active/resolved together because there was no way to know
+            // which check proved which numbered line — a per-call tool
+            // result finally gives that mapping for free. Items beyond the
+            // resolved-call count (or ALL items, when no WRITE tool call
+            // was made this turn — the default, non-agentic-write path)
+            // fall back to CLAUDE-005's original all-together marking
+            // below, resolved via the ordinary aggregate verifySteps
+            // envelope path exactly as before — confirmed unchanged when
+            // _agentWriteResults is empty/absent.
+            if (writeResults.length) {
+                planItems.forEach(function (item, i) {
+                    item.status = (i < writeResults.length)
+                        ? (writeResults[i].allPass ? "done" : "failed")
+                        : "active";
+                });
+            } else {
+                // Verification only produces one aggregate pass/fail result
+                // for the whole Modify response — mark every item active up
+                // front so they all resolve together instead of leaving
+                // items 2+ stuck at "pending" forever (only item 1 would
+                // ever flip otherwise).
+                planItems.forEach(function (item) { item.status = "active"; });
+            }
+            // P10-D2: if this run already has a live "todo" record from
+            // WRITE-tool events (runAgentLoop, modes.js), upgrade it in
+            // place with the real Plan: items instead of creating a
+            // second record for the same run — so a run that paused
+            // mid-flight (refresh, interrupted) and one that completed
+            // normally both end up as ONE record with both events and
+            // items.
+            if (data._agentRunRecord) {
+                todoRec = data._agentRunRecord;
+                todoRec.action = "modify";
+                todoRec.items = planItems;
+            } else {
+                todoRec = addRecord("todo", { action: "modify", items: planItems });
+            }
             rerenderTodoRecord(todoRec);
         }
 
-        addMessage("assistant", data.explanation || "(no explanation returned)");
+        if (writeResults.length) {
+            var deterministicModifySummary = buildDeterministicRunSummary(planItems, writeResults);
+            addMessage("assistant", deterministicModifySummary || "(no explanation returned)");
+            if (shouldShowSecondaryExplanation(deterministicModifySummary, data.explanation)) {
+                addMessage("fp-notice", data.explanation);
+            }
+        } else {
+            addMessage("assistant", data.explanation || "(no explanation returned)");
+        }
         pushHistory("assistant", data.explanation || "(no explanation returned)");
         if (data.skippedNote) { addMessage("assistant", "⚠ " + data.skippedNote); }
 
@@ -870,7 +1427,16 @@
             }
         } : applyModifications;
 
-        addModifyReview(data.flow, data.newNodes || [], data.newWires || [], data.removeNodes || [], applyCallback, null, data.newGroups || []);
+        // CLAUDE-011: agentWriteRules tells the model to omit changes/
+        // newNodes/newWires/removeNodes/newGroups on this final response
+        // when writeResults is non-empty, so already-applied work isn't
+        // proposed a second time — but the model doesn't always comply.
+        // Don't rely on the prompt alone: skip rendering a second review/
+        // apply flow whenever real WRITE-tool work happened this turn,
+        // regardless of what the final envelope contains.
+        if (!writeResults.length) {
+            addModifyReview(data.flow, data.newNodes || [], data.newWires || [], data.removeNodes || [], applyCallback, null, data.newGroups || []);
+        }
         renderActionChip(data.suggestedAction);
         setBusy(false);
         updateSelectionStatus();
@@ -1041,13 +1607,17 @@
 
         var ap = activeProvider();
         var isAgentLoop = ap && ap.supportsTools;
+        var useAgentStrategy = isAgentLoop && endpointName === "generate" &&
+            currentSettings.enableAgentWrite === true;
 
         setBusy(true);
         showPending(isAgentLoop);
         var payload = {
             prompt: prompt, context: context,
             history: historyPayload.messages, historyTruncated: historyPayload.truncated,
-            conversationId: conversationId
+            conversationId: conversationId,
+            strategy: useAgentStrategy ? "agent" : "classic",
+            entry: endpointName
         };
 
         function onError(msg, xhr) {
@@ -1111,6 +1681,40 @@
         return items;
     }
 
+    function buildDeterministicRunSummary(planItems, writeResults) {
+        var lines = [];
+        var unreached = 0;
+        var items = planItems || [];
+        var counted = Math.max(items.length, (writeResults || []).length);
+        for (var i = 0; i < counted; i++) {
+            var item = items[i];
+            if (item && (i >= writeResults.length || item.status === "active" || item.status === "pending")) {
+                unreached++;
+                continue;
+            }
+            var itemText = (item && item.text) ? item.text : ("Step " + (i + 1));
+            if (writeResults[i] && writeResults[i].allPass) {
+                lines.push("✓ " + itemText);
+                continue;
+            }
+            var reason = (writeResults[i] && writeResults[i].reason) || "failed verification";
+            lines.push("✗ " + itemText + " — " + reason);
+        }
+        if (unreached) {
+            lines.push("▶ " + unreached + " step(s) not reached");
+        }
+        return lines.join("\n");
+    }
+
+    function shouldShowSecondaryExplanation(summaryText, explanationText) {
+        if (!explanationText || typeof explanationText !== "string") { return false; }
+        if (!summaryText || typeof summaryText !== "string") { return true; }
+        function normalize(text) {
+            return String(text || "").replace(/\s+/g, " ").trim().toLowerCase();
+        }
+        return normalize(summaryText) !== normalize(explanationText);
+    }
+
     // W4: render or re-render a "todo" record. For a 1-item plan, renders
     // as a compact status line (one chip). For N>1 items, renders as a
     // checklist card. Updates in place when the record already has a
@@ -1147,6 +1751,25 @@
             $wrap.append($ul);
         }
 
+        // P10-D2 (ADR-001 R5): a run whose last recorded event isn't "done"
+        // was abandoned mid-flight — an explicit interruption (stop button,
+        // step/token budget) or an orphaned request that never returned.
+        // Freeze whatever checklist state exists (possibly none yet, if
+        // interrupted before any Plan: text arrived) and say so plainly,
+        // replacing the old silent-death behavior ("Continuing without
+        // tools…" then nothing). "step N" counts completed (applied) WRITE
+        // tool calls, not raw round-trips.
+        if (Array.isArray(rec.events) && rec.events.length) {
+            var lastEvent = rec.events[rec.events.length - 1];
+            if (lastEvent.t !== "done") {
+                var appliedCount = rec.events.filter(function (e) { return e.t === "applied"; }).length;
+                $("<div>").addClass("fp-todo-interrupted").text(
+                    "⚠ This run was interrupted after step " + appliedCount +
+                    " — completed steps are applied (Ctrl+Z to undo). Re-send to continue from here."
+                ).appendTo($wrap);
+            }
+        }
+
         if ($existing.length) {
             $existing.replaceWith($wrap);
         } else {
@@ -1193,11 +1816,11 @@
             if (liveNode.type === "comment" || liveNode.type === "group") { return; }
             if (liveNode._def && liveNode._def.category === "config") {
                 configTotal++;
-                if (RED.nodes.node(liveNode.id)) { configFound++; }
+                if (nodeExists(liveNode.id)) { configFound++; }
                 return;
             }
             total++;
-            if (RED.nodes.node(liveNode.id)) {
+            if (nodeExists(liveNode.id)) {
                 found++;
             } else {
                 missing.push(liveNode.type || pid);
@@ -1240,58 +1863,77 @@
     // assigns it and returns idMap). Property/absent checks already use
     // real existing-node ids, so idMap[id] simply misses and falls through
     // to the id unchanged.
-    function verifyModifySteps(verifySteps, idMap, todoRec) {
-        if (!Array.isArray(verifySteps) || !verifySteps.length) { return; }
+    // One check-vocabulary evaluation (property/exists/absent/wire), shared
+    // by verifyModifySteps (aggregate Modify verification) and W7's
+    // per-tool-call check results (runChecksForToolResult, main.js) — same
+    // approach, applied either to the whole verifySteps batch or scoped to
+    // one WRITE tool call's own touched id(s). Returns null for an
+    // unrecognized check type (caller should skip it, not count it either
+    // way) or { ok, label } where label is the human-readable failure
+    // description used in the aggregate "did not land as expected" message.
+    // P10-E: each case delegates to graph-truth.js (same closure) — the
+    // one implementation of graph truth, per ADR-005. Wire checks in
+    // particular must never fall back to reading node.wires: RED.nodes.
+    // addLink/removeLink never re-sync a live node's own .wires array
+    // mid-session, so it's stale for anything added/removed this session.
+    function runSingleVerifyCheck(step, idMap) {
         idMap = idMap || {};
         function resolve(id) { return (idMap && idMap[id]) || id; }
-
-        var total = 0, passed = 0, failures = [];
-        verifySteps.forEach(function (step) {
-            var ok = false;
-            switch (step.check) {
-            case "property": {
-                var pNode = RED.nodes.node(resolve(step.nodeId));
-                ok = !!pNode && pNode[step.prop] === step.expected;
-                if (!ok) { failures.push((step.prop || "property") + " on " + step.nodeId); }
-                break;
-            }
-            case "exists": {
-                ok = !!RED.nodes.node(resolve(step.nodeId));
-                if (!ok) { failures.push(step.nodeId + " missing"); }
-                break;
-            }
-            case "absent": {
-                ok = !RED.nodes.node(resolve(step.nodeId));
-                if (!ok) { failures.push(step.nodeId + " still present"); }
-                break;
-            }
-            case "wire": {
-                // Read from the live link registry (RED.nodes.eachLink), not
-                // node.wires — RED.nodes.addLink/removeLink never re-sync a
-                // live node's own .wires array mid-session (it's only set at
-                // import and recomputed at export), so fromNode.wires[port] is
-                // stale for any wire added/removed during the current editing
-                // session. Mirrors computeWireDiff (apply-review.js).
-                var fromId = resolve(step.fromId);
-                var toId = resolve(step.toId);
-                var port = step.fromPort || 0;
-                ok = false;
-                RED.nodes.eachLink(function (l) {
-                    if (ok) { return; }
-                    if (l.source && l.source.id === fromId &&
-                            (l.sourcePort || 0) === port &&
-                            l.target && l.target.id === toId) {
-                        ok = true;
-                    }
-                });
-                if (!ok) { failures.push("wire " + step.fromId + " → " + step.toId); }
-                break;
+        switch (step.check) {
+        case "property": {
+            var okP = propertyEquals(resolve(step.nodeId), step.prop, step.expected);
+            var labelP = (step.prop || "property") + " on " + step.nodeId;
+            if (!okP) {
+                var readP = readProperty(resolve(step.nodeId), step.prop);
+                labelP += readP.exists ?
+                    " (expected " + JSON.stringify(step.expected) + ", found " + JSON.stringify(readP.value) + ")" :
+                    " (node does not exist)";
             }
-            default:
-                return; // unrecognized check type — don't count it either way
+            return { ok: okP, label: labelP };
+        }
+        case "exists": {
+            var okE = nodeExists(resolve(step.nodeId));
+            return { ok: okE, label: step.nodeId + " missing" };
+        }
+        case "absent": {
+            var okA = nodeAbsent(resolve(step.nodeId));
+            return { ok: okA, label: step.nodeId + " still present" };
+        }
+        case "wire": {
+            var fromId = resolve(step.fromId);
+            var toId = resolve(step.toId);
+            var port = step.fromPort || 0;
+            var okW = wireExists(fromId, port, toId);
+            var labelW = "wire " + step.fromId + " → " + step.toId;
+            if (!okW) {
+                var fromExists = nodeExists(fromId);
+                var toExists = nodeExists(toId);
+                if (!fromExists && !toExists) {
+                    labelW += " (neither node was ever created)";
+                } else if (!fromExists) {
+                    labelW += " (" + step.fromId + " was never created)";
+                } else if (!toExists) {
+                    labelW += " (" + step.toId + " was never created)";
+                } else {
+                    labelW += " (both nodes exist but aren't connected)";
+                }
             }
+            return { ok: okW, label: labelW };
+        }
+        default:
+            return null; // unrecognized check type — don't count it either way
+        }
+    }
+
+    function verifyModifySteps(verifySteps, idMap, todoRec) {
+        if (!Array.isArray(verifySteps) || !verifySteps.length) { return; }
+
+        var total = 0, passed = 0, failures = [], failedSteps = [];
+        verifySteps.forEach(function (step) {
+            var result = runSingleVerifyCheck(step, idMap);
+            if (!result) { return; }
             total++;
-            if (ok) { passed++; }
+            if (result.ok) { passed++; } else { failures.push(result.label); failedSteps.push(step); }
         });
 
         if (total === 0) { return; }
@@ -1301,6 +1943,25 @@
         } else {
             addMessage("fp-notice", "⚠ Verification: " + passed + "/" + total + " change(s) confirmed — " +
                 failures.length + " did not land as expected (" + failures.join(", ") + ").");
+            // CLAUDE-016: offer a "Fix this" chip naming exactly the nodes
+            // involved in the failed checks, reusing CLAUDE-015/CODEX-014's
+            // targetNodeIds auto-select mechanism rather than a new
+            // retry/loop. User-initiated only — the chip pre-fills a Modify
+            // prompt but still requires the user to review and click Send,
+            // same as every other suggestedAction chip.
+            function resolve(id) { return (idMap && idMap[id]) || id; }
+            var targetNodeIds = [];
+            failedSteps.forEach(function (step) {
+                var ids = step.check === "wire" ? [resolve(step.fromId), resolve(step.toId)] : [resolve(step.nodeId)];
+                ids.forEach(function (id) {
+                    if (id && targetNodeIds.indexOf(id) === -1) { targetNodeIds.push(id); }
+                });
+            });
+            renderActionChip({
+                mode: "modify",
+                prompt: "Fix the following change(s) that didn't land as expected: " + failures.join(", "),
+                targetNodeIds: targetNodeIds
+            });
         }
         if (todoRec && todoRec.items) {
             todoRec.items.forEach(function (item) {
@@ -1314,6 +1975,7 @@
         hidePending();
         if (renderQuestionOrProse(data)) { return; }
         var flow = Array.isArray(data.flow) ? layoutGeneratedFlow(data.flow) : data.flow;
+        var writeResults = Array.isArray(data._agentWriteResults) ? data._agentWriteResults : [];
 
         // Build the todo plan. Parse "Plan:" from explanation if present;
         // fall back to an implicit single item from the goal prompt.
@@ -1323,11 +1985,34 @@
         }
         // Same aggregate-verification reasoning as the Modify path: mark
         // every item active up front so a multi-item plan resolves together.
-        planItems.forEach(function (item) { item.status = "active"; });
-        var todoRec = addRecord("todo", { action: "generate", items: planItems });
+        if (writeResults.length) {
+            planItems.forEach(function (item, i) {
+                item.status = (i < writeResults.length)
+                    ? (writeResults[i].allPass ? "done" : "failed")
+                    : "active";
+            });
+        } else {
+            planItems.forEach(function (item) { item.status = "active"; });
+        }
+        var todoRec;
+        if (data._agentRunRecord) {
+            todoRec = data._agentRunRecord;
+            todoRec.action = "generate";
+            todoRec.items = planItems;
+        } else {
+            todoRec = addRecord("todo", { action: "generate", items: planItems });
+        }
         rerenderTodoRecord(todoRec);
 
-        addMessage("assistant", data.explanation || "(no explanation returned)");
+        if (writeResults.length) {
+            var deterministicQueueSummary = buildDeterministicRunSummary(planItems, writeResults);
+            addMessage("assistant", deterministicQueueSummary || "(no explanation returned)");
+            if (shouldShowSecondaryExplanation(deterministicQueueSummary, data.explanation)) {
+                addMessage("fp-notice", data.explanation);
+            }
+        } else {
+            addMessage("assistant", data.explanation || "(no explanation returned)");
+        }
         pushHistory("assistant", data.explanation || "(no explanation returned)");
         // B1: when a build loop is appropriate, bake deploy-verify into the
         // primary chip (same as handleSimpleGenerationResult). The callback
@@ -1342,7 +2027,9 @@
                 startBuildLoop(goalPrompt, flow, importResult);
             }
             : function (importResult) { verifyImportedNodes(importResult, todoRec); };
-        addGeneratedReview(flow, _onImported, _wantLoop ? goalPrompt : null);
+        if (!writeResults.length) {
+            addGeneratedReview(flow, _onImported, _wantLoop ? goalPrompt : null);
+        }
         // Suppress a server-suggested build chip when deploy-verify is already
         // the primary action inside the review panel.
         renderActionChip(_wantLoop && data.suggestedAction && data.suggestedAction.mode === "build"
@@ -1410,7 +2097,9 @@
         var payload = {
             prompt: instruction, context: context,
             history: historyPayload.messages, historyTruncated: historyPayload.truncated,
-            conversationId: conversationId
+            conversationId: conversationId,
+            strategy: "classic",
+            entry: "build-existing"
         };
 
         function onBuildExistingError(msg, xhr) {
@@ -1543,12 +2232,16 @@
         $("<button>")
             .addClass("fp-consent-chip fp-consent-chip-primary")
             .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "proceed")
             .text("Auto-verify")
             .on("click", function () { decide(true); })
             .appendTo($row);
         $("<button>")
             .addClass("fp-consent-chip fp-consent-chip-alt")
             .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "skip")
             .text("I'll check myself")
             .on("click", function () { decide(false); })
             .appendTo($row);
@@ -1586,6 +2279,209 @@
         renderActionChip(src.suggestedAction);
     }
 
+    // W7 — per-call consent gate for a write-gated agent tool call
+    // (apply_step/remove_step/rename_node touching a node type outside
+    // WRITE_GATE_SAFE_NODE_TYPES). Mirrors renderBuildConsentGate's shape
+    // and CLAUDE-008's fp-consent-chip styling, generalized to hold an
+    // arbitrary pending tool call instead of only a build-loop's node set.
+    //
+    // src.onResume is a live function reference, not plain-data-only —
+    // this is a DELIBERATE, reported deviation from renderBuildConsentGate/
+    // runBuildConsentDecision's full data-reconstruction pattern. Reason:
+    // the actual continuation (resuming the SAME in-flight
+    // runAgentLoop/handleStep batch — remaining tool calls, accumulated
+    // messages, then POSTing the next step and continuing the loop) lives
+    // in per-invocation closures that aren't all JSON-serializable
+    // (onDone/onError are themselves ad-hoc closures at each Modify call
+    // site, e.g. onModifyResult/onModifyError capturing goalPrompt/
+    // existingNodeIds). This mirrors the established, already-shipped
+    // rerenderGeneratedReview "onImported is a live function ref, valid
+    // within the same session" pattern rather than the stricter one.
+    // Confirmed the stricter pattern's actual reason — a genuinely separate
+    // pop-out window JS realm — does NOT apply here: the agent loop only
+    // ever runs in the main window (dispatchSend's pop-out branch relays
+    // via postMessage back to the opener rather than running its own loop,
+    // and runBuildConsentDecision/renderBuildConsentGate itself has no
+    // pop-out relay path either — confirmed via grep, so this is no
+    // weaker than the existing shipped precedent). What DOES carry over
+    // from CLAUDE-004-fix is the actual bug class it fixed: rerenderRecord
+    // must find a dispatch branch and re-render from the SAME stored
+    // record on refresh, never silently fall through to a generic path —
+    // that guarantee is fully delivered below.
+    function renderAgentToolConsentGate(src) {
+        var $box = el("#fp-messages");
+        if (!$box.length) {
+            if (!src.decision && typeof src.onResume === "function") { src.onResume(true); }
+            return;
+        }
+        // The pending "typing" indicator is only cleared automatically when
+        // a turn fully completes or errors — a pause here otherwise leaves
+        // it stuck showing stale narration ("Applying step: …") permanently
+        // above the real gate that renders below it.
+        hidePending();
+
+        var _rec = addRecord("question", {
+            agentToolConsent: true,
+            options: ["Proceed", "Skip this step"],
+            name: src.name,
+            args: src.args,
+            label: describeAgentToolCall(src.name, src.args),
+            onResume: src.onResume,
+            decision: src.decision
+        });
+
+        if (_rec.decision) {
+            // Already resolved before this render (e.g. resolved earlier in
+            // the session, now showing again after a refresh) — settled
+            // state, not an interactive choice. Mirrors
+            // renderBuildConsentGate's settled branch exactly.
+            addMessage("assistant", "Consent requested for: " + _rec.label);
+            var $settledRow = $("<div>").addClass("fp-chip-row fp-question-row");
+            $("<button>")
+                .addClass("fp-consent-chip")
+                .addClass(_rec.decision === "proceed" ? "fp-consent-chip-primary" : "fp-consent-chip-alt")
+                .attr("type", "button").prop("disabled", true)
+                .text(_rec.decision === "proceed" ? "Proceeded ✓" : "Skipped ✓")
+                .appendTo($settledRow);
+            $box.append($settledRow);
+            scrollMessagesToBottom();
+            return;
+        }
+
+        addMessage("assistant", "FlowPilot wants to do this: " + _rec.label +
+            ". Let it proceed, or skip just this one step and continue?");
+
+        var $row = $("<div>").addClass("fp-chip-row fp-question-row");
+
+        function decide(proceed) {
+            $row.find("button").prop("disabled", true);
+            _rec.decision = proceed ? "proceed" : "skip";
+            if (typeof _rec.onResume === "function") { _rec.onResume(proceed); }
+        }
+
+        $("<button>")
+            .addClass("fp-consent-chip fp-consent-chip-primary")
+            .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "proceed")
+            .text("Proceed")
+            .on("click", function () { decide(true); })
+            .appendTo($row);
+        $("<button>")
+            .addClass("fp-consent-chip fp-consent-chip-alt")
+            .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "skip")
+            .text("Skip this step")
+            .on("click", function () { decide(false); })
+            .appendTo($row);
+
+        $box.append($row);
+        scrollMessagesToBottom();
+    }
+
+    // W7 — ask_user tool UI. Reuses renderClarifyingQuestion's button +
+    // free-text presentation, but resumes the SAME in-flight agent-loop
+    // tool-call batch with the answer as a tool result via src.onAnswer —
+    // NOT dispatchSend() (which sends a brand-new user Send, a different
+    // flow entirely from continuing an already-in-progress tool-call turn).
+    // Same refresh-survival shape as renderAgentToolConsentGate (record +
+    // settled state), for the same reason: a mid-answer /refresh must not
+    // strand the loop or silently re-ask a resolved question.
+    function renderAskUserQuestion(src) {
+        var $box = el("#fp-messages");
+        if (!$box.length) {
+            if (src.decision !== "answered" && typeof src.onAnswer === "function") { src.onAnswer(""); }
+            return;
+        }
+        // Same reasoning as renderAgentToolConsentGate: a pause here must
+        // clear the pending indicator itself, since nothing else will.
+        hidePending();
+
+        var _rec = addRecord("question", {
+            askUserTool: true,
+            question: src.question || "FlowPilot has a question.",
+            options: Array.isArray(src.options) ? src.options : [],
+            onAnswer: src.onAnswer,
+            decision: src.decision,
+            answerText: src.answerText
+        });
+
+        if (_rec.decision === "answered") {
+            addMessage("assistant", _rec.question);
+            var $settled = $("<div>").addClass("fp-chip-row fp-question-row");
+            $("<button>")
+                .addClass("red-ui-button red-ui-button-small fp-chip fp-question-option")
+                .attr("type", "button").prop("disabled", true)
+                .text((_rec.answerText || "") + " ✓")
+                .appendTo($settled);
+            $box.append($settled);
+            scrollMessagesToBottom();
+            return;
+        }
+
+        addMessage("assistant", _rec.question);
+
+        var $row = $("<div>").addClass("fp-chip-row fp-question-row");
+        var $otherRow;
+
+        function answer(text) {
+            $row.find("button, input").prop("disabled", true);
+            if ($otherRow) { $otherRow.find("button, input").prop("disabled", true); }
+            _rec.decision = "answered";
+            _rec.answerText = text;
+            if (typeof _rec.onAnswer === "function") { _rec.onAnswer(text); }
+        }
+
+        _rec.options.forEach(function (opt) {
+            $("<button>")
+                .addClass("red-ui-button red-ui-button-small fp-chip fp-question-option")
+                .attr("type", "button")
+                .attr("data-fp-record-id", _rec.id)
+                .attr("data-fp-record-action", "answer")
+                .attr("data-fp-record-value", opt)
+                .text(opt)
+                .on("click", function () { answer(opt); })
+                .appendTo($row);
+        });
+
+        $otherRow = $("<div>").addClass("fp-question-other-row fp-hidden");
+        var $otherInput = $("<input>")
+            .attr("type", "text")
+            .attr("placeholder", "Type your answer…")
+            .addClass("fp-question-other-input");
+        var $otherSend = $("<button>")
+            .addClass("red-ui-button red-ui-button-small")
+            .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "answer-other")
+            .append($("<i>").addClass("fa fa-paper-plane"));
+
+        function submitOther() {
+            var val = $otherInput.val().trim();
+            if (!val) { return; }
+            answer(val);
+        }
+        $otherSend.on("click", submitOther);
+        $otherInput.on("keydown", function (e) { if (e.key === "Enter") { submitOther(); } });
+        $otherRow.append($otherInput).append($otherSend);
+
+        $("<button>")
+            .addClass("red-ui-button red-ui-button-small fp-chip fp-question-other")
+            .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "show-other")
+            .text("Other…")
+            .on("click", function () {
+                $otherRow.removeClass("fp-hidden");
+                $otherInput.focus();
+            })
+            .appendTo($row);
+
+        $box.append($row).append($otherRow);
+        scrollMessagesToBottom();
+    }
+
     function handleBuildResult(data, goalPrompt) {
         hidePending();
         if (renderQuestionOrProse(data)) { return; }
@@ -1622,12 +2518,34 @@
     // Generate — a comment node is just a regular flow-JSON node, so there's
     // nothing import-mechanism-specific to build here. The prompt box holds
     // OPTIONAL notes to steer the explanation; the selection is the real input.
+    // Nothing selected/pinned for a Document send: rather than hard-erroring
+    // (the old behavior — Document previously only ever meant "the
+    // selection"), offer a deterministic one-click scope choice. This is a
+    // pure client-side UX decision, not something worth routing through the
+    // model — a weak/local provider's suggestedAction may omit
+    // targetNodeIds even when the user's intent was clear (see the "all"/
+    // "instance" vocabulary in the system prompts), so this is the backstop
+    // that always works regardless of model reliability.
+    function offerDocumentScopeClarification() {
+        addMessage("info", "Nothing is selected. What would you like documented?");
+        renderChip("This flow", "fa fa-sitemap", function () {
+            var ids = allActiveTabNodeIds();
+            if (ids.length) { pinnedSelectionIds = ids; }
+            documentFlow();
+        });
+        renderChip("Entire instance", "fa fa-server", function () {
+            var ids = allInstanceNodeIds();
+            if (ids.length) { pinnedSelectionIds = ids; }
+            documentFlow();
+        });
+    }
+
     function documentFlow() {
         // Falls back to the pinned selection if nothing is currently
         // selected, so follow-up turns need no reselection.
         var context = collectSelectionContext(activeSelectionIds());
         if (!context || !Array.isArray(context.nodes) || context.nodes.length === 0) {
-            addMessage("error", "Select the node(s) you want documented first.");
+            offerDocumentScopeClarification();
             return;
         }
         context = attachDebugContext(context);
@@ -1649,7 +2567,9 @@
         var payload = {
             prompt: notes, context: context,
             history: historyPayload.messages, historyTruncated: historyPayload.truncated,
-            conversationId: conversationId
+            conversationId: conversationId,
+            strategy: "classic",
+            entry: "document"
         };
 
         function onDocumentError(msg, xhr) {
@@ -1712,14 +2632,17 @@
         $promptBox.val("");
 
         var ap = activeProvider();
-        var isAgentLoop = ap && ap.supportsTools;
+        var isAgentLoop = ap && ap.supportsTools &&
+            currentSettings.enableAgentWrite === true;
 
         setBusy(true);
         showPending(isAgentLoop);
         var payload = {
             prompt: instruction, context: context,
             history: historyPayload.messages, historyTruncated: historyPayload.truncated,
-            conversationId: conversationId
+            conversationId: conversationId,
+            strategy: isAgentLoop ? "agent" : "classic",
+            entry: "modify"
         };
 
         function onModifyError(msg, xhr) {
@@ -1795,6 +2718,14 @@
     //              held in these states.
     var activeBuildLoop = null;
 
+    // CLAUDE-014: plain-language note for a loop-checkpoint "Continue" click,
+    // read and cleared by runBuildReview's payload build. Mirrors
+    // runAgentLoop's pendingDebugNote, but module-scoped since
+    // renderLoopCheckpoint/runBuildReview aren't nested inside runAgentLoop.
+    // No equivalent exists for "Stop loop" — stopBuildLoop makes no server
+    // round trip to attach a note to.
+    var pendingLoopDebugNote = null;
+
     // How long onDebugMessage's auto-attach waits, after each matching
     // message, for another one to arrive before locking in and running
     // the review — see onDebugMessage for why (a forked/split flow can
@@ -1829,9 +2760,25 @@
 
         var $row = $("<div>").addClass("fp-chip-row fp-question-row");
 
+        var _rec = addRecord("question", {
+            options: ["Continue → AI review", "Stop loop"],
+            loopCheckpoint: true,
+            onResume: function (action) {
+                if (action === "continue") {
+                    if (activeBuildLoop) {
+                        if (currentSettings.debugLogging) { pendingLoopDebugNote = "user clicked Continue"; }
+                        runBuildReview(activeBuildLoop);
+                    }
+                } else if (action === "stop") {
+                    stopBuildLoop("Build loop stopped — applied nodes remain as-is.");
+                }
+            }
+        });
+
         function onContinue() {
             $row.find("button").prop("disabled", true);
             if (!activeBuildLoop) { return; }
+            if (currentSettings.debugLogging) { pendingLoopDebugNote = "user clicked Continue"; }
             runBuildReview(activeBuildLoop);
         }
         function onStop() {
@@ -1842,18 +2789,21 @@
         $("<button>")
             .addClass("red-ui-button red-ui-button-small fp-chip fp-question-option")
             .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "continue")
             .text("Continue → AI review")
             .on("click", onContinue)
             .appendTo($row);
         $("<button>")
             .addClass("red-ui-button red-ui-button-small fp-chip fp-question-option")
             .attr("type", "button")
+            .attr("data-fp-record-id", _rec.id)
+            .attr("data-fp-record-action", "stop")
             .text("Stop loop")
             .on("click", onStop)
             .appendTo($row);
 
         $box.append($row);
-        addRecord("question", { options: ["Continue → AI review", "Stop loop"], loopCheckpoint: true });
         scrollMessagesToBottom();
     }
 
@@ -1960,6 +2910,10 @@
         } else {
             loop.iteration++;
             loop.waypoint = "apply";
+            // CLAUDE-025: this fix still needs its OWN fresh deploy before
+            // any evidence counts — the next "deploy" event re-stamps this
+            // once the new apply->attach transition actually fires.
+            loop.deployedAt = null;
             renderLoopStepper(loop);
         }
     }
@@ -2118,7 +3072,12 @@
             bailCount: 0,
             httpEndpoints: httpEndpoints,
             skipCheckpointNodeIds: skipCheckpointNodeIds,
-            skipCheckpointTapIds: skipCheckpointTapIds
+            skipCheckpointTapIds: skipCheckpointTapIds,
+            // CLAUDE-025: stamped by the RED "deploy" listener (init.js) the
+            // moment THIS attempt's own apply->attach transition fires — see
+            // freshBuildLoopEvidence. Starts null: no deploy has happened for
+            // this attempt yet, so nothing can count as evidence.
+            deployedAt: null
         };
         renderLoopStepper(activeBuildLoop);
     }
@@ -2133,7 +3092,21 @@
     // node ids instead of the live/pinned canvas selection) are synthetic.
     function runBuildReview(loop) {
         var context = collectSelectionContext(loop.nodeIds);
-        context = attachDebugContext(context);
+        // CLAUDE-025: deliberately NOT attachDebugContext() here — that pulls
+        // in the full sticky attachedDebugMessages buffer, which can still
+        // hold evidence from an earlier Build attempt (or a manual attach)
+        // that has nothing to do with THIS attempt's own deploy. Only
+        // messages that arrived at/after this attempt's own deploy (see
+        // freshBuildLoopEvidence) count as evidence for its review.
+        var freshEvidence = freshBuildLoopEvidence(loop);
+        if (freshEvidence.length) {
+            context = context || { nodes: [], connections: {} };
+            context = Object.assign({}, context, {
+                debugMessages: freshEvidence.map(function (m) {
+                    return { id: m.id, timestamp: m.timestamp, sourceKind: m.sourceKind, name: m.name, topic: m.topic, value: m.value };
+                })
+            });
+        }
         var reviewEvidence = context && Array.isArray(context.debugMessages)
             ? context.debugMessages : [];
         var statusOnlyEvidence = reviewEvidence.length > 0 &&
@@ -2221,8 +3194,14 @@
         var payload = {
             prompt: instruction, context: context,
             history: historyPayload.messages, historyTruncated: historyPayload.truncated,
-            conversationId: loop.conversationId
+            conversationId: loop.conversationId,
+            strategy: "classic",
+            entry: "build-review"
         };
+        if (pendingLoopDebugNote) {
+            payload.debugNote = pendingLoopDebugNote;
+            pendingLoopDebugNote = null;
+        }
 
         function onReviewError(msg, xhr) {
             hidePending();
@@ -2298,6 +3277,13 @@
         if (data.prose) {
             var explanation = data.explanation || "(no content returned)";
 
+            if (looksLikeToolEnvelope(data.explanation)) {
+                handleExecuteError("FlowPilot's reply didn't come through as expected.", data.explanation);
+                stopBuildLoop("Build loop stopped — the review response wasn't in the expected format. Continue manually with Modify, or start a fresh /build.", false);
+                updateSelectionStatus();
+                return;
+            }
+
             // W0.3: bail detection — a prose reply with a mode-redirect
             // suggestedAction means the model tried to exit the loop
             // context via the Modify escape hatch. Count it and retry or