@xcompiler/cli 0.2.3 → 0.2.4

package/dist/cli/xcompiler_run.js

@@ -59,11 +59,11 @@ var init_types = __esm({
 import { Command } from "commander";
 
 // src/runtime/commands.ts
-import path29 from "path";
-import { promises as fs26 } from "fs";
+import path30 from "path";
+import { promises as fs28 } from "fs";
 
 // src/core/project_file.ts
-import { promises as fs2 } from "fs";
+import { promises as fs3 } from "fs";
 import path4 from "path";
 import { z as z3 } from "zod";
 
@@ -249,7 +249,7 @@ var PlanSchema = z.object({
 }));
 
 // src/core/storage.ts
-import { promises as fs } from "fs";
+import { promises as fs2 } from "fs";
 import path3 from "path";
 
 // src/core/docs.ts
@@ -337,6 +337,9 @@ function testPlanDocForIteration(testPhase, iterationId = "P1") {
   return basename ? `docs/iterations/${iterationId}/tests/${basename}` : canonical;
 }
 
+// src/core/language.ts
+import { promises as fs } from "fs";
+
 // src/core/entry_gate.ts
 import path from "path";
 
@@ -438,6 +441,7 @@ var PYTHON_EXECUTOR_SYSTEM = `You are XCompiler's Step Executor. You may only in
 Every round you must return strict JSON:
 {
   "thoughts": "<one sentence describing this round's intent>",
+  "issueResolutionPlan": "<required only in DEBUG issue mode: concise root cause, repair target, and validation plan>",
   "actions": [ { "tool": "<tool name>", "args": { ... } }, ... ],
   "done": true | false
 }
@@ -522,6 +526,7 @@ var TYPESCRIPT_EXECUTOR_SYSTEM = `You are XCompiler's Step Executor. You may onl
 Every round you must return strict JSON:
 {
   "thoughts": "<one sentence describing this round's intent>",
+  "issueResolutionPlan": "<required only in DEBUG issue mode: concise root cause, repair target, and validation plan>",
   "actions": [ { "tool": "<tool name>", "args": { ... } }, ... ],
   "done": true | false
 }
@@ -545,7 +550,7 @@ Rules:
 7. package.json is the dependency manifest. Use add_dependency for npm packages; never write requirements.txt.
 8. run_program runs the project entry with \`npx tsx\`, run_tests runs Vitest via \`npm test\`, and the final delivery gate also verifies the direct Node entry command.`;
 var PLANNER_CLARIFY_SYSTEM = `You are the requirements analyst for XCompiler's V-model. Do not restate the topic; expose unresolved decisions that would change functional design, acceptance, or architecture boundaries.
-Return strict JSON only. Each question must be directly answerable by a product owner, cover one decision, and avoid vague catch-all or implementation-stack questions.`;
+Return strict JSON only. Each question must be directly answerable by a product owner and cover one decision. Avoid vague catch-all or implementation-stack questions, except for the single development-language question when the user prompt explicitly requires it.`;
 function buildPlannerSystem(profile) {
   return (profile.id === "typescript" ? TYPESCRIPT_PLANNER_SYSTEM : PYTHON_PLANNER_SYSTEM) + profile.plannerPromptOverride;
 }
@@ -637,13 +642,13 @@ var messages = {
     preflightOllamaUnreachable: (baseUrl, message) => `preflight: ollama ${baseUrl} unreachable: ${message}`,
     preflightAutoAdded: (providers, roles) => `preflight: auto-added ${providers} provider(s) for roles [${roles}]`,
     scoreFileHeader: "# XCompiler LLM provider score snapshot (maintained automatically by ScoreStore; do not edit)",
-    scoreFileSemantics: "# Scores: default 1.0; automatic range 0.1-1.0; providers tagged cluster default to 0.2-0.5 unless llm.cluster_score_min/max widens it; failure -0.5; success +0.1; only user-configured score=0 disables a provider."
+    scoreFileSemantics: "# Scores: dynamic snapshot; default 1.0; automatic range 0.1-1.0; providers tagged cluster default to 0.2-0.5 unless llm.cluster_score_min/max widens it; failure -0.5; success +0.1. Put user overrides in llm_scores_user.yaml; 0 disables a provider."
   },
   system: {
     configEnvMissing: (names) => `[xcompiler] unset config environment variables were replaced with empty strings: ${names}`,
     unhandledError: (message) => `Unhandled error: ${message}`,
     unsupportedPypiOnlyNetwork: "network=pypi-only is rejected because Docker cannot enforce a PyPI-only allowlist by itself. Use network=off for isolation or network=download-only for explicitly unrestricted outbound downloads.",
-    dockerInsideContainerUnsupported: "XCompiler is running inside a container, so sandbox=docker is unsupported because Docker-outside-of-Docker can mis-map bind mounts and docker.sock permissions. Use agent.sandbox=subprocess, run XCompiler on the host, or set XC_IN_CONTAINER=0 only in a controlled environment.",
+    dockerInsideContainerUnsupported: "XCompiler is running inside a container, so sandbox mode docker is unsupported because Docker-outside-of-Docker can mis-map bind mounts and docker.sock permissions. Use agent.sandboxes.<language>.mode=subprocess, run XCompiler on the host, or set XC_IN_CONTAINER=0 only in a controlled environment.",
     firejailUnsupported: "sandbox=firejail is not implemented; use subprocess or docker.",
     smokeHeader: (baseUrl) => `Smoke test against ${baseUrl} (streaming)`,
     smokeOk: (model, totalMs, firstTokenMs, chunks, preview) => `[OK total=${totalMs}ms first-token=${firstTokenMs}ms chunks=${chunks}] ${model} -> ${preview}`,
@@ -660,8 +665,8 @@ var messages = {
     loaded: (plugin, version) => `Plugin ${plugin}@${version} loaded.`,
     extensionConflict: (plugin, kind, name) => `Plugin ${plugin} cannot replace existing ${kind} "${name}".`,
     hookFailed: (plugin, stage, message) => `Plugin ${plugin} failed during ${stage}: ${message}`,
-    manifestReadFailed: (path30, message) => `Cannot read plugin manifest ${path30}: ${message}`,
-    moduleLoadFailed: (plugin, path30, message) => `Cannot load plugin ${plugin} from ${path30}: ${message}`,
+    manifestReadFailed: (path31, message) => `Cannot read plugin manifest ${path31}: ${message}`,
+    moduleLoadFailed: (plugin, path31, message) => `Cannot load plugin ${plugin} from ${path31}: ${message}`,
     exportInvalid: (plugin, exportName) => `Plugin ${plugin} export ${exportName} is not a valid XCompiler plugin`,
     manifestMismatch: (plugin) => `Plugin ${plugin} runtime manifest does not match its preflight manifest`
   },
@@ -749,6 +754,7 @@ var messages = {
     optIntent: "plan intent: greenfield | feature | refactor | self",
     optBaselinePlan: "existing baseline phasePlan.json / plan.json path (default <workspace>/phasePlan.json)",
     optProjectFile: "XXX.xc project file path (default <workspace>/<name>.xc)",
+    optDebugWikiPath: "debug wiki root directory path (default <XCompiler path>/.xcompiler/debug-wiki)",
     argPlan: "phasePlan.json or legacy plan.json path (default = <workspace>/phasePlan.json)",
     argProjectFile: "XXX.xc project file",
     argStepId: "Step ID, e.g. S001",
@@ -895,7 +901,7 @@ var messages = {
     stepHeader: (id, phase, title, status, retries, maxRetries) => `${id} ${phase} ${title} ${status} retries=${retries}/${maxRetries}`,
     stepRoleTools: (role, tools) => `role=${role} tools=[${tools}]`,
     stepDependsOn: (ids) => `dependsOn: ${ids}`,
-    outputStatus: (exists, p) => `${exists ? "\u2713" : "\u2717"} ${p}`,
+    outputStatus: (exists2, p) => `${exists2 ? "\u2713" : "\u2717"} ${p}`,
     auditEntry: (ts, kind, message) => `${ts} ${kind} ${message}`
   },
   execute: {
@@ -963,7 +969,7 @@ var messages = {
     deliveryGateReason: (command, exitCode, timedOut) => `FUNCTIONAL_TEST gate: \`${command}\` exit=${exitCode}${timedOut ? " (timeout)" : ""}`,
     missingPythonEntrypoint: "missing Python entrypoint: expected src/main.py, src/<package>/__main__.py, or an explicit CLI file such as src/cli.py",
     missingTypeScriptEntrypoint: "missing TypeScript entrypoint: expected package.json start/bin or one of src/main.ts, src/index.ts, src/main.tsx",
-    invalidPythonEntrypointSource: (path30) => `invalid Python entrypoint source in ${path30}: expected a real CLI entry structure such as def main(...), argparse.ArgumentParser, or if __name__ == "__main__"; placeholder/import-only files are not runnable applications.`,
+    invalidPythonEntrypointSource: (path31) => `invalid Python entrypoint source in ${path31}: expected a real CLI entry structure such as def main(...), argparse.ArgumentParser, or if __name__ == "__main__"; placeholder/import-only files are not runnable applications.`,
     entrypointHelpOutputMissing: (command) => `entrypoint probe \`${command}\` exited 0 but produced no meaningful help/usage text; implement --help instead of relying on an empty script exit.`,
     reasonLine: (reason) => `reason: ${reason}`,
     roundsLine: (rounds) => `rounds: ${rounds}`,
@@ -1032,12 +1038,13 @@ Question mix (functionality first):
 - Label options sequentially from A through the last generated option, for example A-B, A-C, A-D, or A-E. A should be the recommended/default setting when one is apparent. Options must be concrete business/product settings, not vague placeholders.
 - Do not include \u201COther\u201D, \u201CCustom\u201D, or \u201CLet the user decide\u201D as an option. The CLI already allows the user to reply with one of the shown labels or enter a custom free-form answer.
 ${opts.projectShapeAmbiguous ? "- Required for this topic: ask the API library vs runnable application vs mixed-deliverable boundary explicitly.\n" : ""}
+${opts.languageAmbiguous ? "- Required for this topic: include exactly one boundary question confirming the target development language. Options must be A. Python (default/recommended) and B. TypeScript / Node.js. The user may still answer with custom free-form text.\n" : ""}
 
-[Hard constraint] The implementation stack is already fixed by XCompiler config / the existing project baseline. Do not reopen language/runtime/package-manager decisions.
+${opts.languageAmbiguous ? `[Stack decision] XCompiler could not infer the target language from the topic or baseline. Ask only the development-language question described above; do not ask package manager, test framework, or OS questions. If the user does not choose, Python is the default.` : `[Hard constraint] The implementation stack is already fixed by the user's topic or existing project baseline. Do not reopen language/runtime/package-manager decisions.
 **Do NOT** ask questions of these forms:
   - "Which programming language / framework / runtime should this use?"
   - "Which test framework / build tool / package manager?"
-  - "Which OS is the target platform?"
+  - "Which OS is the target platform?"`}
 ${opts.intent && opts.intent !== "greenfield" ? `This is an incremental ${opts.intent} request against an existing project${opts.hasBaseline ? " with a separate baseline summary that will be provided during decomposition" : ""}. Ask ONLY delta questions; do not ask to rebuild the project from scratch.` : ""}The majority of questions must concern functional behaviour; performance, boundaries, and extensibility should eliminate ambiguities that affect this delivery.`,
     plannerDecompose: (raw, qa, addenda, opts = {}) => `Original requirement:
 """
@@ -1139,7 +1146,7 @@ Return strict JSON StepPlan for the current phase only.`,
     executorDebugBlock: (reason, suggestions) => `
 
 You are now in DEBUG retry mode. Previous failure reason: ${reason}
-DEBUG may edit upstream source files and tests within the current allowedWrites. If the failure reveals a real implementation, contract, or downstream integration mismatch, fix that real defect; do not pass by weakening assertions, skipping tests, deleting failing cases, or merely accommodating an incorrect test. If this rollback is in a design/requirements step and the concrete code change belongs to a later V-model step outside the current allowedWrites, update the current contract, test plan, or diagnostic artifact and finish this step so the later CODE step can implement it; do not attempt denied writes. If the failure is a missing third-party dependency or wrong library choice, use add_dependency with the real package name or change the source back to the real library selected by HIGH_LEVEL_DESIGN; never add try/except ImportError fake modules, fake classes/functions, empty implementations, or fallback mocks in production src/ code to bypass the error. Begin with read_file / code_search to localise the issue, then make the smallest possible fix via apply_patch / replace_in_file / add_dependency, and finally run_tests to verify. A DEBUG retry cannot be marked complete from read-only inspection alone: it must produce a successful repair action or a successful verification command in this retry. If the previous failure reason mentions repeated read-only/probe actions, use the existing failure log as sufficient context and make the next action a patch/write/dependency change or a verification command. When a test executes and fails an assertion about returned behaviour, do not repeatedly rewrite fixtures or samples. Only edit fixtures when the evidence is missing-file, malformed-fixture, or parse-error in the fixture itself; otherwise patch the implementation, interface contract, dependency choice, or test expectation that is actually wrong. If the failure log shows a network/API failure, do not stop at probing endpoints: use at most two consecutive http_fetch probes, reject 2xx responses with empty or unusable bodies, then patch the real integration and verify with run_program plus run_tests. Do not set done=true while the entrypoint still reports a network/API failure.` + (suggestions ? `
+When this retry is handling an issue, every JSON response must include issueResolutionPlan before or while fixing it. The plan must be concise and actionable: root cause hypothesis, files/contracts to change, validation command or gate, and what would disprove the plan. DEBUG may edit upstream source files and tests within the current allowedWrites. If the failure reveals a real implementation, contract, or downstream integration mismatch, fix that real defect; do not pass by weakening assertions, skipping tests, deleting failing cases, or merely accommodating an incorrect test. If this rollback is in a design/requirements step and the concrete code change belongs to a later V-model step outside the current allowedWrites, update the current contract, test plan, or diagnostic artifact and finish this step so the later CODE step can implement it; do not attempt denied writes. If the failure is a missing third-party dependency or wrong library choice, use add_dependency with the real package name or change the source back to the real library selected by HIGH_LEVEL_DESIGN; never add try/except ImportError fake modules, fake classes/functions, empty implementations, or fallback mocks in production src/ code to bypass the error. Begin with read_file / code_search to localise the issue, then make the smallest possible fix via apply_patch / replace_in_file / add_dependency, and finally run_tests to verify. A DEBUG retry cannot be marked complete from read-only inspection alone: it must produce a successful repair action or a successful verification command in this retry. If the previous failure reason mentions repeated read-only/probe actions, use the existing failure log as sufficient context and make the next action a patch/write/dependency change or a verification command. When a test executes and fails an assertion about returned behaviour, do not repeatedly rewrite fixtures or samples. Only edit fixtures when the evidence is missing-file, malformed-fixture, or parse-error in the fixture itself; otherwise patch the implementation, interface contract, dependency choice, or test expectation that is actually wrong. If the failure log shows a network/API failure, do not stop at probing endpoints: use at most two consecutive http_fetch probes, reject 2xx responses with empty or unusable bodies, then patch the real integration and verify with run_program plus run_tests. Do not set done=true while the entrypoint still reports a network/API failure.` + (suggestions ? `
 
 ${suggestions}` : ""),
     executorGlobalBlock: (globalPrompt) => `
@@ -1156,7 +1163,8 @@ ${sp}`,
     executorFeedbackVerifyMissing: (paths) => `outputs still missing: ${paths}. Please continue.`,
     executorFeedbackReadOnlyLoopWarning: (rounds, targets) => `Loop guard warning: the last ${rounds} round(s) used only read/probe tools` + (targets ? ` (${targets})` : "") + ". Next response must include a successful repair action (apply_patch / replace_in_file / write_file / add_dependency) or a concrete verification action (run_tests / run_program). Do not continue with only read_file, list_dir, code_search, or http_fetch.",
     executorFeedbackReadOnlyRecoveryRequired: "Read-only recovery mode is active because the previous attempt already failed from probing. The next response must use existing failure evidence to patch/write/change dependency or run verification; one more read-only-only response will fail this retry.",
-    executorFeedbackRepairEvidenceMissing: "Invalid DEBUG completion: this retry has not produced repair evidence yet. Before done=true, perform at least one successful repair action or successful verification run; otherwise stop only with a concrete blocker in thoughts."
+    executorFeedbackRepairEvidenceMissing: "Invalid DEBUG completion: this retry has not produced repair evidence yet. Before done=true, perform at least one successful repair action or successful verification run; otherwise stop only with a concrete blocker in thoughts.",
+    executorFeedbackIssueResolutionPlanMissing: "Invalid DEBUG issue completion: issueResolutionPlan is required before the issue can be resolved. Return JSON with a concise handling plan plus the needed repair or verification actions."
   },
   skills: {
     patcher: "Use apply_patch / replace_in_file for small in-place edits to existing files; never overwrite a whole file.",
@@ -1177,7 +1185,7 @@ ${sp}`,
     summaryOk: "all checks passed.",
     summaryWarn: (n) => `passed with ${n} warning(s).`,
     summaryFail: (n) => `${n} failure(s) detected.`,
-    configLoadOk: (path30) => `config loaded: ${path30}`,
+    configLoadOk: (path31) => `config loaded: ${path31}`,
     configLoadFail: (msg) => `failed to load config: ${msg}`,
     configLocale: (locale) => `locale=${locale}`,
     llmNoProviders: "no LLM providers defined in config.llm.providers",
@@ -1195,7 +1203,7 @@ ${sp}`,
     roleOk: (role, provider) => `role "${role}" \u2192 ${provider}`,
     sandboxKind: (kind) => `sandbox=${kind}`,
     sandboxNetworkPolicy: (policy, ports) => `network=${policy}` + (ports.length ? ` (expose_ports=[${ports.join(", ")}])` : ""),
-    sandboxFullNoPorts: "network=full but no expose_ports configured \u2014 host-side cannot reach container services. Add `agent.sandbox_limits.expose_ports: [<port>]` in config.yaml.",
+    sandboxFullNoPorts: "network=full but no expose_ports configured \u2014 host-side cannot reach container services. Add `agent.sandboxes.<language>.<local|docker>.limits.expose_ports: [<port>]` in config.yaml.",
     sandboxNodeMissing: "node not found on PATH (required by TypeScript subprocess sandbox)",
     sandboxNodeOk: (version) => `node OK (${version})`,
     sandboxNpmMissing: "npm not found on PATH (required by TypeScript subprocess sandbox)",
@@ -1314,6 +1322,7 @@ var PYTHON_EXECUTOR_SYSTEM2 = `\u4F60\u662F XCompiler \u7684 Step Executor\u3002
 \u6BCF\u4E00\u8F6E\u4F60\u5FC5\u987B\u8FD4\u56DE\u4E25\u683C JSON\uFF1A
 {
   "thoughts": "<\u7528\u4E00\u53E5\u8BDD\u8BF4\u660E\u672C\u8F6E\u610F\u56FE>",
+  "issueResolutionPlan": "<\u4EC5 DEBUG issue \u6A21\u5F0F\u5FC5\u586B\uFF1A\u7B80\u660E\u8BF4\u660E\u6839\u56E0\u5047\u8BBE\u3001\u4FEE\u590D\u76EE\u6807\u548C\u9A8C\u8BC1\u65B9\u6848>",
   "actions": [ { "tool": "<\u5DE5\u5177\u540D>", "args": { ... } }, ... ],
   "done": true | false
 }
@@ -1397,6 +1406,7 @@ var TYPESCRIPT_EXECUTOR_SYSTEM2 = `\u4F60\u662F XCompiler \u7684 Step Executor\u
 \u6BCF\u4E00\u8F6E\u4F60\u5FC5\u987B\u8FD4\u56DE\u4E25\u683C JSON\uFF1A
 {
   "thoughts": "<\u7528\u4E00\u53E5\u8BDD\u8BF4\u660E\u672C\u8F6E\u610F\u56FE>",
+  "issueResolutionPlan": "<\u4EC5 DEBUG issue \u6A21\u5F0F\u5FC5\u586B\uFF1A\u7B80\u660E\u8BF4\u660E\u6839\u56E0\u5047\u8BBE\u3001\u4FEE\u590D\u76EE\u6807\u548C\u9A8C\u8BC1\u65B9\u6848>",
   "actions": [ { "tool": "<\u5DE5\u5177\u540D>", "args": { ... } }, ... ],
   "done": true | false
 }
@@ -1510,13 +1520,13 @@ var messages2 = {
     preflightOllamaUnreachable: (baseUrl, message) => `\u9884\u68C0\uFF1AOllama ${baseUrl} \u4E0D\u53EF\u8FBE\uFF1A${message}`,
     preflightAutoAdded: (providers, roles) => `\u9884\u68C0\uFF1A\u81EA\u52A8\u589E\u52A0 ${providers} \u4E2A provider\uFF0C\u8986\u76D6\u89D2\u8272 [${roles}]`,
     scoreFileHeader: "# XCompiler LLM provider \u8BC4\u5206\u5FEB\u7167\uFF08\u7531 ScoreStore \u81EA\u52A8\u7EF4\u62A4\uFF0C\u8BF7\u52FF\u624B\u5DE5\u7F16\u8F91\uFF09",
-    scoreFileSemantics: "# \u8BC4\u5206\u8BED\u4E49\uFF1A\u9ED8\u8BA4 1.0\uFF1B\u81EA\u52A8\u8BC4\u5206\u8303\u56F4 0.1\uFF5E1.0\uFF1Btags: [cluster] \u7684 provider \u9ED8\u8BA4 0.2\uFF5E0.5\uFF0C\u9664\u975E llm.cluster_score_min/max \u6269\u5BBD\uFF1B\u5931\u8D25 -0.5\uFF1B\u6210\u529F +0.1\uFF1B\u53EA\u6709\u7528\u6237\u914D\u7F6E score=0 \u8868\u793A\u7981\u7528\u3002"
+    scoreFileSemantics: "# \u8BC4\u5206\u8BED\u4E49\uFF1A\u8FD9\u662F\u52A8\u6001\u8BC4\u5206\u5FEB\u7167\uFF1B\u9ED8\u8BA4 1.0\uFF1B\u81EA\u52A8\u8BC4\u5206\u8303\u56F4 0.1\uFF5E1.0\uFF1Btags: [cluster] \u7684 provider \u9ED8\u8BA4 0.2\uFF5E0.5\uFF0C\u9664\u975E llm.cluster_score_min/max \u6269\u5BBD\uFF1B\u5931\u8D25 -0.5\uFF1B\u6210\u529F +0.1\u3002\u7528\u6237\u8986\u76D6\u8BF7\u5199 llm_scores_user.yaml\uFF0C0 \u8868\u793A\u7981\u7528\u3002"
   },
   system: {
     configEnvMissing: (names) => `[xcompiler] \u914D\u7F6E\u4E2D\u7684\u73AF\u5883\u53D8\u91CF\u672A\u8BBE\u7F6E\uFF0C\u5DF2\u66FF\u6362\u4E3A\u7A7A\u5B57\u7B26\u4E32\uFF1A${names}`,
     unhandledError: (message) => `\u672A\u5904\u7406\u9519\u8BEF\uFF1A${message}`,
     unsupportedPypiOnlyNetwork: "\u62D2\u7EDD network=pypi-only\uFF1ADocker \u672C\u8EAB\u65E0\u6CD5\u53EF\u9760\u6267\u884C\u201C\u4EC5 PyPI\u201D\u57DF\u540D\u767D\u540D\u5355\u3002\u9700\u8981\u9694\u79BB\u8BF7\u4F7F\u7528 network=off\uFF1B\u660E\u786E\u5141\u8BB8\u4EFB\u610F\u51FA\u7AD9\u4E0B\u8F7D\u65F6\u4F7F\u7528 network=download-only\u3002",
-    dockerInsideContainerUnsupported: "\u68C0\u6D4B\u5230 XCompiler \u8FD0\u884C\u5728\u5BB9\u5668\u5185\uFF0Csandbox=docker \u53EF\u80FD\u5BFC\u81F4 bind-mount \u8DEF\u5F84\u53CA docker.sock \u6743\u9650\u9519\u4F4D\uFF0C\u56E0\u6B64\u4E0D\u53D7\u652F\u6301\u3002\u8BF7\u4F7F\u7528 agent.sandbox=subprocess\u3001\u6539\u5728\u5BBF\u4E3B\u673A\u8FD0\u884C\uFF0C\u6216\u4EC5\u5728\u53D7\u63A7\u73AF\u5883\u8BBE\u7F6E XC_IN_CONTAINER=0\u3002",
+    dockerInsideContainerUnsupported: "\u68C0\u6D4B\u5230 XCompiler \u8FD0\u884C\u5728\u5BB9\u5668\u5185\uFF0Csandbox mode=docker \u53EF\u80FD\u5BFC\u81F4 bind-mount \u8DEF\u5F84\u53CA docker.sock \u6743\u9650\u9519\u4F4D\uFF0C\u56E0\u6B64\u4E0D\u53D7\u652F\u6301\u3002\u8BF7\u4F7F\u7528 agent.sandboxes.<language>.mode=subprocess\u3001\u6539\u5728\u5BBF\u4E3B\u673A\u8FD0\u884C\uFF0C\u6216\u4EC5\u5728\u53D7\u63A7\u73AF\u5883\u8BBE\u7F6E XC_IN_CONTAINER=0\u3002",
     firejailUnsupported: "\u5C1A\u672A\u5B9E\u73B0 sandbox=firejail\uFF0C\u8BF7\u4F7F\u7528 subprocess \u6216 docker\u3002",
     smokeHeader: (baseUrl) => `\u6B63\u5728\u5BF9 ${baseUrl} \u6267\u884C\u6D41\u5F0F\u5192\u70DF\u6D4B\u8BD5`,
     smokeOk: (model, totalMs, firstTokenMs, chunks, preview) => `[\u6210\u529F \u603B\u8017\u65F6=${totalMs}ms \u9996Token=${firstTokenMs}ms \u5206\u5757=${chunks}] ${model} -> ${preview}`,
@@ -1533,8 +1543,8 @@ var messages2 = {
     loaded: (plugin, version) => `\u63D2\u4EF6 ${plugin}@${version} \u5DF2\u52A0\u8F7D\u3002`,
     extensionConflict: (plugin, kind, name) => `\u63D2\u4EF6 ${plugin} \u4E0D\u80FD\u8986\u76D6\u5DF2\u6709 ${kind} \u201C${name}\u201D\u3002`,
     hookFailed: (plugin, stage, message) => `\u63D2\u4EF6 ${plugin} \u5728 ${stage} \u9636\u6BB5\u6267\u884C\u5931\u8D25\uFF1A${message}`,
-    manifestReadFailed: (path30, message) => `\u65E0\u6CD5\u8BFB\u53D6\u63D2\u4EF6\u6E05\u5355 ${path30}\uFF1A${message}`,
-    moduleLoadFailed: (plugin, path30, message) => `\u65E0\u6CD5\u4ECE ${path30} \u52A0\u8F7D\u63D2\u4EF6 ${plugin}\uFF1A${message}`,
+    manifestReadFailed: (path31, message) => `\u65E0\u6CD5\u8BFB\u53D6\u63D2\u4EF6\u6E05\u5355 ${path31}\uFF1A${message}`,
+    moduleLoadFailed: (plugin, path31, message) => `\u65E0\u6CD5\u4ECE ${path31} \u52A0\u8F7D\u63D2\u4EF6 ${plugin}\uFF1A${message}`,
     exportInvalid: (plugin, exportName) => `\u63D2\u4EF6 ${plugin} \u7684\u5BFC\u51FA ${exportName} \u4E0D\u662F\u6709\u6548 XCompiler \u63D2\u4EF6`,
     manifestMismatch: (plugin) => `\u63D2\u4EF6 ${plugin} \u7684\u8FD0\u884C\u65F6\u6E05\u5355\u4E0E\u9884\u68C0\u6E05\u5355\u4E0D\u4E00\u81F4`
   },
@@ -1622,6 +1632,7 @@ var messages2 = {
     optIntent: "\u8BA1\u5212\u610F\u56FE\uFF1Agreenfield | feature | refactor | self",
     optBaselinePlan: "\u5DF2\u6709\u57FA\u7EBF phasePlan.json / plan.json \u8DEF\u5F84\uFF08\u9ED8\u8BA4 <workspace>/phasePlan.json\uFF09",
     optProjectFile: "XXX.xc \u5DE5\u7A0B\u6587\u4EF6\u8DEF\u5F84\uFF08\u9ED8\u8BA4 <workspace>/<name>.xc\uFF09",
+    optDebugWikiPath: "debug wiki \u6839\u76EE\u5F55\u8DEF\u5F84\uFF08\u9ED8\u8BA4 <XCompiler path>/.xcompiler/debug-wiki\uFF09",
     argPlan: "phasePlan.json \u6216\u5386\u53F2 plan.json \u8DEF\u5F84\uFF08\u9ED8\u8BA4 = <workspace>/phasePlan.json\uFF09",
     argProjectFile: "XXX.xc \u5DE5\u7A0B\u6587\u4EF6",
     argStepId: "Step ID\uFF0C\u5982 S001",
@@ -1768,7 +1779,7 @@ var messages2 = {
     stepHeader: (id, phase, title, status, retries, maxRetries) => `${id} ${phase} ${title} ${status} \u91CD\u8BD5=${retries}/${maxRetries}`,
     stepRoleTools: (role, tools) => `\u89D2\u8272=${role} \u5DE5\u5177=[${tools}]`,
     stepDependsOn: (ids) => `\u4F9D\u8D56\uFF1A${ids}`,
-    outputStatus: (exists, p) => `${exists ? "\u2713" : "\u2717"} ${p}`,
+    outputStatus: (exists2, p) => `${exists2 ? "\u2713" : "\u2717"} ${p}`,
     auditEntry: (ts, kind, message) => `${ts} ${kind} ${message}`
   },
   execute: {
@@ -1836,7 +1847,7 @@ var messages2 = {
     deliveryGateReason: (command, exitCode, timedOut) => `FUNCTIONAL_TEST \u95E8\u7981\uFF1A\`${command}\` \u9000\u51FA\u7801=${exitCode}${timedOut ? "\uFF08\u8D85\u65F6\uFF09" : ""}`,
     missingPythonEntrypoint: "\u7F3A\u5C11 Python \u5165\u53E3\uFF1A\u9700\u8981 src/main.py\u3001src/<package>/__main__.py\uFF0C\u6216 src/cli.py \u7B49\u663E\u5F0F CLI \u6587\u4EF6",
     missingTypeScriptEntrypoint: "\u7F3A\u5C11 TypeScript \u5165\u53E3\uFF1A\u9700\u8981 package.json start/bin \u6216 src/main.ts\u3001src/index.ts\u3001src/main.tsx \u4E4B\u4E00",
-    invalidPythonEntrypointSource: (path30) => `Python \u5165\u53E3\u6E90\u7801\u65E0\u6548\uFF1A${path30} \u5FC5\u987B\u662F\u771F\u5B9E CLI \u5165\u53E3\uFF0C\u81F3\u5C11\u5305\u542B def main(...)\u3001argparse.ArgumentParser \u6216 if __name__ == "__main__" \u8FD9\u7C7B\u5165\u53E3\u7ED3\u6784\uFF1B\u4EC5 import/comment \u7684\u5360\u4F4D\u6587\u4EF6\u4E0D\u80FD\u7B97\u53EF\u8FD0\u884C\u5E94\u7528\u3002`,
+    invalidPythonEntrypointSource: (path31) => `Python \u5165\u53E3\u6E90\u7801\u65E0\u6548\uFF1A${path31} \u5FC5\u987B\u662F\u771F\u5B9E CLI \u5165\u53E3\uFF0C\u81F3\u5C11\u5305\u542B def main(...)\u3001argparse.ArgumentParser \u6216 if __name__ == "__main__" \u8FD9\u7C7B\u5165\u53E3\u7ED3\u6784\uFF1B\u4EC5 import/comment \u7684\u5360\u4F4D\u6587\u4EF6\u4E0D\u80FD\u7B97\u53EF\u8FD0\u884C\u5E94\u7528\u3002`,
     entrypointHelpOutputMissing: (command) => `\u5165\u53E3\u63A2\u6D4B \`${command}\` \u867D\u7136\u9000\u51FA\u7801\u4E3A 0\uFF0C\u4F46\u6CA1\u6709\u8F93\u51FA\u6709\u610F\u4E49\u7684 help/usage \u6587\u672C\uFF1B\u5FC5\u987B\u5B9E\u73B0 --help\uFF0C\u4E0D\u80FD\u9760\u7A7A\u811A\u672C\u81EA\u7136\u9000\u51FA\u8FC7\u5173\u3002`,
     reasonLine: (reason) => `\u539F\u56E0\uFF1A${reason}`,
     roundsLine: (rounds) => `\u8F6E\u6B21\uFF1A${rounds}`,
@@ -1881,7 +1892,7 @@ var messages2 = {
 - \u6BCF\u4E2A CODE/\u6D4B\u8BD5\u4EA7\u7269\u5FC5\u987B\u4E25\u683C\u9650\u5B9A\u5728\u672C\u6B21\u589E\u91CF\u8303\u56F4\uFF0C\u7981\u6B62\u6574\u4F53\u91CD\u5EFA\u6216\u66FF\u6362\u4ED3\u5E93\u3002
 - \u5C06\u7A33\u5B9A\u5BBF\u4E3B\u89C6\u4E3A N \u4EE3\u3001\u9694\u79BB worktree \u4E2D\u7684\u5019\u9009\u7248\u672C\u89C6\u4E3A N+1 \u4EE3\uFF1B\u7981\u6B62\u8BBE\u8BA1\u8FDB\u7A0B\u5185\u70ED\u66FF\u6362\u3002`,
     plannerClarifySystem: `\u4F60\u662F XCompiler V \u6A21\u578B\u7684\u9700\u6C42\u5206\u6790\u5E08\u3002\u4F60\u7684\u804C\u8D23\u4E0D\u662F\u590D\u8FF0 topic\uFF0C\u800C\u662F\u53D1\u73B0\u4F1A\u6539\u53D8\u529F\u80FD\u8BBE\u8BA1\u3001\u9A8C\u6536\u7ED3\u679C\u6216\u67B6\u6784\u8FB9\u754C\u7684\u672A\u51B3\u4E8B\u9879\u3002
-\u53EA\u8FD4\u56DE\u4E25\u683C JSON\u3002\u95EE\u9898\u5FC5\u987B\u53EF\u7531\u4E1A\u52A1\u65B9\u76F4\u63A5\u4F5C\u7B54\u3001\u4E00\u6B21\u53EA\u786E\u8BA4\u4E00\u4E2A\u51B3\u7B56\uFF0C\u907F\u514D\u7A7A\u6CDB\u7684\u201C\u8FD8\u6709\u4EC0\u4E48\u8981\u6C42\u201D\u6216\u6280\u672F\u6808\u9009\u578B\u95EE\u9898\u3002`,
+\u53EA\u8FD4\u56DE\u4E25\u683C JSON\u3002\u95EE\u9898\u5FC5\u987B\u53EF\u7531\u4E1A\u52A1\u65B9\u76F4\u63A5\u4F5C\u7B54\u3001\u4E00\u6B21\u53EA\u786E\u8BA4\u4E00\u4E2A\u51B3\u7B56\uFF0C\u907F\u514D\u7A7A\u6CDB\u7684\u201C\u8FD8\u6709\u4EC0\u4E48\u8981\u6C42\u201D\u6216\u6280\u672F\u6808\u9009\u578B\u95EE\u9898\uFF1B\u53EA\u6709\u7528\u6237\u63D0\u793A\u660E\u786E\u8981\u6C42\u65F6\uFF0C\u624D\u5141\u8BB8\u63D0\u51FA\u552F\u4E00\u4E00\u6761\u5F00\u53D1\u8BED\u8A00\u786E\u8BA4\u95EE\u9898\u3002`,
     plannerClarify: (raw, opts = {}) => `\u7528\u6237\u7684\u539F\u59CB\u9700\u6C42\u5982\u4E0B\uFF1A
 
 """
@@ -1906,12 +1917,13 @@ ${raw}
 - \u9009\u9879\u4ECE A \u5F00\u59CB\u8FDE\u7EED\u6807\u53F7\uFF0C\u5230\u5B9E\u9645\u6700\u540E\u4E00\u4E2A\u9009\u9879\u7ED3\u675F\uFF0C\u4F8B\u5982 A-B\u3001A-C\u3001A-D \u6216 A-E\uFF1B\u5982\u679C\u80FD\u5224\u65AD\u63A8\u8350/\u9ED8\u8BA4\u65B9\u6848\uFF0CA \u5E94\u662F\u6700\u9AD8\u4F18\u5148\u7EA7\u65B9\u6848\u3002\u9009\u9879\u5FC5\u987B\u662F\u5177\u4F53\u4E1A\u52A1/\u4EA7\u54C1\u8BBE\u5B9A\uFF0C\u4E0D\u8981\u5199\u6210\u7A7A\u6CDB\u5360\u4F4D\u3002
 - \u4E0D\u8981\u628A\u201C\u5176\u4ED6 / \u81EA\u5B9A\u4E49 / \u7528\u6237\u51B3\u5B9A\u201D\u4F5C\u4E3A\u9009\u9879\uFF1BCLI \u5DF2\u652F\u6301\u7528\u6237\u8F93\u5165\u5DF2\u5C55\u793A\u7684\u9009\u9879\u5B57\u6BCD\u6216\u76F4\u63A5\u8F93\u5165\u81EA\u5B9A\u4E49\u56DE\u7B54\u5185\u5BB9\u3002
 ${opts.projectShapeAmbiguous ? "- \u672C topic \u5FC5\u95EE\uFF1A\u660E\u786E\u786E\u8BA4 API library / \u53EF\u8FD0\u884C\u5E94\u7528 / mixed \u4EA4\u4ED8\u8FB9\u754C\u3002\n" : ""}
+${opts.languageAmbiguous ? "- \u672C topic \u5FC5\u95EE\uFF1A\u5FC5\u987B\u5305\u542B\u4E14\u53EA\u5305\u542B 1 \u4E2A boundary \u95EE\u9898\u786E\u8BA4\u76EE\u6807\u5F00\u53D1\u8BED\u8A00\u3002\u9009\u9879\u5FC5\u987B\u662F A. Python\uFF08\u9ED8\u8BA4/\u63A8\u8350\uFF09 \u548C B. TypeScript / Node.js\uFF1B\u7528\u6237\u4ECD\u53EF\u8F93\u5165\u81EA\u5B9A\u4E49\u56DE\u7B54\u3002\n" : ""}
 
-\u3010\u786C\u7EA6\u675F\u3011\u5B9E\u73B0\u6280\u672F\u6808\u5DF2\u7ECF\u7531 XCompiler \u914D\u7F6E / \u73B0\u6709\u5DE5\u7A0B\u57FA\u7EBF\u56FA\u5B9A\uFF0C\u4E0D\u8981\u91CD\u65B0\u8BE2\u95EE\u8BED\u8A00\u3001\u8FD0\u884C\u65F6\u3001\u5305\u7BA1\u7406\u5668\u8FD9\u7C7B\u95EE\u9898\u3002
+${opts.languageAmbiguous ? `\u3010\u6280\u672F\u6808\u786E\u8BA4\u3011XCompiler \u65E0\u6CD5\u4ECE topic \u6216\u57FA\u7EBF\u4E2D\u5224\u65AD\u76EE\u6807\u5F00\u53D1\u8BED\u8A00\u3002\u53EA\u8BE2\u95EE\u4E0A\u9762\u8981\u6C42\u7684\u5F00\u53D1\u8BED\u8A00\u95EE\u9898\uFF1B\u4E0D\u8981\u8BE2\u95EE\u5305\u7BA1\u7406\u5668\u3001\u6D4B\u8BD5\u6846\u67B6\u6216\u64CD\u4F5C\u7CFB\u7EDF\u3002\u82E5\u7528\u6237\u4E0D\u9009\u62E9\uFF0C\u9ED8\u8BA4 Python\u3002` : `\u3010\u786C\u7EA6\u675F\u3011\u5B9E\u73B0\u6280\u672F\u6808\u5DF2\u7ECF\u7531\u7528\u6237 topic / \u73B0\u6709\u5DE5\u7A0B\u57FA\u7EBF\u56FA\u5B9A\uFF0C\u4E0D\u8981\u91CD\u65B0\u8BE2\u95EE\u8BED\u8A00\u3001\u8FD0\u884C\u65F6\u3001\u5305\u7BA1\u7406\u5668\u8FD9\u7C7B\u95EE\u9898\u3002
 **\u4E25\u7981**\u63D0\u51FA\u4EE5\u4E0B\u7C7B\u578B\u7684\u95EE\u9898\uFF1A
   - "\u5E0C\u671B\u7528\u4EC0\u4E48\u7F16\u7A0B\u8BED\u8A00 / \u6846\u67B6 / \u8FD0\u884C\u65F6\u5B9E\u73B0\uFF1F"
   - "\u9700\u8981\u54EA\u79CD\u6D4B\u8BD5\u6846\u67B6 / \u6784\u5EFA\u5DE5\u5177 / \u5305\u7BA1\u7406\u5668\uFF1F"
-  - "\u76EE\u6807\u5E73\u53F0\u662F\u54EA\u79CD\u64CD\u4F5C\u7CFB\u7EDF\uFF1F"
+  - "\u76EE\u6807\u5E73\u53F0\u662F\u54EA\u79CD\u64CD\u4F5C\u7CFB\u7EDF\uFF1F"`}
 ${opts.intent && opts.intent !== "greenfield" ? `\u8FD9\u662F\u4E00\u6761\u9488\u5BF9\u73B0\u6709\u5DE5\u7A0B\u7684\u589E\u91CF ${opts.intent} \u8BF7\u6C42${opts.hasBaseline ? "\uFF1B\u5206\u89E3\u9636\u6BB5\u8FD8\u4F1A\u63D0\u4F9B\u4E00\u4EFD\u57FA\u7EBF\u6458\u8981" : ""}\u3002\u8BF7\u53EA\u95EE\u201C\u53D8\u66F4\u589E\u91CF\u201D\u76F8\u5173\u95EE\u9898\uFF0C\u4E0D\u8981\u628A\u9879\u76EE\u5F53\u6210\u4ECE\u96F6\u5F00\u59CB\u91CD\u505A\u3002` : ""}\u95EE\u9898\u4E3B\u4F53\u5FC5\u987B\u805A\u7126\u529F\u80FD\u884C\u4E3A\uFF1B\u6027\u80FD\u3001\u8FB9\u754C\u548C\u6269\u5C55\u6027\u7528\u4E8E\u6D88\u9664\u4F1A\u5F71\u54CD\u672C\u671F\u8BBE\u8BA1\u7684\u5173\u952E\u6B67\u4E49\u3002`,
     plannerDecompose: (raw, qa, addenda, opts = {}) => `\u539F\u59CB\u9700\u6C42\uFF1A
 """
@@ -2013,7 +2025,7 @@ ${opts.phasePlan}
     executorDebugBlock: (reason, suggestions) => `
 
 \u6B63\u5904\u4E8E DEBUG \u91CD\u8BD5\u6A21\u5F0F\u3002\u4E0A\u4E00\u8F6E\u5931\u8D25\u539F\u56E0: ${reason}
-DEBUG \u53EF\u4EE5\u4FEE\u6539\u5F53\u524D allowedWrites \u5185\u7684\u4E0A\u6E38\u6E90\u7801\u4E0E\u6D4B\u8BD5\u6587\u4EF6\uFF1B\u82E5\u5931\u8D25\u66B4\u9732\u7684\u662F\u5B9E\u73B0\u3001\u5951\u7EA6\u6216\u4E0B\u6E38\u8C03\u7528\u4E0D\u4E00\u81F4\uFF0C\u5FC5\u987B\u4FEE\u771F\u5B9E\u7F3A\u9677\uFF0C\u7981\u6B62\u901A\u8FC7\u524A\u5F31\u65AD\u8A00\u3001\u8DF3\u8FC7\u6D4B\u8BD5\u3001\u5220\u9664\u5931\u8D25\u7528\u4F8B\u6216\u53EA\u8FCE\u5408\u9519\u8BEF\u6D4B\u8BD5\u6765\u8FC7\u5173\u3002\u5982\u679C\u672C\u6B21\u56DE\u9000\u5904\u4E8E\u9700\u6C42/\u8BBE\u8BA1\u9636\u6BB5\uFF0C\u800C\u5177\u4F53\u6E90\u7801\u4FEE\u6539\u5C5E\u4E8E\u540E\u7EED V \u6A21\u578B Step \u4E14\u76EE\u6807\u6587\u4EF6\u4E0D\u5728\u5F53\u524D allowedWrites \u5185\uFF0C\u5E94\u66F4\u65B0\u5F53\u524D\u5951\u7EA6\u3001\u6D4B\u8BD5\u8BA1\u5212\u6216\u8BCA\u65AD\u4EA7\u7269\u5E76\u5B8C\u6210\u5F53\u524D Step\uFF0C\u8BA9\u540E\u7EED CODE Step \u5B9E\u73B0\uFF1B\u4E0D\u8981\u5C1D\u8BD5\u88AB\u62D2\u7EDD\u7684\u8D8A\u6743\u5199\u5165\u3002\u82E5\u5931\u8D25\u662F\u7B2C\u4E09\u65B9\u4F9D\u8D56\u7F3A\u5931\u6216\u5E93\u9009\u578B\u9519\u8BEF\uFF0C\u5FC5\u987B\u7528 add_dependency \u5199\u5165\u771F\u5B9E\u5305\u540D\uFF0C\u6216\u628A\u6E90\u7801\u6539\u56DE HIGH_LEVEL_DESIGN \u9009\u5B9A\u7684\u771F\u5B9E\u5E93\uFF1B\u4E25\u7981\u5728 src/ \u751F\u4EA7\u4EE3\u7801\u91CC try/except ImportError \u540E\u4F2A\u9020 module\u3001fake class/function\u3001\u7A7A\u5B9E\u73B0\u6216 fallback mock \u6765\u7ED5\u8FC7\u9519\u8BEF\u3002\u8BF7\u5305\u542B read_file/code_search \u5148\u5B9A\u4F4D\u95EE\u9898\uFF0C\u518D\u4EE5 apply_patch / replace_in_file / add_dependency \u4F5C\u6700\u5C0F\u4FEE\u6539\uFF0C\u6700\u540E run_tests \u9A8C\u8BC1\u3002DEBUG \u91CD\u8BD5\u4E0D\u80FD\u53EA\u9760\u53EA\u8BFB\u68C0\u67E5\u5C31\u6807\u8BB0\u5B8C\u6210\uFF1A\u672C\u6B21\u91CD\u8BD5\u5FC5\u987B\u4EA7\u751F\u4E00\u6B21\u6210\u529F\u7684\u4FEE\u590D\u52A8\u4F5C\uFF0C\u6216\u4E00\u6B21\u6210\u529F\u7684\u9A8C\u8BC1\u547D\u4EE4\u3002\u5982\u679C\u4E0A\u4E00\u8F6E\u5931\u8D25\u539F\u56E0\u5305\u542B repeated read-only/probe actions\uFF0C\u8BF7\u628A\u5DF2\u6709 failure log \u89C6\u4E3A\u8DB3\u591F\u4E0A\u4E0B\u6587\uFF0C\u4E0B\u4E00\u6B65\u76F4\u63A5 patch/write/\u6539\u4F9D\u8D56\u6216\u6267\u884C\u9A8C\u8BC1\u547D\u4EE4\u3002\u5F53\u6D4B\u8BD5\u5DF2\u6B63\u5E38\u6267\u884C\u4F46\u5931\u8D25\u70B9\u662F\u8FD4\u56DE\u884C\u4E3A\u65AD\u8A00\u65F6\uFF0C\u7981\u6B62\u53CD\u590D\u91CD\u5199 fixture \u6216\u6837\u4F8B\u3002\u53EA\u6709\u8BC1\u636E\u660E\u786E\u662F\u6587\u4EF6\u7F3A\u5931\u3001fixture \u683C\u5F0F\u9519\u8BEF\u6216 fixture \u672C\u8EAB\u89E3\u6790\u5931\u8D25\u65F6\u624D\u4FEE\u6539 fixture\uFF1B\u5426\u5219\u5E94\u4FEE\u5B9E\u73B0\u3001\u63A5\u53E3\u5951\u7EA6\u3001\u4F9D\u8D56\u9009\u578B\u6216\u786E\u5B9E\u9519\u8BEF\u7684\u65AD\u8A00\u3002\u5982\u679C\u5931\u8D25\u65E5\u5FD7\u663E\u793A\u7F51\u7EDC/API \u8C03\u7528\u5931\u8D25\uFF0C\u4E0D\u5141\u8BB8\u53EA\u505C\u7559\u5728\u63A2\u6D4B\u63A5\u53E3\uFF1A\u6700\u591A\u8FDE\u7EED\u6267\u884C 2 \u6B21 http_fetch \u63A2\u6D4B\uFF1BHTTP 2xx \u4F46 body \u4E3A\u7A7A\u6216\u683C\u5F0F\u4E0D\u53EF\u7528\u4E0D\u7B97\u53EF\u7528\u63A5\u53E3\uFF1B\u968F\u540E\u5FC5\u987B patch \u771F\u5B9E\u96C6\u6210\u4EE3\u7801\uFF0C\u5E76\u7528 run_program \u548C run_tests \u9A8C\u8BC1\u3002\u5165\u53E3\u4ECD\u8F93\u51FA\u7F51\u7EDC/API \u5931\u8D25\u65F6\u4E0D\u5F97 done=true\u3002` + (suggestions ? `
+\u5F53\u672C\u6B21 DEBUG \u6B63\u5728\u5904\u7406 issue \u65F6\uFF0C\u6BCF\u4E00\u8F6E JSON \u90FD\u5FC5\u987B\u5728\u4FEE\u590D\u524D\u6216\u4FEE\u590D\u8FC7\u7A0B\u4E2D\u989D\u5916\u5305\u542B issueResolutionPlan\u3002\u8BE5\u65B9\u6848\u5FC5\u987B\u7B80\u6D01\u4E14\u53EF\u6267\u884C\uFF1A\u6839\u56E0\u5047\u8BBE\u3001\u8981\u4FEE\u6539\u7684\u6587\u4EF6/\u5951\u7EA6\u3001\u9A8C\u8BC1\u547D\u4EE4\u6216\u95E8\u7981\uFF0C\u4EE5\u53CA\u4EC0\u4E48\u8BC1\u636E\u4F1A\u63A8\u7FFB\u8BE5\u65B9\u6848\u3002DEBUG \u53EF\u4EE5\u4FEE\u6539\u5F53\u524D allowedWrites \u5185\u7684\u4E0A\u6E38\u6E90\u7801\u4E0E\u6D4B\u8BD5\u6587\u4EF6\uFF1B\u82E5\u5931\u8D25\u66B4\u9732\u7684\u662F\u5B9E\u73B0\u3001\u5951\u7EA6\u6216\u4E0B\u6E38\u8C03\u7528\u4E0D\u4E00\u81F4\uFF0C\u5FC5\u987B\u4FEE\u771F\u5B9E\u7F3A\u9677\uFF0C\u7981\u6B62\u901A\u8FC7\u524A\u5F31\u65AD\u8A00\u3001\u8DF3\u8FC7\u6D4B\u8BD5\u3001\u5220\u9664\u5931\u8D25\u7528\u4F8B\u6216\u53EA\u8FCE\u5408\u9519\u8BEF\u6D4B\u8BD5\u6765\u8FC7\u5173\u3002\u5982\u679C\u672C\u6B21\u56DE\u9000\u5904\u4E8E\u9700\u6C42/\u8BBE\u8BA1\u9636\u6BB5\uFF0C\u800C\u5177\u4F53\u6E90\u7801\u4FEE\u6539\u5C5E\u4E8E\u540E\u7EED V \u6A21\u578B Step \u4E14\u76EE\u6807\u6587\u4EF6\u4E0D\u5728\u5F53\u524D allowedWrites \u5185\uFF0C\u5E94\u66F4\u65B0\u5F53\u524D\u5951\u7EA6\u3001\u6D4B\u8BD5\u8BA1\u5212\u6216\u8BCA\u65AD\u4EA7\u7269\u5E76\u5B8C\u6210\u5F53\u524D Step\uFF0C\u8BA9\u540E\u7EED CODE Step \u5B9E\u73B0\uFF1B\u4E0D\u8981\u5C1D\u8BD5\u88AB\u62D2\u7EDD\u7684\u8D8A\u6743\u5199\u5165\u3002\u82E5\u5931\u8D25\u662F\u7B2C\u4E09\u65B9\u4F9D\u8D56\u7F3A\u5931\u6216\u5E93\u9009\u578B\u9519\u8BEF\uFF0C\u5FC5\u987B\u7528 add_dependency \u5199\u5165\u771F\u5B9E\u5305\u540D\uFF0C\u6216\u628A\u6E90\u7801\u6539\u56DE HIGH_LEVEL_DESIGN \u9009\u5B9A\u7684\u771F\u5B9E\u5E93\uFF1B\u4E25\u7981\u5728 src/ \u751F\u4EA7\u4EE3\u7801\u91CC try/except ImportError \u540E\u4F2A\u9020 module\u3001fake class/function\u3001\u7A7A\u5B9E\u73B0\u6216 fallback mock \u6765\u7ED5\u8FC7\u9519\u8BEF\u3002\u8BF7\u5305\u542B read_file/code_search \u5148\u5B9A\u4F4D\u95EE\u9898\uFF0C\u518D\u4EE5 apply_patch / replace_in_file / add_dependency \u4F5C\u6700\u5C0F\u4FEE\u6539\uFF0C\u6700\u540E run_tests \u9A8C\u8BC1\u3002DEBUG \u91CD\u8BD5\u4E0D\u80FD\u53EA\u9760\u53EA\u8BFB\u68C0\u67E5\u5C31\u6807\u8BB0\u5B8C\u6210\uFF1A\u672C\u6B21\u91CD\u8BD5\u5FC5\u987B\u4EA7\u751F\u4E00\u6B21\u6210\u529F\u7684\u4FEE\u590D\u52A8\u4F5C\uFF0C\u6216\u4E00\u6B21\u6210\u529F\u7684\u9A8C\u8BC1\u547D\u4EE4\u3002\u5982\u679C\u4E0A\u4E00\u8F6E\u5931\u8D25\u539F\u56E0\u5305\u542B repeated read-only/probe actions\uFF0C\u8BF7\u628A\u5DF2\u6709 failure log \u89C6\u4E3A\u8DB3\u591F\u4E0A\u4E0B\u6587\uFF0C\u4E0B\u4E00\u6B65\u76F4\u63A5 patch/write/\u6539\u4F9D\u8D56\u6216\u6267\u884C\u9A8C\u8BC1\u547D\u4EE4\u3002\u5F53\u6D4B\u8BD5\u5DF2\u6B63\u5E38\u6267\u884C\u4F46\u5931\u8D25\u70B9\u662F\u8FD4\u56DE\u884C\u4E3A\u65AD\u8A00\u65F6\uFF0C\u7981\u6B62\u53CD\u590D\u91CD\u5199 fixture \u6216\u6837\u4F8B\u3002\u53EA\u6709\u8BC1\u636E\u660E\u786E\u662F\u6587\u4EF6\u7F3A\u5931\u3001fixture \u683C\u5F0F\u9519\u8BEF\u6216 fixture \u672C\u8EAB\u89E3\u6790\u5931\u8D25\u65F6\u624D\u4FEE\u6539 fixture\uFF1B\u5426\u5219\u5E94\u4FEE\u5B9E\u73B0\u3001\u63A5\u53E3\u5951\u7EA6\u3001\u4F9D\u8D56\u9009\u578B\u6216\u786E\u5B9E\u9519\u8BEF\u7684\u65AD\u8A00\u3002\u5982\u679C\u5931\u8D25\u65E5\u5FD7\u663E\u793A\u7F51\u7EDC/API \u8C03\u7528\u5931\u8D25\uFF0C\u4E0D\u5141\u8BB8\u53EA\u505C\u7559\u5728\u63A2\u6D4B\u63A5\u53E3\uFF1A\u6700\u591A\u8FDE\u7EED\u6267\u884C 2 \u6B21 http_fetch \u63A2\u6D4B\uFF1BHTTP 2xx \u4F46 body \u4E3A\u7A7A\u6216\u683C\u5F0F\u4E0D\u53EF\u7528\u4E0D\u7B97\u53EF\u7528\u63A5\u53E3\uFF1B\u968F\u540E\u5FC5\u987B patch \u771F\u5B9E\u96C6\u6210\u4EE3\u7801\uFF0C\u5E76\u7528 run_program \u548C run_tests \u9A8C\u8BC1\u3002\u5165\u53E3\u4ECD\u8F93\u51FA\u7F51\u7EDC/API \u5931\u8D25\u65F6\u4E0D\u5F97 done=true\u3002` + (suggestions ? `
 
 ${suggestions}` : ""),
     executorGlobalBlock: (globalPrompt) => `
@@ -2030,7 +2042,8 @@ ${sp}`,
     executorFeedbackVerifyMissing: (paths) => `outputs \u4ECD\u7F3A\u5931\uFF1A${paths}\u3002\u8BF7\u7EE7\u7EED\u3002`,
     executorFeedbackReadOnlyLoopWarning: (rounds, targets) => `\u5FAA\u73AF\u95E8\u7981\u8B66\u544A\uFF1A\u6700\u8FD1 ${rounds} \u8F6E\u53EA\u8C03\u7528\u4E86\u8BFB\u53D6/\u63A2\u6D4B\u5DE5\u5177` + (targets ? `\uFF08${targets}\uFF09` : "") + "\u3002\u4E0B\u4E00\u8F6E\u5FC5\u987B\u5305\u542B\u4E00\u6B21\u6210\u529F\u7684\u4FEE\u590D\u52A8\u4F5C\uFF08apply_patch / replace_in_file / write_file / add_dependency\uFF09\u6216\u660E\u786E\u7684\u9A8C\u8BC1\u52A8\u4F5C\uFF08run_tests / run_program\uFF09\u3002\u4E0D\u8981\u7EE7\u7EED\u53EA\u8C03\u7528 read_file\u3001list_dir\u3001code_search \u6216 http_fetch\u3002",
     executorFeedbackReadOnlyRecoveryRequired: "\u53EA\u8BFB\u6062\u590D\u6A21\u5F0F\u5DF2\u542F\u7528\uFF1A\u4E0A\u4E00\u8F6E\u5DF2\u7ECF\u56E0\u4E3A\u6301\u7EED\u63A2\u6D4B\u5931\u8D25\u3002\u672C\u8F6E\u5FC5\u987B\u57FA\u4E8E\u5DF2\u6709 failure log \u76F4\u63A5 patch/write/\u6539\u4F9D\u8D56\u6216\u6267\u884C\u9A8C\u8BC1\uFF1B\u5982\u679C\u4E0B\u4E00\u8F6E\u4ECD\u7136\u53EA\u6709\u53EA\u8BFB/\u63A2\u6D4B\u52A8\u4F5C\uFF0C\u672C\u6B21\u91CD\u8BD5\u4F1A\u5931\u8D25\u5E76\u56DE\u9000\u3002",
-    executorFeedbackRepairEvidenceMissing: "DEBUG \u5B8C\u6210\u65E0\u6548\uFF1A\u672C\u6B21\u91CD\u8BD5\u8FD8\u6CA1\u6709\u4EA7\u751F\u4FEE\u590D\u8BC1\u636E\u3002\u8BBE\u7F6E done=true \u524D\uFF0C\u5FC5\u987B\u81F3\u5C11\u5B8C\u6210\u4E00\u6B21\u6210\u529F\u7684\u4FEE\u590D\u52A8\u4F5C\u6216\u6210\u529F\u7684\u9A8C\u8BC1\u8FD0\u884C\uFF1B\u5426\u5219\u53EA\u80FD\u5728 thoughts \u4E2D\u7ED9\u51FA\u5177\u4F53 blocker \u540E\u505C\u6B62\u3002"
+    executorFeedbackRepairEvidenceMissing: "DEBUG \u5B8C\u6210\u65E0\u6548\uFF1A\u672C\u6B21\u91CD\u8BD5\u8FD8\u6CA1\u6709\u4EA7\u751F\u4FEE\u590D\u8BC1\u636E\u3002\u8BBE\u7F6E done=true \u524D\uFF0C\u5FC5\u987B\u81F3\u5C11\u5B8C\u6210\u4E00\u6B21\u6210\u529F\u7684\u4FEE\u590D\u52A8\u4F5C\u6216\u6210\u529F\u7684\u9A8C\u8BC1\u8FD0\u884C\uFF1B\u5426\u5219\u53EA\u80FD\u5728 thoughts \u4E2D\u7ED9\u51FA\u5177\u4F53 blocker \u540E\u505C\u6B62\u3002",
+    executorFeedbackIssueResolutionPlanMissing: "DEBUG issue \u5B8C\u6210\u65E0\u6548\uFF1AissueResolutionPlan \u662F issue resolved \u7684\u5FC5\u8981\u5B57\u6BB5\u3002\u8BF7\u8FD4\u56DE\u5305\u542B\u7B80\u660E\u5904\u7406\u65B9\u6848\u7684 JSON\uFF0C\u5E76\u540C\u65F6\u7ED9\u51FA\u5FC5\u8981\u4FEE\u590D\u6216\u9A8C\u8BC1\u52A8\u4F5C\u3002"
   },
   skills: {
     patcher: "\u901A\u8FC7 apply_patch / replace_in_file \u5BF9\u5DF2\u6709\u6587\u4EF6\u505A\u5C0F\u6539\u52A8\uFF0C\u7981\u6B62\u6574\u6587\u4EF6\u8986\u76D6\u3002",
@@ -2051,7 +2064,7 @@ ${sp}`,
     summaryOk: "\u5168\u90E8\u68C0\u67E5\u901A\u8FC7\u3002",
     summaryWarn: (n) => `\u901A\u8FC7\uFF0C\u4F46\u6709 ${n} \u6761 warning\u3002`,
     summaryFail: (n) => `\u68C0\u6D4B\u5230 ${n} \u9879\u5931\u8D25\u3002`,
-    configLoadOk: (path30) => `\u914D\u7F6E\u5DF2\u52A0\u8F7D\uFF1A${path30}`,
+    configLoadOk: (path31) => `\u914D\u7F6E\u5DF2\u52A0\u8F7D\uFF1A${path31}`,
     configLoadFail: (msg) => `\u914D\u7F6E\u52A0\u8F7D\u5931\u8D25\uFF1A${msg}`,
     configLocale: (locale) => `locale=${locale}`,
     llmNoProviders: "config.llm.providers \u4E3A\u7A7A\uFF0C\u672A\u58F0\u660E\u4EFB\u4F55 provider",
@@ -2069,7 +2082,7 @@ ${sp}`,
     roleOk: (role, provider) => `\u89D2\u8272 "${role}" \u2192 ${provider}`,
     sandboxKind: (kind) => `sandbox=${kind}`,
     sandboxNetworkPolicy: (policy, ports) => `network=${policy}` + (ports.length ? `\uFF08expose_ports=[${ports.join(", ")}]\uFF09` : ""),
-    sandboxFullNoPorts: "network=full \u4F46\u672A\u914D\u7F6E expose_ports\u2014\u5BBF\u4E3B\u4FA7\u65E0\u6CD5\u8BBF\u95EE\u5BB9\u5668\u5185\u670D\u52A1\u3002\u8BF7\u5728 config.yaml \u4E2D\u8BBE\u7F6E `agent.sandbox_limits.expose_ports: [<port>]`\u3002",
+    sandboxFullNoPorts: "network=full \u4F46\u672A\u914D\u7F6E expose_ports\u2014\u5BBF\u4E3B\u4FA7\u65E0\u6CD5\u8BBF\u95EE\u5BB9\u5668\u5185\u670D\u52A1\u3002\u8BF7\u5728 config.yaml \u4E2D\u8BBE\u7F6E `agent.sandboxes.<language>.<local|docker>.limits.expose_ports: [<port>]`\u3002",
     sandboxNodeMissing: "PATH \u4E0A\u627E\u4E0D\u5230 node\uFF08TypeScript subprocess \u6C99\u76D2\u5FC5\u9700\uFF09",
     sandboxNodeOk: (version) => `node OK\uFF08${version}\uFF09`,
     sandboxNpmMissing: "PATH \u4E0A\u627E\u4E0D\u5230 npm\uFF08TypeScript subprocess \u6C99\u76D2\u5FC5\u9700\uFF09",
@@ -2131,8 +2144,10 @@ function detectNetworkApiFailure(text) {
 function isTestAssertionDiagnosticLine(line) {
   const text = line.trim();
   if (!text) return false;
+  if (/^\d+\|\s/u.test(text)) return true;
   if (/^(?:[→>-]\s*)?expected\b/iu.test(text)) return true;
   if (/\bAssertionError\b/iu.test(text) && /\bexpected\b/iu.test(text)) return true;
+  if (/\bexpect\s*\(/u.test(text) && /\.(?:to|not)\w*\s*\(/u.test(text)) return true;
   return /\bexpected\b[\s\S]{0,240}\b(?:got|received|to\s+(?:be|equal|throw|contain|have|match))\b/iu.test(text);
 }
 function isTestRunnerStatusLine(line) {
@@ -2179,8 +2194,8 @@ async function autoFixSrcImports(ws, audit) {
   const candidates = [];
   if (await ws.exists("src/main.py")) candidates.push("src/main.py");
   try {
-    const fs27 = await import("fs/promises");
-    const entries = await fs27.readdir(ws.abs("src"), { withFileTypes: true });
+    const fs29 = await import("fs/promises");
+    const entries = await fs29.readdir(ws.abs("src"), { withFileTypes: true });
     for (const e of entries) {
       if (!e.isDirectory()) continue;
       const rel = `src/${e.name}/__main__.py`;
@@ -2331,8 +2346,8 @@ async function detectPythonEntrypoint(ws) {
   if (await ws.exists("src/main.py")) return fileCandidate("src/main.py");
   if (await ws.exists("src/__main__.py")) return fileCandidate("src/__main__.py");
   try {
-    const fs27 = await import("fs/promises");
-    const entries = await fs27.readdir(ws.abs("src"), { withFileTypes: true });
+    const fs29 = await import("fs/promises");
+    const entries = await fs29.readdir(ws.abs("src"), { withFileTypes: true });
     for (const e of entries) {
       if (!e.isDirectory()) continue;
       const rel = `src/${e.name}/__main__.py`;
@@ -2391,7 +2406,7 @@ var typescriptProfile = {
   manifestFile: "package.json",
   codeExtensions: [".ts", ".tsx"],
   seedManifestFromDeps: false,
-  defaultDockerImage: "node:20-slim",
+  defaultDockerImage: "node:24-slim",
   renderManifest(deps) {
     const pkg = {
       name: "app",
@@ -2420,6 +2435,9 @@ var typescriptProfile = {
   },
   plannerPromptOverride: "",
   executorPromptOverride: "",
+  async autoFixImports(ws, audit) {
+    return autoFixTypeScriptTypeOnlyImports(ws, audit);
+  },
   async probeEntry(ws, sandbox) {
     return probeTsEntrypoint(ws, sandbox);
   }
@@ -2569,6 +2587,99 @@ async function readJsonFile(ws, rel) {
     return null;
   }
 }
+var TYPE_ONLY_IMPORTS_BY_PACKAGE = {
+  axios: /* @__PURE__ */ new Set([
+    "AxiosAdapter",
+    "AxiosBasicCredentials",
+    "AxiosHeaderValue",
+    "AxiosInstance",
+    "AxiosInterceptorManager",
+    "AxiosPromise",
+    "AxiosProxyConfig",
+    "AxiosRequestConfig",
+    "AxiosRequestHeaders",
+    "AxiosResponse",
+    "AxiosResponseHeaders",
+    "CreateAxiosDefaults",
+    "InternalAxiosRequestConfig",
+    "RawAxiosRequestHeaders"
+  ])
+};
+async function autoFixTypeScriptTypeOnlyImports(ws, audit) {
+  const files = await listTypeScriptSourceFiles(ws, "src");
+  const fixed = [];
+  for (const rel of files) {
+    const original = await ws.readFile(rel);
+    const next = rewriteKnownTypeOnlyImports(original);
+    if (next === original) continue;
+    await ws.writeFile(rel, next);
+    fixed.push(rel);
+    await audit.event("note", `fixed type-only imports in ${rel}`, {
+      messageId: "audit.typescript_imports_autofix",
+      path: rel
+    });
+  }
+  return fixed;
+}
+async function listTypeScriptSourceFiles(ws, dir) {
+  const abs = ws.abs(dir);
+  let entries;
+  try {
+    entries = await fs.readdir(abs, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const rel = `${dir}/${entry.name}`.replace(/\\/g, "/");
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      files.push(...await listTypeScriptSourceFiles(ws, rel));
+    } else if (entry.isFile() && /\.tsx?$/.test(entry.name)) {
+      files.push(rel);
+    }
+  }
+  return files.sort();
+}
+function rewriteKnownTypeOnlyImports(source) {
+  const importRe = /^import\s+([^'"\n]+?)\s+from\s+(['"])([^'"]+)\2\s*;?$/gm;
+  return source.replace(importRe, (full, clauseRaw, quote, specifier) => {
+    const knownTypes = TYPE_ONLY_IMPORTS_BY_PACKAGE[specifier];
+    if (!knownTypes) return full;
+    if (clauseRaw.trim().startsWith("type ")) return full;
+    const parsed = splitImportClause(clauseRaw);
+    if (!parsed?.named.length) return full;
+    const valueNamed = [];
+    const typeNamed = [];
+    for (const item of parsed.named) {
+      const importedName = item.replace(/^type\s+/u, "").split(/\s+as\s+/iu)[0]?.trim() ?? "";
+      if (knownTypes.has(importedName)) typeNamed.push(item.replace(/^type\s+/u, "").trim());
+      else valueNamed.push(item);
+    }
+    if (typeNamed.length === 0) return full;
+    const lines = [];
+    if (parsed.defaultImport && valueNamed.length > 0) {
+      lines.push(`import ${parsed.defaultImport}, { ${valueNamed.join(", ")} } from ${quote}${specifier}${quote};`);
+    } else if (parsed.defaultImport) {
+      lines.push(`import ${parsed.defaultImport} from ${quote}${specifier}${quote};`);
+    } else if (valueNamed.length > 0) {
+      lines.push(`import { ${valueNamed.join(", ")} } from ${quote}${specifier}${quote};`);
+    }
+    lines.push(`import type { ${typeNamed.join(", ")} } from ${quote}${specifier}${quote};`);
+    return lines.join("\n");
+  });
+}
+function splitImportClause(clauseRaw) {
+  const clause = clauseRaw.trim();
+  const namedMatch = clause.match(/\{([\s\S]*)\}$/u);
+  if (!namedMatch) return void 0;
+  const beforeNamed = clause.slice(0, namedMatch.index).replace(/,\s*$/u, "").trim();
+  const named = (namedMatch[1] ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+  return {
+    defaultImport: beforeNamed || void 0,
+    named
+  };
+}
 
 // src/core/architecture.ts
 var COMPLEXITY_SURFACES = [
@@ -2760,7 +2871,7 @@ function validateArchitectureContract(modules, steps, language, demand) {
       }
       allTestPaths.add(testPath);
     }
-    const owners = codeSteps.filter((step) => module.sourcePaths.every((path30) => pathCoveredByOutputs(path30, step.outputs))).sort((a, b) => (stepIndex.get(a.id) ?? 0) - (stepIndex.get(b.id) ?? 0));
+    const owners = codeSteps.filter((step) => module.sourcePaths.every((path31) => pathCoveredByOutputs(path31, step.outputs))).sort((a, b) => (stepIndex.get(a.id) ?? 0) - (stepIndex.get(b.id) ?? 0));
     if (owners.length === 0) {
       issues.push({
         message: `${module.id} must map all sourcePaths to a CODE macro step; found 0.`
@@ -2790,7 +2901,7 @@ function validateArchitectureContract(modules, steps, language, demand) {
     ownedModules.push(module);
     modulesByCodeOwner.set(codeOwner.id, ownedModules);
     const matchingTests = testSteps.filter(
-      (step) => module.testPaths.some((path30) => pathCoveredByOutputs(path30, step.outputs))
+      (step) => module.testPaths.some((path31) => pathCoveredByOutputs(path31, step.outputs))
     );
     if (matchingTests.length === 0) {
       issues.push({ message: `${module.id} testPaths are not produced by any MODULE_TEST step.` });
@@ -2847,8 +2958,8 @@ function flattenSubTasks(step) {
   }
   return out;
 }
-function pathCoveredByOutputs(path30, outputs) {
-  const normalizedPath = normalizePath(path30);
+function pathCoveredByOutputs(path31, outputs) {
+  const normalizedPath = normalizePath(path31);
   return outputs.some((output) => {
     const normalizedOutput = normalizePath(output);
     return normalizedPath === normalizedOutput || normalizedPath.startsWith(`${normalizedOutput}/`);
@@ -2858,14 +2969,14 @@ function missingArchitectureDocumentTokens(content, modules) {
   const required = modules.flatMap((module) => [module.id, ...module.sourcePaths, ...module.testPaths]);
   return [...new Set(required)].filter((token) => !content.includes(token));
 }
-function isSourcePath(path30, extensions) {
-  return path30.startsWith("src/") && extensions.some((extension) => path30.endsWith(extension));
+function isSourcePath(path31, extensions) {
+  return path31.startsWith("src/") && extensions.some((extension) => path31.endsWith(extension));
 }
-function isTestPath(path30, extensions) {
-  return path30.startsWith("tests/") && extensions.some((extension) => path30.endsWith(extension));
+function isTestPath(path31, extensions) {
+  return path31.startsWith("tests/") && extensions.some((extension) => path31.endsWith(extension));
 }
-function normalizePath(path30) {
-  return path30.replace(/\\/g, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
+function normalizePath(path31) {
+  return path31.replace(/\\/g, "/").replace(/^\.\//u, "").replace(/\/+$/u, "");
 }
 function transitivelyDependsOn(step, targetId, byId) {
   const seen = /* @__PURE__ */ new Set();
@@ -3398,12 +3509,12 @@ function parseLoadedPlan(json) {
 }
 async function savePlan(planPath, plan) {
   PlanSchema.parse(plan);
-  await fs.mkdir(path3.dirname(planPath), { recursive: true });
-  await fs.writeFile(planPath, JSON.stringify(plan, null, 2) + "\n", "utf8");
+  await fs2.mkdir(path3.dirname(planPath), { recursive: true });
+  await fs2.writeFile(planPath, JSON.stringify(plan, null, 2) + "\n", "utf8");
 }
 async function loadPlanTarget(inputPath) {
   const requestedPath = path3.resolve(inputPath);
-  const raw = await fs.readFile(requestedPath, "utf8");
+  const raw = await fs2.readFile(requestedPath, "utf8");
   const json = JSON.parse(raw);
   const phasePlanResult = PhasePlanSchema.safeParse(json);
   if (phasePlanResult.success) {
@@ -3413,7 +3524,7 @@ async function loadPlanTarget(inputPath) {
       throw new Error(`phasePlan ${requestedPath} has no planPath for current phase ${phasePlan.currentPhaseId}`);
     }
     const planPath = path3.resolve(path3.dirname(requestedPath), phase.planPath);
-    const loaded2 = parseLoadedPlan(JSON.parse(await fs.readFile(planPath, "utf8")));
+    const loaded2 = parseLoadedPlan(JSON.parse(await fs2.readFile(planPath, "utf8")));
     return {
       plan: loaded2.plan,
       planPath,
@@ -3518,7 +3629,7 @@ async function findProjectFile(workspace) {
   const ws = path4.resolve(workspace);
   let entries;
   try {
-    entries = await fs2.readdir(ws, { withFileTypes: true });
+    entries = await fs3.readdir(ws, { withFileTypes: true });
   } catch {
     return void 0;
   }
@@ -3568,8 +3679,8 @@ async function updateProjectFile(opts) {
     history: nextHistory
   };
   XCompilerProjectFileSchema.parse(data);
-  await fs2.mkdir(path4.dirname(filePath), { recursive: true });
-  await fs2.writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+  await fs3.mkdir(path4.dirname(filePath), { recursive: true });
+  await fs3.writeFile(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
   return filePath;
 }
 function buildProjectProgress(plan) {
@@ -3612,7 +3723,7 @@ function buildProjectProgress(plan) {
 }
 async function readExistingProjectFile(filePath) {
   try {
-    const raw = await fs2.readFile(filePath, "utf8");
+    const raw = await fs3.readFile(filePath, "utf8");
     return XCompilerProjectFileSchema.parse(JSON.parse(raw));
   } catch {
     return void 0;
@@ -3642,10 +3753,10 @@ function assertProjectFileExtension(filePath) {
 
 // src/runtime/build.ts
 import path13 from "path";
-import { promises as fs11 } from "fs";
+import { promises as fs12 } from "fs";
 
 // src/config/config.ts
-import { promises as fs3 } from "fs";
+import { promises as fs4 } from "fs";
 import path5 from "path";
 import YAML from "yaml";
 import { z as z4 } from "zod";
@@ -3711,6 +3822,73 @@ var ProviderSchema = z4.object({
   think: z4.boolean().optional()
 });
 var LocaleSchema = z4.enum(["en", "zh"]);
+var TargetLanguageSchema = z4.enum(["python", "typescript"]);
+var SandboxModeSchema = z4.enum(["subprocess", "docker", "firejail"]);
+var SandboxLimitsSchema = z4.object({
+  cpu: z4.number().positive().default(1),
+  memory_mb: z4.number().int().positive().default(1024),
+  wall_seconds: z4.number().int().positive().default(60),
+  /**
+   * Sandbox network policy.
+   *  - `off`            — no network at all (`docker --network none`).
+   *  - `download-only`  — outbound traffic allowed, no inbound port publishing.
+   *  - `pypi-only`      — legacy value; rejected at sandbox creation rather than silently
+   *                       allowing unrestricted outbound traffic.
+   *  - `full`           — outbound + every port in `expose_ports` is published
+   *                       to `127.0.0.1` so host-side tests can reach the app.
+   */
+  network: z4.enum(["off", "pypi-only", "download-only", "full"]).default("download-only"),
+  /** Container ports to publish to 127.0.0.1 when `network=full`. */
+  expose_ports: z4.array(z4.number().int().min(1).max(65535)).default([])
+}).default({
+  cpu: 1,
+  memory_mb: 1024,
+  wall_seconds: 60,
+  network: "download-only",
+  expose_ports: []
+});
+var LocalSandboxSchema = z4.object({
+  sandbox_dir: z4.string().min(1).optional(),
+  python_bin: z4.string().min(1).optional(),
+  inherit_env: z4.boolean().optional(),
+  limits: SandboxLimitsSchema
+}).default(() => ({ limits: defaultSandboxLimits() }));
+var DockerSandboxSchema = z4.object({
+  image: z4.string().default("python:3.11-slim"),
+  workdir: z4.string().default("/workspace"),
+  pull: z4.boolean().default(false),
+  docker_bin: z4.string().default("docker"),
+  extra_run_args: z4.array(z4.string()).default([]),
+  sandbox_dir: z4.string().min(1).optional(),
+  limits: SandboxLimitsSchema
+}).default({
+  image: "python:3.11-slim",
+  workdir: "/workspace",
+  pull: false,
+  docker_bin: "docker",
+  extra_run_args: [],
+  limits: defaultSandboxLimits()
+});
+var LanguageSandboxSchema = z4.object({
+  mode: SandboxModeSchema.default("subprocess"),
+  local: LocalSandboxSchema,
+  docker: DockerSandboxSchema
+}).default(() => ({
+  mode: "subprocess",
+  local: { limits: defaultSandboxLimits() },
+  docker: {
+    image: "python:3.11-slim",
+    workdir: "/workspace",
+    pull: false,
+    docker_bin: "docker",
+    extra_run_args: [],
+    limits: defaultSandboxLimits()
+  }
+}));
+var SandboxesSchema = z4.object({
+  python: LanguageSandboxSchema.optional(),
+  typescript: LanguageSandboxSchema.optional()
+}).default({});
 var LlmSchema = z4.object({
   default: z4.string(),
   providers: z4.record(z4.string(), ProviderSchema),
@@ -3718,7 +3896,7 @@ var LlmSchema = z4.object({
    * 角色 → provider 数组的映射。
    * 兼容旧格式：单字符串 `Coder: ollama_code` 自动归一化为 `[ollama_code]`。
    * 数组形式 `Coder: [ollama_code, openai]` 表示该角色的候选 LLM 池；
-   * 实际选择顺序由 `llm.scores` 评分降序决定；用户显式设置评分=0 的 provider 直接跳过。
+   * 实际选择顺序由 ScoreStore 有效评分降序决定；有效评分为用户覆盖优先，否则使用动态评分。
    */
   roles: z4.record(z4.string(), z4.union([z4.string(), z4.array(z4.string())])).default({}).transform((obj) => {
     const out = {};
@@ -3732,9 +3910,8 @@ var LlmSchema = z4.object({
   /** 可选：按角色指定 fallback 链（覆盖全局） */
   role_fallbacks: z4.record(z4.string(), z4.array(z4.string())).default({}),
   /**
-   * Provider 评分快照（启动时从 sidecar 文件加载，运行时由 ScoreStore 维护并自动落盘）。
-   * 配置文件里也可以手工设置初始值；不存在的 provider 默认评分 = 1。
-   * 用户手工设置评分 = 0 表示禁用；运行时自动评分只在 0.1～1.0 范围内调整。
+   * Provider 兼容初值。运行时动态评分由 ScoreStore 写入 llm_scores.yaml；
+   * 用户手动覆盖应写入 llm_scores_user.yaml。旧配置里显式 0 仍表示用户禁用。
    */
   scores: z4.record(z4.string(), z4.number().min(0)).default({}),
   /**
@@ -3754,65 +3931,107 @@ var LlmSchema = z4.object({
     });
   }
 });
+var AgentSchema = z4.object({
+  /** @deprecated Target project language is inferred from topic/baseline. Kept for legacy configs only. */
+  language: TargetLanguageSchema.optional(),
+  max_steps: z4.number().int().positive().default(50),
+  max_debug_retries: z4.number().int().positive().default(3),
+  /** Debugger 滑动窗口的硬上限（默认 = max(max_debug_retries*4, 10)）。 */
+  max_debug_retries_cap: z4.number().int().positive().optional(),
+  max_rounds_per_step: z4.number().int().positive().default(6),
+  max_debug_rounds_per_step: z4.number().int().positive().optional(),
+  max_edit_lines_per_step: z4.union([z4.literal("auto"), z4.number().int().positive()]).default("auto"),
+  max_write_chunk_bytes: z4.union([z4.literal("auto"), z4.number().int().positive()]).default("auto"),
+  /** @deprecated Use agent.sandboxes.<language>.mode. */
+  sandbox: SandboxModeSchema.optional(),
+  /** @deprecated Use agent.sandboxes.<language>.<local|docker>.limits. */
+  sandbox_limits: SandboxLimitsSchema.optional(),
+  /** @deprecated Use agent.sandboxes.<language>.docker. */
+  sandbox_docker: DockerSandboxSchema.optional(),
+  sandboxes: SandboxesSchema
+}).transform((agent) => {
+  const legacyLanguage = agent.language ?? "python";
+  const legacyMode = agent.sandbox ?? "subprocess";
+  const legacyLimits = agent.sandbox_limits ?? defaultSandboxLimits();
+  const defaults = {
+    python: defaultLanguageSandbox("python", legacyMode, legacyLimits),
+    typescript: defaultLanguageSandbox("typescript", legacyMode, legacyLimits)
+  };
+  const sandboxes = {
+    python: mergeLanguageSandbox(
+      defaults.python,
+      agent.sandboxes.python,
+      legacyLanguage === "python" ? agent.sandbox_docker : void 0
+    ),
+    typescript: mergeLanguageSandbox(
+      defaults.typescript,
+      agent.sandboxes.typescript,
+      legacyLanguage === "typescript" ? agent.sandbox_docker : void 0
+    )
+  };
+  return {
+    ...agent,
+    language: legacyLanguage,
+    sandbox: sandboxes.python.mode,
+    sandbox_limits: sandboxes.python.local.limits,
+    sandbox_docker: sandboxes.python.docker,
+    sandboxes
+  };
+});
 var ConfigSchema = z4.object({
   /** CLI / prompt locale. Accepts 'en' (default) or 'zh'. */
   locale: LocaleSchema.optional(),
   /** @deprecated use `locale` instead. Kept as a backwards-compatible alias. */
   ui_language: LocaleSchema.optional(),
   llm: LlmSchema,
-  agent: z4.object({
-    language: z4.enum(["python", "typescript"]).default("python"),
-    max_steps: z4.number().int().positive().default(50),
-    max_debug_retries: z4.number().int().positive().default(3),
-    /** Debugger 滑动窗口的硬上限（默认 = max(max_debug_retries*4, 10)）。 */
-    max_debug_retries_cap: z4.number().int().positive().optional(),
-    max_rounds_per_step: z4.number().int().positive().default(6),
-    max_debug_rounds_per_step: z4.number().int().positive().optional(),
-    max_edit_lines_per_step: z4.union([z4.literal("auto"), z4.number().int().positive()]).default("auto"),
-    max_write_chunk_bytes: z4.union([z4.literal("auto"), z4.number().int().positive()]).default("auto"),
-    sandbox: z4.enum(["subprocess", "docker", "firejail"]).default("subprocess"),
-    sandbox_limits: z4.object({
-      cpu: z4.number().positive().default(1),
-      memory_mb: z4.number().int().positive().default(1024),
-      wall_seconds: z4.number().int().positive().default(60),
-      /**
-       * Sandbox network policy.
-       *  - `off`            — no network at all (`docker --network none`).
-       *  - `download-only`  — outbound traffic allowed, no inbound port publishing
-       *                       (default; lets python pip-install / fetch web pages).
-       *  - `pypi-only`      — legacy value; rejected at sandbox creation rather than silently
-       *                       allowing unrestricted outbound traffic.
-       *  - `full`           — outbound + every port in `expose_ports` is published
-       *                       to `127.0.0.1` so host-side tests can reach the app.
-       */
-      network: z4.enum(["off", "pypi-only", "download-only", "full"]).default("download-only"),
-      /** Container ports to publish to 127.0.0.1 when `network=full`. */
-      expose_ports: z4.array(z4.number().int().min(1).max(65535)).default([])
-    }).default({
-      cpu: 1,
-      memory_mb: 1024,
-      wall_seconds: 60,
-      network: "download-only",
-      expose_ports: []
-    }),
-    sandbox_docker: z4.object({
-      image: z4.string().default("python:3.11-slim"),
-      workdir: z4.string().default("/workspace"),
-      pull: z4.boolean().default(false),
-      docker_bin: z4.string().default("docker"),
-      extra_run_args: z4.array(z4.string()).default([])
-    }).default({
-      image: "python:3.11-slim",
-      workdir: "/workspace",
-      pull: false,
-      docker_bin: "docker",
-      extra_run_args: []
-    })
-  })
+  agent: AgentSchema
 }).transform(({ locale, ui_language, ...rest }) => ({
   locale: locale ?? ui_language ?? "en",
   ...rest
 }));
+function defaultSandboxLimits() {
+  return {
+    cpu: 1,
+    memory_mb: 1024,
+    wall_seconds: 60,
+    network: "download-only",
+    expose_ports: []
+  };
+}
+function defaultLanguageSandbox(language, mode, limits) {
+  return {
+    mode,
+    local: {
+      sandbox_dir: `.sandbox/${language}`,
+      limits: { ...limits, expose_ports: [...limits.expose_ports ?? []] }
+    },
+    docker: {
+      image: language === "typescript" ? "node:24-slim" : "python:3.11-slim",
+      workdir: "/workspace",
+      pull: false,
+      docker_bin: "docker",
+      extra_run_args: [],
+      sandbox_dir: `.sandbox/${language}`,
+      limits: { ...limits, expose_ports: [...limits.expose_ports ?? []] }
+    }
+  };
+}
+function mergeLanguageSandbox(defaults, override, legacyDocker) {
+  const dockerOverride = legacyDocker ?? override?.docker;
+  return {
+    mode: override?.mode ?? defaults.mode,
+    local: {
+      ...defaults.local,
+      ...override?.local ?? {},
+      limits: override?.local?.limits ?? defaults.local.limits
+    },
+    docker: {
+      ...defaults.docker,
+      ...dockerOverride ?? {},
+      limits: dockerOverride?.limits ?? defaults.docker.limits
+    }
+  };
+}
 function getXCompilerPath() {
   const env = xcEnv("PATH");
   if (env && env.trim()) return path5.resolve(env.trim());
@@ -3834,7 +4053,7 @@ async function loadConfigWithPath(explicitPath) {
   for (const abs of candidates) {
     tried.push(abs);
     try {
-      const raw = await fs3.readFile(abs, "utf8");
+      const raw = await fs4.readFile(abs, "utf8");
       const expanded = expandEnv(raw);
       const data = YAML.parse(expanded);
       return { config: ConfigSchema.parse(data), path: abs };
@@ -3876,6 +4095,11 @@ var LOOP_REPEATS = 12;
 var LOOP_MIN_LEN = 1500;
 var LOOP_MIN_WINDOW = 96;
 var LOOP_MAX_PERIOD = 256;
+var TEXT_LOOP_MIN_LEN = 6e3;
+var TEXT_LOOP_TAIL = 14e3;
+var TEXT_LOOP_SAMPLE_LEN = 48;
+var TEXT_LOOP_STRIDE = 8;
+var TEXT_LOOP_REPEATS = 5;
 function detectCyclicTokenLoop(aggregate) {
   if (aggregate.length < LOOP_MIN_LEN) return false;
   const maxPeriod = Math.min(LOOP_MAX_PERIOD, Math.floor(aggregate.length / LOOP_REPEATS));
@@ -3897,6 +4121,35 @@ function detectCyclicTokenLoop(aggregate) {
   }
   return false;
 }
+function detectRepeatedTextLoop(aggregate) {
+  if (aggregate.length < TEXT_LOOP_MIN_LEN) return false;
+  const tail = aggregate.slice(-TEXT_LOOP_TAIL).replace(/\s+/gu, " ").trim();
+  if (tail.length < TEXT_LOOP_MIN_LEN) return false;
+  const seen = /* @__PURE__ */ new Map();
+  for (let i = 0; i + TEXT_LOOP_SAMPLE_LEN <= tail.length; i += TEXT_LOOP_STRIDE) {
+    const sample = tail.slice(i, i + TEXT_LOOP_SAMPLE_LEN);
+    if (!isHighSignalLoopSample(sample)) continue;
+    const prior = seen.get(sample);
+    if (!prior) {
+      seen.set(sample, { count: 1, first: i, last: i });
+      continue;
+    }
+    const next = { count: prior.count + 1, first: prior.first, last: i };
+    seen.set(sample, next);
+    if (next.count >= TEXT_LOOP_REPEATS && next.last - next.first >= TEXT_LOOP_SAMPLE_LEN * 3) {
+      return true;
+    }
+  }
+  return false;
+}
+function isHighSignalLoopSample(sample) {
+  const chars = [...sample];
+  const signalChars = chars.filter((ch) => /[\p{L}\p{N}]/u.test(ch));
+  if (signalChars.length < 20) return false;
+  if (signalChars.length / Math.max(1, chars.length) < 0.4) return false;
+  const unique = new Set(signalChars.map((ch) => ch.toLowerCase())).size;
+  return unique >= 10;
+}
 var RepeatTokenDetector = class {
   constructor(threshold = 40) {
     this.threshold = threshold;
@@ -4075,6 +4328,12 @@ function streamPostNdjson(url, body, watchdog, onLine, shouldStopWhen) {
                   );
                   return;
                 }
+                if (detectRepeatedTextLoop(aggregate)) {
+                  fail(
+                    new Error("detected repeated text loop in stream (semantic tail repetition); aborting")
+                  );
+                  return;
+                }
               }
               if (obj.error) {
                 fail(new Error(`Ollama error: ${obj.error}`));
@@ -4103,6 +4362,10 @@ function streamPostNdjson(url, body, watchdog, onLine, shouldStopWhen) {
               fail(new Error("detected token loop in stream; aborting"));
               return;
             }
+            if (detectRepeatedTextLoop(aggregate)) {
+              fail(new Error("detected repeated text loop in stream; aborting"));
+              return;
+            }
           }
         });
         res.on("end", () => {
@@ -4373,6 +4636,9 @@ var OpenAIClient = class {
           if (detectCyclicTokenLoop(aggregate)) {
             throw new Error("detected cyclic token loop in OpenAI stream (periodic tail); aborting");
           }
+          if (detectRepeatedTextLoop(aggregate)) {
+            throw new Error("detected repeated text loop in OpenAI stream (semantic tail repetition); aborting");
+          }
           if (maxOutputChars > 0 && expectsJsonObject && aggregate.length > maxOutputChars && hasInvalidJsonPrefix(aggregate)) {
             throw new Error(`OpenAI stream exceeded ${maxOutputChars} chars without a valid JSON prefix; aborting`);
           }
@@ -4909,22 +5175,28 @@ async function reportRoleModelAdvice(router, audit, reporter = (message) => {
 }
 
 // src/llm/scores.ts
-import { promises as fs4 } from "fs";
+import { promises as fs5 } from "fs";
 import path6 from "path";
 import YAML2 from "yaml";
 var CLUSTER_PROVIDER_TAG = "cluster";
+var LLM_DYNAMIC_SCORES_FILE = "llm_scores.yaml";
+var LLM_USER_SCORES_FILE = "llm_scores_user.yaml";
 var ScoreStore = class _ScoreStore {
   constructor(configPath, initial = {}, audit, opts = {}) {
     this.audit = audit;
-    this.sidecarPath = path6.join(path6.dirname(configPath), "llm_scores.yaml");
+    const configDir = path6.dirname(configPath);
+    this.sidecarPath = path6.join(configDir, LLM_DYNAMIC_SCORES_FILE);
+    this.userScoresPath = path6.join(configDir, LLM_USER_SCORES_FILE);
     this.clusterProviders = new Set(opts.clusterProviderNames ?? []);
     const bounds = normalizeClusterBounds(opts.clusterScoreMin, opts.clusterScoreMax);
     this.clusterMin = bounds.min;
     this.clusterMax = bounds.max;
     for (const [k, v] of Object.entries(initial)) {
-      const score = this.clampConfigured(k, v);
-      this.scores.set(k, score);
-      if (score === _ScoreStore.DISABLED) this.userDisabled.add(k);
+      if (v === _ScoreStore.DISABLED) {
+        this.userScores.set(k, _ScoreStore.DISABLED);
+      } else {
+        this.dynamicScores.set(k, this.clampDynamic(k, v));
+      }
     }
   }
   audit;
@@ -4936,24 +5208,28 @@ var ScoreStore = class _ScoreStore {
   static CLUSTER_MAX = 0.5;
   static DECAY = 0.5;
   static BOOST = 0.1;
-  scores = /* @__PURE__ */ new Map();
-  userDisabled = /* @__PURE__ */ new Set();
+  dynamicScores = /* @__PURE__ */ new Map();
+  userScores = /* @__PURE__ */ new Map();
   clusterProviders;
   clusterMin;
   clusterMax;
   dirty = false;
   writeQueue = Promise.resolve();
   sidecarPath;
-  /** 异步加载 sidecar 文件；失败/不存在不抛错，使用 ctor 提供的初值。 */
+  userScoresPath;
+  /** 异步加载动态 sidecar 与用户覆盖文件；失败/不存在不抛错，使用 ctor 提供的初值。 */
   async load() {
+    await this.loadDynamicScores();
+    await this.loadUserScores();
+  }
+  async loadDynamicScores() {
     try {
-      const raw = await fs4.readFile(this.sidecarPath, "utf8");
+      const raw = await fs5.readFile(this.sidecarPath, "utf8");
       const parsed = YAML2.parse(raw);
       if (parsed && typeof parsed === "object") {
         for (const [k, v] of Object.entries(parsed)) {
           if (typeof v === "number" && Number.isFinite(v)) {
-            if (this.userDisabled.has(k)) continue;
-            this.scores.set(k, this.clampDynamic(k, v));
+            this.dynamicScores.set(k, this.clampPersistedDynamic(k, v));
           }
         }
       }
@@ -4966,44 +5242,73 @@ var ScoreStore = class _ScoreStore {
       }
     }
   }
+  async loadUserScores() {
+    try {
+      const raw = await fs5.readFile(this.userScoresPath, "utf8");
+      const parsed = YAML2.parse(raw);
+      if (parsed && typeof parsed === "object") {
+        for (const [k, v] of Object.entries(parsed)) {
+          if (typeof v === "number" && Number.isFinite(v)) {
+            this.userScores.set(k, this.clampUserScore(v));
+          }
+        }
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        await this.audit?.event("llm.error", t().llm.scoreReadFailed(this.userScoresPath, err.message), {
+          messageId: "llm.user_score_read_failed",
+          sidecarPath: this.userScoresPath
+        });
+      }
+    }
+  }
   get(name) {
-    return this.scores.has(name) ? this.scores.get(name) : this.defaultFor(name);
+    if (this.userScores.has(name)) return this.userScores.get(name);
+    return this.dynamicScores.has(name) ? this.dynamicScores.get(name) : this.defaultFor(name);
   }
-  /** 主动设置评分；value=0 仅用于显式禁用，其它值会归一到动态范围。 */
+  /** 主动设置动态评分；用户覆盖只从配置或 llm_scores_user.yaml 读取。 */
   set(name, value, reason) {
-    if (this.userDisabled.has(name) && value !== _ScoreStore.DISABLED) return;
     const v = value === _ScoreStore.DISABLED ? _ScoreStore.DISABLED : this.clampDynamic(name, value);
-    const prev = this.scores.get(name);
+    const prev = this.dynamicScores.get(name);
     if (prev === v) return;
-    this.scores.set(name, v);
+    this.dynamicScores.set(name, v);
     this.dirty = true;
-    void this.audit?.event("llm.score", t().llm.scoreChanged(name, v.toFixed(2), (prev ?? _ScoreStore.DEFAULT).toFixed(2)), {
+    void this.audit?.event("llm.score", t().llm.scoreChanged(name, v.toFixed(2), (prev ?? this.defaultFor(name)).toFixed(2)), {
       messageId: "llm.score_changed",
       provider: name,
       score: v,
-      previous: prev ?? _ScoreStore.DEFAULT,
+      previous: prev ?? this.defaultFor(name),
       reason: reason ?? "set"
     });
     this.scheduleSave();
   }
   decay(name, reason) {
-    if (this.get(name) === _ScoreStore.DISABLED) return;
-    this.set(name, Math.max(this.minFor(name), this.get(name) - _ScoreStore.DECAY), reason);
+    if (this.isUserDisabled(name)) return;
+    const cur = this.dynamicScore(name);
+    if (cur === _ScoreStore.DISABLED) return;
+    this.set(name, Math.max(this.minFor(name), cur - _ScoreStore.DECAY), reason);
   }
   boost(name, reason) {
-    const cur = this.get(name);
+    if (this.isUserDisabled(name)) return;
+    const cur = this.dynamicScore(name);
     if (cur === _ScoreStore.DISABLED) return;
     if (cur >= this.maxFor(name)) return;
     this.set(name, Math.min(this.maxFor(name), cur + _ScoreStore.BOOST), reason);
   }
-  /** True only for providers explicitly disabled by user config (`llm.scores.<provider>: 0`). */
+  /** True only for providers explicitly disabled by user config or llm_scores_user.yaml. */
   isUserDisabled(name) {
-    return this.userDisabled.has(name);
+    return this.userScores.get(name) === _ScoreStore.DISABLED;
   }
-  /** 全量快照（用于测试与 audit 输出）。 */
+  /** 动态评分快照（用于持久化、测试与 audit 输出；不包含用户覆盖）。 */
   snapshot() {
     const out = {};
-    for (const [k, v] of this.scores) out[k] = v;
+    for (const [k, v] of this.dynamicScores) out[k] = v;
+    return out;
+  }
+  /** 用户覆盖快照（用于测试/诊断；运行时不会改写用户文件）。 */
+  userSnapshot() {
+    const out = {};
+    for (const [k, v] of this.userScores) out[k] = v;
     return out;
   }
   /** 等待待写入完成（CLI 退出前调用，确保评分已落盘）。 */
@@ -5026,8 +5331,8 @@ var ScoreStore = class _ScoreStore {
 ${t().llm.scoreFileSemantics}
 ` + YAML2.stringify(data);
     const tmp = `${this.sidecarPath}.tmp`;
-    await fs4.writeFile(tmp, yaml, "utf8");
-    await fs4.rename(tmp, this.sidecarPath);
+    await fs5.writeFile(tmp, yaml, "utf8");
+    await fs5.rename(tmp, this.sidecarPath);
   }
   defaultFor(name) {
     return this.isClusterProvider(name) ? this.clusterMax : _ScoreStore.DEFAULT;
@@ -5041,10 +5346,8 @@ ${t().llm.scoreFileSemantics}
   isClusterProvider(name) {
     return this.clusterProviders.has(name);
   }
-  clampConfigured(name, v) {
-    if (!Number.isFinite(v)) return this.defaultFor(name);
-    if (v === _ScoreStore.DISABLED) return _ScoreStore.DISABLED;
-    return this.clampDynamic(name, v);
+  dynamicScore(name) {
+    return this.dynamicScores.has(name) ? this.dynamicScores.get(name) : this.defaultFor(name);
   }
   clampDynamic(name, v) {
     if (!Number.isFinite(v)) return this.defaultFor(name);
@@ -5053,6 +5356,18 @@ ${t().llm.scoreFileSemantics}
     if (v > this.maxFor(name)) return this.maxFor(name);
     return v;
   }
+  clampPersistedDynamic(name, v) {
+    if (!Number.isFinite(v)) return this.defaultFor(name);
+    if (v === _ScoreStore.DISABLED) return _ScoreStore.DISABLED;
+    return this.clampDynamic(name, v);
+  }
+  clampUserScore(v) {
+    if (!Number.isFinite(v)) return _ScoreStore.DEFAULT;
+    if (v <= _ScoreStore.DISABLED) return _ScoreStore.DISABLED;
+    if (v < _ScoreStore.MIN) return _ScoreStore.MIN;
+    if (v > _ScoreStore.MAX) return _ScoreStore.MAX;
+    return v;
+  }
 };
 function normalizeClusterBounds(rawMin, rawMax) {
   const min = clampBound(rawMin ?? ScoreStore.CLUSTER_MIN);
@@ -5232,7 +5547,7 @@ async function defaultFetchTags(baseUrl, timeoutMs) {
 }
 
 // src/workspace/workspace.ts
-import { promises as fs5 } from "fs";
+import { promises as fs6 } from "fs";
 import path7 from "path";
 var Workspace = class {
   constructor(root) {
@@ -5243,31 +5558,31 @@ var Workspace = class {
     return path7.resolve(this.root, ...p);
   }
   async ensure(dir) {
-    await fs5.mkdir(this.abs(dir), { recursive: true });
+    await fs6.mkdir(this.abs(dir), { recursive: true });
   }
   async writeFile(rel, content) {
     const full = this.abs(rel);
-    await fs5.mkdir(path7.dirname(full), { recursive: true });
-    await fs5.writeFile(full, content, "utf8");
+    await fs6.mkdir(path7.dirname(full), { recursive: true });
+    await fs6.writeFile(full, content, "utf8");
   }
   async readFile(rel) {
-    return fs5.readFile(this.abs(rel), "utf8");
+    return fs6.readFile(this.abs(rel), "utf8");
   }
   async exists(rel) {
     try {
-      await fs5.stat(this.abs(rel));
+      await fs6.stat(this.abs(rel));
       return true;
     } catch {
       return false;
     }
   }
   async remove(rel) {
-    await fs5.rm(this.abs(rel), { recursive: true, force: true });
+    await fs6.rm(this.abs(rel), { recursive: true, force: true });
   }
 };
 
 // src/workspace/doc_archive.ts
-import { promises as fs6 } from "fs";
+import { promises as fs7 } from "fs";
 import path8 from "path";
 async function archiveIfExists(ws, rel, audit) {
   const norm = rel.replaceAll("\\", "/");
@@ -5280,7 +5595,7 @@ async function archiveIfExists(ws, rel, audit) {
   const target = `docs/history/${base}-${ts}${ext}`;
   try {
     await ws.ensure("docs/history");
-    await fs6.rename(ws.abs(norm), ws.abs(target));
+    await fs7.rename(ws.abs(norm), ws.abs(target));
     await audit?.event("plan.persist", t().audit.documentArchived(norm, target), {
       messageId: "audit.document_archived",
       from: norm,
@@ -5482,6 +5797,18 @@ var DOC_PATH_ALIASES = {
   "docs/integration-test.md": DOC_NAMES.integrationTest,
   "docs/module-test.md": DOC_NAMES.moduleTest,
   "docs/functional-test.md": DOC_NAMES.functionalTest,
+  "docs/unit-test-plan.md": DOC_NAMES.unitTestPlan,
+  "docs/unit_test_plan.md": DOC_NAMES.unitTestPlan,
+  "docs/tests/unit_test_plan.md": DOC_NAMES.unitTestPlan,
+  "docs/integration-test-plan.md": DOC_NAMES.integrationTestPlan,
+  "docs/integration_test_plan.md": DOC_NAMES.integrationTestPlan,
+  "docs/tests/integration_test_plan.md": DOC_NAMES.integrationTestPlan,
+  "docs/module-test-plan.md": DOC_NAMES.moduleTestPlan,
+  "docs/module_test_plan.md": DOC_NAMES.moduleTestPlan,
+  "docs/tests/module_test_plan.md": DOC_NAMES.moduleTestPlan,
+  "docs/functional-test-plan.md": DOC_NAMES.functionalTestPlan,
+  "docs/functional_test_plan.md": DOC_NAMES.functionalTestPlan,
+  "docs/tests/functional_test_plan.md": DOC_NAMES.functionalTestPlan,
   "docs/quick-start.md": DOC_NAMES.quickstart,
   "docs/quick_start.md": DOC_NAMES.quickstart,
   "docs/quickstart.md": DOC_NAMES.quickstart,
@@ -5854,11 +6181,11 @@ function renderDebugSuggestions(sugs) {
 var normalizePythonRequirements = calibratePythonRequirements;
 
 // src/core/incremental.ts
-import { promises as fs8 } from "fs";
+import { promises as fs9 } from "fs";
 import path10 from "path";
 
 // src/core/project_memory.ts
-import { promises as fs7 } from "fs";
+import { promises as fs8 } from "fs";
 import path9 from "path";
 var PROJECT_MEMORY_PATH = ".xcompiler/project_memory.json";
 async function refreshProjectMemory(ws, opts = {}) {
@@ -6016,7 +6343,7 @@ async function defaultPlanMetadataPath(root) {
 }
 async function fileExists(filePath) {
   try {
-    await fs7.stat(filePath);
+    await fs8.stat(filePath);
     return true;
   } catch {
     return false;
@@ -6044,7 +6371,7 @@ async function readWorkspaceText(ws, rel, maxChars) {
 }
 async function readAbsoluteText(fullPath, maxChars) {
   try {
-    const raw = await fs7.readFile(fullPath, "utf8");
+    const raw = await fs8.readFile(fullPath, "utf8");
     return truncate(raw, maxChars);
   } catch {
     return "";
@@ -6066,7 +6393,7 @@ async function walk(abs, rel, out, depth) {
   if (depth > 6 || out.length >= 160) return;
   let entries;
   try {
-    entries = await fs7.readdir(abs, { withFileTypes: true });
+    entries = await fs8.readdir(abs, { withFileTypes: true });
   } catch {
     return;
   }
@@ -6293,20 +6620,20 @@ function extractImportedStems(text) {
 function normalizeImportStem(value) {
   return value.replace(/^\.\//u, "").replace(/^\.\.\//u, "").replace(/\.(js|ts|tsx|py)$/u, "").replace(/\/index$/u, "").trim();
 }
-function extractContractsFromDoc(path30, text) {
+function extractContractsFromDoc(path31, text) {
   const contracts = [];
   for (const rawLine of text.split("\n")) {
     const line = rawLine.replace(/^[-*#\d.\s]+/u, "").trim();
     if (line.length < 18) continue;
     const lower = line.toLowerCase();
     if (INVARIANT_RE.test(lower)) {
-      contracts.push({ kind: "invariant", subject: path30, path: path30, detail: trimContractLine(line) });
+      contracts.push({ kind: "invariant", subject: path31, path: path31, detail: trimContractLine(line) });
     } else if (LIMITATION_RE.test(lower)) {
-      contracts.push({ kind: "limitation", subject: path30, path: path30, detail: trimContractLine(line) });
+      contracts.push({ kind: "limitation", subject: path31, path: path31, detail: trimContractLine(line) });
     } else if (EXTENSION_RE.test(lower)) {
-      contracts.push({ kind: "extension-point", subject: path30, path: path30, detail: trimContractLine(line) });
+      contracts.push({ kind: "extension-point", subject: path31, path: path31, detail: trimContractLine(line) });
     } else if (INTEGRATION_RE.test(lower)) {
-      contracts.push({ kind: "integration", subject: path30, path: path30, detail: trimContractLine(line) });
+      contracts.push({ kind: "integration", subject: path31, path: path31, detail: trimContractLine(line) });
     }
   }
   return contracts;
@@ -6331,7 +6658,7 @@ function dedupContracts(contracts) {
 }
 
 // src/audit/audit.ts
-import { promises as fs9, appendFileSync, mkdirSync, existsSync, writeFileSync } from "fs";
+import { promises as fs10, appendFileSync, mkdirSync, existsSync, writeFileSync } from "fs";
 import { createHash } from "crypto";
 import path11 from "path";
 var AuditLogger = class {
@@ -6488,8 +6815,8 @@ var AuditLogger = class {
     });
   }
   /**
-   * 记录一轮 Executor 思考：thoughts 文本、计划调用的 actions、是否完成。
-   * 写入 jsonl + markdown 折叠块，交付时可作为"AI 思考过程完整记录"。
+   * 记录一轮 Executor 执行摘要：简短 intent、issue 处理方案、计划调用的 actions、是否完成。
+   * 写入 jsonl + markdown 折叠块，交付时可追溯每轮决策和动作。
    */
   async executorTurn(stepId, role, round, payload) {
     const storedPayload = protectAuditContent(payload, this.contentMode);
@@ -6561,8 +6888,8 @@ ${t().audit.processLogPreamble}
   }
   async appendMd(text) {
     this.mdQueue = this.mdQueue.then(
-      () => fs9.appendFile(this.mdAbs, text, "utf8"),
-      () => fs9.appendFile(this.mdAbs, text, "utf8")
+      () => fs10.appendFile(this.mdAbs, text, "utf8"),
+      () => fs10.appendFile(this.mdAbs, text, "utf8")
     ).catch((err) => {
       console.warn(t().audit.markdownAppendFailed(err.message));
     });
@@ -6644,7 +6971,7 @@ function redactText(value) {
 }
 
 // src/core/lock.ts
-import { promises as fs10, unlinkSync } from "fs";
+import { promises as fs11, unlinkSync } from "fs";
 import path12 from "path";
 import os from "os";
 var LockError = class extends Error {
@@ -6671,7 +6998,7 @@ function isAlive(pid) {
 }
 async function readLock(file) {
   try {
-    const raw = await fs10.readFile(file, "utf8");
+    const raw = await fs11.readFile(file, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -6679,7 +7006,7 @@ async function readLock(file) {
 }
 async function acquireLock(workspace, command, options = {}) {
   const file = lockPath(workspace);
-  await fs10.mkdir(path12.dirname(file), { recursive: true });
+  await fs11.mkdir(path12.dirname(file), { recursive: true });
   const info = {
     pid: process.pid,
     host: os.hostname(),
@@ -6689,7 +7016,7 @@ async function acquireLock(workspace, command, options = {}) {
   const payload = JSON.stringify(info, null, 2);
   const tryCreate = async () => {
     try {
-      const fh = await fs10.open(file, "wx");
+      const fh = await fs11.open(file, "wx");
       await fh.writeFile(payload, "utf8");
       await fh.close();
       return true;
@@ -6702,14 +7029,14 @@ async function acquireLock(workspace, command, options = {}) {
     return makeReleaser(file);
   }
   if (options.force) {
-    await fs10.writeFile(file, payload, "utf8");
+    await fs11.writeFile(file, payload, "utf8");
     return makeReleaser(file);
   }
   const existing = await readLock(file);
   if (existing) {
     const sameHost = existing.host === info.host;
     if (sameHost && !isAlive(existing.pid)) {
-      await fs10.writeFile(file, payload, "utf8");
+      await fs11.writeFile(file, payload, "utf8");
       return makeReleaser(file);
     }
     throw new LockError(
@@ -6718,7 +7045,7 @@ async function acquireLock(workspace, command, options = {}) {
       existing
     );
   }
-  await fs10.writeFile(file, payload, "utf8");
+  await fs11.writeFile(file, payload, "utf8");
   return makeReleaser(file);
 }
 function makeReleaser(file) {
@@ -6727,7 +7054,7 @@ function makeReleaser(file) {
     if (released) return;
     released = true;
     try {
-      await fs10.unlink(file);
+      await fs11.unlink(file);
     } catch {
     }
   };
@@ -6752,7 +7079,7 @@ function makeReleaser(file) {
 }
 
 // src/version.ts
-var XCOMPILER_VERSION = "0.2.3";
+var XCOMPILER_VERSION = "0.2.4";
 var XCOMPILER_PLUGIN_API_VERSION = 1;
 
 // src/plugins/compatibility.ts
@@ -7054,10 +7381,10 @@ function runtimeResult(io, command, status, data) {
 }
 
 // src/runtime/run.ts
-import path27 from "path";
+import path28 from "path";
 
 // src/workspace/git.ts
-import { promises as fs12 } from "fs";
+import { promises as fs13 } from "fs";
 import path14 from "path";
 import { simpleGit } from "simple-git";
 var RUNTIME_EXCLUDE_PATTERNS = [
@@ -7109,14 +7436,14 @@ var GitService = class {
     const excludePath = this.ws.abs(".git/info/exclude");
     let current2 = "";
     try {
-      current2 = await fs12.readFile(excludePath, "utf8");
+      current2 = await fs13.readFile(excludePath, "utf8");
     } catch {
       return;
     }
     const missing = RUNTIME_EXCLUDE_PATTERNS.filter((pattern) => !current2.split(/\r?\n/u).includes(pattern));
     if (missing.length === 0) return;
     const prefix = current2.endsWith("\n") ? "\n" : "\n\n";
-    await fs12.appendFile(
+    await fs13.appendFile(
       excludePath,
       `${prefix}# XCompiler runtime artifacts
 ${missing.join("\n")}
@@ -7161,7 +7488,7 @@ import { existsSync as existsSync2, readFileSync } from "fs";
 
 // src/sandbox/subprocess.ts
 import { spawn } from "child_process";
-import { promises as fs13 } from "fs";
+import { promises as fs14 } from "fs";
 import path15 from "path";
 import crypto from "crypto";
 
@@ -7215,6 +7542,9 @@ function formatCommand(cmd, argv) {
 }
 
 // src/sandbox/subprocess.ts
+var INSTALL_IDLE_TIMEOUT_FLOOR_MS = 15 * 6e4;
+var INSTALL_IDLE_TIMEOUT_MULTIPLIER = 10;
+var INSTALL_PROGRESS_CHECK_INTERVAL_MS = 15e3;
 var SubprocessSandbox = class {
   constructor(opts) {
     this.opts = opts;
@@ -7268,12 +7598,13 @@ var SubprocessSandbox = class {
    * Python → requirements.txt (venv + pip)；TypeScript → package.json (npm install)。
    */
   async build(manifestFile) {
-    await fs13.mkdir(this.sandboxAbs, { recursive: true });
+    await fs14.mkdir(this.sandboxAbs, { recursive: true });
     if (this.opts.inheritEnv === false) {
       await Promise.all([
-        fs13.mkdir(path15.join(this.sandboxAbs, "home"), { recursive: true }),
-        fs13.mkdir(path15.join(this.sandboxAbs, "tmp"), { recursive: true }),
-        fs13.mkdir(path15.join(this.sandboxAbs, "npm-cache"), { recursive: true })
+        fs14.mkdir(path15.join(this.sandboxAbs, "home"), { recursive: true }),
+        fs14.mkdir(path15.join(this.sandboxAbs, "tmp"), { recursive: true }),
+        fs14.mkdir(path15.join(this.sandboxAbs, "npm-cache"), { recursive: true }),
+        fs14.mkdir(path15.join(this.sandboxAbs, "pip-cache"), { recursive: true })
       ]);
     }
     if (this.language === "typescript") {
@@ -7283,10 +7614,10 @@ var SubprocessSandbox = class {
   }
   async buildPython(requirementsTxt) {
     const reqAbs = this.opts.ws.abs(requirementsTxt);
-    const reqContent = await fs13.readFile(reqAbs, "utf8").catch(() => "");
+    const reqContent = await fs14.readFile(reqAbs, "utf8").catch(() => "");
     const sig = crypto.createHash("sha256").update(reqContent).digest("hex");
-    const cached = await fs13.readFile(this.cacheFile, "utf8").catch(() => "");
-    const venvExists = await fs13.stat(this.pythonInVenv).then(() => true).catch(() => false);
+    const cached = await fs14.readFile(this.cacheFile, "utf8").catch(() => "");
+    const venvExists = await fs14.stat(this.pythonInVenv).then(() => true).catch(() => false);
     if (venvExists && cached === sig) {
       return { rebuilt: false, reason: "cache hit" };
     }
@@ -7303,7 +7634,7 @@ var SubprocessSandbox = class {
       }
     }
     const pyVenv = this.pythonInVenv;
-    const pyVenvExists = await fs13.stat(pyVenv).then(() => true).catch(() => false);
+    const pyVenvExists = await fs14.stat(pyVenv).then(() => true).catch(() => false);
     if (!pyVenvExists) {
       throw new Error(`venv python missing after creation: ${pyVenv} (install system package python3-venv / python3-virtualenv)`);
     }
@@ -7320,17 +7651,26 @@ Install on the host: apt-get install python3-venv python3-pip   or   yum install
       }
     }
     if (reqContent.trim().length > 0) {
+      const progressWatch = createInstallProgressWatch(
+        [this.venvAbs, path15.join(this.sandboxAbs, "pip-cache")],
+        this.opts.limits,
+        "pip install"
+      );
+      await this.opts.audit?.event("sandbox.exec", t().sandboxLog.command("subprocess", `pip install -r ${reqAbs}`), {
+        messageId: "sandbox.command",
+        cwd: this.opts.ws.root,
+        progressIdleTimeoutMs: progressWatch.idleTimeoutMs,
+        progressPaths: progressWatch.paths
+      });
       const r = await execRaw(pyVenv, ["-m", "pip", "install", "-r", reqAbs, "--quiet", "--disable-pip-version-check"], {
-        timeoutMs: this.opts.limits.wall_seconds * 1e3 * 5
+        env: this.baseEnvironment(),
+        progressWatch
       });
       if (r.exitCode !== 0) {
-        throw new Error(
-          `pip install failed (venv=${this.venvAbs}, requirements=${reqAbs}):
-${r.stderr || r.stdout}`
-        );
+        throw new Error(formatExecFailure(`pip install failed (venv=${this.venvAbs}, requirements=${reqAbs})`, r));
       }
     }
-    await fs13.writeFile(this.cacheFile, sig, "utf8");
+    await fs14.writeFile(this.cacheFile, sig, "utf8");
     await this.opts.audit?.event("sandbox.exec", t().sandboxLog.subprocessBuilt(!!reqContent), {
       messageId: "sandbox.subprocess_built"
     });
@@ -7338,29 +7678,39 @@ ${r.stderr || r.stdout}`
   }
   async buildNode(manifestFile) {
     const pkgAbs = this.opts.ws.abs(manifestFile);
-    const pkgContent = await fs13.readFile(pkgAbs, "utf8").catch(() => "");
+    const pkgContent = await fs14.readFile(pkgAbs, "utf8").catch(() => "");
     if (!pkgContent) {
       return { rebuilt: false, reason: "no package.json yet" };
     }
     const lockAbs = this.opts.ws.abs("package-lock.json");
-    const lockContent = await fs13.readFile(lockAbs, "utf8").catch(() => "");
+    const lockContent = await fs14.readFile(lockAbs, "utf8").catch(() => "");
     const sig = crypto.createHash("sha256").update(pkgContent + "\n" + lockContent).digest("hex");
-    const cached = await fs13.readFile(this.cacheFile, "utf8").catch(() => "");
-    const modulesExist = await fs13.stat(this.opts.ws.abs("node_modules")).then(() => true).catch(() => false);
+    const cached = await fs14.readFile(this.cacheFile, "utf8").catch(() => "");
+    const modulesExist = await fs14.stat(this.opts.ws.abs("node_modules")).then(() => true).catch(() => false);
     if (modulesExist && cached === sig) {
       return { rebuilt: false, reason: "cache hit" };
     }
     const installArgs = lockContent.trim() ? ["ci", "--ignore-scripts", "--no-audit", "--no-fund"] : ["install", "--ignore-scripts", "--no-audit", "--no-fund"];
+    const progressWatch = createInstallProgressWatch(
+      [this.opts.ws.abs("node_modules"), path15.join(this.sandboxAbs, "npm-cache")],
+      this.opts.limits,
+      "npm install"
+    );
+    await this.opts.audit?.event("sandbox.exec", t().sandboxLog.command("subprocess", `npm ${installArgs.join(" ")}`), {
+      messageId: "sandbox.command",
+      cwd: this.opts.ws.root,
+      progressIdleTimeoutMs: progressWatch.idleTimeoutMs,
+      progressPaths: progressWatch.paths
+    });
     const r = await execRaw("npm", installArgs, {
       cwd: this.opts.ws.root,
       env: this.baseEnvironment(),
-      timeoutMs: this.opts.limits.wall_seconds * 1e3 * 10
+      progressWatch
     });
     if (r.exitCode !== 0) {
-      throw new Error(`npm dependency install failed (cwd=${this.opts.ws.root}):
-${r.stderr || r.stdout}`);
+      throw new Error(formatExecFailure(`npm dependency install failed (cwd=${this.opts.ws.root})`, r));
     }
-    await fs13.writeFile(this.cacheFile, sig, "utf8");
+    await fs14.writeFile(this.cacheFile, sig, "utf8");
     await this.opts.audit?.event("sandbox.exec", t().sandboxLog.subprocessNodeBuilt, {
       messageId: "sandbox.subprocess_node_built"
     });
@@ -7384,9 +7734,11 @@ ${r.stderr || r.stdout}`);
     await this.opts.audit?.event("sandbox.exec", t().sandboxLog.command("subprocess", `${cmd} ${argv.join(" ")}`), {
       messageId: "sandbox.command",
       cwd,
-      timeoutMs
+      timeoutMs,
+      progressIdleTimeoutMs: extra?.progressWatch?.idleTimeoutMs,
+      progressPaths: extra?.progressWatch?.paths
     });
-    const r = await execRaw(cmd, argv, { cwd, env, timeoutMs });
+    const r = await execRaw(cmd, argv, { cwd, env, timeoutMs, progressWatch: extra?.progressWatch });
     return r;
   }
   baseEnvironment() {
@@ -7420,16 +7772,55 @@ ${r.stderr || r.stdout}`);
   }
   /** 安装额外依赖（不会写入依赖清单，需要由调用方自行回写）。 */
   async installDeps(packages) {
+    const progressWatch = createInstallProgressWatch(
+      [
+        this.language === "typescript" ? this.opts.ws.abs("node_modules") : this.venvAbs,
+        path15.join(this.sandboxAbs, this.language === "typescript" ? "npm-cache" : "pip-cache")
+      ],
+      this.opts.limits,
+      this.language === "typescript" ? "npm install" : "pip install"
+    );
     if (this.language === "typescript") {
-      return this.exec("npm", ["install", "--no-audit", "--no-fund", ...packages]);
+      return this.exec("npm", ["install", "--no-audit", "--no-fund", ...packages], {
+        timeoutMs: 0,
+        progressWatch
+      });
     }
-    return this.exec(this.pythonInVenv, ["-m", "pip", "install", ...packages, "--quiet", "--disable-pip-version-check"]);
+    return this.exec(this.pythonInVenv, ["-m", "pip", "install", ...packages, "--quiet", "--disable-pip-version-check"], {
+      timeoutMs: 0,
+      progressWatch
+    });
   }
 };
 function sanitizeVenvName(name) {
   const cleaned = name.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
   return cleaned.length > 0 ? cleaned : "venv";
 }
+function createInstallProgressWatch(paths, limits, label = "dependency install") {
+  const idleTimeoutMs = Math.max(
+    limits.wall_seconds * 1e3 * INSTALL_IDLE_TIMEOUT_MULTIPLIER,
+    INSTALL_IDLE_TIMEOUT_FLOOR_MS
+  );
+  return {
+    paths: dedupPaths(paths),
+    idleTimeoutMs,
+    checkIntervalMs: INSTALL_PROGRESS_CHECK_INTERVAL_MS,
+    label
+  };
+}
+function formatExecFailure(label, r) {
+  const parts = [
+    `${label} (exit=${r.exitCode}, timedOut=${r.timedOut ? "true" : "false"}, durationMs=${r.durationMs}${r.timeoutReason ? `, reason=${r.timeoutReason}` : ""}):`
+  ];
+  const stdout = clipExecOutput(r.stdout);
+  const stderr = clipExecOutput(r.stderr);
+  if (stdout) parts.push(`stdout:
+${stdout}`);
+  if (stderr) parts.push(`stderr:
+${stderr}`);
+  if (!stdout && !stderr) parts.push("(no stdout/stderr captured)");
+  return parts.join("\n");
+}
 async function execRaw(cmd, argv, opts = {}) {
   const start = Date.now();
   return new Promise((resolve) => {
@@ -7441,10 +7832,46 @@ async function execRaw(cmd, argv, opts = {}) {
     let stdout = "";
     let stderr = "";
     let timedOut = false;
+    let timeoutReason;
+    let settled = false;
+    let progressTimer = null;
+    let progressStopped = false;
     const t2 = opts.timeoutMs ? setTimeout(() => {
       timedOut = true;
+      timeoutReason = `wall-clock timeout after ${opts.timeoutMs}ms`;
       child.kill("SIGKILL");
     }, opts.timeoutMs) : null;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      progressStopped = true;
+      if (t2) clearTimeout(t2);
+      if (progressTimer) clearTimeout(progressTimer);
+      resolve(result);
+    };
+    if (opts.progressWatch?.paths.length) {
+      const watch = opts.progressWatch;
+      let lastProgressAt = start;
+      let lastObservedSize = null;
+      const checkProgress = async () => {
+        if (progressStopped) return;
+        const observedAt = Date.now();
+        const currentSize = await directoryTreeSize(watch.paths);
+        if (progressStopped) return;
+        if (lastObservedSize !== null && currentSize > lastObservedSize) {
+          lastProgressAt = observedAt;
+        }
+        lastObservedSize = currentSize;
+        if (observedAt - lastProgressAt >= watch.idleTimeoutMs) {
+          timedOut = true;
+          timeoutReason = `${watch.label ?? "process"} progress idle for ${watch.idleTimeoutMs}ms; watched paths did not grow: ${watch.paths.join(", ")}`;
+          child.kill("SIGKILL");
+          return;
+        }
+        progressTimer = setTimeout(checkProgress, watch.checkIntervalMs ?? INSTALL_PROGRESS_CHECK_INTERVAL_MS);
+      };
+      progressTimer = setTimeout(checkProgress, watch.checkIntervalMs ?? INSTALL_PROGRESS_CHECK_INTERVAL_MS);
+    }
     child.stdout.on("data", (b) => {
       stdout += b.toString();
     });
@@ -7452,31 +7879,69 @@ async function execRaw(cmd, argv, opts = {}) {
       stderr += b.toString();
     });
     child.on("error", (err) => {
-      if (t2) clearTimeout(t2);
-      resolve({
+      finish({
         exitCode: -1,
         stdout,
         stderr: stderr + `
 [spawn error] ${err.message}`,
         timedOut,
+        ...timeoutReason ? { timeoutReason } : {},
         durationMs: Date.now() - start
       });
     });
     child.on("close", (code) => {
-      if (t2) clearTimeout(t2);
-      resolve({
+      finish({
         exitCode: code ?? -1,
         stdout,
         stderr,
         timedOut,
+        ...timeoutReason ? { timeoutReason } : {},
         durationMs: Date.now() - start
       });
     });
   });
 }
+async function directoryTreeSize(paths) {
+  let total = 0;
+  for (const p of dedupPaths(paths)) {
+    total += await pathTreeSize(p);
+  }
+  return total;
+}
+async function pathTreeSize(abs) {
+  let stat;
+  try {
+    stat = await fs14.lstat(abs);
+  } catch {
+    return 0;
+  }
+  if (!stat.isDirectory()) {
+    return stat.isFile() ? stat.size : 0;
+  }
+  let total = stat.size;
+  let entries;
+  try {
+    entries = await fs14.readdir(abs, { withFileTypes: true });
+  } catch {
+    return total;
+  }
+  for (const entry of entries) {
+    total += await pathTreeSize(path15.join(abs, entry.name));
+  }
+  return total;
+}
+function dedupPaths(paths) {
+  return Array.from(new Set(paths.map((p) => path15.resolve(p)).filter(Boolean)));
+}
+function clipExecOutput(text, max = 6e3) {
+  const normalized = String(text ?? "").trim();
+  if (normalized.length <= max) return normalized;
+  return `${normalized.slice(0, max)}
+...[truncated ${normalized.length - max} chars]`;
+}
 
 // src/sandbox/docker.ts
-import { promises as fs14 } from "fs";
+import { promises as fs15 } from "fs";
 import path16 from "path";
 import crypto2 from "crypto";
 var DockerSandbox = class {
@@ -7486,7 +7951,7 @@ var DockerSandbox = class {
       throw new Error(t().system.unsupportedPypiOnlyNetwork);
     }
     this.language = opts.language ?? "python";
-    this.image = opts.image ?? (this.language === "typescript" ? "node:20-slim" : "python:3.11-slim");
+    this.image = opts.image ?? (this.language === "typescript" ? "node:24-slim" : "python:3.11-slim");
     this.workdir = opts.workdir ?? "/workspace";
     this.sandboxRel = (opts.sandboxDir ?? ".sandbox").replaceAll("\\", "/");
     this.cacheRel = `${this.sandboxRel}/${this.language === "typescript" ? "package.sha256" : "requirements.sha256"}`;
@@ -7535,7 +8000,7 @@ var DockerSandbox = class {
   async build(manifestFile) {
     await this.assertDocker();
     const sandboxAbs = this.opts.ws.abs(this.sandboxRel);
-    await fs14.mkdir(sandboxAbs, { recursive: true });
+    await fs15.mkdir(sandboxAbs, { recursive: true });
     if (this.language === "typescript") {
       return this.buildNode(manifestFile ?? "package.json");
     }
@@ -7544,11 +8009,11 @@ var DockerSandbox = class {
   async buildPython(requirementsTxt) {
     const sandboxAbs = this.opts.ws.abs(this.sandboxRel);
     const reqAbs = this.opts.ws.abs(requirementsTxt);
-    const reqContent = await fs14.readFile(reqAbs, "utf8").catch(() => "");
+    const reqContent = await fs15.readFile(reqAbs, "utf8").catch(() => "");
     const sig = crypto2.createHash("sha256").update(this.image + "\n" + reqContent).digest("hex");
     const cacheAbs = this.opts.ws.abs(this.cacheRel);
-    const cached = await fs14.readFile(cacheAbs, "utf8").catch(() => "");
-    const venvExists = await fs14.stat(path16.join(sandboxAbs, this.venvName, "bin", "python")).then(() => true).catch(() => false);
+    const cached = await fs15.readFile(cacheAbs, "utf8").catch(() => "");
+    const venvExists = await fs15.stat(path16.join(sandboxAbs, this.venvName, "bin", "python")).then(() => true).catch(() => false);
     if (venvExists && cached === sig) {
       return { rebuilt: false, reason: "cache hit" };
     }
@@ -7560,6 +8025,11 @@ var DockerSandbox = class {
     }
     const reqInContainer = `${this.workdir}/${requirementsTxt}`;
     const installCmd = reqContent.trim().length > 0 ? `python -m venv ${this.venvInContainer} && ${this.pipInContainer} install --quiet -r ${reqInContainer}` : `python -m venv ${this.venvInContainer}`;
+    const progressWatch = createInstallProgressWatch(
+      [path16.join(sandboxAbs, this.venvName)],
+      this.opts.limits,
+      "docker pip install"
+    );
     const r = await execRaw(
       this.dockerBin,
       [
@@ -7575,15 +8045,12 @@ var DockerSandbox = class {
         "-lc",
         installCmd
       ],
-      { timeoutMs: this.opts.limits.wall_seconds * 1e3 * 10 }
+      { progressWatch }
     );
     if (r.exitCode !== 0) {
-      throw new Error(
-        `docker sandbox build failed (exit=${r.exitCode}):
-${r.stderr || r.stdout}`
-      );
+      throw new Error(formatExecFailure(`docker sandbox build failed (image=${this.image}, cwd=${this.opts.ws.root})`, r));
     }
-    await fs14.writeFile(cacheAbs, sig, "utf8");
+    await fs15.writeFile(cacheAbs, sig, "utf8");
     await this.opts.audit?.event("sandbox.exec", t().sandboxLog.dockerBuilt(!!reqContent), {
       messageId: "sandbox.docker_built",
       image: this.image
@@ -7592,15 +8059,15 @@ ${r.stderr || r.stdout}`
   }
   async buildNode(manifestFile) {
     const pkgAbs = this.opts.ws.abs(manifestFile);
-    const pkgContent = await fs14.readFile(pkgAbs, "utf8").catch(() => "");
+    const pkgContent = await fs15.readFile(pkgAbs, "utf8").catch(() => "");
     if (!pkgContent) {
       return { rebuilt: false, reason: "no package.json yet" };
     }
-    const lockContent = await fs14.readFile(this.opts.ws.abs("package-lock.json"), "utf8").catch(() => "");
+    const lockContent = await fs15.readFile(this.opts.ws.abs("package-lock.json"), "utf8").catch(() => "");
     const sig = crypto2.createHash("sha256").update(this.image + "\n" + pkgContent + "\n" + lockContent).digest("hex");
     const cacheAbs = this.opts.ws.abs(this.cacheRel);
-    const cached = await fs14.readFile(cacheAbs, "utf8").catch(() => "");
-    const modulesExist = await fs14.stat(this.opts.ws.abs("node_modules")).then(() => true).catch(() => false);
+    const cached = await fs15.readFile(cacheAbs, "utf8").catch(() => "");
+    const modulesExist = await fs15.stat(this.opts.ws.abs("node_modules")).then(() => true).catch(() => false);
     if (modulesExist && cached === sig) {
       return { rebuilt: false, reason: "cache hit" };
     }
@@ -7611,6 +8078,11 @@ ${r.stderr || r.stdout}`
       }
     }
     const installCommand = lockContent.trim() ? "npm ci --ignore-scripts --no-audit --no-fund" : "npm install --ignore-scripts --no-audit --no-fund";
+    const progressWatch = createInstallProgressWatch(
+      [this.opts.ws.abs("node_modules")],
+      this.opts.limits,
+      "docker npm install"
+    );
     const r = await execRaw(
       this.dockerBin,
       [
@@ -7626,13 +8098,12 @@ ${r.stderr || r.stdout}`
         "-lc",
         installCommand
       ],
-      { timeoutMs: this.opts.limits.wall_seconds * 1e3 * 10 }
+      { progressWatch }
     );
     if (r.exitCode !== 0) {
-      throw new Error(`docker sandbox build failed (exit=${r.exitCode}):
-${r.stderr || r.stdout}`);
+      throw new Error(formatExecFailure(`docker sandbox build failed (image=${this.image}, cwd=${this.opts.ws.root})`, r));
     }
-    await fs14.writeFile(cacheAbs, sig, "utf8");
+    await fs15.writeFile(cacheAbs, sig, "utf8");
     await this.opts.audit?.event("sandbox.exec", t().sandboxLog.dockerNodeBuilt, {
       messageId: "sandbox.docker_node_built",
       image: this.image
@@ -7685,7 +8156,7 @@ ${r.stderr || r.stdout}`);
       image: this.image,
       network: this.opts.limits.network
     });
-    return execRaw(this.dockerBin, dockerArgs, { timeoutMs });
+    return execRaw(this.dockerBin, dockerArgs, { timeoutMs, progressWatch: extra?.progressWatch });
   }
   async runProgram(args, extra) {
     if (this.language === "typescript") {
@@ -7703,10 +8174,23 @@ ${r.stderr || r.stdout}`);
     return this.exec(this.pythonInContainer, ["-m", "pytest", ...args], extra);
   }
   async installDeps(packages) {
+    const progressWatch = createInstallProgressWatch(
+      [
+        this.language === "typescript" ? this.opts.ws.abs("node_modules") : this.opts.ws.abs(`${this.sandboxRel}/${this.venvName}`)
+      ],
+      this.opts.limits,
+      this.language === "typescript" ? "docker npm install" : "docker pip install"
+    );
     if (this.language === "typescript") {
-      return this.exec("npm", ["install", "--no-audit", "--no-fund", ...packages]);
+      return this.exec("npm", ["install", "--no-audit", "--no-fund", ...packages], {
+        timeoutMs: 0,
+        progressWatch
+      });
     }
-    return this.exec(this.pipInContainer, ["install", "--quiet", ...packages]);
+    return this.exec(this.pipInContainer, ["install", "--quiet", ...packages], {
+      timeoutMs: 0,
+      progressWatch
+    });
   }
   /** 将宿主机绝对路径映射回容器路径；相对路径或 undefined 原样返回（相对则拼到 workdir）。 */
   toContainerPath(p) {
@@ -7737,12 +8221,11 @@ function isRunningInContainer() {
   }
   return false;
 }
-function createSandbox(cfg, ws, audit, language = cfg.agent.language) {
-  const profile = getLanguageProfile(language);
-  const configuredImage = cfg.agent.sandbox_docker.image;
-  const image = language === cfg.agent.language ? configuredImage : profile.defaultDockerImage;
-  const kind = cfg.agent.sandbox;
-  if (cfg.agent.sandbox_limits.network === "pypi-only") {
+function createSandbox(cfg, ws, audit, language = "python") {
+  const languageSandbox = cfg.agent.sandboxes?.[language] ?? legacyLanguageSandbox(cfg, language);
+  const kind = languageSandbox.mode;
+  const activeLimits = kind === "docker" ? languageSandbox.docker.limits : languageSandbox.local.limits;
+  if (activeLimits.network === "pypi-only") {
     throw new Error(t().system.unsupportedPypiOnlyNetwork);
   }
   if (kind === "docker") {
@@ -7751,24 +8234,60 @@ function createSandbox(cfg, ws, audit, language = cfg.agent.language) {
     }
     return new DockerSandbox({
       ws,
-      limits: cfg.agent.sandbox_limits,
+      limits: languageSandbox.docker.limits,
       audit,
       language,
-      image,
-      workdir: cfg.agent.sandbox_docker.workdir,
-      pull: cfg.agent.sandbox_docker.pull,
-      dockerBin: cfg.agent.sandbox_docker.docker_bin,
-      extraRunArgs: cfg.agent.sandbox_docker.extra_run_args
+      image: languageSandbox.docker.image ?? getLanguageProfile(language).defaultDockerImage,
+      workdir: languageSandbox.docker.workdir,
+      pull: languageSandbox.docker.pull,
+      dockerBin: languageSandbox.docker.docker_bin,
+      extraRunArgs: languageSandbox.docker.extra_run_args,
+      sandboxDir: languageSandbox.docker.sandbox_dir
     });
   }
   if (kind === "firejail") {
     throw new Error(t().system.firejailUnsupported);
   }
-  return new SubprocessSandbox({ ws, limits: cfg.agent.sandbox_limits, audit, language });
+  return new SubprocessSandbox({
+    ws,
+    limits: languageSandbox.local.limits,
+    audit,
+    language,
+    sandboxDir: languageSandbox.local.sandbox_dir,
+    pythonBin: languageSandbox.local.python_bin,
+    inheritEnv: languageSandbox.local.inherit_env
+  });
+}
+function legacyLanguageSandbox(cfg, language) {
+  const legacyAgent = cfg.agent;
+  const limits = legacyAgent.sandbox_limits ?? {
+    cpu: 1,
+    memory_mb: 1024,
+    wall_seconds: 60,
+    network: "download-only",
+    expose_ports: []
+  };
+  const useLegacyDocker = legacyAgent.language === language ? legacyAgent.sandbox_docker : void 0;
+  return {
+    mode: legacyAgent.sandbox ?? "subprocess",
+    local: {
+      sandbox_dir: `.sandbox/${language}`,
+      limits
+    },
+    docker: {
+      image: useLegacyDocker?.image ?? getLanguageProfile(language).defaultDockerImage,
+      workdir: useLegacyDocker?.workdir ?? "/workspace",
+      pull: useLegacyDocker?.pull ?? false,
+      docker_bin: useLegacyDocker?.docker_bin ?? "docker",
+      extra_run_args: useLegacyDocker?.extra_run_args ?? [],
+      sandbox_dir: useLegacyDocker?.sandbox_dir ?? `.sandbox/${language}`,
+      limits: useLegacyDocker?.limits ?? limits
+    }
+  };
 }
 
 // src/core/engine.ts
-import path26 from "path";
+import path27 from "path";
 import chalk2 from "chalk";
 
 // src/util/spinner.ts
@@ -7854,10 +8373,10 @@ init_types();
 // src/tools/fs.ts
 init_types();
 import path18 from "path";
-import { promises as fs16 } from "fs";
+import { promises as fs17 } from "fs";
 
 // src/tools/path_guard.ts
-import { promises as fs15 } from "fs";
+import { promises as fs16 } from "fs";
 import path17 from "path";
 async function resolveWorkspacePath(ws, rawPath, operation, opts = {}) {
   const raw = rawPath && rawPath.trim() ? rawPath : ".";
@@ -7866,19 +8385,19 @@ async function resolveWorkspacePath(ws, rawPath, operation, opts = {}) {
   if (!isInside(root, abs)) return deny(operation, raw);
   if (opts.mustExist) {
     try {
-      const real = await fs15.realpath(abs);
+      const real = await fs16.realpath(abs);
       if (!isInside(root, real)) return deny(operation, raw);
     } catch (err) {
       return { ok: false, error: `${operation} failed: ${err.message}` };
     }
   } else if (opts.forWrite) {
-    const existingTarget = await fs15.realpath(abs).catch(() => void 0);
+    const existingTarget = await fs16.realpath(abs).catch(() => void 0);
     if (existingTarget && !isInside(root, existingTarget)) return deny(operation, raw);
     const parent = await nearestExistingParent(path17.dirname(abs));
-    const realParent = await fs15.realpath(parent).catch(() => parent);
+    const realParent = await fs16.realpath(parent).catch(() => parent);
     if (!isInside(root, realParent)) return deny(operation, raw);
   } else {
-    const existing = await fs15.realpath(abs).catch(() => void 0);
+    const existing = await fs16.realpath(abs).catch(() => void 0);
     if (existing && !isInside(root, existing)) return deny(operation, raw);
   }
   return { ok: true, abs };
@@ -7888,13 +8407,13 @@ function isInside(root, candidate) {
   return rel === "" || !!rel && !rel.startsWith("..") && !path17.isAbsolute(rel);
 }
 async function realpathOrResolve(p) {
-  return fs15.realpath(p).catch(() => path17.resolve(p));
+  return fs16.realpath(p).catch(() => path17.resolve(p));
 }
 async function nearestExistingParent(start) {
   let current2 = path17.resolve(start);
   while (true) {
     try {
-      const stat = await fs15.stat(current2);
+      const stat = await fs16.stat(current2);
       if (stat.isDirectory()) return current2;
     } catch {
     }
@@ -7920,9 +8439,9 @@ var readFileTool = {
       const resolved = await resolveWorkspacePath(ctx.ws, args.path, "read_file", { mustExist: true });
       if (!resolved.ok) return { ok: false, error: resolved.error };
       const abs = resolved.abs;
-      const stat = await fs16.stat(abs);
+      const stat = await fs17.stat(abs);
       if (!stat.isFile()) return { ok: false, error: "not a file" };
-      const buf = await fs16.readFile(abs);
+      const buf = await fs17.readFile(abs);
       const limit = args.maxBytes ?? 2e5;
       const content = buf.byteLength > limit ? buf.subarray(0, limit).toString("utf8") + `
 ... [truncated ${buf.byteLength - limit} bytes]` : buf.toString("utf8");
@@ -7983,8 +8502,8 @@ var writeFileTool = {
     }
     try {
       const abs = resolved.abs;
-      await fs16.mkdir(path18.dirname(abs), { recursive: true });
-      await fs16.writeFile(abs, args.content, "utf8");
+      await fs17.mkdir(path18.dirname(abs), { recursive: true });
+      await fs17.writeFile(abs, args.content, "utf8");
       return {
         ok: true,
         data: { bytes: size },
@@ -8020,11 +8539,11 @@ var appendFileTool = {
     }
     try {
       const abs = resolved.abs;
-      await fs16.mkdir(path18.dirname(abs), { recursive: true });
-      await fs16.appendFile(abs, args.content, "utf8");
+      await fs17.mkdir(path18.dirname(abs), { recursive: true });
+      await fs17.appendFile(abs, args.content, "utf8");
       let total = size;
       try {
-        total = (await fs16.stat(abs)).size;
+        total = (await fs17.stat(abs)).size;
       } catch {
       }
       return {
@@ -8057,7 +8576,7 @@ var listDirTool = {
       const resolved = await resolveWorkspacePath(ctx.ws, args.path ?? ".", "list_dir", { mustExist: true });
       if (!resolved.ok) return { ok: false, error: resolved.error };
       const abs = resolved.abs;
-      const entries = await fs16.readdir(abs, { withFileTypes: true });
+      const entries = await fs17.readdir(abs, { withFileTypes: true });
       return {
         ok: true,
         data: { entries: entries.map((e) => e.isDirectory() ? e.name + "/" : e.name) },
@@ -8072,7 +8591,7 @@ var listDirTool = {
 // src/tools/patch.ts
 init_types();
 import path19 from "path";
-import { promises as fs17 } from "fs";
+import { promises as fs18 } from "fs";
 var applyPatchTool = {
   name: "apply_patch",
   description: "\u5E94\u7528 unified diff \u8865\u4E01\uFF1B\u76EE\u6807\u6587\u4EF6\u5FC5\u987B\u5728\u5F53\u524D Step writable allowlist \u5185\u3002",
@@ -8090,14 +8609,14 @@ var applyPatchTool = {
       const abs = resolved.abs;
       let original = "";
       try {
-        original = await fs17.readFile(abs, "utf8");
+        original = await fs18.readFile(abs, "utf8");
       } catch {
         if (!fd.isNewFile) return { ok: false, error: `target file missing: ${fd.target}` };
       }
       const next = applyHunks(original, fd.hunks);
       if (next.error) return { ok: false, error: `${fd.target}: ${next.error}` };
-      await fs17.mkdir(path19.dirname(abs), { recursive: true });
-      await fs17.writeFile(abs, next.content, "utf8");
+      await fs18.mkdir(path19.dirname(abs), { recursive: true });
+      await fs18.writeFile(abs, next.content, "utf8");
       changed.push(fd.target);
     }
     return { ok: true, data: { changedFiles: changed }, summary: `patched ${changed.join(", ")}` };
@@ -8313,7 +8832,7 @@ var pipInstallTool = {
 // src/tools/edit.ts
 init_types();
 import path20 from "path";
-import { promises as fs18 } from "fs";
+import { promises as fs19 } from "fs";
 var replaceInFileTool = {
   name: "replace_in_file",
   description: "\u628A\u5F53\u524D Step writable allowlist \u5185\u76EE\u6807\u6587\u4EF6\u7684 find \u5B57\u7B26\u4E32\u7CBE\u786E\u66FF\u6362\u4E3A replace\uFF08\u9ED8\u8BA4\u8981\u6C42\u51FA\u73B0 1 \u6B21\uFF09\u3002",
@@ -8334,7 +8853,7 @@ var replaceInFileTool = {
     const abs = resolved.abs;
     let original;
     try {
-      original = await fs18.readFile(abs, "utf8");
+      original = await fs19.readFile(abs, "utf8");
     } catch {
       return { ok: false, error: `file not found: ${args.path}` };
     }
@@ -8366,8 +8885,8 @@ var replaceInFileTool = {
       return { ok: false, error: hint.join("\n") };
     }
     const next = parts.join(args.replace);
-    await fs18.mkdir(path20.dirname(abs), { recursive: true });
-    await fs18.writeFile(abs, next, "utf8");
+    await fs19.mkdir(path20.dirname(abs), { recursive: true });
+    await fs19.writeFile(abs, next, "utf8");
     return {
       ok: true,
       data: { occurrences },
@@ -8384,7 +8903,7 @@ var codeSearchTool = {
     const resolved = await resolveWorkspacePath(ctx.ws, args.root ?? ".", "code_search", { mustExist: true });
     if (!resolved.ok) return { ok: false, error: resolved.error };
     const root = resolved.abs;
-    const workspaceRoot = await fs18.realpath(ctx.ws.root).catch(() => ctx.ws.root);
+    const workspaceRoot = await fs19.realpath(ctx.ws.root).catch(() => ctx.ws.root);
     const max = args.maxResults ?? 50;
     const exts = args.ext && args.ext.length > 0 ? new Set(args.ext.map((e) => e.startsWith(".") ? e : "." + e)) : null;
     const matches = [];
@@ -8393,9 +8912,9 @@ var codeSearchTool = {
       if (/(?:^|\/)(node_modules|\.git|\.sandbox|\.xcompiler|dist|__pycache__)\//.test(abs)) return;
       let content;
       try {
-        const stat = await fs18.stat(abs);
+        const stat = await fs19.stat(abs);
         if (stat.size > 512e3) return;
-        content = await fs18.readFile(abs, "utf8");
+        content = await fs19.readFile(abs, "utf8");
       } catch {
         return;
       }
@@ -8418,7 +8937,7 @@ var codeSearchTool = {
 async function walk2(dir, onFile) {
   let entries;
   try {
-    entries = await fs18.readdir(dir, { withFileTypes: true });
+    entries = await fs19.readdir(dir, { withFileTypes: true });
   } catch {
     return;
   }
@@ -8472,7 +8991,7 @@ var analyzeErrorTool = {
 };
 
 // src/tools/deps.ts
-import { promises as fs19 } from "fs";
+import { promises as fs20 } from "fs";
 var addDependencyTool = {
   name: "add_dependency",
   description: "\u5411\u4F9D\u8D56\u6E05\u5355\u8FFD\u52A0\u4F9D\u8D56\uFF08python: requirements.txt\uFF1Btypescript: package.json\uFF09\u5E76\u91CD\u5EFA\u6C99\u76D2\u3002",
@@ -8492,7 +9011,7 @@ var addDependencyTool = {
     const added = [];
     let final;
     if (ctx.language === "typescript") {
-      const pkg = await fs19.readFile(abs, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
+      const pkg = await fs20.readFile(abs, "utf8").then((text) => JSON.parse(text)).catch(() => ({}));
       const existingDeps = pkg.dependencies && typeof pkg.dependencies === "object" && !Array.isArray(pkg.dependencies) ? { ...pkg.dependencies } : {};
       const before = new Set(Object.keys(existingDeps));
       for (const name of normalized) {
@@ -8501,11 +9020,11 @@ var addDependencyTool = {
       }
       final = Object.keys(existingDeps).sort();
       pkg.dependencies = Object.fromEntries(final.map((name) => [name, existingDeps[name] ?? "*"]));
-      await fs19.writeFile(abs, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+      await fs20.writeFile(abs, JSON.stringify(pkg, null, 2) + "\n", "utf8");
     } else {
       let existing = "";
       try {
-        existing = await fs19.readFile(abs, "utf8");
+        existing = await fs20.readFile(abs, "utf8");
       } catch {
       }
       const set = /* @__PURE__ */ new Set();
@@ -8519,7 +9038,7 @@ var addDependencyTool = {
         set.add(p);
       }
       final = [...set].sort();
-      await fs19.writeFile(abs, final.join("\n") + "\n", "utf8");
+      await fs20.writeFile(abs, final.join("\n") + "\n", "utf8");
     }
     try {
       await ctx.sandbox.build(manifestPath);
@@ -8538,7 +9057,7 @@ var addDependencyTool = {
 };
 
 // src/tools/net.ts
-import { promises as fs20 } from "fs";
+import { promises as fs21 } from "fs";
 import path21 from "path";
 var DEFAULT_TIMEOUT_MS = 15e3;
 var DEFAULT_MAX_BYTES = 256 * 1024;
@@ -8600,8 +9119,8 @@ var httpFetchTool = {
       if (timer) clearTimeout(timer);
       const trimmed = buf.length > maxBytes ? buf.subarray(0, maxBytes) : buf;
       const abs = saveAsAbs;
-      await fs20.mkdir(path21.dirname(abs), { recursive: true });
-      await fs20.writeFile(abs, trimmed);
+      await fs21.mkdir(path21.dirname(abs), { recursive: true });
+      await fs21.writeFile(abs, trimmed);
       await ctx.audit?.event("tool.call", t().audit.httpFetchSaved(method, args.url, args.saveAs, trimmed.length), {
         messageId: "audit.http_fetch_saved",
         stepId: ctx.stepId,
@@ -8659,7 +9178,7 @@ var httpFetchTool = {
 init_types();
 
 // src/tools/guard.ts
-import { promises as fs21 } from "fs";
+import { promises as fs22 } from "fs";
 import path22 from "path";
 var WRITE_TOOLS = /* @__PURE__ */ new Set(["write_file", "append_file", "apply_patch", "replace_in_file", "add_dependency"]);
 var DEFAULT_EDIT_LINES_PER_STEP = 400;
@@ -8742,8 +9261,8 @@ var EditGuard = class {
   async record(partial) {
     const rec = { ts: (/* @__PURE__ */ new Date()).toISOString(), stepId: this.opts.stepId, ...partial };
     try {
-      await fs21.mkdir(path22.dirname(this.logAbs), { recursive: true });
-      await fs21.appendFile(this.logAbs, JSON.stringify(rec) + "\n", "utf8");
+      await fs22.mkdir(path22.dirname(this.logAbs), { recursive: true });
+      await fs22.appendFile(this.logAbs, JSON.stringify(rec) + "\n", "utf8");
     } catch {
     }
   }
@@ -8799,8 +9318,9 @@ function buildDefaultRegistry() {
 
 // src/agents/executor.ts
 import path23 from "path";
-import { promises as fs22 } from "fs";
+import { promises as fs23 } from "fs";
 import { jsonrepair } from "jsonrepair";
+var MISSING_OUTPUT_STALL_ROUND_LIMIT = 3;
 var StepExecutor = class {
   constructor(opts) {
     this.opts = opts;
@@ -8824,8 +9344,12 @@ var StepExecutor = class {
     ];
     const calls = [];
     let finalThought;
-    const initialMissing = (await verifyOutputs(inp)).missing.length;
+    let issueResolutionPlan;
+    const initialVerify = await verifyOutputs(inp);
+    const initialMissing = initialVerify.missing.length;
     const hardRoundLimit = Math.max(maxRounds, maxRounds + Math.min(12, Math.max(4, initialMissing * 2)));
+    let lastMissingCount = initialMissing;
+    let missingOutputStallRounds = 0;
     let parseFailures = 0;
     let repeatedTurns = 0;
     let lastActionsKey = null;
@@ -8874,11 +9398,12 @@ var StepExecutor = class {
       } catch (err) {
         rep.done("failed");
         const errMsg = err.message;
+        actualRounds = round;
         const dumpRel = `.xcompiler/llm-stream/${inp.step.id}-${role}-r${round}.txt`;
         try {
           const dumpAbs = inp.ctx.ws.abs(dumpRel);
-          await fs22.mkdir(path23.dirname(dumpAbs), { recursive: true });
-          await fs22.writeFile(
+          await fs23.mkdir(path23.dirname(dumpAbs), { recursive: true });
+          await fs23.writeFile(
             dumpAbs,
             `${t().audit.partialFailureHeader(errMsg)}
 ${t().audit.streamLength(rawAggregate.length)}
@@ -8907,11 +9432,33 @@ ${rawAggregate}`,
             partialBytes: rawAggregate.length
           }
         );
+        if (isLowQualityLLMResponseError(errMsg)) {
+          repeatedTurns++;
+          const verify2 = await verifyOutputs(inp);
+          const metrics2 = computeMetrics({
+            rounds: actualRounds,
+            parseFailures,
+            repeatedTurns,
+            calls,
+            initialMissing,
+            currentMissing: verify2.missing.length
+          });
+          return {
+            success: false,
+            rounds: round,
+            toolCalls: calls,
+            finalThought,
+            issueResolutionPlan,
+            error: errMsg,
+            metrics: metrics2
+          };
+        }
         throw err;
       }
       rep.done();
       const turn = parseTurn(text);
       finalThought = turn.thoughts;
+      issueResolutionPlan = extractIssueResolutionPlan(turn) ?? issueResolutionPlan;
       const normalizedActions = normalizeActions(turn.actions);
       const actions = normalizedActions.actions;
       if (normalizedActions.invalid.length > 0) {
@@ -8961,6 +9508,7 @@ ${rawAggregate}`,
       }
       await inp.ctx.audit?.executorTurn(inp.step.id, role, round, {
         thoughts: turn.thoughts,
+        issueResolutionPlan,
         actions,
         done: turn.done === true,
         raw: text,
@@ -9069,12 +9617,25 @@ ${rawAggregate}`,
         turnResults.push({ ...r, tool: a.tool });
       }
       const verify = await verifyOutputs(inp);
+      const mutationSucceededThisRound = turnResults.some((r) => r.ok && isRepairEvidenceTool(r.tool));
+      if (verify.missing.length < lastMissingCount) {
+        lastMissingCount = verify.missing.length;
+        missingOutputStallRounds = 0;
+      } else if (!verify.ok && initialMissing > 0 && mutationSucceededThisRound && !readOnlyRound && unresolvedToolFailures.size === 0) {
+        missingOutputStallRounds++;
+      }
       if (turnResults.some((r) => r.tool === "run_tests" && !r.ok) && !advisoryFailureTools.has("run_tests")) {
         failedTestRunRounds++;
       }
       const repairGateOk = !repairRequired || repairEvidence || canAcceptOutputCompletionRecovery(inp, initialMissing);
+      const issueResolutionPlanRequired = role === "Debugger" && !!inp.debugContext?.issueId;
+      const issueResolutionPlanOk = !issueResolutionPlanRequired || !!issueResolutionPlan?.trim();
       const verifiedCompletion = !turn.done && hasSuccessfulCompletionVerification(calls);
-      if ((turn.done || verifiedCompletion) && verify.ok && unresolvedToolFailures.size === 0 && repairGateOk) {
+      const outputCompletionRecovery = verify.ok && canAcceptOutputCompletionRecovery(inp, initialMissing);
+      const supersededContractFailures = repairEvidence && hasSuccessfulCompletionVerification(calls) && hasOnlySupersededToolContractFailures(unresolvedToolFailures);
+      const unresolvedFailuresOk = unresolvedToolFailures.size === 0 || outputCompletionRecovery && hasOnlyUntargetedToolContractFailures(unresolvedToolFailures) || supersededContractFailures;
+      const completionSignal = turn.done || verifiedCompletion || outputCompletionRecovery;
+      if (completionSignal && verify.ok && unresolvedFailuresOk && repairGateOk && issueResolutionPlanOk) {
         const metrics2 = computeMetrics({
           rounds: actualRounds,
           parseFailures,
@@ -9083,7 +9644,7 @@ ${rawAggregate}`,
           initialMissing,
           currentMissing: verify.missing.length
         });
-        return { success: true, rounds: round, toolCalls: calls, finalThought, metrics: metrics2 };
+        return { success: true, rounds: round, toolCalls: calls, finalThought, issueResolutionPlan, metrics: metrics2 };
       }
       if (this.opts.maxFailedTestRuns && failedTestRunRounds >= this.opts.maxFailedTestRuns) {
         const metrics2 = computeMetrics({
@@ -9102,7 +9663,27 @@ ${rawAggregate}`,
           failedTestRunRounds,
           maxFailedTestRuns: this.opts.maxFailedTestRuns
         });
-        return { success: false, rounds: round, toolCalls: calls, finalThought, error, metrics: metrics2 };
+        return { success: false, rounds: round, toolCalls: calls, finalThought, issueResolutionPlan, error, metrics: metrics2 };
+      }
+      if (missingOutputStallRounds >= MISSING_OUTPUT_STALL_ROUND_LIMIT) {
+        repeatedTurns++;
+        const metrics2 = computeMetrics({
+          rounds: actualRounds,
+          parseFailures,
+          repeatedTurns,
+          calls,
+          initialMissing,
+          currentMissing: verify.missing.length
+        });
+        const error = `write/progress actions did not reduce missing outputs for ${missingOutputStallRounds} rounds; missing outputs: ${verify.missing.join(", ")}. Next attempt must create those exact outputs before rewriting already-existing files.`;
+        await inp.ctx.audit?.event("note", error, {
+          messageId: "audit.executor_missing_output_stall",
+          stepId: inp.step.id,
+          round,
+          missingOutputStallRounds,
+          missingOutputs: verify.missing
+        });
+        return { success: false, rounds: round, toolCalls: calls, finalThought, issueResolutionPlan, error, metrics: metrics2 };
       }
       const readOnlyRecoveryViolation = readOnlyRecoveryMode && readOnlyRecoveryRounds >= 2;
       const readOnlyRoundLimit = directRepairMode ? 2 : 3;
@@ -9125,7 +9706,7 @@ ${rawAggregate}`,
           consecutiveReadOnlyRounds,
           actions
         });
-        return { success: false, rounds: round, toolCalls: calls, finalThought, error, metrics: metrics2 };
+        return { success: false, rounds: round, toolCalls: calls, finalThought, issueResolutionPlan, error, metrics: metrics2 };
       }
       if (round >= roundLimit && roundLimit < hardRoundLimit && shouldExtendProductiveRun({
         parseFailures,
@@ -9159,8 +9740,13 @@ ${rawAggregate}`,
             rounds: consecutiveReadOnlyRounds,
             targets: actions.flatMap((action) => actionTargetPaths(action.tool, action.args)).join(", ")
           } : void 0,
+          missingOutputStallWarning: missingOutputStallRounds >= MISSING_OUTPUT_STALL_ROUND_LIMIT - 1 && !verify.ok ? {
+            rounds: missingOutputStallRounds,
+            missing: verify.missing.join(", ")
+          } : void 0,
           readOnlyRecoveryWarning: (readOnlyRecoveryMode || directRepairMode) && readOnlyRound,
-          repairEvidenceMissing: repairRequired && turn.done === true && verify.ok && unresolvedToolFailures.size === 0 && !repairEvidence
+          repairEvidenceMissing: repairRequired && turn.done === true && verify.ok && unresolvedToolFailures.size === 0 && !repairEvidence,
+          issueResolutionPlanMissing: issueResolutionPlanRequired && turn.done === true && verify.ok && unresolvedToolFailures.size === 0 && !issueResolutionPlanOk
         })
       });
     }
@@ -9178,7 +9764,8 @@ ${rawAggregate}`,
       rounds: actualRounds || roundLimit,
       toolCalls: calls,
       finalThought,
-      error: repairRequired && finalVerify.ok && unresolvedToolFailures.size === 0 && !repairEvidence && !canAcceptOutputCompletionRecovery(inp, initialMissing) ? "DEBUG retry ended without repair evidence; run a successful patch/write/dependency change or verification command before done=true." : finalVerify.ok && unresolvedToolFailures.size > 0 ? `unresolved tool failures remain: ${[...unresolvedToolFailures.values()].join("; ")}` : "max rounds exceeded without satisfying outputs",
+      issueResolutionPlan,
+      error: role === "Debugger" && !!inp.debugContext?.issueId && !issueResolutionPlan?.trim() ? "DEBUG issue completion missing issueResolutionPlan; provide a concrete handling plan before marking the issue resolved." : repairRequired && finalVerify.ok && unresolvedToolFailures.size === 0 && !repairEvidence && !canAcceptOutputCompletionRecovery(inp, initialMissing) ? "DEBUG retry ended without repair evidence; run a successful patch/write/dependency change or verification command before done=true." : finalVerify.ok && unresolvedToolFailures.size > 0 ? `unresolved tool failures remain: ${[...unresolvedToolFailures.values()].join("; ")}` : "max rounds exceeded without satisfying outputs",
       metrics
     };
   }
@@ -9191,6 +9778,9 @@ function isReadOnlyOrProbeAction(action) {
 function isReadOnlyLoopFailure(reason) {
   return /repeated read-only\/probe actions without progress/i.test(reason) || /read-only recovery mode repeated probe actions/i.test(reason);
 }
+function isLowQualityLLMResponseError(message) {
+  return /low-quality (?:debugger )?response/i.test(message) || /read-only\/probe actions in read-only recovery mode/i.test(message);
+}
 function hasActionableDebuggerFailure(debugContext) {
   if (!debugContext) return false;
   const text = [
@@ -9206,6 +9796,18 @@ function canAcceptOutputCompletionRecovery(inp, initialMissing) {
   if (initialMissing !== 0) return false;
   return isOutputCompletionFailure(inp.debugContext.reason, inp.debugContext.failureLog);
 }
+function hasOnlyUntargetedToolContractFailures(unresolved) {
+  if (unresolved.size === 0) return true;
+  return [...unresolved.entries()].every(
+    ([key, detail]) => key.startsWith("tool:") && /invalid (?:write_file|append_file|replace_in_file|read_file) args: path must be a non-empty string/i.test(detail)
+  );
+}
+function hasOnlySupersededToolContractFailures(unresolved) {
+  if (unresolved.size === 0) return true;
+  return [...unresolved.values()].every(
+    (detail) => /invalid (?:write_file|append_file|replace_in_file|apply_patch|read_file) args/i.test(detail) || /(?:read_file|write_file|append_file|replace_in_file|apply_patch) denied: path "\." is outside the project directory/i.test(detail) || /(?:read_file|write_file|append_file|replace_in_file) failed:.*path must be a non-empty string/i.test(detail) || /path must be a non-empty string/i.test(detail)
+  );
+}
 function isOutputCompletionFailure(reason = "", failureLog = "") {
   const text = `${reason}
 ${failureLog}`;
@@ -9280,6 +9882,7 @@ function compactTurnForHistory(turn) {
   const normalized = normalizeActions(turn.actions);
   return JSON.stringify({
     thoughts: truncate2(turn.thoughts ?? "", 500),
+    issueResolutionPlan: truncate2(extractIssueResolutionPlan(turn) ?? "", 900),
     actions: normalized.actions.map((action) => ({
       tool: action.tool,
       args: compactActionArgs(action.tool, action.args)
@@ -9618,8 +10221,8 @@ async function verifyOutputs(inp) {
   const missing = [];
   for (const out of inp.step.outputs) {
     if (out.endsWith("/")) continue;
-    const exists = await inp.ctx.ws.exists(out);
-    if (!exists) missing.push(out);
+    const exists2 = await inp.ctx.ws.exists(out);
+    if (!exists2) missing.push(out);
   }
   return { ok: missing.length === 0, missing };
 }
@@ -9635,13 +10238,21 @@ function renderUserPrompt(inp, toolDocs) {
 ${truncate2(s.content, s.path === ".xcompiler/architecture-contract.json" ? architectureLimit : snippetLimit)}
 \`\`\``
   ).join("\n\n");
-  const dbg = inp.debugContext ? `## debug failure log
+  const dbg = inp.debugContext ? [
+    inp.debugContext.issueId ? `## issue
+id: ${inp.debugContext.issueId}
+` : "",
+    inp.debugContext.debugBrief ? `${inp.debugContext.debugBrief}
+` : "",
+    `## compact failure evidence
 \`\`\`
 ${truncate2(inp.debugContext.failureLog, failureLogLimit)}
 \`\`\`
-` + (inp.debugContext.suggestions ? `
+`,
+    inp.debugContext.suggestions ? `
 ${inp.debugContext.suggestions}
-` : "") : "";
+` : ""
+  ].join("\n") : "";
   return [
     `# Step ${inp.step.id} \u2014 ${inp.step.title}`,
     `phase: ${inp.step.phase}`,
@@ -9729,6 +10340,11 @@ function renderFeedback(results, verify, turn) {
       )
     );
   }
+  if (turn.missingOutputStallWarning) {
+    lines.push(
+      `Output progress warning: required outputs have not decreased for ${turn.missingOutputStallWarning.rounds} write/progress rounds. Create these exact missing outputs next: ${turn.missingOutputStallWarning.missing}. Do not keep rewriting files that already satisfy declared outputs.`
+    );
+  }
   if (turn.readOnlyRecoveryWarning) {
     lines.push(M.executorFeedbackReadOnlyRecoveryRequired);
     if (!verify.ok && verify.missing.length > 0) {
@@ -9737,6 +10353,9 @@ function renderFeedback(results, verify, turn) {
       );
     }
   }
+  if (turn.issueResolutionPlanMissing) {
+    lines.push(M.executorFeedbackIssueResolutionPlanMissing);
+  }
   if (turn.unresolvedFailures && turn.unresolvedFailures.length > 0) {
     lines.push(
       `Unresolved tool failures remain: ${turn.unresolvedFailures.map((failure) => truncate2(failure, 1200)).join("; ")}`
@@ -9947,6 +10566,21 @@ function isTurnObject(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return value;
 }
+function extractIssueResolutionPlan(turn) {
+  const candidates = [
+    turn.issueResolutionPlan,
+    turn.issue_resolution_plan,
+    turn.resolutionPlan,
+    turn.handlingPlan,
+    turn.fixPlan
+  ];
+  for (const value of candidates) {
+    if (typeof value === "string" && value.trim().length > 0) {
+      return truncate2(value.trim(), 2400);
+    }
+  }
+  return void 0;
+}
 function normalizeJsonLikeStrings(text) {
   let out = "";
   let inStr = false;
@@ -10084,8 +10718,301 @@ function buildDefaultSkills() {
 }
 
 // src/core/debug_cache.ts
-import { promises as fs23 } from "fs";
+import { promises as fs24 } from "fs";
 import path24 from "path";
+
+// src/core/debug_brief.ts
+var MAX_EVIDENCE = 8;
+var MAX_EVIDENCE_LINE = 260;
+var MAX_TOOL_FAILURES = 6;
+var MAX_FAILED_TESTS = 8;
+var MAX_FILES = 10;
+function buildDebugBrief(input2) {
+  const reason = oneLine(input2.reason ?? "");
+  const raw = `${reason}
+${input2.failureLog ?? ""}`.trim();
+  const sections = splitFailureSections(raw);
+  const rootSignals = extractSignals(sections.root || raw);
+  const latestSignals = sections.latest ? extractSignals(sections.latest) : void 0;
+  const chosen = choosePrimarySignals(rootSignals, latestSignals);
+  const category = chosen.category;
+  const primaryError = chosen.primaryError || reason || "Unknown failure";
+  const failedTests = dedup3([...rootSignals.failedTests ?? [], ...latestSignals?.failedTests ?? []]).slice(0, MAX_FAILED_TESTS);
+  const files = dedup3([...rootSignals.files ?? [], ...latestSignals?.files ?? []]).slice(0, MAX_FILES);
+  const toolFailures = dedup3([...rootSignals.toolFailures ?? [], ...latestSignals?.toolFailures ?? []]).slice(0, MAX_TOOL_FAILURES);
+  const statusCodes = dedup3([...rootSignals.statusCodes ?? [], ...latestSignals?.statusCodes ?? []]).slice(0, 6);
+  const evidence = selectEvidenceLines(raw, category, primaryError, failedTests, files, toolFailures);
+  return {
+    version: 1,
+    category,
+    summary: buildSummary({ category, reason, primaryError, failedTests, files, phase: input2.phase, targetPhase: input2.targetPhase }),
+    primaryError,
+    debugDemand: buildDebugDemand(category, input2.targetPhase ?? input2.phase, statusCodes),
+    failedTests,
+    files,
+    toolFailures,
+    statusCodes,
+    evidence: evidence.lines,
+    omittedEvidenceLines: evidence.omitted
+  };
+}
+function renderDebugBriefForPrompt(brief) {
+  const lines = [
+    "## debug brief",
+    `- category: ${brief.category}`,
+    `- summary: ${brief.summary}`,
+    `- primaryError: ${brief.primaryError}`,
+    `- debugDemand: ${brief.debugDemand}`
+  ];
+  if (brief.failedTests.length > 0) lines.push(`- failedTests: ${brief.failedTests.join(", ")}`);
+  if (brief.files.length > 0) lines.push(`- likelyFiles: ${brief.files.join(", ")}`);
+  if (brief.toolFailures.length > 0) lines.push(`- toolFailures: ${brief.toolFailures.join(" | ")}`);
+  if (brief.statusCodes.length > 0) lines.push(`- httpStatus: ${brief.statusCodes.join(", ")}`);
+  if (brief.evidence.length > 0) {
+    lines.push("- keyEvidence:");
+    for (const line of brief.evidence) lines.push(`  - ${line}`);
+  }
+  if (brief.omittedEvidenceLines > 0) {
+    lines.push(`- omittedEvidenceLines: ${brief.omittedEvidenceLines}`);
+  }
+  return lines.join("\n");
+}
+function compactFailureEvidence(input2) {
+  const maxChars = input2.maxChars ?? 2400;
+  const maxLines = input2.maxLines ?? 50;
+  const reason = shouldSuppressReasonInEvidence(input2.reason, input2.failureLog) ? "" : input2.reason ?? "";
+  const raw = `${reason}
+${input2.failureLog ?? ""}`.trim();
+  if (!raw) return "";
+  const brief = buildDebugBrief({ ...input2, reason });
+  const important = selectEvidenceLines(
+    raw,
+    brief.category,
+    brief.primaryError,
+    brief.failedTests,
+    brief.files,
+    brief.toolFailures,
+    Math.min(MAX_EVIDENCE + 4, 12)
+  ).lines;
+  const tail = raw.split(/\r?\n/u).map((line) => line.trimEnd()).filter((line) => line.trim().length > 0).slice(-Math.max(10, Math.floor(maxLines / 2))).map((line) => truncateLine(line, 320));
+  const lines = dedup3([...important, ...tail]).slice(-maxLines);
+  const joined = lines.join("\n");
+  if (joined.length <= maxChars) return joined;
+  const head = joined.slice(0, Math.floor(maxChars * 0.45));
+  const tailText2 = joined.slice(-Math.floor(maxChars * 0.45));
+  return `${head}
+... [debug evidence truncated ${joined.length - head.length - tailText2.length} chars]
+${tailText2}`;
+}
+function splitFailureSections(text) {
+  const marker = /\n##\s+latest Debugger attempt failure\b/u.exec(text);
+  if (!marker) return { root: text };
+  return {
+    root: text.slice(0, marker.index).trim(),
+    latest: text.slice(marker.index + 1).trim()
+  };
+}
+function choosePrimarySignals(root, latest) {
+  if (!latest) return root;
+  if (isProcessNoise(latest.category) && !isProcessNoise(root.category)) return root;
+  if (latest.category !== "unknown") return latest;
+  return root.category !== "unknown" ? root : latest;
+}
+function extractSignals(text) {
+  const lines = normalizedLines(text);
+  const failedTests = extractFailedTests(text);
+  const files = extractFiles(text);
+  const toolFailures = extractToolFailures(lines);
+  const statusCodes = extractStatusCodes(text);
+  const category = classify(text, lines, failedTests, toolFailures);
+  return {
+    category,
+    primaryError: findPrimaryError(text, lines, category, failedTests, toolFailures),
+    failedTests,
+    files,
+    toolFailures,
+    statusCodes
+  };
+}
+function classify(text, lines, failedTests, toolFailures) {
+  const lower = text.toLowerCase();
+  if (/openai|ollama|openrouter|llm provider|provider_call_failed|all llm providers failed|prefill_memory_exceeded|context window|token limit|prompt too long/u.test(lower)) {
+    return "llm_provider";
+  }
+  if (/repeated read-only\/probe actions|read-only recovery mode|low-quality debugger response/u.test(lower)) {
+    return "tool_loop";
+  }
+  if (/permission denied/u.test(lower)) return "permission_denied";
+  if (/network api failure detected|http_fetch|https?:\/\/|http\s+(?:401|403|404|408|409|410|422|429|5\d\d)|timed out|timeout/u.test(lower)) {
+    if (!/openai|ollama|openrouter|llm provider/u.test(lower)) return "network_api_failure";
+  }
+  if (/modulenotfounderror|importerror/u.test(lower)) return "import_error";
+  if (/could not find a version|no matching distribution|pip install|add_dependency/u.test(lower)) return "dependency_error";
+  if (/syntaxerror|indentationerror|taberror/u.test(lower)) return "syntax_error";
+  if (/outputs? (?:still )?missing|missing required outputs?|outputs? \S*缺失|仍缺失/u.test(lower)) return "missing_output";
+  if (failedTests.length > 0 || /pytest exit=\s*[1-9]|tests? exit=\s*[1-9]|test gate|测试门禁|vitest|assertionerror|failed tests?|test failures?|(?:unit|integration|module|functional|gate) regression failed/u.test(lower)) {
+    return "test_failure";
+  }
+  if (toolFailures.length > 0) return "exception";
+  if (lines.some((line) => /error|exception|traceback|failed/i.test(line))) return "exception";
+  return "unknown";
+}
+function findPrimaryError(text, lines, category, failedTests, toolFailures) {
+  if (failedTests.length > 0 && category === "test_failure") return `failed test: ${failedTests[0]}`;
+  if (toolFailures.length > 0 && (category === "tool_loop" || category === "exception")) return toolFailures[0];
+  const patterns = [
+    /(?:SyntaxError|IndentationError|TabError|ModuleNotFoundError|ImportError|AssertionError|TypeError|ValueError|FileNotFoundError|AttributeError|RuntimeError):[^\n]+/u,
+    /\bFAILED\s+[^\n]+/u,
+    /\b(?:pytest|vitest)[^\n]*(?:exit|failed|FAIL)[^\n]*/iu,
+    /\bHTTP\s+(?:401|403|404|408|409|410|422|429|5\d\d)[^\n]*/iu,
+    /Network API failure detected[^\n]*/iu,
+    /outputs?[^\n]*(?:missing|缺失|仍缺失)[^\n]*/iu,
+    /repeated read-only\/probe actions[^\n]*/iu
+  ];
+  for (const pattern of patterns) {
+    const match = text.match(pattern)?.[0];
+    if (match) return oneLine(match);
+  }
+  const lastMeaningful = [...lines].reverse().find((line) => /error|exception|failed|exit=\s*[1-9]|缺失/i.test(line));
+  return oneLine(lastMeaningful ?? lines.at(-1) ?? "Unknown failure");
+}
+function buildSummary(args) {
+  const scope = args.targetPhase || args.phase ? ` in ${args.targetPhase ?? args.phase}` : "";
+  if (args.failedTests.length > 0) return `${args.category}${scope}: ${args.failedTests[0]} failed`;
+  if (args.files.length > 0) return `${args.category}${scope}: ${args.primaryError} (${args.files[0]})`;
+  return `${args.category}${scope}: ${args.primaryError || args.reason || "failure"}`;
+}
+function buildDebugDemand(category, phase, statusCodes = []) {
+  const phaseHint = phase ? ` for ${phase}` : "";
+  switch (category) {
+    case "test_failure":
+      return `Fix the root implementation/contract defect${phaseHint}, then run the smallest relevant test command before done=true. Do not rewrite fixtures unless evidence says the fixture is missing or malformed.`;
+    case "syntax_error":
+      return `Read the referenced file, patch the syntax/indentation at the failing location, then run tests.`;
+    case "import_error":
+      return `Resolve the real import/module path or dependency. Do not add fake fallback modules or swallow ImportError in production code.`;
+    case "dependency_error":
+      return `Replace hallucinated dependency names with real package names and update the manifest via add_dependency.`;
+    case "network_api_failure":
+      return networkDemand(statusCodes);
+    case "missing_output":
+      return `Create or repair the declared output files. Do not mark done=true until verify outputs passes.`;
+    case "tool_loop":
+      return `Stop repeating read-only/probe actions. Use the current evidence to make a patch/write/dependency change or run a concrete verification command.`;
+    case "permission_denied":
+      return `Treat the denied operation as a real blocker unless an allowed alternative exists; do not bypass the permission gate.`;
+    case "llm_provider":
+      return `This is provider/context infrastructure, not a project code bug. Reduce prompt/debug context or fix provider config before retrying.`;
+    case "exception":
+      return `Localize the exception to a file or tool call, make the smallest allowed repair, then verify.`;
+    case "unknown":
+      return `Read the most relevant files and produce a concrete diagnosis before making a minimal allowed repair.`;
+  }
+}
+function networkDemand(statusCodes) {
+  if (statusCodes.some((code) => code === "401" || code === "403")) {
+    return "The API is unauthorized/forbidden. If no user key/token is available, switch to a public no-key API and verify the real integration.";
+  }
+  if (statusCodes.some((code) => code === "404" || code === "410")) {
+    return "The API URL/resource is unavailable. Stop retrying the same URL; switch to a maintained endpoint and verify response shape.";
+  }
+  if (statusCodes.includes("429")) {
+    return "The API is rate-limited. Switch to a suitable fallback API or implement explicit retry/cache behaviour and tests.";
+  }
+  if (statusCodes.some((code) => /^5/u.test(code))) {
+    return "The API server failed. Use a stable fallback endpoint or fail closed with a clear user-visible error path.";
+  }
+  return "Locate the failing URL/status/body, patch the real API integration, and verify with run_program plus tests. Do not hide the API failure.";
+}
+function isProcessNoise(category) {
+  return ["tool_loop", "llm_provider", "permission_denied", "exception"].includes(category);
+}
+function shouldSuppressReasonInEvidence(reason, failureLog) {
+  if (!reason || !failureLog?.trim()) return false;
+  const lowerReason = reason.toLowerCase();
+  const lowerLog = failureLog.toLowerCase();
+  const hasRootSignal = /pytest exit=\s*[1-9]|tests? exit=\s*[1-9]|test gate|测试门禁|failed\s+(?:tests?|src)\/|assertionerror|syntaxerror|modulenotfounderror|importerror|network api failure|http\s+(?:401|403|404|408|409|410|422|429|5\d\d)|outputs?.*(?:missing|缺失|仍缺失)/u.test(lowerLog);
+  if (!hasRootSignal) return false;
+  return /script exhausted|completed phase debug finished without|repeated read-only\/probe actions|read-only recovery mode|low-quality debugger response|openai http (?:400|401|403|408|409|429|5\d\d)|rate limit exceeded|free-models-per-day|stream (?:wall-clock|idle)|request timed out|provider_call_failed|all llm providers failed/u.test(lowerReason);
+}
+function extractFailedTests(text) {
+  const patterns = [
+    /\bFAILED\s+([^\s]+(?:\.py|\.ts|\.tsx|\.js|\.jsx)(?:::[^\s]+)?)/gu,
+    /([^\s]+(?:\.py|\.ts|\.tsx|\.js|\.jsx)::[A-Za-z0-9_:[\].-]+)/gu,
+    /[×x]\s+([^\n]+?>\s+[^\n]+)/gu
+  ];
+  const out = [];
+  for (const pattern of patterns) {
+    for (const match of text.matchAll(pattern)) {
+      const value = oneLine(match[1] ?? "");
+      if (value) out.push(value);
+    }
+  }
+  return dedup3(out);
+}
+function extractFiles(text) {
+  const out = [];
+  const patterns = [
+    /\b((?:src|tests?|docs)\/[A-Za-z0-9_./-]+\.(?:py|ts|tsx|js|jsx|json|md|dbc|csv|xlsx?))/gu,
+    /File\s+["']([^"']+)["']/gu
+  ];
+  for (const pattern of patterns) {
+    for (const match of text.matchAll(pattern)) {
+      const file = normalizePath2(match[1] ?? "");
+      if (file && !file.includes("node_modules/")) out.push(file);
+    }
+  }
+  return dedup3(out);
+}
+function extractToolFailures(lines) {
+  return lines.filter((line) => /(?:\b(?:FAIL|failed|denied|exit=[1-9]|Error:)|失败)/iu.test(line)).filter((line) => /\b(?:run_tests|run_program|write_file|replace_in_file|apply_patch|append_file|http_fetch|add_dependency|read_file)\b/u.test(line)).map((line) => oneLine(line)).slice(0, MAX_TOOL_FAILURES);
+}
+function extractStatusCodes(text) {
+  const out = [];
+  for (const match of text.matchAll(/\b(?:HTTP\s*)?(401|403|404|408|409|410|422|429|5\d\d)\b/giu)) {
+    out.push(match[1]);
+  }
+  return dedup3(out);
+}
+function selectEvidenceLines(text, category, primaryError, failedTests, files, toolFailures, maxEvidence = MAX_EVIDENCE) {
+  const lines = normalizedLines(text);
+  const needles = [
+    primaryError,
+    ...failedTests,
+    ...files,
+    ...toolFailures,
+    category === "network_api_failure" ? "http" : "",
+    category === "missing_output" ? "missing" : "",
+    category === "tool_loop" ? "read-only" : ""
+  ].map((item) => item.toLowerCase()).filter(Boolean);
+  const selected = [];
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    if (needles.some((needle) => lower.includes(needle.slice(0, 80))) || /\b(?:FAILED|Traceback|Error|Exception|AssertionError|SyntaxError|ModuleNotFoundError|pytest exit=|HTTP\s*[45]\d\d|outputs?.*missing)\b/iu.test(line) || /失败/u.test(line)) {
+      selected.push(truncateLine(line, MAX_EVIDENCE_LINE));
+    }
+  }
+  const compact = dedup3(selected).slice(0, maxEvidence);
+  return { lines: compact, omitted: Math.max(0, selected.length - compact.length) };
+}
+function normalizedLines(text) {
+  return text.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0).filter((line) => !/^##\s+历史\s+DEBUG/u.test(line)).filter((line) => !/^##\s+修复建议/u.test(line)).filter((line) => !/^prior suggestions:/iu.test(line));
+}
+function oneLine(text) {
+  return truncateLine(text.replace(/\s+/gu, " ").trim(), MAX_EVIDENCE_LINE);
+}
+function truncateLine(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 24))}... [truncated ${text.length - max + 24} chars]`;
+}
+function normalizePath2(file) {
+  return file.replace(/\\/g, "/").replace(/^.*?((?:src|tests?|docs)\/)/u, "$1");
+}
+function dedup3(items) {
+  return [...new Set(items.filter((item) => String(item ?? "").length > 0))];
+}
+
+// src/core/debug_cache.ts
 var EMPTY = { version: 1, steps: {} };
 function sanitizeDebugFailureLogForPrompt(log) {
   const lines = log.split(/\r?\n/u);
@@ -10097,19 +11024,23 @@ function sanitizeDebugFailureLogForPrompt(log) {
       mode = "skip-history";
       continue;
     }
+    if (/^##\s+(?:debug brief|root issue brief|current retry brief)\b/u.test(line)) {
+      mode = "skip-brief";
+      continue;
+    }
     if (/^##\s+修复建议/u.test(line)) {
       mode = "skip-suggestions";
       continue;
     }
     if (mode === "skip-history") {
-      if (/^(原因：|Reason:|##\s+debug failure log\b)/u.test(line)) {
+      if (/^(原因：|Reason:|##\s+(?:debug failure log|compact failure evidence)\b)/u.test(line)) {
         mode = "keep";
       } else {
         continue;
       }
     }
     if (mode === "skip-suggestions") {
-      if (/^(原因：|Reason:|轮次：|工具调用：|---\s+|##\s+历史\s+DEBUG\s+尝试|##\s+debug failure log\b)/u.test(line)) {
+      if (/^(原因：|Reason:|轮次：|工具调用：|---\s+|##\s+历史\s+DEBUG\s+尝试|##\s+(?:debug failure log|compact failure evidence)\b)/u.test(line)) {
         mode = "keep";
         if (/^##\s+历史\s+DEBUG\s+尝试/u.test(line)) {
           mode = "skip-history";
@@ -10119,6 +11050,13 @@ function sanitizeDebugFailureLogForPrompt(log) {
         continue;
       }
     }
+    if (mode === "skip-brief") {
+      if (/^(原因：|Reason:|轮次：|工具调用：|---\s+|##\s+修复建议|##\s+历史\s+DEBUG\s+尝试|##\s+(?:debug failure log|compact failure evidence)\b)/u.test(line)) {
+        mode = "keep";
+      } else {
+        continue;
+      }
+    }
     if (/^\s*suggestions:\s/u.test(line)) continue;
     if (/^(原因：|Reason:)/u.test(line)) {
       const normalized = line.trim();
@@ -10156,7 +11094,7 @@ var DebugCache = class {
     if (this.loaded) return;
     this.loaded = true;
     try {
-      const raw = await fs23.readFile(this.file, "utf8");
+      const raw = await fs24.readFile(this.file, "utf8");
       const parsed = JSON.parse(raw);
       if (parsed && parsed.version === 1 && parsed.steps && typeof parsed.steps === "object") {
         this.data = { version: 1, steps: parsed.steps };
@@ -10184,11 +11122,24 @@ var DebugCache = class {
     const cleanedFailureLog = stripNestedLatestDebuggerFailures(
       sanitizeDebugFailureLogForPrompt(entry.failureLogTail ?? "")
     );
+    const debugBrief = buildDebugBrief({
+      reason: entry.reason,
+      failureLog: cleanedFailureLog
+    });
+    const compactFailureLog = compactFailureEvidence({
+      reason: entry.reason,
+      failureLog: cleanedFailureLog,
+      maxChars: 3600,
+      maxLines: this.maxLogLines
+    });
     const e = {
       attempt: entry.attempt,
       ts: entry.ts ?? (/* @__PURE__ */ new Date()).toISOString(),
       reason: (entry.reason ?? "").slice(0, 500),
-      failureLogTail: tail(cleanedFailureLog),
+      failureLogTail: tail(compactFailureLog),
+      debugBrief,
+      contextMode: entry.contextMode,
+      testScopeArgs: entry.testScopeArgs,
       suggestions: entry.suggestions,
       snapshotSha: entry.snapshotSha,
       metrics: entry.metrics
@@ -10253,8 +11204,10 @@ var DebugCache = class {
       const m = e.metrics ? ` [health=${e.metrics.healthScore.toFixed(2)} parseFail=${e.metrics.parseFailures} repeat=${e.metrics.repeatedTurns}]` : "";
       const sugg = e.suggestions && e.suggestions.length > 0 ? `
     prior suggestions: omitted (${e.suggestions.length}) to avoid stale guidance; use the current failure log first.` : "";
+      const brief = e.debugBrief ? `
+    brief: ${e.debugBrief.category} \u2014 ${e.debugBrief.summary}` : "";
       return `- attempt #${e.attempt} @ ${e.ts}${m}
-    reason: ${e.reason}${sugg}`;
+    reason: ${e.reason}${brief}${sugg}`;
     });
     const omitted = [
       noisyCount > 0 ? `- omitted ${noisyCount} noisy provider/read-only/recovery attempt(s); keep focus on the current actionable failure.` : "",
@@ -10270,18 +11223,609 @@ var DebugCache = class {
     ].join("\n");
   }
   async save() {
-    await fs23.mkdir(path24.dirname(this.file), { recursive: true });
-    await fs23.writeFile(this.file, JSON.stringify(this.data, null, 2), "utf8");
+    await fs24.mkdir(path24.dirname(this.file), { recursive: true });
+    await fs24.writeFile(this.file, JSON.stringify(this.data, null, 2), "utf8");
   }
 };
 function isNoisyDebugReason(reason) {
   const text = reason.toLowerCase();
-  return /repeated read-only\/probe actions without progress/u.test(text) || /read-only recovery mode repeated probe actions/u.test(text) || /low-quality debugger response/u.test(text) || /without repair evidence/u.test(text) || /had an unresolved failure from a previous run.*rolling back/u.test(text) || /tool verification failed.*rolling back/u.test(text) || /openai http (?:400|401|403|408|409|429|5\d\d)/u.test(text) || /rate limit exceeded|free-models-per-day|retry_after_seconds|retry-after/u.test(text) || /response_format|json_object|json_schema|invalid_request_body/u.test(text) || /stream (?:wall-clock|idle)|request timed out|fetch failed/u.test(text);
+  return /repeated read-only\/probe actions without progress/u.test(text) || /read-only recovery mode repeated probe actions/u.test(text) || /low-quality debugger response/u.test(text) || /script exhausted/u.test(text) || /without repair evidence/u.test(text) || /without a successful repair mutation or verification tool call/u.test(text) || /had an unresolved failure from a previous run.*rolling back/u.test(text) || /tool verification failed.*rolling back/u.test(text) || /openai http (?:400|401|403|408|409|429|5\d\d)/u.test(text) || /rate limit exceeded|free-models-per-day|retry_after_seconds|retry-after/u.test(text) || /response_format|json_object|json_schema|invalid_request_body/u.test(text) || /stream (?:wall-clock|idle)|request timed out|fetch failed/u.test(text);
 }
 
-// src/core/project_audit.ts
-import { promises as fs24 } from "fs";
+// src/core/debug_wiki.ts
+import { promises as fs25 } from "fs";
 import path25 from "path";
+import { fileURLToPath } from "url";
+import YAML3 from "yaml";
+var DEFAULT_DEBUG_WIKI_REL_PATH = ".xcompiler/debug-wiki";
+var BUNDLED_DEBUG_WIKI_REL_PATH = "debug-wiki";
+var DEBUG_WIKI_VERSION = 1;
+var LAYERS = ["system", "agent", "external"];
+var EMPTY_STATS = { uses: 0, successes: 0, failures: 0 };
+function defaultDebugWikiPath() {
+  const configured = xcEnv("PATH")?.trim();
+  const base = configured ? path25.resolve(configured) : path25.resolve(path25.dirname(fileURLToPath(import.meta.url)), "..", "..");
+  return path25.join(base, DEFAULT_DEBUG_WIKI_REL_PATH);
+}
+function bundledDebugWikiPath() {
+  return path25.join(path25.resolve(path25.dirname(fileURLToPath(import.meta.url)), "..", ".."), BUNDLED_DEBUG_WIKI_REL_PATH);
+}
+var DebugWiki = class {
+  loaded = false;
+  entries = [];
+  rootPath;
+  filePath;
+  bundledPath;
+  constructor(rootPath, opts = {}) {
+    this.rootPath = path25.resolve(rootPath);
+    this.filePath = this.rootPath;
+    this.bundledPath = opts.bundledPath ?? bundledDebugWikiPath();
+  }
+  async load() {
+    if (this.loaded) return;
+    this.loaded = true;
+    await this.ensureLayout();
+    await this.ensureRootReadme();
+    await this.ensureOperationLog();
+    await this.copyBundledLayers();
+    this.entries = [];
+    for (const layer of LAYERS) {
+      this.entries.push(...await this.readLayer(layer));
+    }
+    await this.applyFeedbackLog();
+    await this.writeIndex();
+  }
+  async search(brief, opts = {}) {
+    await this.load();
+    const limit = opts.limit ?? 3;
+    return this.rank(brief, opts.language).filter((match) => match.score >= 4).slice(0, limit);
+  }
+  async recordUse(entryIds, input2) {
+    await this.load();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const feedback = this.feedbackFrom(entryIds, input2, now, "used");
+    if (feedback.length === 0) return;
+    for (const item of feedback) {
+      const entry = this.byId(item.entryId);
+      if (!entry) continue;
+      entry.stats.uses += 1;
+      entry.lastUsedAt = now;
+      entry.updatedAt = now;
+      pushFeedback(entry, item);
+    }
+    await this.appendLayerFeedback(feedback);
+    await this.persistExternalEntries();
+    await this.writeIndex(now);
+    await this.appendOperationLog({
+      at: now,
+      action: "use",
+      entryIds: feedback.map((item) => item.entryId).filter(Boolean),
+      issueId: input2.issueId,
+      stepId: input2.stepId,
+      phase: input2.phase,
+      summary: input2.brief.summary
+    });
+  }
+  async recordFailure(entryIds, input2) {
+    await this.load();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const feedback = this.feedbackFrom(entryIds, input2, now, "failure", input2.reason);
+    if (feedback.length === 0) return;
+    for (const item of feedback) {
+      const entry = this.byId(item.entryId);
+      if (!entry) continue;
+      entry.stats.failures += 1;
+      entry.status = "needs_review";
+      entry.updatedAt = now;
+      pushFeedback(entry, item);
+    }
+    await this.appendLayerFeedback(feedback);
+    await this.persistExternalEntries();
+    await this.writeIndex(now);
+    await this.appendOperationLog({
+      at: now,
+      action: "failure",
+      entryIds: feedback.map((item) => item.entryId).filter(Boolean),
+      issueId: input2.issueId,
+      stepId: input2.stepId,
+      phase: input2.phase,
+      summary: input2.brief.summary,
+      reason: input2.reason
+    });
+  }
+  async recordResolution(input2) {
+    await this.load();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const used = this.byIds(input2.usedEntryIds ?? []);
+    const externalTargets = used.filter((entry) => entry.layer === "external");
+    const target = externalTargets.length > 0 ? externalTargets : this.rank(input2.brief, input2.language).filter((match) => match.entry.layer === "external" && match.score >= 8).slice(0, 1).map((m) => m.entry);
+    const updated = [];
+    let createdId;
+    for (const entry of target) {
+      this.applyResolution(entry, input2, now, entry.stats.failures > 0 ? "corrected" : "success");
+      updated.push(entry.id);
+    }
+    if (updated.length === 0) {
+      const created = createEntry(input2, now, this.nextExternalId(now), "external");
+      created.supersedes = used.length > 0 ? used.map((entry) => entry.id) : void 0;
+      this.entries.push(created);
+      createdId = created.id;
+    }
+    const correctedFeedback = this.feedbackFrom(
+      used.filter((entry) => entry.layer !== "external").map((entry) => entry.id),
+      input2,
+      now,
+      "corrected"
+    );
+    for (const item of correctedFeedback) {
+      const entry = this.byId(item.entryId);
+      if (!entry) continue;
+      entry.stats.successes += 1;
+      entry.status = "active";
+      entry.updatedAt = now;
+      pushFeedback(entry, item);
+    }
+    await this.appendLayerFeedback(correctedFeedback);
+    await this.persistExternalEntries();
+    await this.writeIndex(now);
+    await this.appendOperationLog({
+      at: now,
+      action: createdId ? "resolution_created" : "resolution_updated",
+      entryIds: createdId ? [createdId] : updated,
+      issueId: input2.issueId,
+      stepId: input2.stepId,
+      phase: input2.phase,
+      summary: input2.brief.summary
+    });
+    return createdId ? { created: createdId, updated: [] } : { updated };
+  }
+  async ensureLayout() {
+    for (const layer of LAYERS) {
+      await fs25.mkdir(this.layerDir(layer), { recursive: true });
+    }
+  }
+  async ensureRootReadme() {
+    const to = path25.join(this.rootPath, "README.md");
+    if (await exists(to)) return;
+    const from = path25.join(this.bundledPath, "README.md");
+    const fallback = defaultDebugWikiReadme();
+    const text = await fs25.readFile(from, "utf8").catch(() => fallback);
+    await fs25.writeFile(to, text.endsWith("\n") ? text : `${text}
+`, "utf8");
+  }
+  async ensureOperationLog() {
+    const file = this.operationLogPath();
+    if (await exists(file)) return;
+    await fs25.writeFile(file, "# XCompiler Debug Wiki Log\n\nAppend-only operational notes for retrieval, failed reuse, and confirmed repairs.\n", "utf8");
+  }
+  async copyBundledLayers() {
+    if (path25.resolve(this.bundledPath) === this.rootPath) return;
+    for (const layer of ["system", "agent"]) {
+      const from = path25.join(this.bundledPath, "wiki", layer);
+      const to = this.layerDir(layer);
+      if (!await exists(from)) continue;
+      await fs25.cp(from, to, { recursive: true, force: true });
+    }
+  }
+  async readLayer(layer) {
+    const dir = this.layerDir(layer);
+    const files = (await fs25.readdir(dir).catch(() => [])).filter((file) => file.endsWith(".md")).sort();
+    const entries = [];
+    for (const file of files) {
+      const abs = path25.join(dir, file);
+      const page = parseWikiPage(await fs25.readFile(abs, "utf8"));
+      const entry = normalizeEntry({ ...page.data, layer, solution: page.data.solution ?? page.body }, layer);
+      entry.sourcePath = path25.relative(this.rootPath, abs).replace(/\\/g, "/");
+      entries.push(entry);
+    }
+    return entries;
+  }
+  async applyFeedbackLog() {
+    const log = await fs25.readFile(this.feedbackPath(), "utf8").catch(() => "");
+    for (const line of log.split(/\r?\n/u)) {
+      if (!line.trim()) continue;
+      const item = JSON.parse(line);
+      const entry = this.byId(item.entryId);
+      if (!entry) continue;
+      if (item.kind === "used") entry.stats.uses += 1;
+      if (item.kind === "failure") {
+        entry.stats.failures += 1;
+        entry.status = "needs_review";
+      }
+      if (item.kind === "success" || item.kind === "corrected") {
+        entry.stats.successes += 1;
+        if (item.kind === "corrected") entry.status = "active";
+      }
+      entry.updatedAt = item.at;
+      pushFeedback(entry, item);
+    }
+  }
+  applyResolution(entry, input2, now, kind) {
+    entry.status = "active";
+    entry.updatedAt = now;
+    entry.summary = input2.brief.summary;
+    entry.primaryError = input2.brief.primaryError;
+    entry.debugDemand = input2.brief.debugDemand;
+    entry.fingerprints = dedup4([...entry.fingerprints, ...fingerprints(input2.brief)]);
+    entry.symptoms = dedup4([...input2.brief.evidence, ...entry.symptoms]).slice(0, 12);
+    entry.evidence = dedup4([...input2.evidence ?? [], ...entry.evidence]).slice(0, 12);
+    if (input2.resolutionPlan?.trim()) entry.resolutionPlan = input2.resolutionPlan.trim();
+    entry.solution = mergeSolution(entry.solution, input2.solution);
+    entry.repairFiles = dedup4([...input2.repairFiles ?? [], ...entry.repairFiles ?? []]).slice(0, 12);
+    entry.stats.successes += 1;
+    pushFeedback(entry, {
+      at: now,
+      kind,
+      entryId: entry.id,
+      issueId: input2.issueId,
+      stepId: input2.stepId,
+      phase: input2.phase,
+      summary: input2.brief.summary
+    });
+  }
+  async persistExternalEntries() {
+    for (const entry of this.entries.filter((item) => item.layer === "external")) {
+      const abs = path25.join(this.rootPath, entry.sourcePath ?? this.externalEntryPath(entry));
+      entry.sourcePath = path25.relative(this.rootPath, abs).replace(/\\/g, "/");
+      await fs25.mkdir(path25.dirname(abs), { recursive: true });
+      await fs25.writeFile(abs, renderWikiPage(entry), "utf8");
+    }
+  }
+  async appendFeedback(feedback) {
+    if (feedback.length === 0) return;
+    await fs25.mkdir(path25.dirname(this.feedbackPath()), { recursive: true });
+    await fs25.appendFile(this.feedbackPath(), feedback.map((item) => JSON.stringify(item)).join("\n") + "\n", "utf8");
+  }
+  async appendLayerFeedback(feedback) {
+    await this.appendFeedback(feedback.filter((item) => this.byId(item.entryId)?.layer !== "external"));
+  }
+  async appendOperationLog(entry) {
+    await fs25.mkdir(path25.dirname(this.operationLogPath()), { recursive: true });
+    await fs25.appendFile(this.operationLogPath(), renderOperationLogEntry(entry), "utf8");
+  }
+  async writeIndex(now = (/* @__PURE__ */ new Date()).toISOString()) {
+    const layerCounts = Object.fromEntries(LAYERS.map((layer) => [
+      layer,
+      { entries: this.entries.filter((entry) => entry.layer === layer).length, writable: layer === "external" }
+    ]));
+    const index = {
+      version: DEBUG_WIKI_VERSION,
+      updatedAt: now,
+      root: this.rootPath,
+      layers: layerCounts,
+      entries: this.entries.map((entry) => ({
+        id: entry.id,
+        layer: entry.layer,
+        status: entry.status,
+        category: entry.category,
+        summary: entry.summary,
+        updatedAt: entry.updatedAt,
+        sourcePath: entry.sourcePath
+      }))
+    };
+    await fs25.writeFile(path25.join(this.rootPath, "index.json"), `${JSON.stringify(index, null, 2)}
+`, "utf8");
+    await fs25.writeFile(path25.join(this.rootPath, "index.md"), renderReadableIndex(index, this.entries), "utf8");
+  }
+  feedbackFrom(ids, input2, now, kind, reason) {
+    return dedup4(ids).filter((id) => this.byId(id)).map((id) => ({
+      at: now,
+      kind,
+      entryId: id,
+      issueId: input2.issueId,
+      stepId: input2.stepId,
+      phase: input2.phase,
+      summary: input2.brief.summary,
+      reason
+    }));
+  }
+  rank(brief, language) {
+    const queryTokens = new Set(tokensForBrief(brief));
+    const queryFingerprints = fingerprints(brief);
+    return this.entries.filter((entry) => entry.status !== "superseded").map((entry) => {
+      const reasons = [];
+      let score = entry.layer === "agent" ? 1 : entry.layer === "system" ? 0.5 : 0;
+      if (entry.category === brief.category) {
+        score += 4;
+        reasons.push(`category:${entry.category}`);
+      }
+      if (language && entry.language === language) score += 1;
+      const exact = entry.fingerprints.filter((fp) => queryFingerprints.includes(fp));
+      if (exact.length > 0) {
+        score += exact.length * 3;
+        reasons.push(`fingerprint:${exact.length}`);
+      }
+      const entryTokens = new Set(tokensForEntry(entry));
+      let overlap = 0;
+      for (const token of queryTokens) if (entryTokens.has(token)) overlap++;
+      score += Math.min(6, overlap);
+      if (overlap > 0) reasons.push(`tokens:${overlap}`);
+      const confidence = confidenceFor(entry);
+      return { entry, score: score * confidence, confidence, reasons };
+    }).sort((a, b) => b.score - a.score);
+  }
+  byId(id) {
+    return this.entries.find((entry) => entry.id === id);
+  }
+  byIds(ids) {
+    const wanted = new Set(ids);
+    return this.entries.filter((entry) => wanted.has(entry.id));
+  }
+  layerDir(layer) {
+    return path25.join(this.rootPath, "wiki", layer);
+  }
+  feedbackPath() {
+    return path25.join(this.rootPath, "wiki", "external", "feedback.jsonl");
+  }
+  operationLogPath() {
+    return path25.join(this.rootPath, "log.md");
+  }
+  nextExternalId(now) {
+    const stamp = now.replace(/[-:.TZ]/g, "").slice(0, 14);
+    const count = this.entries.filter((entry) => entry.layer === "external").length + 1;
+    return `external.${stamp}.${String(count).padStart(4, "0")}`;
+  }
+  externalEntryPath(entry) {
+    return path25.join("wiki", "external", `${slugify(entry.id)}.md`);
+  }
+};
+function renderDebugWikiMatchesForPrompt(matches) {
+  if (matches.length === 0) return "";
+  const lines = [
+    "## debug wiki matches",
+    "LLM-wiki layered retrieval. Treat entries as hypotheses, verify against current files/tests, and stop using any entry that current evidence disproves."
+  ];
+  for (const match of matches) {
+    const entry = match.entry;
+    lines.push(
+      `- ${entry.id} layer=${entry.layer} score=${match.score.toFixed(2)} confidence=${match.confidence.toFixed(2)} status=${entry.status}`,
+      `  problem: [${entry.category}] ${entry.summary}`,
+      `  symptoms: ${entry.symptoms.slice(0, 4).join(" | ") || entry.primaryError}`,
+      entry.resolutionPlan ? `  priorPlan: ${entry.resolutionPlan}` : "",
+      `  confirmedSolution: ${entry.solution}`,
+      `  feedback: uses=${entry.stats.uses} successes=${entry.stats.successes} failures=${entry.stats.failures}`
+    );
+    if (entry.repairFiles?.length) lines.push(`  repairFiles: ${entry.repairFiles.join(", ")}`);
+    if (entry.supersedes?.length) lines.push(`  supersedes: ${entry.supersedes.join(", ")}`);
+    if (match.reasons.length) lines.push(`  matchedBy: ${match.reasons.join(", ")}`);
+  }
+  return lines.filter(Boolean).join("\n");
+}
+function createEntry(input2, now, id, layer) {
+  return normalizeEntry({
+    id,
+    layer,
+    createdAt: now,
+    updatedAt: now,
+    status: "active",
+    category: input2.brief.category,
+    summary: input2.brief.summary,
+    primaryError: input2.brief.primaryError,
+    debugDemand: input2.brief.debugDemand,
+    fingerprints: fingerprints(input2.brief),
+    symptoms: input2.brief.evidence.slice(0, 12),
+    resolutionPlan: input2.resolutionPlan?.trim(),
+    solution: input2.solution,
+    evidence: (input2.evidence ?? input2.brief.evidence).slice(0, 12),
+    sourceIssueId: input2.issueId,
+    sourceStepId: input2.stepId,
+    sourcePhase: input2.phase,
+    targetPhase: input2.targetPhase,
+    language: input2.language,
+    repairFiles: input2.repairFiles?.slice(0, 12),
+    stats: { uses: 0, successes: 1, failures: 0 },
+    feedback: [{ at: now, kind: "success", entryId: id, issueId: input2.issueId, stepId: input2.stepId, phase: input2.phase, summary: input2.brief.summary }]
+  }, layer);
+}
+function normalizeEntry(raw, layer) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  return {
+    id: String(raw.id ?? `${layer}.${slugify(raw.summary ?? raw.primaryError ?? "entry")}`),
+    layer: raw.layer ?? layer,
+    createdAt: raw.createdAt ?? now,
+    updatedAt: raw.updatedAt ?? raw.createdAt ?? now,
+    status: raw.status ?? "active",
+    category: raw.category ?? "unknown",
+    summary: raw.summary ?? raw.primaryError ?? "Debug wiki entry",
+    primaryError: raw.primaryError ?? raw.summary ?? "",
+    debugDemand: raw.debugDemand ?? "",
+    fingerprints: raw.fingerprints ?? [],
+    symptoms: raw.symptoms ?? [],
+    resolutionPlan: raw.resolutionPlan,
+    solution: raw.solution ?? "",
+    evidence: raw.evidence ?? [],
+    sourceIssueId: raw.sourceIssueId,
+    sourceStepId: raw.sourceStepId,
+    sourcePhase: raw.sourcePhase,
+    targetPhase: raw.targetPhase,
+    language: raw.language,
+    repairFiles: raw.repairFiles ?? [],
+    supersedes: raw.supersedes ?? [],
+    stats: { ...EMPTY_STATS, ...raw.stats ?? {} },
+    lastUsedAt: raw.lastUsedAt,
+    feedback: (raw.feedback ?? []).slice(-20),
+    sourcePath: raw.sourcePath
+  };
+}
+function renderWikiPage(entry) {
+  const frontmatter = { ...entry, sourcePath: void 0 };
+  return [
+    "---",
+    YAML3.stringify(frontmatter).trim(),
+    "---",
+    "",
+    `# ${entry.summary}`,
+    "",
+    "## Problem",
+    "",
+    `- category: ${entry.category}`,
+    `- status: ${entry.status}`,
+    `- primaryError: ${entry.primaryError || "n/a"}`,
+    `- debugDemand: ${entry.debugDemand || "n/a"}`,
+    "",
+    "## Resolution Plan",
+    "",
+    entry.resolutionPlan?.trim() || "No explicit plan recorded.",
+    "",
+    "## Confirmed Solution",
+    "",
+    entry.solution.trim() || "No confirmed solution recorded.",
+    "",
+    "## Evidence",
+    "",
+    renderMarkdownList(entry.evidence),
+    "",
+    "## Retrieval",
+    "",
+    `- fingerprints: ${entry.fingerprints.join(", ") || "n/a"}`,
+    `- repairFiles: ${(entry.repairFiles ?? []).join(", ") || "n/a"}`,
+    `- stats: uses=${entry.stats.uses} successes=${entry.stats.successes} failures=${entry.stats.failures}`,
+    "",
+    "## Feedback",
+    "",
+    renderMarkdownList(entry.feedback.slice(-8).map((item) => `${item.at} ${item.kind}: ${item.summary}`)),
+    ""
+  ].join("\n");
+}
+function parseWikiPage(text) {
+  const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/u);
+  if (!match) return { data: {}, body: text.trim() };
+  return { data: YAML3.parse(match[1] ?? "") ?? {}, body: (match[2] ?? "").trim() };
+}
+function fingerprints(brief) {
+  return dedup4([
+    `cat:${brief.category}`,
+    brief.primaryError ? `err:${normalize(brief.primaryError)}` : "",
+    ...brief.failedTests.map((test) => `test:${normalize(test)}`),
+    ...brief.files.map((file) => `file:${normalize(file)}`),
+    ...brief.statusCodes.map((code) => `http:${code}`)
+  ]);
+}
+function tokensForBrief(brief) {
+  return tokenize2([brief.summary, brief.primaryError, brief.debugDemand, ...brief.failedTests, ...brief.files, ...brief.evidence, ...brief.statusCodes].join(" "));
+}
+function tokensForEntry(entry) {
+  return tokenize2([entry.id, entry.summary, entry.primaryError, entry.debugDemand, entry.resolutionPlan ?? "", entry.solution, ...entry.symptoms, ...entry.evidence, ...entry.repairFiles ?? []].join(" "));
+}
+function tokenize2(text) {
+  return dedup4(text.toLowerCase().split(/[^a-z0-9_./:-]+/u).filter((token) => token.length >= 3));
+}
+function normalize(text) {
+  return tokenize2(text).slice(0, 24).join(" ");
+}
+function renderReadableIndex(index, entries) {
+  const lines = [
+    "# XCompiler Debug Wiki Index",
+    "",
+    `Updated: ${index.updatedAt}`,
+    "",
+    "This file is regenerated from wiki pages and feedback overlays. Edit knowledge pages under `wiki/`, not this index.",
+    "",
+    "## Layers",
+    "",
+    "| Layer | Entries | Writable | Purpose |",
+    "| --- | ---: | --- | --- |"
+  ];
+  for (const layer of LAYERS) {
+    const info = index.layers[layer];
+    lines.push(`| ${layer} | ${info.entries} | ${info.writable ? "yes" : "no"} | ${layerPurpose(layer)} |`);
+  }
+  for (const layer of LAYERS) {
+    const layerEntries = entries.filter((entry) => entry.layer === layer);
+    lines.push("", `## ${layer}`, "");
+    if (layerEntries.length === 0) {
+      lines.push("No entries.");
+      continue;
+    }
+    lines.push("| ID | Status | Category | Summary | Source |", "| --- | --- | --- | --- | --- |");
+    for (const entry of layerEntries) {
+      const source = entry.sourcePath ? `[${entry.sourcePath}](${entry.sourcePath})` : "";
+      lines.push(`| ${escapeTable(entry.id)} | ${entry.status} | ${entry.category} | ${escapeTable(entry.summary)} | ${source} |`);
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function renderOperationLogEntry(entry) {
+  const lines = [
+    "",
+    `- ${entry.at} ${entry.action}: ${entry.entryIds.join(", ") || "none"}`,
+    `  - issue: ${entry.issueId ?? "n/a"}; step: ${entry.stepId ?? "n/a"}; phase: ${entry.phase ?? "n/a"}`,
+    `  - summary: ${entry.summary}`
+  ];
+  if (entry.reason) lines.push(`  - reason: ${entry.reason}`);
+  return `${lines.join("\n")}
+`;
+}
+function defaultDebugWikiReadme() {
+  return [
+    "# XCompiler Debug Wiki",
+    "",
+    "This directory is an LLM-wiki style knowledge base for Debugger repair.",
+    "",
+    "- `wiki/system/` contains system-level debug policies and safety rules.",
+    "- `wiki/agent/` contains agent-level calibration knowledge derived from recurring LLM failure patterns.",
+    "- `wiki/external/` stores real project issue resolutions and feedback.",
+    "- `index.md` is a human-readable regenerated catalog.",
+    "- `index.json` is the machine-readable retrieval cache.",
+    "- `log.md` is an append-only operational log.",
+    ""
+  ].join("\n");
+}
+function layerPurpose(layer) {
+  switch (layer) {
+    case "system":
+      return "bundled system debug policies";
+    case "agent":
+      return "bundled agent calibration knowledge";
+    case "external":
+      return "local project issue resolutions";
+  }
+}
+function renderMarkdownList(items) {
+  const compact = items.map((item) => item.trim()).filter(Boolean);
+  if (compact.length === 0) return "- n/a";
+  return compact.map((item) => `- ${item}`).join("\n");
+}
+function escapeTable(text) {
+  return text.replace(/\|/gu, "\\|").replace(/\r?\n/gu, " ");
+}
+function confidenceFor(entry) {
+  const total = entry.stats.uses + entry.stats.successes + entry.stats.failures;
+  const base = (entry.stats.successes + 1) / Math.max(2, total + 2);
+  const statusFactor = entry.status === "needs_review" ? 0.45 : 1;
+  const layerFactor = entry.layer === "system" ? 0.9 : 1;
+  return Math.max(0.1, Math.min(1, base * statusFactor * layerFactor));
+}
+function mergeSolution(previous, next) {
+  const trimmed = next.trim();
+  if (!trimmed || previous.includes(trimmed)) return previous;
+  if (!previous.trim()) return trimmed;
+  return `${previous.trim()}
+Corrected/confirmed resolution: ${trimmed}`;
+}
+function pushFeedback(entry, feedback) {
+  entry.feedback.push(feedback);
+  if (entry.feedback.length > 20) entry.feedback.splice(0, entry.feedback.length - 20);
+}
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9._-]+/gu, "-").replace(/^-+|-+$/gu, "").slice(0, 96) || "entry";
+}
+async function exists(filePath) {
+  try {
+    await fs25.stat(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function dedup4(items) {
+  return [...new Set(items.filter((item) => String(item ?? "").length > 0))];
+}
+
+// src/core/project_audit.ts
+import { promises as fs26 } from "fs";
+import path26 from "path";
 function renderProjectAuditFailureLog(result) {
   const failed = result.checks.filter((check) => !check.ok);
   const interesting = failed.length > 0 ? failed : result.checks;
@@ -10330,12 +11874,12 @@ async function checkDocumentationBundle(ws, projectType, iterationId) {
   const docs = iterationId ? deliveryDocsForIteration(projectType, iterationId) : deliveryDocsForProjectType(projectType);
   const checks = [];
   for (const doc of docs) {
-    const exists = await ws.exists(doc);
+    const exists2 = await ws.exists(doc);
     checks.push({
       name: docCheckName(doc),
-      severity: exists ? "info" : "error",
-      ok: exists,
-      summary: exists ? t().execute.auditDocPresent(doc) : t().execute.auditDocMissing(doc)
+      severity: exists2 ? "info" : "error",
+      ok: exists2,
+      summary: exists2 ? t().execute.auditDocPresent(doc) : t().execute.auditDocMissing(doc)
     });
   }
   return checks;
@@ -10456,14 +12000,14 @@ async function listFiles(ws, dir) {
 async function walk3(abs, rel, out) {
   let entries;
   try {
-    entries = await fs24.readdir(abs, { withFileTypes: true });
+    entries = await fs26.readdir(abs, { withFileTypes: true });
   } catch {
     return;
   }
   for (const entry of entries) {
     if (entry.name.startsWith(".")) continue;
     const childRel = `${rel}/${entry.name}`;
-    const childAbs = path25.join(abs, entry.name);
+    const childAbs = path26.join(abs, entry.name);
     if (entry.isDirectory()) {
       await walk3(childAbs, childRel, out);
     } else {
@@ -10483,6 +12027,7 @@ var PhaseEngine = class {
     this.skills = opts.skills ?? buildDefaultSkills();
     this.plugins = opts.plugins ?? new PluginHost();
     this.debugCache = new DebugCache(opts.ws.abs(".xcompiler/debug_cache.json"));
+    this.debugWiki = new DebugWiki(opts.debugWikiPath ?? defaultDebugWikiPath());
   }
   opts;
   registry;
@@ -10491,6 +12036,8 @@ var PhaseEngine = class {
   pluginExtensionsApplied = false;
   /** 跨 xcompiler run 持久化的 debug 历史（`<workspace>/.xcompiler/debug_cache.json`）。 */
   debugCache;
+  /** 跨项目 debug 知识库，记录错误摘要、解决方案和正/负反馈。 */
+  debugWiki;
   /** 当前 Plan 的语言 profile（在 run() 起始处按 plan.language 解析）。 */
   profile = getLanguageProfile("python");
   /** 当前 workspace 的项目记忆，用于给执行阶段注入更稳定的跨轮上下文。 */
@@ -10510,6 +12057,21 @@ var PhaseEngine = class {
   spin(text, options) {
     return this.terminalOutput ? spinner(text, options).start() : null;
   }
+  async withDebugWiki(operation, action, fallback) {
+    try {
+      return await action();
+    } catch (err) {
+      const message = err.message;
+      await this.opts.audit.event("note", `debug wiki ${operation} failed: ${message}`, {
+        messageId: "engine.debug_wiki_failed",
+        operation,
+        path: this.debugWiki.filePath,
+        error: message
+      });
+      if (this.opts.debugWikiStrict) throw err;
+      return fallback;
+    }
+  }
   async requestEnginePermission(request) {
     if (!this.opts.requestPermission) return { approved: true };
     const decision = await this.opts.requestPermission(request);
@@ -10534,6 +12096,7 @@ var PhaseEngine = class {
   }
   async run(plan) {
     await this.plugins.initialize();
+    await this.withDebugWiki("load", () => this.debugWiki.load(), void 0);
     if (!this.pluginExtensionsApplied) {
       this.plugins.applyExtensions({ tools: this.registry, skills: this.skills });
       this.pluginExtensionsApplied = true;
@@ -10741,7 +12304,23 @@ var PhaseEngine = class {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     this.issueSeq += 1;
     const id = `ISSUE-${now.replace(/[-:.TZ]/g, "").slice(0, 14)}-${String(this.issueSeq).padStart(3, "0")}`;
-    const failureLog = cleanFailureLogForDebugContext(input2.failureLog);
+    const rawFailureLog = input2.failureLog ?? "";
+    const cleanedFailureLog = cleanFailureLogForDebugContext(rawFailureLog);
+    const debugBrief = buildDebugBrief({
+      reason: input2.reason,
+      failureLog: cleanedFailureLog,
+      phase: step?.phase
+    });
+    const failureLog = compactFailureEvidence({
+      reason: input2.reason,
+      failureLog: cleanedFailureLog,
+      phase: step?.phase,
+      maxChars: 6e3,
+      maxLines: 90
+    });
+    const rawFailureLogPath = `.xcompiler/issues/${id}/failure.raw.log`;
+    await this.opts.ws.writeFile(rawFailureLogPath, rawFailureLog.endsWith("\n") ? rawFailureLog : `${rawFailureLog}
+`);
     const issue = {
       id,
       createdAt: now,
@@ -10759,6 +12338,9 @@ var PhaseEngine = class {
       title: step?.title,
       reason: input2.reason,
       failureLog,
+      failureLogBytes: Buffer.byteLength(rawFailureLog, "utf8"),
+      rawFailureLogPath,
+      debugBrief,
       metrics: input2.metrics,
       evidence: input2.evidence
     };
@@ -10776,6 +12358,12 @@ var PhaseEngine = class {
     issue.status = "routed";
     issue.targetStepId = target.id;
     issue.targetPhase = target.phase;
+    issue.debugBrief = buildDebugBrief({
+      reason: issue.reason,
+      failureLog: issue.failureLog,
+      phase: issue.phase,
+      targetPhase: target.phase
+    });
     issue.routedAt = (/* @__PURE__ */ new Date()).toISOString();
     issue.updatedAt = issue.routedAt;
     await this.persistIssue(issue, "routed", { routingReason: reason });
@@ -10794,13 +12382,27 @@ var PhaseEngine = class {
     issue.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
     await this.persistIssue(issue, "unresolved", { reason });
   }
-  async markIssueResolved(issueId, step, repair) {
+  async markIssueResolved(issueId, step, repair, issueResolutionPlan) {
     const issue = issueId ? this.findIssue(issueId) : void 0;
     if (!issue) return;
     issue.status = "resolved";
     issue.resolvedAt = (/* @__PURE__ */ new Date()).toISOString();
     issue.updatedAt = issue.resolvedAt;
     if (repair) issue.repair = repair;
+    if (issueResolutionPlan?.trim()) {
+      issue.issueResolutionPlan = issueResolutionPlan.trim();
+      issue.resolutionPlanHistory = [
+        ...issue.resolutionPlanHistory ?? [],
+        {
+          at: issue.resolvedAt,
+          stepId: step.id,
+          phase: step.phase,
+          plan: issue.issueResolutionPlan,
+          outcome: "accepted"
+        }
+      ].slice(-8);
+    }
+    await this.recordDebugWikiResolution(issue, step, repair);
     await this.persistIssue(issue, "resolved");
     await this.opts.audit.event("issue.resolve", `${issue.id} resolved by ${step.id} ${step.phase}`, {
       messageId: "engine.issue_resolved",
@@ -10810,6 +12412,82 @@ var PhaseEngine = class {
       repair
     });
   }
+  async recordDebugWikiFailure(step, debug, outcome) {
+    const entryIds = dedup5(debug.debugWikiEntryIds ?? []);
+    if (entryIds.length === 0) return;
+    const issue = debug.issueId ? this.findIssue(debug.issueId) : void 0;
+    const brief = buildDebugBrief({
+      reason: outcome.reason ?? debug.reason,
+      failureLog: cleanFailureLogForDebugContext(outcome.failureLog),
+      phase: issue?.phase ?? step.phase,
+      targetPhase: issue?.targetPhase ?? step.phase
+    });
+    await this.withDebugWiki(
+      "record-failure",
+      () => this.debugWiki.recordFailure(entryIds, {
+        brief,
+        issueId: issue?.id,
+        stepId: step.id,
+        phase: step.phase,
+        targetPhase: issue?.targetPhase,
+        language: this.profile.id,
+        solution: "retrieved wiki solution did not resolve this attempt",
+        reason: outcome.reason ?? debug.reason
+      }),
+      void 0
+    );
+    await this.opts.audit.event("note", `debug wiki marked ${entryIds.join(", ")} for review`, {
+      messageId: "engine.debug_wiki_feedback",
+      kind: "failure",
+      entryIds,
+      issueId: issue?.id,
+      stepId: step.id,
+      reason: outcome.reason ?? debug.reason
+    });
+  }
+  async recordDebugWikiResolution(issue, step, repair) {
+    const brief = issue.debugBrief ?? buildDebugBrief({
+      reason: issue.reason,
+      failureLog: issue.failureLog,
+      phase: issue.phase,
+      targetPhase: issue.targetPhase
+    });
+    const repairFiles = repair?.changedFiles?.length ? repair.changedFiles : step.outputs;
+    const evidenceSummary = [
+      `Resolved ${issue.kind} by Debugger in ${step.id}/${step.phase}.`,
+      `Mode: ${repair?.mode ?? "verification"}.`,
+      repairFiles.length > 0 ? `Changed/verified files: ${repairFiles.join(", ")}.` : "",
+      repair?.patchPath ? `Patch: ${repair.patchPath}.` : "",
+      `Demand: ${brief.debugDemand}`
+    ].filter(Boolean).join(" ");
+    const solution = issue.issueResolutionPlan ? `${issue.issueResolutionPlan}
+Resolution evidence: ${evidenceSummary}` : evidenceSummary;
+    const result = await this.withDebugWiki(
+      "record-resolution",
+      () => this.debugWiki.recordResolution({
+        brief,
+        issueId: issue.id,
+        stepId: step.id,
+        phase: step.phase,
+        targetPhase: issue.targetPhase,
+        language: this.profile.id,
+        resolutionPlan: issue.issueResolutionPlan,
+        solution,
+        evidence: brief.evidence,
+        repairFiles,
+        usedEntryIds: issue.debugWikiEntryIds
+      }),
+      { updated: [] }
+    );
+    if (result.created || result.updated.length > 0) {
+      await this.opts.audit.event("note", `debug wiki updated after ${issue.id}`, {
+        messageId: "engine.debug_wiki_updated",
+        issueId: issue.id,
+        created: result.created,
+        updated: result.updated
+      });
+    }
+  }
   findIssue(issueId) {
     return this.issues.find((issue) => issue.id === issueId);
   }
@@ -10829,6 +12507,10 @@ var PhaseEngine = class {
       targetStepId: issue.targetStepId,
       targetPhase: issue.targetPhase,
       reason: issue.reason,
+      debugSummary: issue.debugBrief?.summary,
+      debugDemand: issue.debugBrief?.debugDemand,
+      debugWikiEntryIds: issue.debugWikiEntryIds,
+      issueResolutionPlan: issue.issueResolutionPlan,
       ...extra
     });
     await this.opts.ws.writeFile(eventPath, `${existing}${line}
@@ -10848,6 +12530,7 @@ var PhaseEngine = class {
     const diff = await this.opts.git.raw().diff([beforeRef, "--"]).catch((err) => `# git diff failed: ${err.message}
 `);
     const mode = inferRepairMode(toolCalls);
+    const changedFiles = parsePatchChangedFiles(diff);
     await this.opts.ws.writeFile(patchPath, diff || "# No textual diff captured.\n");
     await this.opts.ws.writeFile(
       summaryPath,
@@ -10871,7 +12554,8 @@ var PhaseEngine = class {
       completedBeforeDebug,
       mode,
       patchPath,
-      summaryPath
+      summaryPath,
+      changedFiles
     };
   }
   async completedPhaseRepairViolation(toolCalls) {
@@ -10888,13 +12572,13 @@ var PhaseEngine = class {
     return void 0;
   }
   async repairChangedFiles() {
-    const planPath = normalizeGitPath(path26.relative(this.opts.ws.root, path26.resolve(this.opts.planPath)));
+    const planPath = normalizeGitPath(path27.relative(this.opts.ws.root, path27.resolve(this.opts.planPath)));
     const status = await this.opts.git.raw().status();
     return status.files.map((file) => normalizeGitPath(file.path)).filter((file) => file.length > 0).filter((file) => !isRuntimeOnlyChange(file, planPath));
   }
   testGateArgsForStep(step) {
     if (step.phase === "FUNCTIONAL_TEST") return [];
-    return dedup3(
+    return dedup5(
       step.outputs.filter((out) => typeof out === "string" && !out.endsWith("/")).map((out) => normalizeGitPath(out)).filter(isTestFilePath)
     );
   }
@@ -11062,7 +12746,7 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
         initialDebug: {
           reason,
           failureLog: debugFailureLog,
-          contextPaths: dedup3([
+          contextPaths: dedup5([
             ...sourceStep.inputs,
             ...sourceStep.outputs,
             ...routedTest.inputs,
@@ -11070,7 +12754,7 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
             ...failedTest.inputs,
             ...failedTest.outputs
           ]),
-          extraAllowedWrites: dedup3([...routedTest.outputs]),
+          extraAllowedWrites: dedup5([...routedTest.outputs]),
           contextMode: "test-rollback",
           testScopeArgs: this.testGateArgsForStep(routedTest),
           issueId: issue?.id,
@@ -11211,6 +12895,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
     await this.debugCache.load();
     const initialDebug = opts.initialDebug;
     const inheritedExtraAllowedWrites = initialDebug?.extraAllowedWrites;
+    const inheritedContextMode = initialDebug?.contextMode;
+    const inheritedTestScopeArgs = initialDebug?.testScopeArgs;
     const completedBeforeDebug = initialDebug?.completedBeforeDebug ?? step.status === "DONE";
     const rootDebugFailureLog = initialDebug ? cleanFailureLogForDebugContext(initialDebug.failureLog) : void 0;
     const includeRootDebugFailureLog = (failureLog, reason) => rootDebugFailureLog ? composeDebugRetryFailureLog(rootDebugFailureLog, failureLog, reason) : failureLog;
@@ -11244,7 +12930,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
           priorAttemptsPrompt: priorPrompt,
           contextPaths: initialDebug.contextPaths,
           extraAllowedWrites: inheritedExtraAllowedWrites,
-          contextMode: initialDebug.contextMode,
+          contextMode: inheritedContextMode,
+          testScopeArgs: inheritedTestScopeArgs,
           issueId: activeIssueId,
           completedBeforeDebug
         });
@@ -11252,6 +12939,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
         const attempts = this.debugCache.attempts(step.id);
         const last = attempts.slice(-1)[0];
         const resume = latestActionableDebugAttempt(attempts) ?? last;
+        const cachedTestScopeArgs = inferCachedTestScopeArgs(resume);
+        const cachedContextMode = resume.contextMode ?? (cachedTestScopeArgs.length > 0 ? "test-rollback" : void 0);
         this.log(
           chalk2.yellow(
             t().engine.debugResumeNotice(step.id, attempts.length)
@@ -11279,6 +12968,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
               reason: resume.reason,
               priorAttemptsPrompt: priorPrompt,
               extraAllowedWrites: inheritedExtraAllowedWrites,
+              contextMode: cachedContextMode,
+              testScopeArgs: cachedTestScopeArgs,
               issueId: activeIssueId,
               completedBeforeDebug
             });
@@ -11307,6 +12998,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
             reason: resume.reason,
             priorAttemptsPrompt: priorPrompt,
             extraAllowedWrites: inheritedExtraAllowedWrites,
+            contextMode: cachedContextMode,
+            testScopeArgs: cachedTestScopeArgs,
             issueId: activeIssueId,
             completedBeforeDebug
           });
@@ -11357,6 +13050,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
       suggestions: calibrateDebugSuggestions(cleanFailureLogForDebugContext(initialFailureLogForRecord), initialReason).map(
         (s) => `[${s.code}] ${s.hint}`
       ),
+      contextMode: inheritedContextMode,
+      testScopeArgs: inheritedTestScopeArgs,
       metrics: initial.metrics ? {
         healthScore: initial.metrics.healthScore,
         parseFailures: initial.metrics.parseFailures,
@@ -11428,6 +13123,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
           reason: lastReason,
           priorAttemptsPrompt: priorPrompt,
           extraAllowedWrites: inheritedExtraAllowedWrites,
+          contextMode: inheritedContextMode,
+          testScopeArgs: inheritedTestScopeArgs,
           issueId: activeIssueId,
           completedBeforeDebug
         });
@@ -11483,6 +13180,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
           suggestions: calibrateDebugSuggestions(cleanFailureLogForDebugContext(recordedFailureLog2), rollbackReason).map(
             (s) => `[${s.code}] ${s.hint}`
           ),
+          contextMode: inheritedContextMode,
+          testScopeArgs: inheritedTestScopeArgs,
           metrics: r.metrics ? {
             healthScore: r.metrics.healthScore,
             parseFailures: r.metrics.parseFailures,
@@ -11502,9 +13201,11 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
       }
       const m = r.metrics;
       const readOnlyProbeLoop = isReadOnlyProbeLoopFailure(r.reason);
+      const missingOutputStall = isMissingOutputStallFailure(r.reason);
+      const lowQualityDebuggerResponse = isLowQualityDebuggerResponseFailure(r.reason);
       const repairEvidenceMissing = isRepairEvidenceMissingFailure(r.reason);
-      const healthy = !readOnlyProbeLoop && !repairEvidenceMissing && !!m && m.parseFailures === 0 && m.repeatedTurns <= 1 && m.healthScore >= 0.6;
-      const bad = readOnlyProbeLoop || repairEvidenceMissing || !!m && (m.healthScore < 0.3 || m.parseFailures + m.repeatedTurns >= Math.max(2, Math.ceil(m.rounds / 2)));
+      const healthy = !readOnlyProbeLoop && !missingOutputStall && !lowQualityDebuggerResponse && !repairEvidenceMissing && !!m && m.parseFailures === 0 && m.repeatedTurns <= 1 && m.healthScore >= 0.6;
+      const bad = readOnlyProbeLoop || missingOutputStall || lowQualityDebuggerResponse || repairEvidenceMissing || !!m && (m.healthScore < 0.3 || m.parseFailures + m.repeatedTurns >= Math.max(2, Math.ceil(m.rounds / 2)));
       const tag = m ? `health=${m.healthScore.toFixed(2)} parseFail=${m.parseFailures} repeat=${m.repeatedTurns} progress=${m.progressRatio.toFixed(2)}` : "";
       if (healthy) {
         const before = budget;
@@ -11555,6 +13256,8 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
         suggestions: calibrateDebugSuggestions(cleanFailureLogForDebugContext(recordedFailureLog), r.reason ?? "").map(
           (s) => `[${s.code}] ${s.hint}`
         ),
+        contextMode: inheritedContextMode,
+        testScopeArgs: inheritedTestScopeArgs,
         metrics: m ? {
           healthScore: m.healthScore,
           parseFailures: m.parseFailures,
@@ -11674,9 +13377,75 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
         `${iterationPrefix}/api-guide.md`
       ] : []
     ];
-    if (failedNames.has("entrypoint")) return dedup3([...codeAndTests, ...docs]);
-    if (failedNames.has("tests") || failedNames.has("test-files")) return dedup3([...codeAndTests, ...docs]);
-    return dedup3([...codeAndTests, ...step.inputs, ...docs]);
+    if (failedNames.has("entrypoint")) return dedup5([...codeAndTests, ...docs]);
+    if (failedNames.has("tests") || failedNames.has("test-files")) return dedup5([...codeAndTests, ...docs]);
+    return dedup5([...codeAndTests, ...step.inputs, ...docs]);
+  }
+  async buildDebugPromptPayload(step, debug, failureLog) {
+    const issue = debug.issueId ? this.findIssue(debug.issueId) : void 0;
+    const currentBrief = buildDebugBrief({
+      reason: debug.reason,
+      failureLog,
+      phase: issue?.phase ?? step.phase,
+      targetPhase: issue?.targetPhase ?? step.phase
+    });
+    const rootBrief = issue?.debugBrief;
+    const briefBlocks = rootBrief && rootBrief.summary !== currentBrief.summary ? [
+      "## root issue brief",
+      renderDebugBriefForPrompt(rootBrief),
+      "",
+      "## current retry brief",
+      renderDebugBriefForPrompt(currentBrief)
+    ] : [renderDebugBriefForPrompt(currentBrief)];
+    const evidence = compactFailureEvidence({
+      reason: debug.reason,
+      failureLog,
+      phase: issue?.phase ?? step.phase,
+      targetPhase: issue?.targetPhase ?? step.phase,
+      maxChars: 2600,
+      maxLines: 50
+    });
+    const suggestions = renderDebugSuggestions(
+      calibrateDebugSuggestions(failureLog, debug.reason)
+    );
+    const wikiMatches = await this.withDebugWiki(
+      "search",
+      () => this.debugWiki.search(currentBrief, { language: this.profile.id, limit: 3 }),
+      []
+    );
+    const debugWikiEntryIds = wikiMatches.map((match) => match.entry.id);
+    if (debugWikiEntryIds.length > 0) {
+      debug.debugWikiEntryIds = dedup5([...debug.debugWikiEntryIds ?? [], ...debugWikiEntryIds]);
+      if (issue) {
+        issue.debugWikiEntryIds = dedup5([...issue.debugWikiEntryIds ?? [], ...debugWikiEntryIds]);
+      }
+      await this.withDebugWiki(
+        "record-use",
+        () => this.debugWiki.recordUse(debugWikiEntryIds, {
+          brief: currentBrief,
+          issueId: issue?.id,
+          stepId: step.id,
+          phase: step.phase,
+          targetPhase: issue?.targetPhase,
+          language: this.profile.id,
+          solution: "retrieved for Debugger prompt"
+        }),
+        void 0
+      );
+      await this.opts.audit.event("note", `debug wiki matched ${debugWikiEntryIds.join(", ")}`, {
+        messageId: "engine.debug_wiki_matched",
+        entryIds: debugWikiEntryIds,
+        stepId: step.id,
+        phase: step.phase
+      });
+    }
+    const wikiPrompt = renderDebugWikiMatchesForPrompt(wikiMatches);
+    return {
+      debugBrief: [briefBlocks.join("\n"), wikiPrompt].filter(Boolean).join("\n\n"),
+      failureLog: evidence,
+      suggestions,
+      debugWikiEntryIds
+    };
   }
   /** 一次执行尝试：可选 debug 模式（使用 Debugger 角色 + 注入失败日志）。 */
   async runOneAttempt(plan, step, debug) {
@@ -11690,6 +13459,9 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
     });
     try {
       const outcome = await this.runOneAttemptCore(plan, step, debug);
+      if (debug && !outcome.ok) {
+        await this.recordDebugWikiFailure(step, debug, outcome);
+      }
       await this.plugins.emit("step.attempt.after", {
         plan,
         step,
@@ -11705,6 +13477,9 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
         failureLog: error instanceof Error ? error.stack ?? error.message : String(error),
         reason: error instanceof Error ? error.message : String(error)
       };
+      if (debug) {
+        await this.recordDebugWikiFailure(step, debug, outcome);
+      }
       await this.plugins.emit("step.attempt.after", {
         plan,
         step,
@@ -11728,10 +13503,10 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
         hints.push(`[debugger] ${dbg.prompt}`);
       }
     }
-    const allNames = dedup3([...resolvedToolNames, ...extraNames]);
+    const allNames = dedup5([...resolvedToolNames, ...extraNames]);
     const baseTools = this.registry.pick(allNames);
-    const allowedWrites = debug ? dedup3([...this.computeDebugAllowedWrites(plan, step), ...debug.extraAllowedWrites ?? []]) : this.computeStepAllowedWrites(plan, step);
-    const augmentedWrites = this.isVModelTestPhase(step.phase) || step.phase === "DEBUG" || debug ? dedup3([...allowedWrites, "tests/fixtures"]) : allowedWrites;
+    const allowedWrites = debug ? dedup5([...this.computeDebugAllowedWrites(plan, step), ...debug.extraAllowedWrites ?? []]) : this.computeStepAllowedWrites(plan, step);
+    const augmentedWrites = this.isVModelTestPhase(step.phase) || step.phase === "DEBUG" || debug ? dedup5([...allowedWrites, "tests/fixtures"]) : allowedWrites;
     const budgetContext = {
       phase: step.phase,
       role,
@@ -11818,6 +13593,7 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
       { animate: false }
     );
     const debugFailureLog = debug ? cleanFailureLogForDebugContext(debug.failureLog) : void 0;
+    const debugPayload = debug ? await this.buildDebugPromptPayload(step, debug, debugFailureLog ?? debug.failureLog) : void 0;
     try {
       const r = await executor.run({
         step,
@@ -11827,14 +13603,15 @@ ${cleanFailureLogForDebugContext(sourceFailureLog)}` : ""
         contextSnippets: ctxSnippets,
         skillHints: hints,
         debugContext: debug ? {
+          issueId: debug.issueId,
           reason: debug.reason,
-          failureLog: debugFailureLog ?? debug.failureLog,
+          failureLog: debugPayload?.failureLog ?? debugFailureLog ?? debug.failureLog,
+          debugBrief: debugPayload?.debugBrief,
           repairRequired: !debug.completedBeforeDebug,
-          suggestions: renderDebugSuggestions(
-            calibrateDebugSuggestions(debugFailureLog ?? debug.failureLog, debug.reason)
-          ) + (debug.priorAttemptsPrompt ? `
-
-${debug.priorAttemptsPrompt}` : "")
+          suggestions: [
+            debugPayload?.suggestions,
+            debug.priorAttemptsPrompt
+          ].filter(Boolean).join("\n\n")
         } : void 0,
         globalPrompt: plan.globalPrompt,
         languageProfile: this.profile
@@ -12087,7 +13864,7 @@ ${pt.stderr}`);
           r.toolCalls
         ) : void 0;
         if (debug?.issueId) {
-          await this.markIssueResolved(debug.issueId, step, repair);
+          await this.markIssueResolved(debug.issueId, step, repair, r.issueResolutionPlan);
         }
         await this.opts.git.snapshot(step.id, step.retries, debug ? "debug done" : "done");
         spin?.succeed(t().engine.phaseDone(step.id, r.rounds));
@@ -12096,9 +13873,12 @@ ${pt.stderr}`);
           rounds: r.rounds,
           retry: step.retries
         });
-        return { ok: true, failureLog: "" };
+        return { ok: true, failureLog: "", issueResolutionPlan: r.issueResolutionPlan };
+      }
+      let reason = r.error ?? t().engine.outputsMissing(verify.missing.join(", "));
+      if (debug?.completedBeforeDebug && !hasSuccessfulRepairMutation(r.toolCalls) && hasFailedVerificationEvidence(r.toolCalls)) {
+        reason = "completed phase debug finished with failed verification but without a successful repair mutation";
       }
-      const reason = r.error ?? t().engine.outputsMissing(verify.missing.join(", "));
       const m = r.metrics;
       const metricsLine = m ? t().engine.metricsLine(m.healthScore.toFixed(2), m.parseFailures, m.repeatedTurns, m.toolFailRatio.toFixed(2), m.progressRatio.toFixed(2)) : t().engine.metricsUnavailable;
       const failureLog = [
@@ -12132,7 +13912,7 @@ ${pt.stderr}`);
       } else {
         await this.opts.git.revertTo(sha);
       }
-      return { ok: false, failureLog, reason, metrics: m, issueKind: "phase" };
+      return { ok: false, failureLog, reason, metrics: m, issueKind: "phase", issueResolutionPlan: r.issueResolutionPlan };
     } catch (err) {
       const msg = err.message;
       const stack = err.stack ?? msg;
@@ -12146,7 +13926,7 @@ ${pt.stderr}`);
       });
       return { ok: false, failureLog: stack, reason: msg, issueKind: "exception" };
     } finally {
-      void path26;
+      void path27;
     }
   }
   async buildContextSnippets(plan, step, debug) {
@@ -12203,7 +13983,7 @@ ${pt.stderr}`);
     if (downstream) {
       out.set(`.xcompiler/downstream/${step.id}.md`, downstream);
     }
-    return [...out.entries()].map(([path30, content]) => ({ path: path30, content }));
+    return [...out.entries()].map(([path31, content]) => ({ path: path31, content }));
   }
   findOwningTestStepForFailure(plan, currentStep, failureText) {
     const failedPaths = extractFailedTestPaths(failureText);
@@ -12326,7 +14106,7 @@ ${pt.stderr}`);
     ].join("\n").length;
   }
 };
-function dedup3(arr) {
+function dedup5(arr) {
   return [...new Set(arr)];
 }
 function isDesignSourcePhase(phase) {
@@ -12358,6 +14138,9 @@ var REPAIR_VERIFICATION_TOOLS = /* @__PURE__ */ new Set([
 function hasSuccessfulVerificationEvidence(toolCalls) {
   return toolCalls.some((call) => call.ok && REPAIR_VERIFICATION_TOOLS.has(call.tool));
 }
+function hasFailedVerificationEvidence(toolCalls) {
+  return toolCalls.some((call) => !call.ok && REPAIR_VERIFICATION_TOOLS.has(call.tool));
+}
 function shouldRollbackTestPhaseFromToolFailures(step, toolCalls) {
   let unresolvedTestFailure = false;
   for (const call of toolCalls) {
@@ -12477,32 +14260,65 @@ function extractFailedTestPaths(text) {
       if (file && isTestFilePath(file)) found.push(file);
     }
   }
-  return dedup3(found);
+  return dedup5(found);
 }
 function isNonDebuggableInfrastructureFailure(reason, failureLog) {
   const text = `${reason ?? ""}
 ${failureLog ?? ""}`.toLowerCase();
-  return /typeerror:\s*fetch failed/u.test(text) || /(?:openai|ollama) http (?:401|403|408|409|429|5\d\d)\b/u.test(text) || /\bhttp (?:401|403|408|409|429|5\d\d)\b/u.test(text) || /rate limit exceeded|free-models-per-day|retry_after_seconds|retry-after/u.test(text) || /(?:openai|ollama|llm|provider)[^\n]{0,180}(?:rate[- ]?limit|rate limited|rate-limited|retry-after|retry_after_seconds)/u.test(text) || /(?:response_format|json_object|json_schema)[^\n]{0,220}(?:not support|unsupported|invalid_request_body|supported formats)/u.test(text) || /openai stream (?:wall-clock|idle)/u.test(text) || /ollama stream (?:wall-clock|idle)/u.test(text) || /request timed out after \d+ms/u.test(text) || /prefill_memory_exceeded|prefill memory guard|dynamic ceiling/u.test(text) || /context (?:length|window)|token limit|too many tokens|prompt too long|max(?:imum)? context/u.test(text) || /input[^\n]{0,80}tokens[^\n]{0,120}(?:exceed|limit|ceiling)/u.test(text) || /llm provider|provider_call_failed|all llm providers failed/u.test(text);
+  if (/low-quality debugger response/u.test(text)) return false;
+  return /typeerror:\s*fetch failed/u.test(text) || /(?:openai|ollama) http (?:401|403|408|409|429|5\d\d)\b/u.test(text) || /rate limit exceeded|free-models-per-day|retry_after_seconds|retry-after/u.test(text) || /(?:openai|ollama|llm|provider)[^\n]{0,180}(?:rate[- ]?limit|rate limited|rate-limited|retry-after|retry_after_seconds)/u.test(text) || /(?:response_format|json_object|json_schema)[^\n]{0,220}(?:not support|unsupported|invalid_request_body|supported formats)/u.test(text) || /openai stream (?:wall-clock|idle)/u.test(text) || /ollama stream (?:wall-clock|idle)/u.test(text) || /request timed out after \d+ms/u.test(text) || /prefill_memory_exceeded|prefill memory guard|dynamic ceiling/u.test(text) || /context (?:length|window)|token limit|too many tokens|prompt too long|max(?:imum)? context/u.test(text) || /input[^\n]{0,80}tokens[^\n]{0,120}(?:exceed|limit|ceiling)/u.test(text) || /llm provider|provider_call_failed|all llm providers failed/u.test(text);
 }
 function isReadOnlyProbeLoopFailure(reason) {
   return /repeated read-only\/probe actions without progress/u.test(reason ?? "") || /read-only recovery mode repeated probe actions/u.test(reason ?? "");
 }
+function isMissingOutputStallFailure(reason) {
+  return /write\/progress actions did not reduce missing outputs/u.test(reason ?? "");
+}
+function isLowQualityDebuggerResponseFailure(reason) {
+  return /low-quality debugger response/u.test(reason ?? "");
+}
 function isRepairEvidenceMissingFailure(reason) {
-  return /without repair evidence/u.test(reason ?? "") || /without a successful repair mutation or verification tool call/u.test(reason ?? "");
+  return /without repair evidence/u.test(reason ?? "") || /without a successful repair mutation/u.test(reason ?? "") || /without a successful repair mutation or verification tool call/u.test(reason ?? "");
 }
 function shouldRollbackTestPhaseFailure(reason, failureLog) {
   const text = `${reason ?? ""}
 ${failureLog ?? ""}`.toLowerCase();
   if (isReadOnlyProbeLoopFailure(reason) || isRepairEvidenceMissingFailure(reason)) return false;
+  if (/tool verification failed.*rolling back to paired/u.test(text)) return true;
   if (isCachedTestArtifactDiscoveryFailure(text)) return false;
   if (/missing outputs|outputs? 校验|verify outputs|declared outputs|产物/u.test(text)) return false;
   if (/invalid action|args must be an object|invalid json|parse failure/u.test(text)) return false;
-  if (/tool verification failed.*rolling back to paired/u.test(text)) return true;
-  if (/test gate|functional gate|functional entry probe|entry probe|delivery gate/u.test(text)) return true;
+  if (/test gate|functional gate|functional entry probe|entry probe|delivery gate|测试门禁|功能门禁|功能入口探测|入口探测|交付门禁/u.test(text)) return true;
   if (/pytest exit=\s*[1-9]\d*|exit code\s*[1-9]\d*|failed tests?|test failures?/u.test(text)) return true;
   if (/assertionerror|failed:\s+did not|traceback \(most recent call last\)/u.test(text)) return true;
   return false;
 }
+function inferCachedTestScopeArgs(entry) {
+  const explicit = (entry.testScopeArgs ?? []).map(normalizeGitPath).filter(isTestFilePath);
+  if (explicit.length > 0) return dedup5(explicit);
+  const text = [
+    entry.failureLogTail,
+    entry.debugBrief?.toolFailures?.join("\n") ?? "",
+    entry.debugBrief?.evidence?.join("\n") ?? ""
+  ].filter(Boolean).join("\n");
+  const fromRunTestsArgs = extractRunTestsArgs(text);
+  if (fromRunTestsArgs.length > 0) return fromRunTestsArgs;
+  const failedPaths = extractFailedTestPaths(text);
+  if (failedPaths.length > 0) return failedPaths;
+  return dedup5((entry.debugBrief?.files ?? []).map(normalizeGitPath).filter(isTestFilePath));
+}
+function extractRunTestsArgs(text) {
+  const out = [];
+  for (const match of text.matchAll(/\brun_tests[^\n]*\bargs=([^\n]+)/giu)) {
+    const raw = match[1] ?? "";
+    for (const token of raw.split(/\s+/u)) {
+      const cleaned = token.replace(/^["'`]+|["'`,;]+$/gu, "");
+      const normalized = normalizeGitPath(cleaned);
+      if (isTestFilePath(normalized)) out.push(normalized);
+    }
+  }
+  return dedup5(out);
+}
 function isCachedTestArtifactDiscoveryFailure(text) {
   return /no test files? found|no tests? found/u.test(text) || /filter:\s+tests?\//u.test(text) || /(?:enoent|no such file or directory|not a file)[^\n]{0,240}tests?\//u.test(text);
 }
@@ -12558,6 +14374,13 @@ function inferRepairMode(toolCalls) {
   if (usedRewrite) return "rewrite";
   return "verification";
 }
+function parsePatchChangedFiles(diff) {
+  const files = [];
+  for (const match of diff.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gmu)) {
+    files.push(normalizeGitPath(match[2] ?? match[1] ?? ""));
+  }
+  return dedup5(files.filter(Boolean));
+}
 
 // src/runtime/run.ts
 async function runExecute(opts) {
@@ -12566,7 +14389,7 @@ async function runExecute(opts) {
     io.interaction?.pauseStdin?.();
   } catch {
   }
-  const ws = new Workspace(path27.resolve(opts.workspace));
+  const ws = new Workspace(path28.resolve(opts.workspace));
   const { config: cfg, path: cfgPath } = await loadConfigWithPath(opts.configPath);
   if (!hasXcEnv("LANG")) setLocale(cfg.locale);
   let lock;
@@ -12736,6 +14559,8 @@ async function runExecute(opts) {
     maxEditLinesPerStep: cfg.agent.max_edit_lines_per_step,
     maxWriteChunkBytes: cfg.agent.max_write_chunk_bytes,
     terminalOutput: opts.terminalOutput ?? true,
+    debugWikiPath: opts.debugWikiPath ? path28.resolve(opts.debugWikiPath) : void 0,
+    debugWikiStrict: !!opts.debugWikiPath,
     requestPermission: io.requestPermission ? async (request) => {
       await io.emit({ type: "permission", status: "requested", request });
       const decision = await io.requestPermission(request);
@@ -12980,15 +14805,15 @@ async function emitProjectAudit(io, result) {
 }
 
 // src/runtime/workspace.ts
-import path28 from "path";
-import { promises as fs25 } from "fs";
+import path29 from "path";
+import { promises as fs27 } from "fs";
 
 // src/runtime/commands.ts
 async function runRunCommand(opts) {
   const cwd = opts.cwd ?? process.cwd();
   const explicit = opts.output ?? opts.workspace;
-  const workspace = explicit ? path29.resolve(explicit) : opts.planArg ? path29.dirname(path29.resolve(opts.planArg)) : cwd;
-  const planPath = opts.planArg ? path29.resolve(opts.planArg) : await defaultRunnablePlanPath(workspace);
+  const workspace = explicit ? path30.resolve(explicit) : opts.planArg ? path30.dirname(path30.resolve(opts.planArg)) : cwd;
+  const planPath = opts.planArg ? path30.resolve(opts.planArg) : await defaultRunnablePlanPath(workspace);
   return runExecute({
     ...opts,
     workspace,
@@ -12997,15 +14822,15 @@ async function runRunCommand(opts) {
   });
 }
 async function defaultRunnablePlanPath(workspace) {
-  const phasePlanPath = path29.join(workspace, DEFAULT_PHASE_PLAN_FILE);
+  const phasePlanPath = path30.join(workspace, DEFAULT_PHASE_PLAN_FILE);
   if (await fileExists2(phasePlanPath)) return phasePlanPath;
-  const legacyPlanPath = path29.join(workspace, DEFAULT_PLAN_FILE);
+  const legacyPlanPath = path30.join(workspace, DEFAULT_PLAN_FILE);
   if (await fileExists2(legacyPlanPath)) return legacyPlanPath;
   return phasePlanPath;
 }
 async function fileExists2(filePath) {
   try {
-    await fs26.stat(filePath);
+    await fs28.stat(filePath);
     return true;
   } catch {
     return false;
@@ -13184,7 +15009,7 @@ configureLocalizedHelp(program);
 program.name("xcompiler_run").description(t().cli.runDescription).version(XCOMPILER_VERSION, "-V, --version", t().cli.versionOption).option("--lang <code>", t().cli.optLang, parseLocale).hook("preAction", (cmd) => {
   const l = cmd.opts().lang;
   if (l) setLocale(l);
-}).argument("[plan]", t().cli.argPlan).option("-o, --output <dir>", t().cli.optOutput).option("-w, --workspace <dir>", t().cli.optWorkspace).option("-c, --config <file>", t().cli.optConfig).option("--dry-run", t().cli.optDryRun, false).option("--from <stepId>", t().cli.optFrom, parseStepId).option("--phase <phase>", t().cli.optPhase, parsePhase).option("--reset", t().cli.optReset, false).option("--force", t().cli.optForce, false).option("--project-file <file>", t().cli.optProjectFile).action(async (planArg, opts) => {
+}).argument("[plan]", t().cli.argPlan).option("-o, --output <dir>", t().cli.optOutput).option("-w, --workspace <dir>", t().cli.optWorkspace).option("-c, --config <file>", t().cli.optConfig).option("--dry-run", t().cli.optDryRun, false).option("--from <stepId>", t().cli.optFrom, parseStepId).option("--phase <phase>", t().cli.optPhase, parsePhase).option("--reset", t().cli.optReset, false).option("--force", t().cli.optForce, false).option("--project-file <file>", t().cli.optProjectFile).option("--debug-wiki-path <dir>", t().cli.optDebugWikiPath).action(async (planArg, opts) => {
   const result = await runRunCommand({
     planArg,
     output: opts.output,
@@ -13196,6 +15021,7 @@ program.name("xcompiler_run").description(t().cli.runDescription).version(XCOMPI
     resetStatus: !!opts.reset,
     force: !!opts.force,
     projectFilePath: opts.projectFile,
+    debugWikiPath: opts.debugWikiPath,
     cwd: process.cwd(),
     io: createCliRuntimeIO()
   });