kc-beta 0.7.3 → 0.8.1

package/src/agent/engine.js

@@ -5,6 +5,9 @@ import {
   deriveSkillAuthoringMilestones,
   deriveSkillTestingMilestones,
 } from "./pipelines/_milestone-derive.js";
+import { getPrescriptiveHint } from "./pipelines/_advance-hints.js";
+import { loadEnvFile } from "../config.js";
+import { MarathonDriver } from "../marathon/driver.js";
 import { ContextAssembler } from "./context.js";
 import { ConversationHistory } from "./history.js";
 import { findSafeSplitPoint } from "./message-utils.js";
@@ -38,6 +41,7 @@ import { TierDowngradeTool } from "./tools/tier-downgrade.js";
 import { AgentTool } from "./tools/agent-tool.js";
 import { WebSearchTool } from "./tools/web-search.js";
 import { TaskCreateTool, TaskUpdateTool, TaskCompleteTool } from "./tools/task-board.js";
+import { ConsultSkillTool } from "./tools/consult-skill.js";
 import { SkillLoader } from "./skill-loader.js";
 import { TaskManager } from "./task-manager.js";
 import { Scheduler } from "./scheduler.js";
@@ -165,6 +169,10 @@ export class AgentEngine {
       { gitAutoCommit: config.gitAutoCommit !== false },
     );
 
+    // v0.8 P1-B: workspace .env overlay deferred until after eventLog
+    // init (see _overlayWorkspaceEnv call below). Workspace dir is
+    // known here, but the overlay's audit event needs eventLog.
+
     // For sub-agents, persistence (history/events/state) lives under
     // sub_agents/<scope>/ instead of the workspace root. Workspace files
     // (rules/, rule_skills/, workflows/) stay shared.
@@ -202,6 +210,26 @@ export class AgentEngine {
     // Event log (append-only JSONL, source of truth)
     this.eventLog = new EventLog(this.workspace.cwd, { logDir });
 
+    // v0.8 P1-B: overlay workspace .env onto this.config. cli/index.js
+    // calls loadSettings() without a workspace path because the path
+    // isn't known until this constructor runs. Result: workspace .env's
+    // VLM_TIER1 / OCR_MODEL_TIER1 / TIER1..4 / LANGUAGE were silently
+    // ignored, with gc defaults (~/.kc_agent/config.json) winning.
+    // 资管 audit § 9.2 finding 7: user's OCR_MODEL_TIER1=zai-org/GLM-4.6V
+    // never reached document_parse; error messages quoted gc's
+    // Qwen3-VL-235B default. Overlay reads workspace .env, fills in
+    // fields where current config came from gc fallback (penv-set values
+    // still win because loadSettings applied them).
+    try { this._overlayWorkspaceEnv(); } catch { /* best-effort */ }
+
+    // v0.8.1 P8-A: inline marathon driver. v0.8.0's separate-process
+    // kc-marathon CLI + filesystem-watcher IPC died silently when the
+    // launching terminal closed (E2E #11 audit). Redesigned as an inline
+    // state machine activated via /marathon slash command. No filesystem
+    // marker, no inbox.jsonl. Driver instance set by enterMarathonMode(),
+    // cleared by exitMarathonMode(). Query via this.marathonDriver.
+    this.marathonDriver = null;
+
     // Context windowing
     this.contextWindow = new ContextWindow({
       contextLimit: config.kcContextLimit || 200000,
@@ -215,8 +243,6 @@ export class AgentEngine {
     // so they don't get a TaskManager.
     this.taskManager = this._isSubagent ? null : new TaskManager(this.workspace.cwd);
 
-    // Build all tool instances (but register phase-appropriate ones)
-    this._buildTools = this._createAllTools();
     this._phaseSummaries = [];
 
     // Pipeline system (meta-meta skills as code)
@@ -232,22 +258,47 @@ export class AgentEngine {
     };
 
     // Skill discovery (Claude Code pattern: index in context, full content on demand)
+    // v0.7.5 — must initialize BEFORE _createAllTools() because ConsultSkillTool
+    // takes this._skillLoader as a constructor arg. Was a v0.7.5 init-order bug:
+    // _createAllTools ran first, passed undefined skillLoader to ConsultSkillTool,
+    // calls to consult_skill threw "Cannot read properties of undefined".
     this._skillLoader = new SkillLoader(config.language);
 
+    // Build all tool instances (but register phase-appropriate ones)
+    this._buildTools = this._createAllTools();
+
+    // v0.7.5 G-D1: populate <workspace>/skills/ with the initial phase's
+    // available skill set. Symlink with copy fallback. Re-populated on
+    // every phase advance/retreat (see _advancePhase).
+    try {
+      const res = this._skillLoader.populateWorkspaceSkills(this.workspace.cwd, this.currentPhase);
+      this.eventLog?.append?.("skills_populated", {
+        phase: res.phase,
+        populated: res.populated,
+        failures: res.failures,
+      });
+    } catch { /* best-effort; skills/ population is not a critical-path failure */ }
+
+    // v0.8.1 P10-A: auto-populate <workspace>/workflows/common/llm_client.py
+    // from the template. Idempotent (skips if file already exists). Covers
+    // the bench-corpus flow where `kc-beta init` was bypassed. v0.8.0
+    // shipped this shim as embedded source in skill-to-workflow teaching;
+    // E2E #11 audits found BOTH agents ignored the teaching and wrote
+    // their own (non-canonical) llm_client.py. Shipping it as a template
+    // file the agent finds via filesystem walk is more robust.
+    try { this._populateWorkspaceCommonShims(); } catch { /* best-effort */ }
+
     // Register tools for initial phase
     this.toolRegistry = new ToolRegistry();
     this._registerToolsForPhase(this.currentPhase);
 
-    // Edge-trigger state for _maybeAutoAdvance. Initialize to false for every
-    // phase so the first real false→true flip inside onToolResult triggers an
-    // advance — even when the user launches from a pre-populated workspace
-    // whose exit criteria already happen to be met at boot.
-    // resume() re-primes this from the restored pipeline state (see ~L566),
-    // which is the correct behaviour there: resumed sessions that were already
-    // past this phase shouldn't re-fire.
-    this._lastReady = Object.fromEntries(
-      Object.keys(this.pipelines).map((p) => [p, false]),
-    );
+    // v0.8 P1-D: removed `_lastReady` edge-trigger state. It was the
+    // bookkeeping for `_maybeAutoAdvance`, which v0.7.4 G0b decommissioned
+    // (all call sites removed because v0.7.3's mid-session auto-advance
+    // chain regression was caused by it). The method definition itself
+    // is also gone in P1-D. Phase advance is now 100% explicit: agent's
+    // `phase_advance` tool or user re-prompt. Resume + rollback paths
+    // that previously re-primed `_lastReady` are no-ops now.
 
     // B0.1: Heap sampler. Parent engines only — sub-agents share a process
     // with the parent and would double-log. Writes a single JSONL line
@@ -258,6 +309,111 @@ export class AgentEngine {
     this._heapSamplerStop = this._isSubagent ? null : this._startHeapSampler();
   }
 
+  /**
+   * v0.8 P1-B: overlay workspace .env onto this.config now that
+   * this.workspace.cwd is known. Only fills in fields where the current
+   * config value was a gc fallback (empty OR the gc default) — does NOT
+   * override fields that came from process.env (those win at
+   * loadSettings() time and stay winning).
+   *
+   * Without this overlay, workspace .env's VLM_TIER1 / OCR_MODEL_TIER1 /
+   * TIER1..4 / LANGUAGE are silently ignored — the v0.7.4 G1b OCR_MODEL_TIER1
+   * alias fix landed at the config layer but never reached the runtime
+   * because loadSettings() is called without a workspace path.
+   */
+  /**
+   * v0.8.1 P10-A: copy canonical `workflows/common/*.py` shims from the
+   * bundled template if they're missing in the workspace. Provides
+   * `llm_client.py` (worker LLM HTTP shim, provider-agnostic) and
+   * `utils.py` (strip_annotations + helpers). Idempotent — never
+   * overwrites existing files (agent edits stay intact).
+   *
+   * Runs at engine init. Covers bench-corpus mode where `kc-beta init`
+   * doesn't run; init-flow workspaces already have these from copyDir.
+   */
+  _populateWorkspaceCommonShims() {
+    const __dirname = path.dirname(new URL(import.meta.url).pathname);
+    const templateRoot = path.resolve(__dirname, "..", "..", "template", "workflows", "common");
+    if (!fs.existsSync(templateRoot)) return;
+
+    const targetRoot = path.join(this.workspace.cwd, "workflows", "common");
+    fs.mkdirSync(targetRoot, { recursive: true });
+
+    const copied = [];
+    const skipped = [];
+    for (const entry of fs.readdirSync(templateRoot)) {
+      if (!entry.endsWith(".py") || entry.startsWith(".")) continue;
+      const srcPath = path.join(templateRoot, entry);
+      const dstPath = path.join(targetRoot, entry);
+      if (fs.existsSync(dstPath)) {
+        skipped.push(entry);
+        continue;
+      }
+      try {
+        fs.copyFileSync(srcPath, dstPath);
+        copied.push(entry);
+      } catch { /* best-effort */ }
+    }
+
+    if (copied.length > 0) {
+      try {
+        this.eventLog?.append?.("workflows_common_populated", { copied, skipped });
+      } catch { /* best-effort */ }
+    }
+  }
+
+  _overlayWorkspaceEnv() {
+    if (!this.workspace?.cwd) return;
+    const envPath = path.join(this.workspace.cwd, ".env");
+    if (!fs.existsSync(envPath)) return;
+    let wsEnv;
+    try { wsEnv = loadEnvFile(envPath); } catch { return; }
+    if (!wsEnv || typeof wsEnv !== "object") return;
+
+    // VLM tiers — workspace .env's VLM_TIER1 / OCR_MODEL_TIER1 wins over
+    // gc's vlm_tiers.tier1 default. process.env precedence preserved
+    // because loadSettings already applied it; we only fill in slots
+    // that fell through to gc-or-empty.
+    const overlays = [
+      { configKey: "vlmTier1", envKey: ["VLM_TIER1", "OCR_MODEL_TIER1"] },
+      { configKey: "vlmTier2", envKey: ["VLM_TIER2", "OCR_MODEL_TIER2"] },
+      { configKey: "vlmTier3", envKey: ["VLM_TIER3", "OCR_MODEL_TIER3"] },
+      { configKey: "tier1", envKey: ["TIER1"] },
+      { configKey: "tier2", envKey: ["TIER2"] },
+      { configKey: "tier3", envKey: ["TIER3"] },
+      { configKey: "tier4", envKey: ["TIER4"] },
+      { configKey: "language", envKey: ["LANGUAGE"] },
+    ];
+
+    const applied = [];
+    for (const { configKey, envKey } of overlays) {
+      // Find first non-empty workspace .env value for this config key
+      let wsValue = "";
+      for (const k of envKey) {
+        if (wsEnv[k]) { wsValue = wsEnv[k]; break; }
+      }
+      if (!wsValue) continue;
+      // Skip if process.env has the same key set — penv already won
+      const penvWon = envKey.some((k) => process.env[k] && process.env[k] !== wsValue);
+      if (penvWon) continue;
+      // Apply the workspace value
+      if (this.config[configKey] !== wsValue) {
+        applied.push({ key: configKey, from: this.config[configKey] || "(empty)", to: wsValue });
+        this.config[configKey] = wsValue;
+      }
+    }
+
+    // Audit visibility: emit a one-time event listing what was overlaid.
+    if (applied.length > 0) {
+      try {
+        this.eventLog?.append?.("workspace_env_overlay", {
+          envPath: path.relative(this.workspace.cwd, envPath),
+          fields: applied,
+        });
+      } catch { /* best-effort */ }
+    }
+  }
+
   /**
    * Start sampling process.memoryUsage() every 60 s into logs/heap.jsonl.
    * Returns a stop fn. Timer is .unref()'d so it never keeps the process
@@ -267,11 +423,22 @@ export class AgentEngine {
   _startHeapSampler() {
     const logDir = path.join(this.workspace.cwd, "logs");
     const logPath = path.join(logDir, "heap.jsonl");
+    let stopped = false;
+    let lastSampleAt = 0;
+
     const sample = () => {
       try {
         const mem = process.memoryUsage();
+        const now = Date.now();
+        // v0.8 P1-C: track skipped intervals. If more than 90s elapsed
+        // since last sample on a 60s cadence, the previous tick was missed
+        // (event loop sleep, GC pause, etc.). Surface in the row so the
+        // post-mortem audit can detect gaps without needing to compare
+        // adjacent timestamps.
+        const skippedMs = lastSampleAt > 0 ? (now - lastSampleAt - 60_000) : 0;
+        lastSampleAt = now;
         const row = {
-          t: new Date().toISOString(),
+          t: new Date(now).toISOString(),
           seq: this.eventLog?.currentSeq ?? 0,
           phase: this.currentPhase,
           rssMB: Math.round(mem.rss / 1024 / 1024),
@@ -288,17 +455,36 @@ export class AgentEngine {
           // and the row gets `componentsErr` instead.
           components: this._sampleComponents(),
         };
+        if (skippedMs > 0) row.skippedMs = skippedMs;
         fs.mkdirSync(logDir, { recursive: true });
         fs.appendFileSync(logPath, JSON.stringify(row) + "\n", "utf-8");
       } catch { /* never fatal */ }
     };
+
+    // v0.8 P1-C: self-rescheduling setTimeout instead of setInterval. The
+    // 资管 v0.7.5 session shows only 2 heap.jsonl entries (12:39:40 start
+    // + 12:40:40 first tick) across an 18-hour run — the unref'd
+    // setInterval was somehow dropped between event-loop idle phases.
+    // setTimeout reschedules from inside the sample callback, so the
+    // timer is re-registered every tick. unref'd so we don't block exit.
+    let timeoutHandle = null;
+    const scheduleNext = () => {
+      if (stopped) return;
+      timeoutHandle = setTimeout(() => {
+        sample();
+        scheduleNext();
+      }, 60_000);
+      timeoutHandle.unref?.();
+    };
+
     // Record one sample at startup so we have a baseline even on short runs.
     sample();
-    const timer = setInterval(sample, 60_000);
-    timer.unref?.();
+    scheduleNext();
+
     return () => {
       try {
-        clearInterval(timer);
+        stopped = true;
+        if (timeoutHandle) clearTimeout(timeoutHandle);
         sample(); // one final sample on shutdown
       } catch { /* ignore */ }
     };
@@ -415,7 +601,10 @@ export class AgentEngine {
     return {
       // Always available (BUILD + DISTILL)
       core: [
-        new SandboxExecTool(this.workspace, this.config.kcExecTimeout),
+        new SandboxExecTool(this.workspace, {
+          defaultTimeoutMs: this.config.kcExecDefaultTimeoutMs,
+          maxTimeoutMs: this.config.kcExecMaxTimeoutMs,
+        }),
         new WorkspaceFileTool(this.workspace, this.versionManager),
         new CopyToWorkspaceTool(this.workspace, {
           largeRefThresholdMB: this.config.largeRefThresholdMB ?? 10,
@@ -455,7 +644,12 @@ export class AgentEngine {
           mineruApiKey: this.config.mineruApiKey,
           llmApiKey: workerApiKey,
           llmBaseUrl: workerBaseUrl,
+          // v0.8.1 P9-B: live-read vlmTier1 so workspace_env_overlay
+          // changes after tool construction (or mid-run .env edits)
+          // reach document_parse. The static `ocrModel` is the
+          // construction-time fallback; getOcrModel takes precedence.
           ocrModel: vlmModel,
+          getOcrModel: () => this.config.vlmTier1 || vlmModel,
         }),
         new DocumentSearchTool(this.workspace),
         // Group C — chunker/RAG infrastructure ported from AMC app. Core
@@ -476,16 +670,27 @@ export class AgentEngine {
           () => this.currentPhase,
         ),
         new WebSearchTool(this.config.tavilyApiKey),
-        // v0.7.3: completes the v0.7.0 "agent owns TaskBoard" design.
-        // Skills already reference TaskCreate by name; these tools make
-        // that contract truthful. See task-board.js + work-decomposition
-        // SKILL.md. Skipped for subagents — they don't own a task board
-        // (taskManager is null in subagent scope, line 216).
+        // v0.7.4 (re-applied from v0.7.3 G2b): TaskCreate /
+        // TaskUpdate / TaskComplete — agent populates the
+        // Ralph-loop queue for the CURRENT phase only. Phase
+        // boundaries exit the loop (v0.7.4 G0c). Skipped for
+        // subagents (taskManager null in subagent scope).
         ...(this.taskManager ? [
           new TaskCreateTool(this.workspace, this.taskManager),
           new TaskUpdateTool(this.workspace, this.taskManager),
           new TaskCompleteTool(this.workspace, this.taskManager),
         ] : []),
+        // v0.7.5: consult_skill loads a meta-skill body into conversation
+        // history on demand. Always-loaded skills are already in the
+        // system prompt via SkillLoader.formatForContext; this tool covers
+        // the "available" set for the current phase. Both main + subagents
+        // register their own — each has its own skillLoader + phase.
+        new ConsultSkillTool(
+          this.workspace,
+          this._skillLoader,
+          () => this.currentPhase,
+          this.eventLog,
+        ),
       ],
       // Distillation+ only (DISTILL mode)
       distill: [
@@ -944,16 +1149,9 @@ export class AgentEngine {
         }
       }
 
-      // Re-prime _lastReady AFTER importState so it reflects the restored
-      // pipeline milestones, not the empty defaults from constructor.
-      // (Bug 5 fix — without this, resume reignites auto-advance.)
-      for (const phase of Object.keys(engine.pipelines)) {
-        try {
-          engine._lastReady[phase] = !!engine.pipelines[phase].exitCriteriaMet?.();
-        } catch {
-          engine._lastReady[phase] = false;
-        }
-      }
+      // v0.8 P1-D: removed `_lastReady` re-prime. Was the bookkeeping for
+      // `_maybeAutoAdvance` which v0.7.4 G0b decommissioned. Phase advance
+      // is explicit now; nothing to re-prime on resume.
 
       engine.eventLog.append("session_resume", {
         resumedPhase: engine.currentPhase,
@@ -1062,6 +1260,29 @@ export class AgentEngine {
       // budget. Better to lose some history than crash with HTTP 400.
       messages = this._enforceTokenBudget(messages);
 
+      // v0.8 P3-A: skill usage counter — emit one skill_byte_send event
+      // per always-loaded skill per LLM send. Captures the cost of having
+      // a skill body inlined in the system prompt (Layer B per design doc).
+      // Agent-blind: events go to events.jsonl only; never surfaced to the
+      // agent's context. consult_skill tool results emit their own
+      // skill_invoked events with via_tool="consult_skill" (already in
+      // place since v0.7.5 G-C4), so we don't double-count those here.
+      try {
+        const { alwaysLoaded } = this._skillLoader.getPhaseSkillSet(this.currentPhase) || {};
+        if (Array.isArray(alwaysLoaded)) {
+          for (const skill of alwaysLoaded) {
+            const body = this._skillLoader.loadSkillBody(skill);
+            if (!body) continue;
+            this.eventLog.append("skill_byte_send", {
+              skill,
+              via: "system_prompt_always_loaded",
+              byte_count: body.length,
+              phase: this.currentPhase,
+            });
+          }
+        }
+      } catch { /* counter is best-effort; never break the turn */ }
+
       this.eventLog.append("llm_start", {
         model: this.config.kcModel,
         messageCount: messages.length,
@@ -1196,11 +1417,11 @@ export class AgentEngine {
           }
           this._totalTurns = (this._totalTurns || 0) + 1;
 
-          // Bug 4 trigger (1): re-check phase criteria at end of every turn —
-          // KC may have advanced state via conversation alone, without any
-          // tool that the pipeline narrowly watches.
-          const advancedEv = this._maybeAutoAdvance();
-          if (advancedEv) yield advancedEv;
+          // v0.7.4 G0b: removed `_maybeAutoAdvance()` auto-fire here.
+          // Phase advance is now 100% explicit (agent's `phase_advance`
+          // tool, or user re-prompt). v0.7.3 phase-control regression
+          // was caused by this edge-triggered auto-advance firing mid-
+          // session and chaining into next phase without user check-in.
 
           this.eventLog.append("turn_complete", {});
           this.saveState();
@@ -1289,23 +1510,55 @@ export class AgentEngine {
 
           this.eventLog.append("tool_result", {
             name: tc.name,
+            input: inputData,
             output: result.content || "",
             isError: result.isError,
             traceId: offload?.traceId || null,
           });
 
-          // D3a: trace skill invocations. When the agent reads a SKILL.md via
-          // workspace_file (the canonical way KC "uses" a skill, since skills
-          // are progressively-disclosed markdown), emit a skill_invoked event.
-          // Makes "which skills did KC actually consult?" answerable in post-run
-          // analysis — before this, skills were opaque to the event log.
+          // v0.7.5 (G-F4): added `input` above so events.jsonl carries the
+          // tool inputs (v0.7.4 G1c only patched the AgentEvent yield path,
+          // missed the persistence path — audit confirmed 0/453 + 0/946
+          // tool_result events had `input` in v0.7.4 sessions).
+
+          // D3a: trace skill invocations. v0.7.5 (G-C6): only fire on
+          // READS of meta-skill paths. Writes to rule_skills/<id>/SKILL.md
+          // during skill_authoring are NOT skill invocations — they're the
+          // agent producing its own deliverable. The old "(unknown)" spam
+          // (100% of events in v0.7.1 + v0.7.4 sessions) is gone.
+          //
+          // Note: meta-skill body reads now happen via consult_skill, which
+          // emits skill_invoked itself (with the real skill name). This
+          // path-matching emission stays only as a fallback for any agent
+          // that reads a SKILL.md path directly (out of pattern).
           try {
+            // v0.8 P1-E: heredoc detection. `cat << 'EOF' > /tmp/skill.md`
+            // matches the read-verb regex but is actually a WRITE — the
+            // heredoc operator `<<` means cat is consuming inline content
+            // (the heredoc body), not a file path. 资管 v0.7.5 audit § 5f
+            // confirmed 1 spurious skill_invoked event of this kind.
+            // Excluding any command with `<<` from the isRead classification.
+            const cmd = String(inputData?.command || "");
+            const isHeredoc = cmd.includes("<<");
+            const isRead =
+              (tc.name === "workspace_file" && inputData?.operation === "read") ||
+              (tc.name === "sandbox_exec" && !isHeredoc && /\b(cat|head|tail|less|grep|view|read)\b/.test(cmd));
             if (
               !result.isError &&
+              isRead &&
               (tc.name === "workspace_file" || tc.name === "sandbox_exec")
             ) {
               const p = String(inputData?.path || inputData?.command || "");
-              const skillMatch = p.match(/(?:template\/)?skills\/[a-z-]+\/(?:meta-meta|meta|skill-creator)\/([a-zA-Z0-9_-]+)(?:\/SKILL\.md|\/)?|\bSKILL\.md\b/);
+              // v0.7.5 flat layout: skills/<name>/SKILL.md (workspace scope)
+              // OR template/skills/<lang>/<name>/SKILL.md (template scope, rare)
+              // Deep layout backward-compat preserved for any stragglers.
+              // v0.8 P0-B: accept lowercase `skill.md` too — 资管 audit § 3.2
+              // found agents writing lowercase consistently (14/14 rule_skills/).
+              // Limited to exact uppercase OR exact lowercase (no mixed case)
+              // to avoid spurious matches on unrelated files (e.g., `Skill.md`).
+              const skillMatch = p.match(
+                /(?:template\/)?skills\/(?:[a-z]+\/)?(?:(?:meta-meta|meta|skill-creator)\/)?([a-zA-Z0-9_-]+)\/(?:SKILL|skill)\.md\b/
+              ) || p.match(/\b(?:SKILL|skill)\.md\b/);
               if (skillMatch) {
                 const skillName = skillMatch[1] || "(unknown)";
                 this.eventLog.append("skill_invoked", {
@@ -1386,12 +1639,9 @@ export class AgentEngine {
           }
         }
 
-        // Bug 4 fix: re-check exit criteria after every tool-result loop, not
-        // just from pipeline.onToolResult. The pipeline's describeState() (called
-        // on every turn) already re-scans, so exitCriteriaMet() is accurate; we
-        // just need to act on it eagerly.
-        const ev = this._maybeAutoAdvance();
-        if (ev) yield ev;
+        // v0.7.4 G0b: removed post-tool `_maybeAutoAdvance()` call.
+        // Phase advance is now 100% explicit. See `_runTaskLoopSerial`
+        // phase-change-exit guard for the loop-level checkpoint.
 
       } catch (err) {
         // A8: If the LLM client tagged the stream termination reason, pass
@@ -1409,10 +1659,12 @@ export class AgentEngine {
   }
 
   /**
-   * Centralized phase transition (Bug 4). All three triggers route through here:
+   * Centralized phase transition (Bug 4). Two triggers route through here
+   * after v0.7.4 G0b + v0.8 P1-D:
    * (1) pipeline.onToolResult returning phase_ready
-   * (2) post-turn auto-check via _maybeAutoAdvance
-   * (3) explicit user request via the phase_advance tool
+   * (2) explicit user request via the phase_advance tool
+   * (The historical (3) post-turn auto-check via `_maybeAutoAdvance` was
+   * removed; phase advance is 100% explicit.)
    *
    * Reachability: by default only forward-by-one transitions per NEXT_PHASE.
    * Set `force: true` to allow non-adjacent or backward transitions (e.g. user
@@ -1490,9 +1742,17 @@ export class AgentEngine {
         try { criteriaMet = !!fromPipeline?.exitCriteriaMet?.(); } catch { criteriaMet = true; }
         if (!criteriaMet) {
           const counts = this._buildEngineCountsBlock(this.currentPhase);
+          // v0.8 P0-E: prescriptive hint in the event payload so post-mortem
+          // audits see what the agent was told (matches what phase-advance.js
+          // returns to the LLM).
+          let prescriptive = null;
+          try {
+            prescriptive = getPrescriptiveHint(this.currentPhase, null, counts || "");
+          } catch { /* hint generation is best-effort */ }
           this.eventLog.append("phase_advance_refused", {
             from: this.currentPhase, to: nextPhase, reason,
             hint: "exit criteria not met by engine telemetry",
+            prescriptive_hint: prescriptive,
             engineCounts: counts || null,
           });
           return false;
@@ -1541,6 +1801,20 @@ export class AgentEngine {
     this.workspace.setPhase(this.currentPhase);
     this._createTasksForPhase(this.currentPhase);
 
+    // v0.7.5 G-D2: re-populate <workspace>/skills/ with the new phase's
+    // available set. Symlinks are wiped + recreated. Agent's `ls skills/`
+    // and any read-by-path reflects the current phase's allowlist.
+    try {
+      const res = this._skillLoader?.populateWorkspaceSkills(this.workspace.cwd, this.currentPhase);
+      if (res) {
+        this.eventLog.append("skills_populated", {
+          phase: res.phase,
+          populated: res.populated,
+          failures: res.failures,
+        });
+      }
+    } catch { /* best-effort */ }
+
     // v0.7.0 N (#94): give the entered pipeline a chance to do
     // phase-entry setup. Used by finalization to copy the release
     // template into output/releases/v1/. Other pipelines are no-ops.
@@ -1553,23 +1827,16 @@ export class AgentEngine {
       });
     }
 
-    // v0.6.2 J2: on rollback, reset the rolled-FROM phase's lastReady
-    // edge-trigger so that if the agent revisits it and re-flips
-    // exit-criteria true, _maybeAutoAdvance will fire correctly. Without
-    // this, the auto-advance edge trigger stays latched true and the
-    // moment the agent returns to fromPhase the engine immediately
-    // bounces them back out — defeating the rollback.
-    if (direction === "rollback" && this._lastReady) {
-      this._lastReady[fromPhase] = false;
-    }
+    // v0.8 P1-D: removed `_lastReady` rollback reset. Was the bookkeeping
+    // for `_maybeAutoAdvance` which v0.7.4 G0b decommissioned. Phase
+    // advance is explicit now; rollback just needs to commit the new phase.
 
     this.saveState();
 
     // B8: Soft signal — surface any sub-agents left running from the prior
     // phase so the main agent's next turn can decide whether to kill them.
-    // NOT automated: phase_advance can fire from _maybeAutoAdvance on a
-    // criteria-flip, and auto-killing would couple lifecycle with blast
-    // radius. This just informs.
+    // NOT automated: auto-killing would couple lifecycle with blast radius.
+    // This just informs.
     try {
       const agentTool = this._buildTools?.core?.find((t) => t?.name === "agent_tool");
       const runningIds = agentTool?.getRunningTaskIds?.() || [];
@@ -1769,35 +2036,12 @@ export class AgentEngine {
     return false;
   }
 
-  /**
-   * Bug 4 trigger (1) auto-detect, edge-triggered (Bug 5): only fires on a
-   * fresh false → true flip in `exitCriteriaMet()`. Sessions resumed in an
-   * already-met state do nothing; users iterating in a phase whose criteria
-   * have been met for a while do nothing. Real new evidence is required.
-   */
-  _maybeAutoAdvance() {
-    const phase = this.currentPhase;
-    const pipeline = this.pipelines[phase];
-    let nowReady = false;
-    try { nowReady = !!pipeline?.exitCriteriaMet?.(); } catch { nowReady = false; }
-
-    if (!nowReady) {
-      this._lastReady[phase] = false;
-      return null;
-    }
-    // Edge-trigger: nowReady && !wasReady
-    if (this._lastReady[phase]) return null;
-    this._lastReady[phase] = true;
-
-    const next = NEXT_PHASE[phase];
-    if (!next) return null;
-    const advanced = this._advancePhase(next, "exit criteria flipped to met");
-    if (!advanced) return null;
-    return new AgentEvent({
-      type: "pipeline_event",
-      data: { type: "phase_ready", nextPhase: next, message: "exit criteria flipped to met" },
-    });
-  }
+  // v0.8 P1-D: `_maybeAutoAdvance()` deleted. The method auto-fired phase
+  // advance on a false→true flip of `exitCriteriaMet()`, but v0.7.3
+  // showed mid-session auto-advance chains were a regression hazard
+  // (user couldn't review between phases). v0.7.4 G0b removed all call
+  // sites; v0.8 P1-D removes the now-dead method definition + the
+  // `_lastReady` bookkeeping it relied on. Phase advance is 100% explicit.
 
   /**
    * Tool-call offloading. If the tool's content exceeds the threshold,
@@ -2106,10 +2350,40 @@ export class AgentEngine {
   /** B1: original serial ralph-loop path — one task at a time, shared
    *  conversation history. Unchanged from pre-v0.6.0 behavior. */
   async *_runTaskLoopSerial(userMessage) {
-    // Run the initial turn (user's request)
+    // v0.8 P5-A: F5 re-enabled, conditional on marathon mode.
+    // - Interactive sessions (marathon NOT active): capture startingPhase
+    //   BEFORE the initial runTurn, and exit the loop on ANY phase change
+    //   (including within the initial runTurn). One user prompt = one
+    //   phase advance. Path (a) per design doc Q5 lean.
+    // - Marathon sessions: the kc-marathon driver provides per-phase
+    //   prompts via .kc_marathon/inbox.jsonl, so the engine doesn't need
+    //   F5's checkpoint — phase chaining is OK because each chained phase
+    //   STILL gets its own driver-emitted prompt next tick.
+    //
+    // v0.7.3 demonstrated why F5 matters interactively: auto-chained
+    // phase advances skip the user check-in cycle and broke phase
+    // control in team testing. v0.7.4 G0c first fixed it via
+    // post-initial-runTurn exit; v0.7.5 added the strict capture-BEFORE
+    // refinement; v0.8 P5-A preserves both with the marathon escape;
+    // v0.8.1 P8-A switched marathon-active source from filesystem
+    // marker to inline driver instance.
+    const marathonActive = this.isMarathonActive();
+    const startingPhase = this.currentPhase;
     yield* this.runTurn(userMessage);
 
-    // Auto-continue through pending tasks
+    // F5 strict gate: if interactive AND phase changed during initial
+    // runTurn, exit immediately (don't auto-continue tasks in the new
+    // phase). Marathon bypasses — driver decides pacing.
+    if (!marathonActive && this.currentPhase !== startingPhase) {
+      this.eventLog.append("ralph_loop_exit", {
+        reason: "f5_strict_initial_turn",
+        from: startingPhase,
+        to: this.currentPhase,
+      });
+      return;
+    }
+
+    // Auto-continue through pending tasks (within current phase only)
     while (this.taskManager.getNextPending()) {
       // v0.7.0 #93: budget-aware compact threshold. The old
       // `messages.length > 15` was message-count-based and frozen
@@ -2170,28 +2444,102 @@ export class AgentEngine {
         },
       });
 
-      // Bug 4 trigger (2): auto-advance when all phase tasks are done AND
-      // the pipeline's exit criteria are also met (Bug 5 fix — task state
-      // alone is a ralph-loop convenience, not authoritative phase signal;
-      // tasks could be marked skipped manually or by an editor).
-      if (this._allCurrentPhaseTasksComplete()) {
-        const pipeline = this.pipelines[this.currentPhase];
-        let exitMet = false;
-        try { exitMet = !!pipeline?.exitCriteriaMet?.(); } catch { exitMet = false; }
-        if (exitMet) {
-          const next = NEXT_PHASE[this.currentPhase];
-          if (next) {
-            const advanced = this._advancePhase(next, "all current-phase tasks completed + exit criteria met");
-            if (advanced) {
-              yield new AgentEvent({
-                type: "pipeline_event",
-                data: { type: "phase_ready", nextPhase: next, message: "all phase tasks done; exit criteria met" },
-              });
-            }
-          }
-        }
+      // v0.7.4 G0c: phase boundary = user checkpoint. Exit the
+      // loop if the agent advanced phase during this task —
+      // even if pre-created tasks for the new phase are queued.
+      // User sees current state and explicitly re-prompts to
+      // begin the next phase. Marathon-style end-to-end
+      // autonomy belongs to an external driver (Claude Code
+      // /loop pattern), not the engine.
+      if (this.currentPhase !== startingPhase) {
+        this.eventLog.append("ralph_loop_exit", {
+          reason: "phase_changed",
+          from: startingPhase,
+          to: this.currentPhase,
+        });
+        break;
+      }
+    }
+
+    // v0.8.1 P8-A: marathon mode — inline driver. After the F5 phase-
+    // boundary exit, if marathon is active, query the driver for the
+    // next continuation prompt and run additional turns until the driver
+    // signals stop (null return). State machine logic unchanged from
+    // v0.8.0; the I/O wrapper just shifted from filesystem-watcher to
+    // direct method calls.
+    while (this.marathonDriver) {
+      const turnsSnapshot = this.marathonDriver.turnsThisPhase;
+      const phaseChanged = this.currentPhase !== this.marathonDriver.currentPhase;
+      const milestones = this._buildEngineCountsBlock(this.currentPhase) || {};
+      const decision = this.marathonDriver.decideNext({
+        currentPhase: this.currentPhase,
+        milestones,
+        phaseChanged,
+        errorSeen: false, // engine surfaces errors via tool_result.isError; not propagated here for v0.8.1 MVP
+        turnsThisPhase: turnsSnapshot + 1,
+      });
+      if (!decision) {
+        // Stop condition met — driver returned null
+        this.eventLog.append("marathon_detach", {
+          reason: this.marathonDriver.stopReason || "unknown",
+          decisions: this.marathonDriver.decisionCount,
+        });
+        this.marathonDriver = null;
+        break;
       }
+      this.eventLog.append("marathon_decision", {
+        template: decision.template,
+        reason: decision.reason,
+        phase: this.currentPhase,
+      });
+      yield* this.runTurn(decision.prompt);
+      // Loop back: another turn just completed; driver gets another decideNext call.
+    }
+  }
+
+  /**
+   * v0.8.1 P8-A: activate marathon mode with a goal-description.
+   * Called from cli/index.js's /marathon slash command handler.
+   * The engine's next runTaskLoop will use marathonDriver.getInitialPrompt()
+   * as the kickoff user message.
+   *
+   * @param {string} goal — the marathon goal description (user-typed)
+   * @param {object} [opts] — {maxWallclockMs?, stuckAfterMs?}
+   * @returns {object} {goal, language, startedAt} for confirmation
+   */
+  enterMarathonMode(goal, opts = {}) {
+    if (this.marathonDriver) {
+      throw new Error("Marathon already active — use /marathon off to disengage first");
     }
+    this.marathonDriver = new MarathonDriver({
+      goal,
+      language: this.config.language || "en",
+      maxWallclockMs: opts.maxWallclockMs,
+      stuckAfterMs: opts.stuckAfterMs,
+    });
+    this.eventLog.append("marathon_attach", {
+      goal: goal.slice(0, 200),
+      language: this.config.language || "en",
+    });
+    return this.marathonDriver.getStatus();
+  }
+
+  /** v0.8.1 P8-A: deactivate marathon mode. Returns final status snapshot. */
+  exitMarathonMode(reason = "user_off") {
+    if (!this.marathonDriver) return null;
+    const status = this.marathonDriver.getStatus();
+    this.marathonDriver.stop(reason);
+    this.eventLog.append("marathon_detach", {
+      reason,
+      decisions: this.marathonDriver.decisionCount,
+    });
+    this.marathonDriver = null;
+    return status;
+  }
+
+  /** v0.8.1 P8-A: is marathon mode currently active? (for TUI status bar) */
+  isMarathonActive() {
+    return !!this.marathonDriver && !this.marathonDriver.stopped;
   }
 
   /**
@@ -2212,9 +2560,27 @@ export class AgentEngine {
    * amortized against the 2-4× wall-clock speedup.
    */
   async *_runTaskLoopParallel(userMessage, parallelism) {
+    // v0.8 P5-A: F5 re-enabled, conditional on marathon mode.
+    // Mirror _runTaskLoopSerial — capture startingPhase BEFORE initial
+    // runTurn so phase advance during the initial turn exits the loop
+    // unless marathon is active.
+    // v0.8.1 P8-A: marathon check now uses inline driver instance.
+    const marathonActive = this.isMarathonActive();
+    const startingPhase = this.currentPhase;
+
     // Initial turn: main agent reads user request, creates tasks.
     yield* this.runTurn(userMessage);
 
+    if (!marathonActive && this.currentPhase !== startingPhase) {
+      this.eventLog.append("ralph_loop_exit", {
+        reason: "f5_strict_initial_turn",
+        from: startingPhase,
+        to: this.currentPhase,
+        mode: "parallel",
+      });
+      return;
+    }
+
     const agentTool = this._buildTools.core.find((t) => t?.name === "agent_tool");
     if (!agentTool) {
       // Shouldn't happen (agent_tool is core), but fall back safely.
@@ -2239,6 +2605,9 @@ export class AgentEngine {
     const inFlight = new Map();
 
     const dispatch = async () => {
+      // v0.7.4 G0c: stop dispatching if phase changed since loop start.
+      // In-flight workers complete naturally; queue stays untouched.
+      if (this.currentPhase !== startingPhase) return;
       while (inFlight.size < parallelism) {
         const task = this.taskManager.claimNextPending(`pool${inFlight.size}`);
         if (!task) return;
@@ -2374,23 +2743,15 @@ export class AgentEngine {
 
     this.saveState();
 
-    // After all workers done, check for phase auto-advance (same as serial path).
-    if (this._allCurrentPhaseTasksComplete()) {
-      const pipeline = this.pipelines[this.currentPhase];
-      let exitMet = false;
-      try { exitMet = !!pipeline?.exitCriteriaMet?.(); } catch { exitMet = false; }
-      if (exitMet) {
-        const next = NEXT_PHASE[this.currentPhase];
-        if (next) {
-          const advanced = this._advancePhase(next, "all parallel tasks completed + exit criteria met");
-          if (advanced) {
-            yield new AgentEvent({
-              type: "pipeline_event",
-              data: { type: "phase_ready", nextPhase: next, message: "all phase tasks done; exit criteria met" },
-            });
-          }
-        }
-      }
+    // v0.7.4 G0c: if phase changed during the parallel run, log the
+    // checkpoint event for the audit trail. No auto-advance — that
+    // belongs to the agent (phase_advance tool) or user re-prompt.
+    if (this.currentPhase !== startingPhase) {
+      this.eventLog.append("ralph_loop_exit", {
+        reason: "phase_changed",
+        from: startingPhase,
+        to: this.currentPhase,
+      });
     }
   }