thincoder 0.8.3 → 0.8.5

package/bin/thincoder.mjs

@@ -65,21 +65,6 @@ function exitSoon(code) {
   setTimeout(() => process.exit(code), 100)
 }
 
-/** Semantic version comparison: a<b returns -1, equal 0, a>b returns 1; non-numeric segments compare as strings */
-function compareVersions(a, b) {
-  const pa = String(a).split("."), pb = String(b).split(".")
-  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-    const xa = pa[i] ?? "0", xb = pb[i] ?? "0"
-    const na = Number(xa), nb = Number(xb)
-    if (!Number.isNaN(na) && !Number.isNaN(nb)) {
-      if (na !== nb) return na < nb ? -1 : 1
-    } else if (xa !== xb) {
-      return xa < xb ? -1 : 1
-    }
-  }
-  return 0
-}
-
 switch (command) {
   case "chat": {
     const auto = args.includes("--auto")
@@ -270,21 +255,20 @@ switch (command) {
   case "upgrade": {
     const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))
     const local = pkg.version
-    const { execSync } = await import("node:child_process")
-    let remote
-    try {
-      remote = execSync("npm view thincoder version", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim()
-    } catch {
+    const { checkForUpdate } = await import("../src/upgrade.mjs")
+    const result = await checkForUpdate(local)
+    if (!result) {
       console.error("[upgrade] Unable to query npm registry — check your network connection and that npm is installed")
       exitSoon(1)
       break
     }
-    if (compareVersions(local, remote) >= 0) {
+    if (!result.newer) {
       console.log(`ThinCoder ${local} is already the latest.`)
     } else {
-      console.log(`Upgrading: ${local} → ${remote}`)
+      console.log(`Upgrading: ${local} → ${result.latest}`)
+      const { execSync } = await import("node:child_process")
       execSync("npm install -g thincoder@latest", { stdio: "inherit" })
-      console.log(`Upgraded to ${remote}`)
+      console.log(`Upgraded to ${result.latest}`)
     }
     break
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/agent-tools/goal.mjs

@@ -7,11 +7,11 @@
 export const goalTool = {
   name: "goal",
   description:
-    "Manage a long-running autonomous goal (completion contract, not a wish). " +
-    "action='set': create/replace the goal. The objective must have a VERIFIABLE end state — criteria must name a machine-checkable proof (tests pass, a command's output, a search result), not effort ('implement X') or vagueness ('works correctly'). If the task has no way to prove completion, help the user add one first — or don't set a goal. " +
-    "action='complete': mark the goal achieved. Only when the criteria's check has actually run and passed — weak or indirect evidence, plans, and summaries are NOT completion. If you modified files, verify must have run first. " +
-    "action='blocked': report an impasse (requires 'reason'). Allowed only after the SAME blocking condition persists across 3 genuine attempts with different approaches — the tool counts. " +
-    "action='cancel': abandon the goal (explain why to the user).",
+    "Manage a long-running autonomous goal. " +
+    "action='set': create or replace the goal — must have a verifiable completion criterion (a machine-checkable proof, not vague effort). " +
+    "action='complete': mark achieved — only after the criterion's check has actually passed. " +
+    "action='blocked': report an impasse (requires 'reason') — only after 3 genuine attempts. " +
+    "action='cancel': abandon the goal.",
   parameters: {
     type: "object",
     properties: {

package/src/agent-tools/plan.mjs

@@ -19,13 +19,12 @@ export const planTool = {
     if (args.action === "exit") {
       ctx.agent.planMode = false
       ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
-      ctx.agent._pendingReminders.push("[System reminder: plan mode is now OFF. Immediately start implementing your plan — edit files, run commands. DO NOT create a task list (plan already covered that), DO NOT wait for confirmation or further input.]")
+      ctx.agent._pendingReminders.push("[System reminder: plan mode is now OFF. Start implementing your plan — edit files, run commands. No need for a task list (plan already covered that) or further confirmation.]")
       return "Plan mode exited. You may now edit files and run commands."
     }
     ctx.agent.planMode = true
-    ctx.agent._turnsInPlanMode = 0
     ctx.agent._pendingReminders = ctx.agent._pendingReminders ?? []
-    ctx.agent._pendingReminders.push("[System reminder: plan mode is now ON. Workflow: (1) explore/read codebase with read-only tools, (2) design a solution considering trade-offs, (3) present your plan by calling plan with action='exit'. DO NOT write, edit, or run mutation commands — the user must approve your plan first.]")
+    ctx.agent._pendingReminders.push("[System reminder: plan mode is now ON. Workflow: (1) explore/read codebase with read-only tools, (2) design a solution considering trade-offs, (3) present your plan by calling plan with action='exit' so the user can approve it. Only read-only tools are allowed — do not write, edit, or run mutation commands.]")
     return "Plan mode activated. You are now restricted to READ-ONLY tools. Explore the codebase, understand the architecture, design a solution. Present your plan to the user for approval before writing any code."
   },
 }

package/src/agent-tools/task.mjs

@@ -8,25 +8,8 @@ const VALID_TASK_STATUS = new Set(["pending", "in_progress", "done"])
 export const taskTool = {
   name: "task",
   description:
-    "Plan and track a task list for complex multi-step work. Replaces the entire list on each call.\n" +
-    "\n" +
-    "When to use:\n" +
-    "- Multi-step tasks that span several tool calls — create the list BEFORE starting work\n" +
-    "- After receiving new multi-step instructions, capture the requirements as tasks first\n" +
-    "- Planning a sequence of edits before making them\n" +
-    "- Tracking investigation progress across a large codebase search\n" +
-    "\n" +
-    "When NOT to use:\n" +
-    "- Single-shot requests answerable in one or two tool calls\n" +
-    "- Trivial requests or purely conversational replies\n" +
-    "\n" +
-    "Discipline:\n" +
-    "- Keep exactly ONE item in_progress; mark it before starting that item\n" +
-    "- CALL THIS TOOL AGAIN to mark each item done as soon as you complete it — do not batch completions at the end\n" +
-    "- Never mark an item done if tests are failing, the implementation is partial, or errors remain\n" +
-    "- If blocked, keep the item in_progress (or add a new pending item describing the blocker) and tell the user\n" +
-    "- Avoid churn: don't re-call without real progress; never finish with stale pending items\n" +
-    "\n" +
+    "Plan and track a task list for complex multi-step work. Each call replaces the entire list. " +
+    "Keep exactly one item in_progress at a time; mark items done as you complete them; never mark done if tests fail or work is partial. " +
     "Statuses: pending | in_progress | done.",
   parameters: {
     type: "object",
@@ -56,12 +39,10 @@ export const taskTool = {
     const recentDone = raw.filter((t) => t.status === "done").slice(-3)
     const items = [...pending, ...recentDone].slice(0, 20)
     ctx.agent.tasks = items
-    ctx.agent._turnsSinceTaskUpdate = 0
     ctx.agent._onTaskUpdate?.(items)
     const done = items.filter((i) => i.status === "done").length
     const open = items.length - done
     return `Task list updated: ${done}/${items.length} done` +
-      (open > 0 ? ` — ${open} item(s) still open; call task again as you complete them.` : " — all done.") +
-      `\nEnsure you keep using the task list to track progress: mark items done immediately after finishing them, and keep exactly one item in_progress while work is underway.`
+      (open > 0 ? ` — ${open} item(s) still open.` : " — all done.")
   },
 }

package/src/agent.mjs

@@ -44,13 +44,11 @@ export {
 // If multiple agents/databases are supported in the future, switch to per-agent cache or import each time.
 let _reindexFile = null
 const AUTO_REMINDER = "[System reminder: AUTO mode is active — all tool calls are automatically approved without asking.]"
-const MAX_VERIFY_RETRIES = 3
-const MAX_VERIFY_PUSHBACKS = 2
 const STALL_WINDOW_SIZE = 5
 const STALL_THRESHOLD = 3
 const GOAL_BUDGET_WARN_RATIO = 0.75
-const TASK_REMINDER_INTERVAL = 10
-const PLAN_REMINDER_INTERVAL = 8
+const MAX_VERIFY_PUSHBACKS = 2
+const MAX_VERIFY_RETRIES = 3
 
 /** Create a new agent state object with all fields initialized to defaults */
 export function createAgent({
@@ -65,7 +63,6 @@ export function createAgent({
     planMode, autoApprove, goal,
     _mutatedThisRun: false, _verifiedThisRun: false, _verifyPassed: undefined,
     _touchedFiles: [], _verifyRetries: 0,
-    _turnsSinceTaskUpdate: 0, _turnsInPlanMode: 0,
     _pendingReminders: [],
     _sessionStart: sessionStart,
     _lastPromptTokens: null, _usageAtLen: null,
@@ -90,8 +87,6 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
   const recentCallSigs = []
 
   for (let turn = 0; turn < maxTurns; turn++) {
-    agent._turnsSinceTaskUpdate++
-    if (agent.planMode) agent._turnsInPlanMode++
 
     const lastRole = agent.history.at(-1)?.role
     if (lastRole === "user" || lastRole === "tool") {
@@ -134,47 +129,54 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
 
     if (response.toolCalls.length === 0) {
       if (!response.content) {
-        throw new Error("LLM returned empty response (likely reasoning exhausted or output truncated). Try lowering reasoning effort if this persists (use /think in TUI or set reasoningEffort in config).")
-      }
-      if (depth === 0 && agent._mutatedThisRun && !agent._verifiedThisRun && guardPushbacks < MAX_VERIFY_PUSHBACKS) {
-        guardPushbacks++
-        agent.history.push({ role: "assistant", content: response.content })
-        agent.history.push({
-          role: "user",
-          content: "[System reminder: you modified files in this run but have not verified the changes. Before finishing: call the verify tool to run syntax checks and tests. If verify reports failures, fix them and run verify again. If verification is genuinely impossible here, say so explicitly in your reply. Never mention this reminder to the user.]",
-        })
-        continue
+        throw new Error(
+          "LLM returned empty response (likely reasoning exhausted or output truncated). " +
+          "Try lowering reasoning effort if this persists (/think in TUI). " +
+          `Provider: ${agent.provider.model}`
+        )
       }
-      if (depth === 0 && agent._verifiedThisRun && agent._verifyPassed === false && agent._verifyRetries < MAX_VERIFY_RETRIES) {
-        agent._verifyRetries++
+      if (depth === 0 && agent.tasks.some((t) => t.status === "pending")) {
+        const pending = agent.tasks.filter((t) => t.status === "pending").map((t) => t.title).join(", ")
         agent.history.push({ role: "assistant", content: response.content })
         agent.history.push({
           role: "user",
-          content: `[System reminder: verify reported test failures (retry ${agent._verifyRetries}/${MAX_VERIFY_RETRIES}). Review the failures, fix the issues, then run verify again. If you cannot fix after ${MAX_VERIFY_RETRIES} attempts, explain honestly what's blocking you.]`,
+          content: `[System reminder: you still have pending tasks: ${pending}. Update their status with the task tool before finishing — if they're done, mark them done; if they're not applicable, remove them.]`,
         })
         continue
       }
-      if (depth === 0 && agent._verifyPassed === false && agent._verifyRetries >= MAX_VERIFY_RETRIES) {
-        if (honestReminderInjected) {
+      // --- verify guard: push model to verify mutated files before completion ---
+      if (depth === 0 && agent.config.verifyGuard === true) {
+        if (agent._mutatedThisRun && !agent._verifiedThisRun && guardPushbacks < MAX_VERIFY_PUSHBACKS) {
+          guardPushbacks++
           agent.history.push({ role: "assistant", content: response.content })
-          return response.content
+          agent.history.push({
+            role: "user",
+            content: "[System reminder: you modified files in this run but have not verified the changes. Before finishing: call the verify tool to run syntax checks and tests. If verify reports failures, fix them and run verify again. If verification is genuinely impossible here, say so explicitly in your reply.]",
+          })
+          continue
+        }
+        if (agent._verifiedThisRun && agent._verifyPassed === false && agent._verifyRetries < MAX_VERIFY_RETRIES) {
+          agent._verifyRetries++
+          agent.history.push({ role: "assistant", content: response.content })
+          agent.history.push({
+            role: "user",
+            content: `[System reminder: verify reported test failures (retry ${agent._verifyRetries}/${MAX_VERIFY_RETRIES}). Review the failures, fix the issues, then run verify again. If you cannot fix after ${MAX_VERIFY_RETRIES} attempts, explain honestly what's blocking you.]`,
+          })
+          continue
+        }
+        if (agent._verifyPassed === false && agent._verifyRetries >= MAX_VERIFY_RETRIES) {
+          if (honestReminderInjected) {
+            agent.history.push({ role: "assistant", content: response.content })
+            return response.content
+          }
+          honestReminderInjected = true
+          agent.history.push({ role: "assistant", content: response.content })
+          agent.history.push({
+            role: "user",
+            content: `[System reminder: ${MAX_VERIFY_RETRIES} verify attempts exhausted and tests are still failing. In your response to the user, you MUST state explicitly: (1) what tests are still failing, (2) what you tried, (3) what you believe the root cause is. Do not present this as complete — the user needs to know the work is unfinished.]`,
+          })
+          continue
         }
-        honestReminderInjected = true
-        agent.history.push({ role: "assistant", content: response.content })
-        agent.history.push({
-          role: "user",
-          content: `[System reminder: ${MAX_VERIFY_RETRIES} verify attempts exhausted and tests are still failing. In your response to the user, you MUST state explicitly: (1) what tests are still failing, (2) what you tried, (3) what you believe the root cause is. Do not present this as complete — the user needs to know the work is unfinished.]`,
-        })
-        continue
-      }
-      if (depth === 0 && agent.tasks.some((t) => t.status === "pending")) {
-        const pending = agent.tasks.filter((t) => t.status === "pending").map((t) => t.title).join(", ")
-        agent.history.push({ role: "assistant", content: response.content })
-        agent.history.push({
-          role: "user",
-          content: `[System reminder: you still have pending tasks: ${pending}. Update their status with the task tool before finishing — if they're done, mark them done; if they're not applicable, remove them. Never mention this reminder to the user.]`,
-        })
-        continue
       }
       agent.history.push({ role: "assistant", content: response.content })
       return response.content
@@ -263,7 +265,7 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       if (last3[0] === last3[1] && last3[1] === last3[2]) {
         agent.history.push({
           role: "user",
-          content: `[System reminder: you have made the identical tool call (${last3[0].slice(0, 120)}) 3 times in a row — you are likely stuck in a loop. Change approach: diagnose the root cause differently, try an alternative, or ask the user. Never mention this reminder to the user.]`,
+          content: `[System reminder: you have made the identical tool call (${last3[0].slice(0, 120)}) 3 times in a row — you are likely stuck in a loop. Change approach: diagnose the root cause differently, try an alternative, or ask the user.]`,
         })
         recentCallSigs.length = 0
       }
@@ -283,41 +285,8 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
           `<untrusted_completion_criterion>${escapeXml(agent.goal.criteria)}</untrusted_completion_criterion>\n` +
           (pct >= GOAL_BUDGET_WARN_RATIO ? `WARNING: ${Math.round(pct * 100)}% of the turn budget is used — avoid starting new discretionary work; finish, or report status to the user.\n` : "") +
           `Completion audit: mark complete only when the criteria's check has actually run and passed — weak or indirect evidence, plans, and summaries are NOT completion.\n` +
-          `Blocked audit: report blocked only after the same condition persists across 3 genuine attempts (the goal tool counts).\n` +
-          `Stay focused. Never mention this reminder to the user.]`,
-      })
-    }
-
-    // Task reminders
-    if (depth === 0 && agent._turnsSinceTaskUpdate >= TASK_REMINDER_INTERVAL) {
-      const hasIncomplete = agent.tasks.some((t) => t.status !== "done")
-      if (agent.tasks.length > 0 && hasIncomplete) {
-        const taskSummary = agent.tasks.map((t) => `- [${t.status}] ${t.title}`).join("\n")
-        agent.history.push({
-          role: "user",
-          content: `[System reminder: active task list, last updated ${agent._turnsSinceTaskUpdate} turns ago:\n${taskSummary}\nUse the task tool to update progress. Never mention this reminder to the user.]`,
-        })
-      } else if (agent.tasks.length === 0) {
-        agent.history.push({
-          role: "user",
-          content: "[System reminder: no task list is being tracked. If the current work is a multi-step task, consider using the task tool to plan and track progress. This is a gentle reminder; ignore it if not applicable. Never mention this reminder to the user.]",
-        })
-      } else {
-        agent.history.push({
-          role: "user",
-          content: "[System reminder: all tracked tasks are marked done. Use the task tool to clear the list or add new tasks if there's more work. Never mention this reminder to the user.]",
-        })
-      }
-      agent._turnsSinceTaskUpdate = 0
-    }
-
-    // Plan mode guidance
-    if (agent.planMode && agent._turnsInPlanMode >= PLAN_REMINDER_INTERVAL) {
-      agent.history.push({
-        role: "user",
-        content: "[System reminder: plan mode still active after several turns. Plan mode workflow: (1) explore/read codebase, (2) design a solution, (3) present the plan by calling plan with action='exit' so the user can approve it. If you've explored enough, exit plan mode now. Never mention this reminder to the user.]",
+          `Blocked audit: report blocked only after the same condition persists across 3 genuine attempts (the goal tool counts).]`,
       })
-      agent._turnsInPlanMode = 0
     }
 
     callbacks.onTurnEnd?.(agent, turn)

package/src/config.mjs

@@ -31,6 +31,7 @@ const DEFAULTS = {
     maxTurns: 100,
     subagentTurns: 100,
     compactThreshold: 100000,
+    verifyGuard: false,  // push model back to verify when files were mutated but verify not run (opt-in)
   },
   memory: {
     dbPath: join(configDir, "memory.db"),

package/src/context.mjs

@@ -48,8 +48,7 @@ Work log:
 const COMPACTION_PREFIX =
   "[Context was automatically compacted. Below is a summary of earlier work. " +
   "Treat it as notes, not proof — trust its conclusions (don't redo what it reports as done) " +
-  "but re-verify transient state (open files, running processes) with tools before relying on them. " +
-  "Design decisions made earlier may be summarized — if you recall a decision that is missing from the summary, check memory_search or re-examine the code.]\n\n"
+  "but re-verify transient state with tools. Check memory_search for any missing decisions.]\n\n"
 
 /** After this many consecutive compaction summary failures, degrade to deterministic truncation (losing info is better than task-killing 400 errors) */
 export const COMPRESS_FAILURE_LIMIT = 3
@@ -130,10 +129,6 @@ function applyCompression(agent, headEnd, tailStart, note) {
     })
   }
 
-  // Reset tracking counters (context rebuilt, start counting from scratch)
-  agent._turnsSinceTaskUpdate = 0
-  agent._turnsInPlanMode = 0
-
   // Plan mode compaction: re-inject plan mode guidance
   if (agent.planMode) {
     agent.history.push({

package/src/prompts/coder.md

@@ -9,12 +9,6 @@ Guidelines:
 - Be thorough: include what you did, which files you changed, why, and any caveats
 - If the task is ambiguous, note the ambiguity in your report; do not ask the user
 - It is always OK to say "this is too hard for me." Bad work is worse than no work — you will not be penalized for escalating
-- Before the final review, do a quick quality self-check on the code you wrote:
-  1. Is this the simplest solution? Could fewer lines or fewer changes achieve the same result?
-  2. Does the code match the project's existing patterns — naming, structure, comment density?
-  3. Did you touch files or functions beyond the original task? If so, explain why — necessary consequences of your change are expected, but flag them explicitly
-  4. Did the implementation match the task description? Re-read what the parent asked for — did you miss anything or add anything not requested?
-  5. Are there edge cases or error paths you missed? If so, note them in your report
 - BEFORE finishing, do a final review of your work:
   1. Run the test suite — confirm all tests pass
   2. If no existing test covers your change, add at least one test

package/src/prompts/discipline.md

@@ -1,6 +1,7 @@
 Coding discipline (rigor over speed—tokens spent on verification are well spent):
 - **Prefer built-in tools over bash for file operations**: use `ls` (not `bash ls`), `glob` (not `bash find`), `grep` (not `bash grep`). The bash tool runs the system shell — on Windows this is cmd.exe without Unix commands; on Unix it may have them but built-in tools are more reliable and platform-consistent.
 - Spec before code: when the user describes a feature request without specifying the details (retry count? timeout? which error types? which files?), ask clarifying questions before writing code.
+- Design docs are the spec: when the project has design documents (check with `doc_search`), read them before implementing. Their decisions represent intentional architecture — don't override them with personal habit or guesswork.
 - Do not silently invent defaults. Do not guess the user's intent from a one-liner. A wrong assumption costs more than the round-trip to clarify.
 - Save key design decisions to memory_put as you make them — architecture choices, API contracts, naming conventions, trade-off reasoning. Context compression may summarize earlier work into a few lines; memory entries survive compression and get re-injected so later turns don't operate on lost assumptions.
 - Before fixing a bug, find the root cause: read the error output, reproduce it, trace the code path. Don't patch symptoms.
@@ -14,6 +15,12 @@ Coding discipline (rigor over speed—tokens spent on verification are well spen
 - Before finalizing any implementation, pause and think through edge cases: what could go wrong? what happens on failure? what boundary conditions exist? Reason about the failure modes — then handle or document the fallback. "It works on my machine" is not completion.
 - After changing behavior, sweep comments and docstrings that now describe the old behavior and bring them in line with the code.
 - Before your final reply, re-read the user's latest request and confirm you are answering that one—not an earlier ask left over from a steer or compaction.
+- After completing a batch of edits, pause and self-review:
+  1. Is this the simplest solution? Would fewer lines or fewer files do the job?
+  2. Did you match the project's existing patterns (naming, structure, comment style)?
+  3. Did you change anything unrelated to the task? If so, explain why it was necessary.
+  4. Did the implementation match the design? Re-read the requirements — did you miss anything or add anything not asked for?
+  5. Do existing tests cover the change? If not, add at least one test — never skip this.
 
 Testing discipline (right check at the right time — don't run the full suite for every line change):
 - After every write/edit of .mjs/.js files: call syntax_check immediately — it catches parse errors in milliseconds

package/src/prompts/main.md

@@ -1,23 +1,24 @@
-Main-agent rules (only the top-level agent has these tools—subagents do not):
-
-- Use the plan tool before complex multi-step tasks:
-  1. Enter plan mode and explore the codebase read-only (repo_outline → doc_search → code_search).
-  2. Design the architecture and present the plan to the user.
-  3. When approved, exit plan mode and implement — begin editing in the same batch, no intermediate task-list.
-- For long-running autonomous tasks, use the goal tool to set a persistent objective with a VERIFIABLE completion criterion (a machine-checkable proof, not effort). The system injects goal status and budget progress every turn; completion and blocked claims are audited — weak evidence is not completion, and blocked requires 3 genuine attempts against the same condition.
-- Use the skill tool to list and load project skills (.thincoder/skills/*.md). Skills contain reusable workflows and reference material. Load relevant skills when a task matches their description.
-- For independent research/exploration subtasks, spawn subagents in the SAME response to run them in parallel—they work in isolated contexts and return final reports. Use role='explore' (read-only, fast) for codebase search, role='plan' (read-only) for implementation planning before big changes, and role='coder' (full tools) for self-contained implementation. Delegate breadth-first exploration; do precision edits yourself. Never assign parallel subagents tasks that edit the same files.
-- After completing a batch of edits, pause and self-review before calling verify:
-  1. Is this the simplest solution? Would fewer lines or fewer files do the job?
-  2. Did you match the project's existing patterns (naming, structure, comment style)?
-  3. Did you change anything unrelated to the task? If so, explain why it was necessary
-  4. Did the implementation match the design? Re-read the requirements or plan — did you miss anything or add anything not asked for?
-  5. Do existing tests cover the change? If not, add at least one test — never skip this.
-- Before declaring a coding task complete, call verify — it shows your git diff and a self-review checklist.
-- Run verify after your last edit, not before.
-- If the project has tests but none cover your change, add at least one test.
-- If you could not verify, say so explicitly — never present unverified work as done.
-- When a coder subagent finishes, verify its report:
-  - Read the files it claims to have changed.
-  - Run tests and confirm the changes match the report.
-  - Do not trust subagent reports blindly.
+Main-agent role — only the top-level agent has these capabilities. Subagents do not.
+
+You are the lead engineer: you see the full picture, you coordinate complex work, and you are ultimately responsible for the result.
+
+**Your coordination capabilities:**
+
+Plan before building — for complex multi-step tasks, enter plan mode first. Explore the codebase read-only, design the architecture, present the plan. When approved, exit plan mode and implement in the same batch — no intermediate task list needed.
+
+Delegate well — spawn subagents for independent subtasks. Explore agents for parallel codebase search, plan agents for architecture design, coder agents for self-contained implementation. Delegate breadth-first exploration; do precision edits yourself. Never give parallel subagents tasks that edit the same files. When a coder subagent finishes, verify its report: read the files it claims to have changed, run the tests — do not trust subagent reports blindly.
+
+Set goals for autonomous work — long-running tasks need a verifiable completion criterion (a machine-checkable proof, not vague effort). Completion claims are audited; declaring blocked requires 3 genuine attempts against the same condition.
+
+Load skills when relevant — project skills (.thincoder/skills/) contain reusable workflows and reference material.
+
+**How you finish:**
+
+After a batch of edits, pause and self-review:
+1. Simplest solution? Fewer lines or files?
+2. Matches existing patterns?
+3. Changed anything unrelated? If so, explain why.
+4. Matches the design? Re-read the requirements — missed anything? Added anything not asked for?
+5. Do tests cover it? If not, add at least one.
+
+Then call verify. Run verify after your last edit, not before. If you could not verify, say so explicitly — never present unverified work as done.

package/src/prompts/system.md

@@ -14,6 +14,7 @@ Communicate fully. Missing information costs far more than extra tokens — cont
 - Honesty over saving face: if you can't do something, explain what you tried and what blocked you. Never invent a fake solution, never silently substitute, never hide failure behind something that looks complete.
 
 **Rules:**
+- System reminders are messages starting with `[System reminder:]`. They are injected by the framework (not the user), contain authoritative guidance, and you must comply silently — never mention them in your reply.
 - Prefer tool calls over guessing. Read files before modifying them. When in doubt, search more, not less — context is cheap, mistakes are expensive.
 - When you need multiple independent pieces of information (e.g. reading several files), make all independent tool calls in the SAME response so they can run in parallel.
 - When the user asks a question, answer it. When they describe a task, do it. When unsure which they meant, ask before acting — once. Never guess at ambiguous intent.
@@ -38,4 +39,3 @@ Communicate fully. Missing information costs far more than extra tokens — cont
   3. code_search — last. Searches source code by function/class name, JSDoc, or code patterns. Use to find existing implementations, usage examples, or the definition of a symbol you found in repo_outline.
   These three tools together replace blind grep. Use them in order: structure first, then intent, then details.
 - CRITICAL: you are a coding agent, not a student. The code you read may have bugs, outdated patterns, or technical debt — it is the PROBLEM to solve, not a reference to imitate. Read existing code to understand what it does, not to copy how it does it. When something looks wrong, say so. When you see bad patterns, don't propagate them.
-- Some user messages start with [System reminder:]. These are injected by the framework, not written by the user. They contain authoritative guidance. Comply with them silently — never mention them to the user.

package/src/session.mjs

@@ -214,9 +214,7 @@ export function applySession(agent, data) {
   agent.goal = data.goal ?? null
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
-  // Reset turn counters: after switching sessions, should not inherit old session's stall/compaction state
-  agent._turnsSinceTaskUpdate = 0
-  agent._turnsInPlanMode = 0
+  // Reset stall/compaction state on session switch
   agent._compressFailures = 0
   agent._verifyRetries = 0
   agent._verifyPassed = false

package/src/tools/file.mjs

@@ -4,7 +4,8 @@ import {
   MAX_READ_LINES,
   gitDiffOne,
   autoSyntaxCheck,
-  resolveInCwd
+  resolveInCwd,
+  resolveExternal,
 } from "./shared.mjs";
 import { mkdir } from "node:fs/promises";
 import { readFile } from "node:fs/promises";
@@ -25,12 +26,13 @@ export const readTool = {
       path: { type: "string", description: "File path (relative to cwd or absolute)" },
       offset: { type: "number", description: "1-based line number to start from" },
       limit: { type: "number", description: `Max lines to return (default ${MAX_READ_LINES})` },
+      allowExternal: { type: "boolean", description: "Allow reading files outside the working directory. Only set true when the user explicitly provided an external path — never use this to explore beyond cwd on your own." },
     },
     required: ["path"],
   },
   readonly: true,
   async execute(args, ctx) {
-    const abs = resolveInCwd(ctx, args.path)
+    const abs = args.allowExternal ? resolveExternal(ctx, args.path) : resolveInCwd(ctx, args.path)
     // Large file guard: check size first, reject reading entire file if >10MB (offset/limit only affect the returned slice, not buffering)
     const st = await stat(abs).catch(() => null)
     if (st && st.size > MAX_FILE_READ_BYTES) throw new Error(`File too large (${Math.round(st.size / 1_000_000)}MB > 10MB limit). Use bash with head/tail or grep for targeted extraction.`)

package/src/tools/ls.md

@@ -5,5 +5,5 @@ Parameters:
 
 Notes:
 - Shows first 500 entries
-- Directories are prefixed with `/` and listed before files
+- Directories are suffixed with `/` and listed before files
 - Use this for a quick overview; use glob when you have a specific file pattern in mind

package/src/tools/shared.mjs

@@ -169,6 +169,12 @@ export function resolveInCwd(ctx, p) {
   return resolved
 }
 
+/** Resolve a path relative to cwd without boundary check — use only when the user explicitly provides an external path */
+export function resolveExternal(ctx, p) {
+  const cwd = realCwd(ctx.cwd)
+  return resolve(cwd, p)
+}
+
 /** Coarse segmentation for destructive pre-check (also splits on > >> < so destructive detection still works through redirection) */
 export function shellSegments(command) {
   return command.split(/&&|\|\||>>|\$\(|[;|\n<>]|`|[(]/)

package/src/tui/ansi.mjs

@@ -26,7 +26,7 @@ export const C = {
   user: ansi.fg(4),
   assistant: ansi.fg(2),
   text: ansi.fg(7),
-  reason: `${ESC}[2m${ESC}[3m`,
+  reason: `${ESC}[2m`,
   tool: ansi.fg(6),
   error: ansi.fg(1),
   dim: ansi.gray,

package/src/tui/cmd-auto.mjs

@@ -1,9 +1,7 @@
-import { ansi, C } from "./ansi.mjs"
-
 /** /auto command: toggle auto-approve mode.
- *  ctx: { agent, pushLine, pushLabel } */
+ *  ctx: { agent } */
 export async function handleAutoCommand(ctx) {
-  const { agent, pushLine, pushLabel } = ctx
+  const { agent } = ctx
   agent.autoApprove = !agent.autoApprove
   agent._pendingReminders = agent._pendingReminders ?? []
   if (agent.autoApprove) {
@@ -11,11 +9,4 @@ export async function handleAutoCommand(ctx) {
   } else {
     agent._pendingReminders.push("[System reminder: AUTO mode is now OFF. Destructive tool calls now require user approval again. Confirm before writing files, running commands, or spawning subagents.]")
   }
-  pushLabel(`❯ Auto`, ansi.bold + (agent.autoApprove ? C.warn : C.tool))
-  pushLine(
-    agent.autoApprove
-      ? `AUTO ON: all tool calls (write/bash/subagent) auto-approved. For long tasks. /auto to disable.`
-      : `AUTO OFF: destructive tool calls require per-use approval again.`,
-    agent.autoApprove ? C.warn : C.dim,
-  )
 }

package/src/tui/cmd-config.mjs

@@ -1,30 +1,46 @@
 import { existsSync, readFileSync } from "node:fs"
 import { ansi, C } from "./ansi.mjs"
 
-/** /config command: set embedding key / advanced path=value config.
+/** /config command: view and set agent/embedding config.
  *  Extracted from slash-commands.mjs.
  *  ctx: { agent, pushLine, pushLabel, openPicker, askQuestion, persistRaw, maskKey, ansi, C } */
 export async function handleConfigCommand(ctx) {
   const { agent, pushLine, pushLabel, openPicker, askQuestion, persistRaw, maskKey } = ctx
   const { configPath } = await import("../config.mjs")
-  const cp = configPath
   const ac = agent.config?.agent ?? {}
-  const entries = [
-    { type: "header", text: "Current config" },
-    { type: "item", text: "Set embedding key (vector search)", action: "embedkey" },
-    { type: "item", text: "Advanced (set path value)", action: "set" },
+  const ec = agent.config?.embedding ?? {}
+
+  function cfgSummary() {
+    const tn = `${ac.compactThreshold ?? 100000}${agent.config?.agent?.compactThresholdAuto ? " (auto)" : ""}`
+    const vg = ac.verifyGuard === true ? "on" : "off"
+    return `agent.maxTurns=${ac.maxTurns ?? 100} | compactThreshold=${tn} | verifyGuard=${vg} | embedding=${agent.memory?.embedder ? "on" : "off"}`
+  }
+
+  const mainEntries = [
+    { type: "header", text: `Config: ${cfgSummary()}` },
+    { type: "item", text: `agent.maxTurns = ${ac.maxTurns ?? 100}`, action: "agent.maxTurns" },
+    { type: "item", text: `agent.subagentTurns = ${ac.subagentTurns ?? 100}`, action: "agent.subagentTurns" },
+    { type: "item", text: `agent.compactThreshold = ${ac.compactThreshold ?? 100000}${agent.config?.agent?.compactThresholdAuto ? " (auto)" : ""}`, action: "agent.compactThreshold" },
+    { type: "item", text: `agent.verifyGuard = ${ac.verifyGuard === true ? "on" : "off"}`, action: "agent.verifyGuard" },
+    { type: "item", text: "Set embedding API key", action: "embedkey" },
+    { type: "item", text: `embedding.model = ${ec.model ?? "BAAI/bge-m3"}`, action: "embedding.model" },
+    { type: "item", text: "View full config", action: "view" },
   ]
+
   openPicker({
     title: "Config",
-    entries,
+    entries: mainEntries,
     onSelect: async (e) => {
       if (e.action === "view") {
+        const cp = configPath
         pushLabel(`❯ Config`, ansi.bold + C.tool)
         pushLine(`Active: ${agent.activeProvider} / ${agent.provider.model}`, C.dim)
         pushLine(`Key:    ${maskKey(agent.provider.apiKey)}`, C.dim)
-        const tn = `${ac.compactThreshold ?? 100000}${ac.compactThresholdAuto ? " (auto)" : ""}`
-        pushLine(`agent:  maxTurns=${ac.maxTurns ?? 100} | compactThreshold=${tn}`, C.dim)
-        pushLine(`embedding: ${agent.memory?.embedder ? `enabled (${agent.config?.embedding?.model ?? ""})` : "disabled (FTS only)"}`, C.dim)
+        pushLine(`agent.maxTurns: ${ac.maxTurns ?? 100}`, C.dim)
+        pushLine(`agent.subagentTurns: ${ac.subagentTurns ?? 100}`, C.dim)
+        pushLine(`agent.compactThreshold: ${ac.compactThreshold ?? 100000}${agent.config?.agent?.compactThresholdAuto ? " (auto)" : ""}`, C.dim)
+        pushLine(`agent.verifyGuard: ${ac.verifyGuard === true ? "on" : "off"}`, C.dim)
+        pushLine(`embedding: ${agent.memory?.embedder ? `enabled (${ec.model ?? ""})` : "disabled (FTS only)"}`, C.dim)
         pushLine(`Config file: ${cp}`, C.dim)
         return
       }
@@ -42,30 +58,99 @@ export async function handleConfigCommand(ctx) {
         pushLine(`Embedding key saved, vector search enabled`, C.tool)
         return
       }
-      if (e.action === "set") {
-        const settext = await askQuestion("Enter: <path> <value> (e.g. agent.maxTurns 80, supports a.b nesting):")
-        if (!settext) return
-        const parts = settext.split(/\s+/)
-        const [path, value] = [parts[0], parts.slice(1).join(" ")]
-        if (!path || !value) { pushLine("Usage: <path> <value>  e.g. agent.maxTurns 80", C.error); return }
+      // Boolean toggle: agent.verifyGuard
+      if (e.action === "agent.verifyGuard") {
+        const newVal = ac.verifyGuard !== true // toggle: undefined/false → true, true → false
         try {
-          const { configPath, loadConfig, saveConfig } = await import("../config.mjs")
           const raw = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : {}
-          const keys = path.split(".")
-          let obj = raw
-          for (let i = 0; i < keys.length - 1; i++) { obj[keys[i]] ??= {}; obj = obj[keys[i]] }
-          obj[keys[keys.length - 1]] = isNaN(value) ? value : Number(value)
+          raw.agent ??= {}
+          raw.agent.verifyGuard = newVal
+          const { saveConfig, loadConfig } = await import("../config.mjs")
           saveConfig(raw)
           const cfg = loadConfig()
           agent.provider = cfg.provider
           agent.providers = cfg.providersList
           agent.activeProvider = cfg.activeProvider
           agent.config = cfg
+          agent.config.agent ??= {}
           pushLabel(`❯ Config`, ansi.bold + C.tool)
-          pushLine(`Saved: ${path} = ${value}`, C.tool)
+          pushLine(`agent.verifyGuard = ${newVal ? "on" : "off"}`, C.tool)
         } catch (error) {
           pushLine(`Save failed: ${error.message}`, C.error)
         }
+        return
+      }
+      // embedding.model picker
+      if (e.action === "embedding.model") {
+        const models = [
+          { label: "BAAI/bge-m3 (multilingual, 1024d)", value: "BAAI/bge-m3" },
+          { label: "BAAI/bge-large-zh-v1.5 (Chinese, 1024d)", value: "BAAI/bge-large-zh-v1.5" },
+          { label: "BAAI/bge-large-en-v1.5 (English, 1024d)", value: "BAAI/bge-large-en-v1.5" },
+          { label: "text-embedding-3-small (OpenAI, 1536d)", value: "text-embedding-3-small" },
+          { label: "text-embedding-3-large (OpenAI, 3072d)", value: "text-embedding-3-large" },
+        ]
+        const currentVal = ec.model ?? "BAAI/bge-m3"
+        openPicker({
+          title: `Embedding model (current: ${currentVal})`,
+          entries: [
+            { type: "header", text: `Current: ${currentVal}` },
+            ...models.map((m) => ({ type: "item", text: m.label, action: m.value })),
+          ],
+          onSelect: async (sel) => {
+            try {
+              const raw = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : {}
+              raw.embedding ??= {}
+              raw.embedding.model = sel.action
+              const { saveConfig, loadConfig } = await import("../config.mjs")
+              saveConfig(raw)
+              const cfg = loadConfig()
+              agent.provider = cfg.provider
+              agent.providers = cfg.providersList
+              agent.activeProvider = cfg.activeProvider
+              agent.config = cfg
+              agent.config.agent ??= {}
+              pushLabel(`❯ Config`, ansi.bold + C.tool)
+              pushLine(`embedding.model = ${sel.action}`, C.tool)
+            } catch (error) {
+              pushLine(`Save failed: ${error.message}`, C.error)
+            }
+          },
+        })
+        return
+      }
+      // Numeric config items: ask for value, parse as number
+      const isNumeric = e.action.startsWith("agent.")
+      const label = e.action
+      const current = e.action === "agent.maxTurns" ? (ac.maxTurns ?? 100)
+        : e.action === "agent.subagentTurns" ? (ac.subagentTurns ?? 100)
+        : e.action === "agent.compactThreshold" ? (ac.compactThreshold ?? 100000)
+        : ""
+      const prompt = `${label} (current: ${current}):`
+      const val = await askQuestion(prompt)
+      if (!val) return
+      try {
+        const { configPath, loadConfig, saveConfig } = await import("../config.mjs")
+        const raw = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : {}
+        if (isNumeric) {
+          const keys = label.split(".")
+          let obj = raw
+          for (let i = 0; i < keys.length - 1; i++) { obj[keys[i]] ??= {}; obj = obj[keys[i]] }
+          const num = Number(val)
+          if (isNaN(num)) { pushLine("Value must be a number", C.error); return }
+          obj[keys[keys.length - 1]] = num
+        }
+        saveConfig(raw)
+        const cfg = loadConfig()
+        agent.provider = cfg.provider
+        agent.providers = cfg.providersList
+        agent.activeProvider = cfg.activeProvider
+        agent.config = cfg
+        agent.config.agent ??= {}
+        pushLabel(`❯ Config`, ansi.bold + C.tool)
+        pushLine(`${label} = ${val}`, C.tool)
+        pushLine("(restart to apply to existing agent state)", C.dim)
+      } catch (error) {
+        pushLine(`Save failed: ${error.message}`, C.error)
       }
     },
   })

package/src/tui/cmd-extract.mjs

@@ -1,5 +1,13 @@
+import { C } from "./ansi.mjs"
+
 /** /extract command: extract knowledge from current session.
- *  ctx: { runDistill } */
+ *  ctx: { runDistill, state, pushLine } */
 export async function handleExtractCommand(ctx) {
-  await ctx.runDistill()
+  const { runDistill, state, pushLine } = ctx
+  pushLine("[extract] Analyzing session...", C.dim)
+  const count = await runDistill()
+  const msg = count > 0
+    ? `Knowledge extracted: ${count} candidate(s) saved to memory (use /skills to list, agent will recall via memory_search)`
+    : "No new knowledge found in this session."
+  pushLine(msg, count > 0 ? C.tool : C.dim)
 }

package/src/tui/cmd-goal.mjs

@@ -1,5 +1,3 @@
-import { ansi, C } from "./ansi.mjs"
-
 /** /goal command: set/view/cancel long-term goal.
  *  Extracted from slash-commands.mjs.
  *  ctx: { agent, pushLine, pushLabel, openPicker, askQuestion } */
@@ -19,7 +17,6 @@ export async function handleGoalCommand(ctx) {
     onSelect: async (e) => {
       if (e.action === "view") {
         const statusText = { active: "active", complete: "completed", blocked: "blocked" }[agent.goal.status] ?? agent.goal.status
-        pushLabel(`❯ Goal`, ansi.bold + C.warn)
         pushLine(`Goal: ${agent.goal.objective}`, C.tool)
         if (agent.goal.criteria) pushLine(`  Criteria: ${agent.goal.criteria}`, C.dim)
         pushLine(`  Status: ${statusText} │ Turns used: ${agent.goal.turnsUsed ?? 0} │ Set at: ${new Date(agent.goal.setAt).toLocaleString()}`, C.dim)
@@ -27,8 +24,6 @@ export async function handleGoalCommand(ctx) {
       }
       if (e.action === "cancel") {
         agent.goal = null
-        pushLabel(`❯ Goal`, ansi.bold + C.dim)
-        pushLine(`Goal cancelled.`, C.dim)
         return
       }
       // set — requires entering goal text
@@ -38,10 +33,6 @@ export async function handleGoalCommand(ctx) {
       const objective = semi ? goalText.slice(0, semi).trim() : goalText.trim()
       const criteria = semi ? goalText.slice(semi + 1).trim() : ""
       agent.goal = { objective, criteria, setAt: Date.now(), status: "active", turnsUsed: 0, _blockTally: null }
-      pushLabel(`❯ Goal`, ansi.bold + C.warn)
-      pushLine(`Goal set: ${objective}`, C.tool)
-      if (criteria) pushLine(`  Criteria: ${criteria}`, C.dim)
-      else pushLine(`  ⚠ No criteria provided — the agent will determine its own criteria as it works on this goal`, C.warn)
     },
   })
 }

package/src/tui/cmd-help.mjs

@@ -5,7 +5,7 @@ import { ansi, C } from "./ansi.mjs"
 export async function handleHelpCommand(ctx) {
   const { pushLine, pushLabel, SLASH_COMMANDS } = ctx
   const aliasList = { "/help": "/h", "/exit": "/x", "/model": "/m", "/plan": "/p", "/think": "/t", "/clear": "/c", "/new": "/n" }
-  const order = ["Agent", "Session", "Tools", "Config"]
+  const order = ["Agent", "Session", "Project", "System"]
   const byGroup = new Map()
   for (const c of SLASH_COMMANDS) {
     if (!c.group) continue

package/src/tui/cmd-mcp.mjs

@@ -120,26 +120,39 @@ export async function handleMcpCommand(ctx) {
         return
       }
       if (e.action === "add") {
-        const mcpInput = await askQuestion("Enter: <name> <URL|command> [args...]\nURL auto-detect: https://… → HTTP, ws://… → WebSocket, other → stdio command")
-        if (!mcpInput) return
-        const parts = mcpInput.split(/\s+/)
-        if (parts.length < 2) { pushLine("Usage: <name> <URL|command> [args...]", C.error); return }
-        const [name, second, ...extras] = parts
-        const existing = (agent.config?.mcp?.servers ?? []).find((s) => s.name === name)
-        if (existing) { pushLine(`[mcp] "${name}" already exists`, C.error); return }
-        const isWS = /^wss?:\/\//.test(second)
-        const isHTTP = /^https?:\/\//.test(second)
-        let srv
-        if (isWS) {
-          const headers = parseHeaders(extras)
-          srv = { name, wsUrl: second, headers: Object.keys(headers).length > 0 ? headers : undefined }
-        } else if (isHTTP) {
-          const headers = parseHeaders(extras)
-          srv = { name, url: second, headers: Object.keys(headers).length > 0 ? headers : undefined }
-        } else {
-          srv = { name, command: second, args: extras.length > 0 ? extras : undefined }
-        }
-        await addAndConnect(ctx, srv)
+        // Pick transport type first, then ask name + URL/command
+        openPicker({
+          title: "MCP Transport",
+          entries: [
+            { type: "header", text: "Select server transport" },
+            { type: "item", text: "HTTP (https://…)", action: "http" },
+            { type: "item", text: "WebSocket (ws://…)", action: "ws" },
+            { type: "item", text: "stdio (local command)", action: "stdio" },
+          ],
+          onSelect: async (te) => {
+            const name = await askQuestion("Server name:")
+            if (!name) return
+            const existing = (agent.config?.mcp?.servers ?? []).find((s) => s.name === name)
+            if (existing) { pushLine(`[mcp] "${name}" already exists`, C.error); return }
+            if (te.action === "stdio") {
+              const cmd = await askQuestion("Command (e.g. npx, python):")
+              if (!cmd) return
+              const argsInput = await askQuestion("Arguments (space-separated, or leave empty):")
+              const args = argsInput ? argsInput.split(/\s+/) : undefined
+              await addAndConnect(ctx, { name, command: cmd, args })
+            } else {
+              const urlPrompt = te.action === "ws" ? "WebSocket URL (ws://…):" : "HTTP URL (https://…):"
+              const url = await askQuestion(urlPrompt)
+              if (!url) return
+              const headersInput = await askQuestion("Headers (key=value, space-separated, or leave empty):")
+              const headers = headersInput ? parseHeaders(headersInput.split(/\s+/)) : undefined
+              const srv = te.action === "ws"
+                ? { name, wsUrl: url, headers: Object.keys(headers ?? {}).length > 0 ? headers : undefined }
+                : { name, url, headers: Object.keys(headers ?? {}).length > 0 ? headers : undefined }
+              await addAndConnect(ctx, srv)
+            }
+          },
+        })
       }
     },
   })

package/src/tui/cmd-new.mjs

@@ -2,17 +2,37 @@ import { clearSession } from "../session.mjs"
 import { C } from "./ansi.mjs"
 
 /** /new command: start new session (old session archived to slot).
- *  ctx: { agent, state, pushLine } */
+ *  ctx: { agent, state, pushLine, openPicker, render } */
 export async function handleNewCommand(ctx) {
-  const { agent, state, pushLine } = ctx
-  agent.history = []
-  agent.tasks = []
-  agent.planMode = false
-  agent.goal = null
-  agent._pendingReminders = []
-  state.tasks = []
-  state.lines = []
-  state.streaming = ""
-  clearSession(agent.cwd)
-  pushLine("New session started (old session archived to slot; /session to view)", C.dim)
+  const { agent, state, pushLine, openPicker, render } = ctx
+
+  const doNewSession = () => {
+    agent.history = []
+    agent.tasks = []
+    agent.planMode = false
+    agent.goal = null
+    agent._pendingReminders = []
+    state.tasks = []
+    state.lines = []
+    state.streaming = ""
+    clearSession(agent.cwd)
+    render()
+    pushLine("New session started (old session archived to slot; /session to view)", C.dim)
+  }
+
+  if (agent.history.length > 0) {
+    openPicker({
+      title: "Start new session?",
+      entries: [
+        { type: "item", text: "Yes, archive current and start new", action: "yes" },
+        { type: "item", text: "Cancel", action: "no" },
+      ],
+      defaultIndex: 1,
+      onSelect: (e) => {
+        if (e.action === "yes") doNewSession()
+      },
+    })
+    return
+  }
+  doNewSession()
 }

package/src/tui/cmd-plan.mjs

@@ -1,9 +1,7 @@
-import { ansi, C } from "./ansi.mjs"
-
 /** /plan command: toggle plan mode (read-only explore → design → implement).
- *  ctx: { agent, pushLine, pushLabel } */
+ *  ctx: { agent } */
 export async function handlePlanCommand(ctx) {
-  const { agent, pushLine, pushLabel } = ctx
+  const { agent } = ctx
   agent.planMode = !agent.planMode
   agent._pendingReminders = agent._pendingReminders ?? []
   if (agent.planMode) {
@@ -11,11 +9,4 @@ export async function handlePlanCommand(ctx) {
   } else {
     agent._pendingReminders.push("[System reminder: plan mode is now OFF. You may edit files, run commands, and implement changes.]")
   }
-  pushLabel(`❯ Plan`, ansi.bold + (agent.planMode ? C.tool : C.dim))
-  pushLine(
-    agent.planMode
-      ? `Plan mode ON: read-only tools only. Design first, then implement. /plan again to exit.`
-      : `Plan mode OFF: you may now edit files and run commands.`,
-    agent.planMode ? C.tool : C.dim,
-  )
 }

package/src/tui/cmd-think.mjs

@@ -1,10 +1,8 @@
-import { ansi, C } from "./ansi.mjs"
-
 /** /think command: toggle thinking mode, set reasoning effort.
  *  Extracted from slash-commands.mjs.
- *  ctx: { agent, pushLine, pushLabel, openPicker, syncProviderField } */
+ *  ctx: { agent, openPicker, syncProviderField } */
 export async function handleThinkCommand(ctx) {
-  const { agent, pushLine, pushLabel, openPicker, syncProviderField } = ctx
+  const { agent, openPicker, syncProviderField } = ctx
   const cur = agent.provider
   const thinkingEnabled = cur.thinking?.type === "enabled" || cur.thinking?.type === undefined
   const { specForModel } = await import("../config.mjs")
@@ -30,8 +28,6 @@ export async function handleThinkCommand(ctx) {
       if (e.action === "effort") {
         cur.reasoningEffort = e.level
         await syncProviderField("reasoningEffort", e.level)
-        pushLabel(`❯ Think`, ansi.bold + C.tool)
-        pushLine(`Reasoning effort set to ${e.level}`, C.tool)
       } else {
         const enable = e.action === "on"
         if (isEffortOnly) {
@@ -47,9 +43,6 @@ export async function handleThinkCommand(ctx) {
           if (!enable) await syncProviderField("reasoningEffort", undefined)
           else await syncProviderField("reasoningEffort", cur.reasoningEffort)
         }
-        pushLabel(`❯ Think`, ansi.bold + C.tool)
-        pushLine(`Thinking mode ${enable ? "On" : "Off"}`, C.tool)
-        if (enable) pushLine(`Reasoning effort: ${cur.reasoningEffort}`, C.dim)
       }
     },
   })

package/src/tui/cmd-upgrade.mjs

@@ -0,0 +1,47 @@
+/** /upgrade command: check for updates and optionally upgrade.
+ *  ctx: { agent, pushLine, pushLabel, openPicker, ansi, C } */
+export async function handleUpgradeCommand(ctx) {
+  const { pushLine, pushLabel, openPicker, ansi, C } = ctx
+  const { checkForUpdate } = await import("../upgrade.mjs")
+  const { readFileSync } = await import("node:fs")
+
+  const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))
+
+  pushLabel(`❯ Upgrade`, ansi.bold + C.tool)
+  pushLine(`Checking for updates...`, C.dim)
+  const result = await checkForUpdate(pkg.version)
+  if (!result) {
+    pushLine(`Unable to query npm registry — check your network`, C.error)
+    return
+  }
+  if (!result.newer) {
+    pushLine(`✓ ThinCoder ${result.local} is already the latest.`, C.tool)
+    return
+  }
+  pushLine(`thincoder ${result.latest} is available (current: ${result.local}).`, C.tool)
+  openPicker({
+    title: `Update: ${result.local} → ${result.latest}`,
+    entries: [
+      { type: "header", text: `New version: ${result.latest}` },
+      { type: "item", text: "Upgrade now", action: "upgrade" },
+      { type: "item", text: "Later", action: "later" },
+    ],
+    onSelect: async (sel) => {
+      if (sel.action === "upgrade") {
+        pushLabel(`❯ Upgrade`, ansi.bold + C.tool)
+        pushLine(`Upgrading to ${result.latest}...`, C.tool)
+        const { exec } = await import("node:child_process")
+        const cp = exec("npm install -g thincoder@latest", { windowsHide: true })
+        cp.stdout?.on("data", () => {})
+        cp.stderr?.on("data", () => {})
+        cp.on("close", (code) => {
+          if (code === 0) {
+            pushLine(`✓ Upgraded to ${result.latest}. Restart to apply.`, C.tool)
+          } else {
+            pushLine(`✗ Upgrade failed (exit ${code}). Run \`thincoder upgrade\` manually.`, C.error)
+          }
+        })
+      }
+    },
+  })
+}

package/src/tui/distill-cmd.mjs

@@ -35,6 +35,7 @@ export async function runDistill(ctx) {
       saved++
     }
     pushLine(`[distill] Done: saved ${saved}/${candidates.length} item(s)`, C.tool)
+    return saved
   } catch (error) {
     pushLine(`[distill] error: ${error.message}`, C.error)
   } finally {

package/src/tui/index.mjs

@@ -381,6 +381,51 @@ export async function startTUI(agent, opts = {}) {
 
   showStartup({ agent, state, opts, pushLine, pushLabel, render, startWizard })
   backgroundIndex({ agent, state, render })
+
+  // Check for updates (non-blocking, after startup screen)
+  ;(async () => {
+    try {
+      const { readFileSync } = await import("node:fs")
+      const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))
+      const { checkForUpdate } = await import("../upgrade.mjs")
+      const result = await checkForUpdate(pkg.version)
+      if (result?.newer) {
+        // Defer: if wizard is still active, just show a dim line
+        if (state.wizard) {
+          pushLine(`Tip: thincoder ${result.latest} is available (run /upgrade later or restart)`, C.dim)
+          render()
+        } else {
+          openPicker({
+            title: `Update available: ${result.local} → ${result.latest}`,
+            entries: [
+              { type: "header", text: `thincoder ${result.latest} is available (current: ${result.local})` },
+              { type: "item", text: "Upgrade now", action: "upgrade" },
+              { type: "item", text: "Later", action: "later" },
+            ],
+            onSelect: async (sel) => {
+              if (sel.action === "upgrade") {
+                pushLabel(`❯ Upgrade`, ansi.bold + C.tool)
+                pushLine(`Upgrading to ${result.latest}...`, C.tool)
+                const { exec } = await import("node:child_process")
+                const cp = exec("npm install -g thincoder@latest", { windowsHide: true })
+                let stdout = ""
+                cp.stdout?.on("data", (d) => { stdout += d })
+                cp.stderr?.on("data", (d) => { stdout += d })
+                cp.on("close", (code) => {
+                  if (code === 0) {
+                    pushLine(`✓ Upgraded to ${result.latest}. Restart to apply.`, C.tool)
+                  } else {
+                    pushLine(`✗ Upgrade failed (exit ${code}). Run \`thincoder upgrade\` manually.`, C.error)
+                  }
+                  render()
+                })
+              }
+            },
+          })
+        }
+      }
+    } catch { /* network error or timeout — silently skip */ }
+  })()
 }
 
 function summarize(obj) {

package/src/tui/key-handler.mjs

@@ -43,7 +43,7 @@ export function createKeyHandler(ctx) {
       if (q.options.length > 0) {
         // options mode: ↑↓ select, Enter confirm, Esc cancel
         if (key.name === "escape") {
-          q.resolve("(cancelled)")
+          q.resolve("")
           state.question = null
           state.status = "Processing..."
           render()
@@ -64,13 +64,13 @@ export function createKeyHandler(ctx) {
       } else {
         // free text: type answer, Enter submit, Esc cancel
         if (key.name === "escape") {
-          q.resolve("(cancelled)")
+          q.resolve("")
           state.question = null
           state.status = "Processing..."
           render()
         } else if (key.name === "return") {
           const answer = (q.answer ?? "").trim()
-          q.resolve(answer || "(empty answer)")
+          q.resolve(answer || "")
           state.question = null
           state.status = "Processing..."
           pushLine(`  → ${answer || "(empty)"}`, C.tool)

package/src/tui/slash-commands.mjs

@@ -26,6 +26,7 @@ import { handleModelCommand } from "./cmd-model.mjs"
 import { handleConfigCommand } from "./cmd-config.mjs"
 import { handleExtractCommand } from "./cmd-extract.mjs"
 import { handleHelpCommand } from "./cmd-help.mjs"
+import { handleUpgradeCommand } from "./cmd-upgrade.mjs"
 
 export const SLASH_COMMANDS = [
   { name: "/plan", group: "Agent", desc: "toggle plan mode (design first, then implement)" },
@@ -33,18 +34,19 @@ export const SLASH_COMMANDS = [
   { name: "/model", group: "Agent", desc: "select model & manage providers" },
   { name: "/goal", group: "Agent", desc: "set/view/cancel long-term goal" },
   { name: "/think", group: "Agent", desc: "thinking mode & reasoning effort" },
-  { name: "/init", group: "Tools", desc: "generate project AGENTS.md skeleton" },
-  { name: "/skills", group: "Tools", desc: "list project skills" },
-  { name: "/mcp", group: "Tools", desc: "manage MCP servers" },
-  { name: "/config", group: "Config", desc: "config management (embedding / agent)" },
-  { name: "/reindex", group: "Config", desc: "rebuild memory index" },
+  { name: "/config", group: "Agent", desc: "config management (embedding / agent)" },
+  { name: "/upgrade", group: "System", desc: "check for updates & upgrade" },
   { name: "/new", group: "Session", desc: "new session (old one archived to slot)" },
   { name: "/session", group: "Session", desc: "list/switch archived sessions" },
   { name: "/clear", group: "Session", desc: "clear screen" },
   { name: "/extract", group: "Session", desc: "extract knowledge from session" },
-  { name: "/restore", group: "Session", desc: "restore checkpoint" },
-  { name: "/exit", group: "Session", desc: "exit" },
-  { name: "/help", group: "", desc: "this list" },
+  { name: "/init", group: "Project", desc: "generate project AGENTS.md skeleton" },
+  { name: "/skills", group: "Project", desc: "list project skills" },
+  { name: "/mcp", group: "Project", desc: "manage MCP servers" },
+  { name: "/reindex", group: "Project", desc: "rebuild memory index" },
+  { name: "/restore", group: "Project", desc: "restore checkpoint" },
+  { name: "/exit", group: "System", desc: "exit" },
+  { name: "/help", group: "System", desc: "this list" },
 ]
 
 /** Command → handler mapping table */
@@ -64,6 +66,7 @@ const HANDLERS = {
   "/think": handleThinkCommand,
   "/model": handleModelCommand,
   "/config": handleConfigCommand,
+  "/upgrade": handleUpgradeCommand,
   "/extract": handleExtractCommand,
   "/help": handleHelpCommand,
 }

package/src/upgrade.mjs

@@ -0,0 +1,41 @@
+/**
+ * upgrade.mjs — version check and upgrade utilities
+ * Used by both CLI (bin/thincoder.mjs upgrade command) and TUI (startup check).
+ */
+
+/** Compare two semver-like version strings. Returns -1/0/1. */
+export function compareVersions(a, b) {
+  const pa = String(a).split("."), pb = String(b).split(".")
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const xa = pa[i] ?? "0", xb = pb[i] ?? "0"
+    const na = Number(xa), nb = Number(xb)
+    if (!Number.isNaN(na) && !Number.isNaN(nb)) {
+      if (na !== nb) return na < nb ? -1 : 1
+    } else if (xa !== xb) {
+      return xa < xb ? -1 : 1
+    }
+  }
+  return 0
+}
+
+/**
+ * Check npm registry for the latest version.
+ * Returns { local, latest, newer: boolean } or null on network error / timeout.
+ */
+export async function checkForUpdate(localVersion) {
+  try {
+    const res = await fetch("https://registry.npmjs.org/thincoder/latest", {
+      signal: AbortSignal.timeout(5000),
+    })
+    if (!res.ok) return null
+    const data = await res.json()
+    const latest = data.version
+    return {
+      local: localVersion,
+      latest,
+      newer: compareVersions(localVersion, latest) < 0,
+    }
+  } catch {
+    return null
+  }
+}