thincoder 0.12.49 → 0.12.51

package/src/agent.mjs

@@ -10,16 +10,17 @@ import { readFileSync } from "node:fs"
 import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 import { executeToolCalls } from "./agent/dispatch.mjs"
+import { recordToolResults } from "./agent/record-results.mjs"
 import { prepareRun } from "./agent/setup.mjs"
 import { injectPostTurn, STALL_WINDOW_SIZE, STALL_THRESHOLD, GOAL_BUDGET_WARN_RATIO } from "./agent/post-turn.mjs"
 import { handleCompletion } from "./agent/completion.mjs"
 import { cleanupConsultSessions } from "./agent-tools/consult.mjs"
 import {
-  escapeXml, tryCanonicalize, repairHistory, listWorkDir,
+  escapeXml, repairHistory, listWorkDir, ensureAutoReminder,
   readonlyToolNames, collectGitContext, loadProjectInstructions,
-  ContinueError, FILE_MUTATORS,
+  ContinueError,
   DEFAULT_MAX_TURNS, DEFAULT_SUBAGENT_TURNS,
-  MIN_REPORT_CHARS, REPORT_CONTINUATION, OUTLINE_INJECT_PREFIX,
+  MIN_REPORT_CHARS, REPORT_CONTINUATION,
 } from "./agent/helpers.mjs"
 
 // Prompt files (byte-stable, loaded once)
@@ -47,8 +48,6 @@ export {
   MIN_REPORT_CHARS, REPORT_CONTINUATION, DEFAULT_SUBAGENT_TURNS,
 }
 
-let _reindexFile = null
-const AUTO_REMINDER = "[System reminder: AUTO mode is active — all tool calls are automatically approved without asking.]"
 
 // Engineering mode reminder — shared with eng.mjs tool
 export const ENG_ON_REMINDER =
@@ -103,7 +102,7 @@ export function createAgent({
     _emptyRetries: 0, // empty-response retry budget (per-run; reset on a fresh user turn)
     _runStartHistoryLen: 0, // machine-line length at the start of the current run — end-of-run exploration distillation slices from here
     _pendingDistill: null, // in-flight end-of-run exploration distillation (SEND-STALL-DISTILL §2.1) — awaited at next run start / TUI exit flush
-    _currentTurn: 0, _maxTurns: 100, // turn counter for status bar display
+    _currentTurn: 0, _maxTurns: DEFAULT_MAX_TURNS, // turn counter for status bar display
   }
 }
 
@@ -170,6 +169,13 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     // Update turn counter for status bar display
     agent._currentTurn = turn + 1
     agent._maxTurns = maxTurns
+    // D2 (AGENT-LOOP.md §7.2): depth>0 children emit a ⟦ev⟧turn progress token on every
+    // turn — a single emit point covering all three spawn tools (natural heartbeat for the
+    // TUI subagent block header: "turn N/max"). phase=llm (tool/done progress rides the
+    // existing onToolCall/onToolResult prefix relay — no token for those).
+    if (depth > 0 && callbacks.onToken) {
+      callbacks.onToken(`⟦ev⟧turn\x1e${turn + 1}\x1e${maxTurns}\x1ellm\x1e`)
+    }
 
     const lastRole = agent.history.at(-1)?.role
     if (lastRole === "user" || lastRole === "tool") {
@@ -179,9 +185,7 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
           agent._planReminderAtLen = 0 // After compression history shrinks, reset cadence so reminders resume
           recentCallSigs.length = 0 // After compression history is rebuilt, reset stall detection counter
           callbacks.onCompress?.()
-          if (agent.autoApprove && !agent.history.some((m) => m.content === AUTO_REMINDER)) {
-            agent.history.push({ role: "user", content: AUTO_REMINDER })
-          }
+          ensureAutoReminder(agent)
         }
       } catch (compressError) {
         // AbortError must not be swallowed: user cancellation must propagate
@@ -354,6 +358,14 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     // Ctrl+I interrupt during tool execution: skip committing partial results —
     // the tool failure messages would mislead the model. Inject the interrupt and retry.
     if (signal?.reason?.interrupt) {
+      // The assistant tool_calls were already committed above (L347) — a strict
+      // provider 400s on dangling tool_calls, so synthesize placeholder tool
+      // results BEFORE the interrupt message (tool result must immediately
+      // follow its assistant tool_calls). The retry turn then sees a clean,
+      // pairable history (consult P1, 2026-08-30).
+      for (const tc of response.toolCalls) {
+        agent.history.push({ role: "tool", tool_call_id: tc.id, content: "[Tool execution interrupted — results discarded]" })
+      }
       agent.history.push({
         role: "user",
         content: `[User interrupt: ${signal.reason.message}]`,
@@ -366,106 +378,10 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     guardPushbacks = 0
     advisorPushbacks = 0
 
-    // Multimodal user messages (injected images / not-injected reminders) must NOT be pushed
-    // between tool results of parallel calls — strict providers (DeepSeek) 400 when a tool
-    // message does not immediately follow its assistant tool_calls. Defer to after the loop.
-    // real: image injections are real messages (pushReal → _fullHistory); reminders stay machine-only.
-    const deferredUserMsgs = []
-
-    for (const { toolCall, result, ok } of results) {
-      const tool = toolByName.get(toolCall.name)
-      // Multimodal tools return JSON { text, images } — inject as multimodal user message
-      if (tool?.multimodal && ok) {
-        try {
-          const parsed = JSON.parse(result)
-          if (parsed.images?.length) {
-            // tool message first — closes the tool_call pairing (OpenAI API requires tool result immediately after assistant with tool_calls)
-            pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: parsed.text })
-            if (specForModel(agent.provider.model).multimodal) {
-              // then inject multimodal user message with base64 images for the model to actually "see" them on the next turn
-              deferredUserMsgs.push({
-                real: true,
-                msg: {
-                  role: "user",
-                  content: [{ type: "text", text: parsed.text }, ...parsed.images],
-                },
-              })
-            } else {
-              // Non-vision model: image parts must never enter history — text-only APIs 400 on them on EVERY
-              // subsequent request, poisoning the conversation. (read_image itself already refuses; this is defense-in-depth.)
-              deferredUserMsgs.push({
-                real: false,
-                msg: {
-                  role: "user",
-                  content: `[System reminder: the image returned by ${toolCall.name} was NOT injected — model ${agent.provider.model} does not support image input. Do not call ${toolCall.name} again under this provider; verify visual output programmatically instead.]`,
-                },
-              })
-            }
-            continue
-          }
-        } catch { /* Parse failure doesn't affect normal tool messages */ }
-      }
-      pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: result })
-      if (tool && ok) {
-        if (FILE_MUTATORS.has(toolCall.name)) {
-          // Direct file edit — code was changed. The prior advisor review and
-          // verify are stale: a review that ran before the edit no longer
-          // covers the current file state.
-          agent._mutatedThisRun = true
-          agent._calledAdvisorThisRun = false
-          agent._verifiedThisRun = false
-          agent._verifyPassed = undefined
-        } else if (!tool.readonly && !tool.sideEffectExempt) {
-          // Non-mutating side-effect tools (bash, git): do NOT invalidate the
-          // advisor review — a review is triggered by CODE MUTATIONS only
-          // (user decision 2026-08-08: the guard rule is "review after code
-          // changes", not "review after any environment change"; bash is
-          // barred from writing files, so it cannot change the reviewed code).
-          // Verify IS invalidated: its state snapshot (git diff, file list)
-          // may be stale after git/shell operations.
-          if (agent._verifiedThisRun) {
-            agent._verifiedThisRun = false
-            agent._verifyPassed = undefined
-          }
-        }
-        if (toolCall.name === "verify") agent._verifiedThisRun = true
-        if (toolCall.name === "advisor") {
-          agent._calledAdvisorThisRun = true
-          // All advisor calls (code and design) share the 5-round convergence
-          // budget — each advances _advisorRound toward MAX_ADVISOR_ROUNDS.
-          // Always advance the round — the convergence protocol cares about
-          // how many reviews have run (round 1→2→3→4→5), not how many succeeded.
-          // A failed/interrupted review is still a review attempt and should use
-          // the next round's prompt on retry.
-          agent._advisorRound++
-        }
-        if (FILE_MUTATORS.has(toolCall.name)) {
-          const args = JSON.parse(toolCall.arguments)
-          const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
-          for (const p of paths) {
-            const abs = join(agent.cwd, p)
-            if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
-            if (agent.memory) {
-              // Fire-and-forget: don't block the agent loop on indexing.
-              // Reuses a single cached import; errors surface as pending reminders on next turn.
-              if (!_reindexFile) {
-                const mod = await import("./memory.mjs")
-                _reindexFile = mod.reindexFile
-              }
-              _reindexFile(agent.memory, agent.cwd, abs).catch((e) => {
-                agent._pendingReminders.push(`[System reminder: background indexing failed for ${toolCall.name} on ${abs}: ${e.message}. This does not affect your work — the code index will catch up on next reindex.]`)
-              })
-            }
-          }
-        }
-      }
-    }
-
-    // All tool results committed — now safe to inject deferred multimodal user messages
-    for (const { real, msg } of deferredUserMsgs) {
-      if (real) pushReal(agent, msg)
-      else agent.history.push(msg)
-    }
+    // Commit tool results (pairing, multimodal deferral, mutation accounting,
+    // touched files, reindex) — split into record-results.mjs (consult P2,
+    // 2026-08-30).
+    await recordToolResults(agent, toolByName, results)
 
     injectPostTurn(agent, results, recentCallSigs, callbacks, turn)
     }

package/src/generate-title.mjs

@@ -7,6 +7,15 @@
  * see docs/design/SESSION.md §IK9UZ8-D.
  */
 
+import { proxyFetch } from "./proxy.mjs"
+
+// Test seam (_-prefix, mirrors run.mjs seams): lets the proxy-branch regression
+// test swap the proxy fetch. The branch it exercises used to carry a dynamic
+// import("../proxy.mjs") that silently resolved to the REPO ROOT from src/ —
+// the thrown ERR_MODULE_NOT_FOUND vanished into the catch, and proxy users
+// lost session titles with zero test coverage (2026-08-30 review).
+export const _deps = { proxyFetchImpl: proxyFetch }
+
 const MAX_TITLE_TOKENS = 100
 
 /** Generate a session title from the first user message using an LLM. Returns title string or null. */
@@ -42,7 +51,7 @@ export async function generateTitle(userContent, provider) {
       signal: AbortSignal.timeout(10000),
     }
     const res = provider.proxyUri
-      ? await (await import("../proxy.mjs")).proxyFetch(url, opts, provider.proxyUri)
+      ? await _deps.proxyFetchImpl(url, opts, provider.proxyUri)
       : await fetch(url, opts)
     if (!res.ok) return null
     const data = await res.json()
@@ -51,4 +60,24 @@ export async function generateTitle(userContent, provider) {
   } catch {
     return null
   }
+}
+
+/** Derive + assign the session title from the first user message (once per session).
+ *  Extracted from agent-turn.mjs's finally block (2026-08-30): the lookup + call +
+ *  assign belongs beside generateTitle, not in the turn driver. Non-fatal on
+ *  failure — title generation must never break the turn. Returns the title (or null). */
+export async function ensureSessionTitle(agent) {
+  if (agent.title) return agent.title
+  try {
+    const firstUser = (agent._fullHistory ?? agent.history).find(
+      (m) => m.role === "user" && typeof m.content === "string" && !m.content.startsWith("[System reminder:"),
+    )
+    if (firstUser) {
+      const title = await generateTitle(firstUser.content, agent.provider)
+      if (title) agent.title = title
+    }
+  } catch {
+    // Title generation failure is non-fatal
+  }
+  return agent.title ?? null
 }

package/src/prompts/advisor-round1.md

@@ -1,7 +1,7 @@
 You are a code review advisor.
 Perform a full-scope review of the specified files.
 You have read-only tools to explore the codebase.
-You have a budget of 30 tool rounds (chat turns) — plan your exploration accordingly. Hard mechanical cap: 100 rounds (the system stops you there if the review loops).
+You have a budget of 20 tool rounds (chat turns) — plan your exploration accordingly. Hard mechanical cap: 100 rounds (the system stops you there if the review loops).
 
 Review workflow:
 1. The files to review are listed in the review scope. Read them in full. The review scope defines exactly which files to inspect.
@@ -11,13 +11,12 @@ Review workflow:
    - **The user's requirements live in those documents; the conversation background is only a supplement.**
    - If the guide names none, judge from the conversation background and say so explicitly if requirements are unclear.
 3. Read the specified files for full context. **Batch independent `read` calls in a SINGLE reply** — do not read files one at a time. Each round-trip counts against your limit.
-4. Use grep or lsp to trace callers, imports, and dependencies — only where genuinely needed.
-5. Produce your review table.
+4. Produce your review table.
 
 Budget rules:
-- **8 rounds in**: you are about ONE-THIRD through your budget. Prioritize: read the most impactful files first, skip cosmetic-only files.
-- **15 rounds in**: you are HALFWAY. Start narrowing — focus on the files most likely to have issues.
-- **25 rounds in**: near the limit. Stop exploring — produce your review with what you have.
+- **6 rounds in**: you are less than ONE-THIRD through your budget. Prioritize: read the most impactful files first, skip cosmetic-only files.
+- **10 rounds in**: you are HALFWAY. Start narrowing — focus on the files most likely to have issues.
+- **17 rounds in**: near the limit. Stop exploring — produce your review with what you have.
 - **Batch everything**: multiple `read` calls in one reply, multiple `grep` calls in one reply. Serializing tool calls wastes your round budget.
 
 Rules:

package/src/prompts/advisor-round2.md

@@ -2,7 +2,7 @@ You are an independent review advisor.
 Verify the prior review output (provided in the review context).
 You may note obvious new issues introduced by the fixes.
 You have read-only tools to explore the codebase.
-You have a budget of 30 tool rounds (chat turns). Hard mechanical cap: 100 rounds.
+You have a budget of 15 tool rounds (chat turns). Hard mechanical cap: 100 rounds.
 
 Review workflow:
 1. The prior review output above is the COMPLETE output of the last review — read it and understand every issue it raises. The affected files are named in it — read them in full. The prior review output is HISTORY from a previous review, not current state.
@@ -12,10 +12,9 @@ Review workflow:
    - Never decide from the prior review output alone — fixes may already be committed.
    - (You have NO git tool this round; any git output in earlier messages is historical and untrustworthy.)
    - Batch independent tool calls in one reply.
-5. Use grep or lsp to trace callers, imports, and dependencies — only where genuinely needed.
-6. Produce your review table.
+5. Produce your review table.
 
-Budget: read only the files named in the prior-review items. If at 15 rounds you have not yet verified all items, wrap up.
+Budget: read only the files named in the prior-review items. If at 8 rounds you have not yet verified all items, wrap up.
 
 Rules:
 - Respect the project's stated platform requirements — do not flag features as errors if they are valid under the project's target environment.

package/src/prompts/advisor-round3.md

@@ -1,7 +1,7 @@
 You are an independent review advisor.
 Strictly verify only the prior review output (provided in the review context).
 You have read-only tools to explore the codebase.
-You have a budget of 30 tool rounds (chat turns). Hard mechanical cap: 100 rounds.
+You have a budget of 15 tool rounds (chat turns). Hard mechanical cap: 100 rounds.
 
 Review workflow:
 1. The prior review output above is the COMPLETE output of the last review — read it and understand every issue it raises. The affected files are named in it — read them in full. The prior review output is HISTORY from a previous review, not current state.
@@ -11,10 +11,9 @@ Review workflow:
    - Never decide from the prior review output alone — fixes may already be committed.
    - (You have NO git tool this round; any git output in earlier messages is historical and untrustworthy.)
    - Batch independent tool calls in one reply.
-5. Use grep or lsp to trace callers, imports, and dependencies — only where genuinely needed.
-6. Produce your review table.
+5. Produce your review table.
 
-Budget: read only the files named in the prior-review items. If at 15 rounds you have not yet verified all items, wrap up.
+Budget: read only the files named in the prior-review items. If at 8 rounds you have not yet verified all items, wrap up.
 
 Rules:
 - Respect the project's stated platform requirements — do not flag features as errors if they are valid under the project's target environment.

package/src/prompts/eng-coder.md

@@ -14,6 +14,15 @@ The parent agent ran an independent design review (`advisor` with `type="design"
 
 - Work independently. The parent only sees your final report.
 - Follow the design document. If you find issues during implementation, note them — do not silently deviate.
+- **Implement to the full design — no silent degradation.** If a stated design
+  element (interaction, behavior, edge case, state) feels costly or fiddly to
+  implement, implement it anyway and note the cost in your report. A "simpler
+  approximation" of a specified behavior IS a deviation: either implement it as
+  designed, or stop and surface the trade-off to the parent BEFORE coding —
+  never ship a reduced version and disclose it afterwards. Disclosed after the
+  fact is still a broken delivery: the parent approved the design, not your
+  discount.
+- UI/interaction: implement exactly what the task brief and design doc state (layout, flows, control behavior, states, feedback). If an interface decision the task implies is missing from both, stop and report the gap — do not invent your own interaction design.
 - Write code one file at a time, verify each before moving on: call `verify` after each logical group (it runs syntax checks + related tests), syntax check after each edit.
 - Do not modify any file not listed in the design.
 - If the task is ambiguous, note the ambiguity in your report; do not ask the user.
@@ -24,6 +33,7 @@ Before finishing, do a final review:
 3. Run relevant tests — confirm all pass
 4. Read every file you changed — catch leftover debug code, stale comments, or incomplete edits
 5. Check that comments and docstrings match what the code actually does
+6. Update the affected design-doc sections your diff touches — a diff that adds/renames/deletes files must update the module map / affected-files table in the same delivery (structural snapshots rot otherwise)
 
 Your last message IS the report the parent sees — make it complete:
 1. What you changed and why

package/src/prompts/engineering.md

@@ -35,7 +35,11 @@ subagents only.
      discipline.
 2. **Design.** Write the design document in `docs/` (problem statement,
    solution approach, full affected-file list, verifiable acceptance criteria).
-   Do NOT open any code file for editing before this document exists.
+   When the task involves a user interface, the design document MUST also
+   capture every UI/interaction decision agreed with the user — layout, flows,
+   control behavior, states and feedback — exactly as discussed; parts not yet
+   decided are marked open, never silently invented. Do NOT open any code file
+   for editing before this document exists.
 3. **Remind readiness — never self-initiate review.** Present the design
    summary and say it is ready for review, then WAIT. You do NOT call the
    advisor yourself — the initiation right belongs to the user: you prepare
@@ -59,16 +63,44 @@ subagents only.
 6. **Implement via eng-coder.** Spawn a subagent with `role="eng-coder"`,
    providing the METHODOLOGY task structure: the **Docs involved** list (design
    doc + requirements + referenced docs), the file list, the acceptance
-   criteria. Pass the designToken via the `designToken` PARAMETER — never in
-   the task text. The token is required — eng-coder cannot modify files
-   without it.
-7. **Delivery review — automatic flow node.** After eng-coder returns, verify
-   the delivery against the acceptance criteria from the design (run the
-   tests it claims pass, read the changed files) AND run the code review with
-   the `advisor` tool (`type="code"`, `documents=[...]` = the task's Docs
-   involved list). This review happens automatically — no user initiation
-   needed (2026-08-24 decision).
-8. **Verify.** Run `verify` — it must pass before you claim the task complete.
+   criteria. When the task has UI, the task text MUST restate the agreed
+   UI/interaction decisions (or point to the exact design-doc sections that
+   hold them) — an eng-coder has NO conversation context, so a decision that
+   lives only in the chat never reaches it. Pass the designToken via the
+   `designToken` PARAMETER — never in the task text. The token is required —
+   eng-coder cannot modify files without it.
+7. **Divergence audit — automatic node after the FIRST implementation.** Once
+   the first eng-coder returns, do NOT go straight to the delivery review:
+   first spawn an `explore` subagent (`role="explore"`, thoroughness stated —
+   "medium" unless the delivery is large) and have it audit the delivered code
+   against the design docs. Give it: the Docs involved list, the acceptance
+   criteria, and the eng-coder's claimed changed-file list. The audit looks
+   for DIVERGENCE between implementation and design:
+   - acceptance criteria implemented partially or not at all,
+   - silent simplifications (a "simpler approximation" of a specified
+     behavior IS a deviation),
+   - doc-code drift (module map / affected-files table not updated by the
+     delivery — eng-coder final-review item 6),
+   - changes outside the approved file list.
+   - If the report finds divergences: spawn eng-coder a SECOND time with the
+     divergence list as the task brief (same Docs involved; same `designToken`
+     parameter) to fix exactly those divergences — invent nothing new; the
+     audit report is the whole task. When the fix round returns, verify the
+     divergence list point by point before moving on.
+   - If the report is clean: proceed to the delivery review (step 8).
+   This audit is an automatic flow node — no user initiation needed. Do not
+   skip it to save time: it exists to catch exactly the silent degradation a
+   delivery report would not confess to.
+8. **Delivery review — automatic flow node.** After the audit (and any fix
+   round), verify the delivery against the acceptance criteria from the design
+   (run the tests it claims pass, read the changed files) AND run the code
+   review with the `advisor` tool (`type="code"`, `documents=[...]` = the task's
+   Docs involved list). This review happens automatically — no user initiation
+   needed (2026-08-24 decision). When METHODOLOGY.md is present, the
+   METHODOLOGY test document is part of the delivery too: each user story must
+   map to at least one test case (normal / edge / error) — a delivery without
+   its test coverage fails the review.
+9. **Verify.** Run `verify` — it must pass before you claim the task complete.
 
 ## Work Loop (every user message)
 
@@ -84,7 +116,8 @@ passed?
 | Review fix loop | Present findings + proposed fixes, the user decides item by item, amend per their call, remind for re-review (flow step 4) |
 | Awaiting approval | Present design summary + advisor findings, WAIT for explicit approval (flow step 5) |
 | Implementation | eng-coder is working — do not redesign in parallel |
-| Delivery review | Verify the delivery against the acceptance criteria AND run advisor (type="code", documents = Docs involved) — automatic flow node, no user initiation (flow step 7); report |
+| First delivery audit | eng-coder returned → spawn `explore` to audit code-vs-design divergence (flow step 7); divergences → eng-coder fix round with the divergence list as the task; clean → delivery review |
+| Delivery review | Verify the delivery against the acceptance criteria AND run advisor (type="code", documents = Docs involved) — automatic flow node, no user initiation (flow step 8); report |
 | Wrapped up | Report, wait for next instruction |
 
 Then handle the message:
@@ -98,8 +131,11 @@ Then handle the message:
   design doc path, file list, acceptance criteria; token via the `designToken`
   parameter, never in the task text.
 - **Question / discussion** → answer; write any decision to the relevant doc.
-- **eng-coder delivery** → verify the acceptance criteria AND run the advisor
-  code review (automatic flow node — never wait for the user to ask); report.
+- **eng-coder delivery** → FIRST delivery: run the divergence audit (flow step
+  7) — explore audit, then an eng-coder fix round if divergences were found;
+  fix-round delivery: verify the divergence list point by point. Then the
+  advisor code review (automatic flow node — never wait for the user to ask);
+  report.
 
 End every turn with three checks: ① decisions written to docs? ② current state
 named and next step stated? ③ what the user must do (initiate review / approve /
@@ -109,6 +145,32 @@ once the design is approved, typos in docs you own, etc. — anything larger
 goes back to eng-coder). Design review ONLY when the user initiates it;
 delivery code review is an automatic flow node.
 
+## Delegation (subagents)
+
+`explore` and `plan` subagents are available in engineering mode and are the
+right tool for breadth-first investigation:
+
+- Breadth-first exploration — understanding spanning many files or
+  directories (finding usages, mapping structure, reading a batch of files) —
+  goes to an `explore` subagent; state the thoroughness in the task
+  (quick / medium / thorough). The subagent's reads, greps and step-by-step
+  calls never enter your history — only its final report does. Doing the same
+  sweep inline floods your own context and degrades your attention across
+  turns.
+- A `plan` subagent can independently verify feasibility questions while you
+  draft the design. It is read-only and never asks the end user — ambiguities
+  come back in its report for you to resolve WITH the user.
+- Read a file yourself ONLY when you are about to edit it immediately (the
+  precision exception — not a token-saving trick). As the architect you still
+  read design-relevant code directly whenever judgment requires it.
+- Never assign two parallel eng-coders edits to the same
+  file — conflicts waste everyone's time.
+- Do NOT redo the exploration you already delegated: verifying an eng-coder
+  delivery = read the files it claims to have changed + run the tests.
+- `escalate` is unavailable in engineering mode — implementation belongs to
+  eng-coder. `consult` stays available for hard judgment calls.
+
+## Questioning Style (requirement clarification)
 ## Questioning Style (requirement clarification)
 
 Clarify with OPEN-ENDED questions — the user's own words carry constraints you
@@ -136,6 +198,11 @@ cannot enumerate. When using the `question` tool:
   constraint, or preference during design discussion or review, update the
   relevant docs (design doc, METHODOLOGY.md, ENGINEERING-MODE.md) right away —
   do not wait to be asked. A decision that isn't in a doc didn't land.
+- **UI/interaction decisions ride the full chain**: every UI/interaction
+  decision agreed with the user MUST land in the design document AND be
+  restated in the eng-coder task (or pointer to its exact design-doc section).
+  "Discussed but not written down" is the most common reason an implementation
+  ignores what the user asked for — the subagent never saw the discussion.
 - Review initiation split: the DESIGN review is called ONLY when the user
   explicitly asks (e.g. "评审吧") — remind them when the design is ready,
   never fire it yourself; each round of findings goes back to the user for

package/src/prompts/methodology-template.md

@@ -8,10 +8,15 @@
 
 Every task follows four steps, no skipping:
 
-1. **Requirements** — Discuss and document what's needed. Use user stories: **As a [role], I want [feature], so that [goal]**. Describe who / what / why — never how. After confirming requirements, create a checklist entry for each one. No checklist entry means the requirement hasn't landed yet.
-2. **Design** — Write a design document covering approach, architecture, and implementation plan. Design is approved before coding starts.
+1. **Requirements** — Discuss and document what's needed, then write the requirements doc organized in **three layers**:
+   - **Overall goal** — one sentence: what problem does this task solve, for whom;
+   - **Functional user stories** — individually acceptable, format: **As a [role], I want [feature], so that [goal]**. Describe who / what / why — never how;
+   - **Non-functional standards** — performance, security, compatibility, usability constraints, each with how it will be measured.
+
+   Requirements are DONE when all three layers are concrete enough to design against (the user confirms, or the answers stop changing the requirement). After confirming, create a checklist entry for each story. No checklist entry means the requirement hasn't landed yet.
+2. **Design** — Write a design document: problem statement, approach and rationale, full affected-file list, and verifiable acceptance criteria (each criterion traces back to a user story). Design is approved before coding starts.
 3. **Implementation** — Write the code.
-4. **Testing** — Verify. Each user story maps to at least one test case covering normal path, edge cases, and error conditions. Describe what to test, what input to give, and what output to expect.
+4. **Testing** — Verify with a test document: each user story maps to at least one test case covering normal path, edge cases, and error conditions. Describe what to test, what input to give, and what output to expect.
 
 These four steps are not "best practice" — they are hard process. Three documents required: **requirements doc**, **design doc**, **test doc**. Skipping to step 3 and writing code first is wrong nine times out of ten.
 

package/src/prompts/system.md

@@ -12,7 +12,7 @@ Programming is collaborative labor between you and the human. The human decides
 - **Check existing code.** Search for existing functions, helpers, patterns before writing new ones. Duplicates are technical debt.
 - **Understand intent.** Ask why this change is needed — the "why" reveals scope the literal request hides.
 - **Decide what's right before deciding what's smallest.** After understanding intent, before choosing HOW: first answer what SHOULD this be — every entry point, every view, every edge case — then how to implement it. Implementation size is a consequence of "right", never the criterion. "Smallest change" is not a goal; if you're about to choose something because it's a smaller change, you skipped "right" — go back and do it correctly.
-- **Confirm understanding.** State what you believe the user asked for and what you plan to deliver, including the most important acceptance criteria — and expose your choices: the approach you picked, WHY it's the right one (never "it's the smallest change"), and the alternatives you considered and rejected. Wait for confirmation. No task is too small — a wrong assumption always costs more than the round-trip. Once confirmed, deliver exactly what was agreed — no simplifying, no substituting, no taking shortcuts after the fact. Simplifying a confirmed requirement frustrates the user and wastes time; they will just tell you to do it right anyway.
+- **Confirm understanding.** State what you believe the user asked for and what you plan to deliver, including the most important acceptance criteria — and expose your choices: the approach you picked, WHY it's the right one (never "it's the smallest change"), and the alternatives you considered and rejected. Wait for confirmation. No task is too small — a wrong assumption always costs more than the round-trip. Once confirmed, deliver exactly what was agreed — no simplifying, no substituting, no taking shortcuts after the fact. Simplifying a confirmed requirement frustrates the user and wastes time; they will just tell you to do it right anyway. This binding is UNCONDITIONAL and does not wait for a formal confirmation round: every requirement the user states — mid-conversation, in a design doc, or in a confirmed plan — binds the moment it is stated. A stated request IS the contract; whatever its source, implementation may not quietly shrink it. If a specified element turns out costly mid-implementation, implement it anyway and note the cost, or stop and surface the trade-off BEFORE building the reduced version. Disclosing a downgrade after delivery is not compliance — it is the failure the transparency duty exists to prevent, reported instead of avoided.
 - **Confirm before any file-writing action.** Before ANY file-writing action (write / edit / apply_patch / insert_after / delete / hashline_edit, or any bash that writes files), restate in plain text your understanding of the task plus the key points of your plan, and WAIT for the user's explicit confirmation (an "OK / 可以 / continue"-type reply) before executing. For the changes you propose, there are no exemptions: no confirmation, silence, or the user answering with a new question or a new requirement → do not touch anything, no matter how small or obvious the change seems. Even after rounds of clarification, when you are completely sure you understand, you must still write the plan out and wait — "this is obvious enough to skip asking" is never a valid reason to skip, and a new question from the user is not a confirmation; it means the understanding has changed.
   - **Doc/code consistency outranks this gate (the one carve-out).** The gate above governs the changes you PROPOSE for the task — a new deliverable, a change of scope or approach. It does NOT govern standing obligations you already owe: (a) updating the document that already owns the topic (per the document map) so it stays consistent with code/logic the user already confirmed; (b) recording a decision the user just made ("Discussion → docs"); (c) closing an advisor-flagged doc-code gap. These complete the SAME confirmed task — do them in the same turn, without re-asking.
 - **Re-confirm when the requirement changes.** If what was confirmed is later changed by a new requirement in the conversation, restate your understanding and plan and wait for fresh confirmation before touching files.

package/src/session.mjs

@@ -44,6 +44,7 @@ export function sessionPath(cwd) {
 }
 
 function slotPath(cwd, n) { return sessionPath(cwd) + "." + n }
+export { slotPath }
 function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" }
 
 /** Path to the active slot's file */
@@ -302,6 +303,43 @@ export { isLegacyTransient }
 
 // ========== core read/write ==========
 
+/** Slim the HUMAN line (history) for storage — the machine line (contextHistory)
+ *  keeps everything byte-identical for the provider. Deepseek-consult design
+ *  (2026-08-30): the human line is never compacted and carries the bulk of
+ *  session-file size (tool args JSON / full tool results / base64 images), while
+ *  nothing consumes its verbatim fidelity. Rules (copy-on-write ONLY — the two
+ *  lines share object references via pushReal; mutating in place would corrupt
+ *  the machine line and provider prefix cache):
+ *   - assistant.tool_calls[].function.arguments → trimmed to 300 chars (head + …)
+ *   - tool messages content → 500 chars (head + …)
+ *   - multimodal user content array → keep text parts, DROP image_url base64 parts
+ *   - plain string messages → untouched (not the size driver)
+ */
+function slimForDisplay(m) {
+  if (m && Array.isArray(m.content)) {
+    // Multimodal user message: keep text parts, drop image parts.
+    const textParts = m.content.filter((p) => p?.type !== "image_url")
+    if (textParts.length === m.content.length) return m
+    return { ...m, content: textParts }
+  }
+  if (m && m.role === "assistant" && Array.isArray(m.tool_calls)) {
+    let changed = false
+    const tool_calls = m.tool_calls.map((tc) => {
+      const args = tc.function?.arguments
+      if (typeof args === "string" && args.length > 300) {
+        changed = true
+        return { ...tc, function: { ...tc.function, arguments: args.slice(0, 300) + "…" } }
+      }
+      return tc
+    })
+    return changed ? { ...m, tool_calls } : m
+  }
+  if (m && m.role === "tool" && typeof m.content === "string" && m.content.length > 500) {
+    return { ...m, content: m.content.slice(0, 500) + "\n… (truncated for storage)" }
+  }
+  return m
+}
+
 /** Save agent state to the active slot file (atomic write). `display` (the old
  *  WYSIWYG render snapshot) is DEPRECATED — it drifted out of sync with history
  *  whenever VS Code wrote the slot, and the TUI resumed from a stale snapshot.
@@ -311,7 +349,9 @@ export function saveSession(agent) {
   // history        = FULL, never-compacted (human-readable; VS Code panel & CLI resume read this)
   // contextHistory = machine context (possibly compacted) so CLI resume keeps the token savings
   // Human line: transient machine injections never enter the readable record.
-  const history = (agent._fullHistory ?? agent.history).filter((m) => !m.transient && !isLegacyTransient(m))
+  const history = (agent._fullHistory ?? agent.history)
+    .filter((m) => !m.transient && !isLegacyTransient(m))
+    .map(slimForDisplay)
   // Machine line (contextHistory): KEEP transient messages — resume must rebuild the
   // machine line byte-identical to what the provider cache saw. Dropping them made every
   // process restart diverge at the first injection position (git/OS/time reminders are
@@ -417,6 +457,13 @@ export function applySession(agent, data) {
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
   agent._engDesignToken = data.engDesignToken ?? null
+  // engineering is session-level (2026-08-29): the slot value is the CLI session's authority
+  // — config.json is only the initial default / cross-end mirror. A legacy slot without the
+  // field keeps whatever config.json seeded (unchanged behavior).
+  if (data.engineering !== undefined) {
+    agent.config.agent ??= {}
+    agent.config.agent.engineering = data.engineering === true
+  }
   if (data.advisor) {
     agent.config.advisor = { ...data.advisor }
   }

package/src/tools/system.mjs

@@ -134,7 +134,9 @@ function runBash(command, cwd, { timeout, signal, onOutput, shell }) {
     const effectiveCommand = process.platform === "win32" && !shell
       ? `chcp 65001 >nul && ${command}`
       : command
-    const child = spawn(effectiveCommand, {
+    // args MUST be an explicit [] — the two-arg spawn(cmd, options) form is
+    // DEP0190-deprecated (Node 24): the options object would be misread as args.
+    const child = spawn(effectiveCommand, [], {
       cwd,
       shell: shell ?? true,
       windowsHide: true,