feat(v0.3.0): paradigm shift — TimeWeb-only LLM + persistent advisor trail + improvement queue

This is the rc.4 batch the user requested:

  1. Emergency triggers (low HP + close hostile, lava-under-foot)
     bypass the long cooldown so the LLM is consulted BEFORE the bot
     dies, not after.
  2. Active manifesto need is now included in the advisor user prompt
     — the LLM picks suggestions that satisfy the bot's current
     concrete need (L2 tools_wood → "gather logs nearby" not
     "explore further").
  3. Every advisor recommendation is persisted to SQLite
     (advisor_recommendations table) with full token usage. The
     reflex marks 'applied=1' when it dispatches and updates
     outcome_ok/code when the dispatch completes. Ground truth for
     "is the LLM actually helping" lives in the DB, not in logs.
  4. Pi CLI is OUT of every background loop. coach/postmortem and
     coach/reflect now go through the same TimeWeb endpoint
     fast-advisor uses, via the shared coach/llm-call.js helper.
     Pi is reserved for manual operator commands.
  5. The LLM (postmortem, reflect, advisor) can flag "structural
     gaps" — missing skills/features the operator should implement.
     These land in the new improvement_requests table. Dedup by
     title bumps `votes` instead of inserting duplicates so the
     queue doesn't bloat. Operator views via
     `node scripts/list-improvements.js`.
  6. A deterministic trigger-tuner runs hourly: reads 24h of
     recommendation stats, flags triggers whose success rate is
     below 25% (sample ≥ 5) or whose prompts are expensive (>1000
     input tokens) with mediocre payoff. Improvements get
     source="tuner", category="tuning". No LLM call.

New files:
  runtime/coach/llm-call.js        — askAnalytical() helper
  runtime/coach/trigger-tuner.js   — stats → improvements
  runtime/coach/trigger-tuner.test.js
  scripts/list-improvements.js     — operator CLI

Schema additions:
  advisor_recommendations: id, ts, trigger_reason, planned_skill,
    recommended_skill, action, rationale, active_need, tokens_in,
    tokens_out, latency_ms, applied, outcome_ok, outcome_code, outcome_at
  improvement_requests: id, ts, source, category, title, description,
    context, priority, status, duplicate_of, votes, implemented_at, notes

Renamed env-var consumers:
  Pi-coach drainOnce({ askPi })   → drainOnce({ askAnalyticalFn? })
  Pi-reflect runOnce({ askPi })   → runOnce({ askAnalyticalFn? })
  bot.js attachCoach/attachReflect no longer pass askPi
  attachTuner() added to bot.js spawn handler
  lessons.source 'pi-coach'   → 'timeweb-coach'
  lessons.source 'pi-reflect' → 'timeweb-reflect'

Token cost measured live:
  ~705 input + 45 output = ~750 total per advisor call
  worst case @ 6 calls/hour rate cap = ~108K tokens/day
  OpenAI gpt-5-mini reference price: ~$0.60/month

Operator usage:
  node scripts/list-improvements.js                # open queue
  node scripts/list-improvements.js --stats        # advisor performance
  node scripts/list-improvements.js --done 17 "shipped in 0.3.1"
  node scripts/list-improvements.js --reject 18 "duplicate"

Tests: 360 green (was 332, +28 new).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

runtime/knowledge/index.js

@@ -227,6 +227,191 @@ export function logChat({ direction, speaker, text, intent, repliedWith } = {})
 	}
 }
 
+// ---- v0.3.0 advisor recommendations ----------------------------------------
+//
+// Every fast-advisor call that produced a usable answer is logged here.
+// Rows are mutated post-hoc when reflex applies and when the dispatch
+// finishes — this is the ground truth for "is the LLM advice actually
+// helping" and the input to trigger-tuner.js.
+
+export function insertRecommendation({
+	triggerReason, plannedSkill, recommendedSkill, action, rationale,
+	activeNeed, tokensIn, tokensOut, latencyMs,
+} = {}) {
+	if (!_isAvailable()) return null;
+	try {
+		const res = _getStore().prepare(`
+			INSERT INTO advisor_recommendations
+			  (ts, trigger_reason, planned_skill, recommended_skill, action, rationale,
+			   active_need, tokens_in, tokens_out, latency_ms, applied)
+			VALUES
+			  (@ts, @triggerReason, @plannedSkill, @recommendedSkill, @action, @rationale,
+			   @activeNeed, @tokensIn, @tokensOut, @latencyMs, 0)
+		`).run({
+			ts: Date.now(),
+			triggerReason,
+			plannedSkill: plannedSkill ?? null,
+			recommendedSkill: recommendedSkill ?? null,
+			action,
+			rationale: rationale ?? null,
+			activeNeed: activeNeed ?? null,
+			tokensIn: tokensIn ?? null,
+			tokensOut: tokensOut ?? null,
+			latencyMs: latencyMs ?? null,
+		});
+		return res.lastInsertRowid;
+	} catch (e) {
+		warn("knowledge", `insertRecommendation failed: ${e?.message ?? e}`);
+		return null;
+	}
+}
+
+export function markRecommendationApplied(id) {
+	if (!_isAvailable() || !id) return;
+	try {
+		_getStore().prepare(`UPDATE advisor_recommendations SET applied = 1 WHERE id = ?`).run(id);
+	} catch (e) {
+		warn("knowledge", `markRecommendationApplied failed: ${e?.message ?? e}`);
+	}
+}
+
+export function markRecommendationOutcome(id, { ok, code } = {}) {
+	if (!_isAvailable() || !id) return;
+	try {
+		_getStore().prepare(`
+			UPDATE advisor_recommendations
+			SET outcome_ok = @ok, outcome_code = @code, outcome_at = @at
+			WHERE id = @id
+		`).run({ id, ok: ok ? 1 : 0, code: code ?? null, at: Date.now() });
+	} catch (e) {
+		warn("knowledge", `markRecommendationOutcome failed: ${e?.message ?? e}`);
+	}
+}
+
+export function recommendationStats({ sinceHours = 24 } = {}) {
+	if (!_isAvailable()) return [];
+	try {
+		const since = Date.now() - sinceHours * 3600_000;
+		return _getStore().prepare(`
+			SELECT trigger_reason,
+			       COUNT(*) AS total,
+			       SUM(applied) AS applied,
+			       SUM(CASE WHEN outcome_ok = 1 THEN 1 ELSE 0 END) AS succeeded,
+			       SUM(CASE WHEN outcome_ok = 0 THEN 1 ELSE 0 END) AS failed,
+			       AVG(tokens_in) AS avg_in,
+			       AVG(tokens_out) AS avg_out,
+			       AVG(latency_ms) AS avg_latency_ms
+			FROM advisor_recommendations
+			WHERE ts >= @since
+			GROUP BY trigger_reason
+			ORDER BY total DESC
+		`).all({ since });
+	} catch (e) {
+		warn("knowledge", `recommendationStats failed: ${e?.message ?? e}`);
+		return [];
+	}
+}
+
+export function recentRecommendations({ limit = 20 } = {}) {
+	if (!_isAvailable()) return [];
+	try {
+		return _getStore().prepare(`
+			SELECT * FROM advisor_recommendations ORDER BY ts DESC LIMIT @limit
+		`).all({ limit });
+	} catch (e) {
+		warn("knowledge", `recentRecommendations failed: ${e?.message ?? e}`);
+		return [];
+	}
+}
+
+// ---- v0.3.0 improvement requests -------------------------------------------
+//
+// The LLM (postmortem / reflect / advisor) writes here when it sees the bot
+// lack a needed skill or feature. Operator-readable via scripts/list-improvements.js.
+
+export function createImprovementRequest({
+	source, category, title, description, context, priority = 3,
+} = {}) {
+	if (!_isAvailable() || !title) return null;
+	try {
+		// Dedup: if an open request with same title (case-insensitive) exists,
+		// bump its votes instead of inserting a new row.
+		const dup = _getStore().prepare(`
+			SELECT id, votes FROM improvement_requests
+			WHERE LOWER(title) = LOWER(?) AND status = 'open'
+			ORDER BY ts DESC LIMIT 1
+		`).get(title);
+		if (dup) {
+			_getStore().prepare(`UPDATE improvement_requests SET votes = votes + 1 WHERE id = ?`).run(dup.id);
+			return dup.id;
+		}
+		const res = _getStore().prepare(`
+			INSERT INTO improvement_requests
+			  (ts, source, category, title, description, context, priority, status, votes)
+			VALUES
+			  (@ts, @source, @category, @title, @description, @context, @priority, 'open', 1)
+		`).run({
+			ts: Date.now(),
+			source: source ?? "manual",
+			category: category ?? "other",
+			title,
+			description: description ?? null,
+			context: context ? JSON.stringify(context) : null,
+			priority: clamp(priority, 1, 5),
+		});
+		return res.lastInsertRowid;
+	} catch (e) {
+		warn("knowledge", `createImprovementRequest failed: ${e?.message ?? e}`);
+		return null;
+	}
+}
+
+export function listImprovements({ status, source, category, limit = 50 } = {}) {
+	if (!_isAvailable()) return [];
+	try {
+		const where = [];
+		const params = { limit };
+		if (status) { where.push("status = @status"); params.status = status; }
+		if (source) { where.push("source = @source"); params.source = source; }
+		if (category) { where.push("category = @category"); params.category = category; }
+		const sql = `
+			SELECT * FROM improvement_requests
+			${where.length ? "WHERE " + where.join(" AND ") : ""}
+			ORDER BY (status = 'open') DESC, priority ASC, votes DESC, ts DESC
+			LIMIT @limit
+		`;
+		return _getStore().prepare(sql).all(params).map((r) => ({
+			...r,
+			context: safeParse(r.context),
+		}));
+	} catch (e) {
+		warn("knowledge", `listImprovements failed: ${e?.message ?? e}`);
+		return [];
+	}
+}
+
+export function markImprovementStatus(id, { status, notes } = {}) {
+	if (!_isAvailable() || !id) return;
+	const validStatuses = ["open", "in_progress", "implemented", "rejected", "duplicate"];
+	if (!validStatuses.includes(status)) {
+		warn("knowledge", `markImprovementStatus: invalid status "${status}"`);
+		return;
+	}
+	try {
+		const fields = ["status = @status", "notes = @notes"];
+		const params = { id, status, notes: notes ?? null };
+		if (status === "implemented") {
+			fields.push("implemented_at = @implementedAt");
+			params.implementedAt = Date.now();
+		}
+		_getStore().prepare(`UPDATE improvement_requests SET ${fields.join(", ")} WHERE id = @id`).run(params);
+	} catch (e) {
+		warn("knowledge", `markImprovementStatus failed: ${e?.message ?? e}`);
+	}
+}
+
+function clamp(n, lo, hi) { return Math.max(lo, Math.min(hi, Number(n) || lo)); }
+
 function safeParse(s) {
 	if (!s) return null;
 	try { return JSON.parse(s); } catch { return null; }

runtime/knowledge/knowledge.test.js

@@ -22,6 +22,14 @@ import {
 	recordPOI,
 	poiNearby,
 	logChat,
+	insertRecommendation,
+	markRecommendationApplied,
+	markRecommendationOutcome,
+	recommendationStats,
+	recentRecommendations,
+	createImprovementRequest,
+	listImprovements,
+	markImprovementStatus,
 } from "./index.js";
 import { __resetForTests, closeStore } from "./store.js";
 
@@ -217,6 +225,112 @@ test("chat log: append + select", async () => {
 	assert.ok(id1 && id2);
 });
 
+// ---- v0.3.0 advisor recommendations ---------------------------------------
+
+test("advisor recommendations: insert → markApplied → markOutcome → stats", async () => {
+	await bootstrap();
+	if (!isAvailable()) {
+		assert.equal(insertRecommendation({ triggerReason: "x", action: "switch_skill" }), null);
+		return;
+	}
+	const id = insertRecommendation({
+		triggerReason: "wedged_90s",
+		plannedSkill: "explore.far",
+		recommendedSkill: "recovery.tunnel-out",
+		action: "switch_skill",
+		rationale: "Stuck wedged, tunnel out.",
+		activeNeed: "L2 tools_wood",
+		tokensIn: 700, tokensOut: 40, latencyMs: 5000,
+	});
+	assert.ok(id, "got recommendation id");
+	markRecommendationApplied(id);
+	markRecommendationOutcome(id, { ok: true, code: "done" });
+
+	const recent = recentRecommendations({ limit: 5 });
+	const row = recent.find((r) => r.id === id);
+	assert.ok(row);
+	assert.equal(row.applied, 1);
+	assert.equal(row.outcome_ok, 1);
+
+	// second insert with same trigger to test stats grouping
+	const id2 = insertRecommendation({
+		triggerReason: "wedged_90s",
+		plannedSkill: "explore.far",
+		recommendedSkill: "survive.pillar-up",
+		action: "switch_skill",
+		rationale: "Try pillar.",
+		tokensIn: 720, tokensOut: 50, latencyMs: 6000,
+	});
+	markRecommendationApplied(id2);
+	markRecommendationOutcome(id2, { ok: false, code: "no_progress" });
+
+	const stats = recommendationStats({ sinceHours: 24 });
+	const wedged = stats.find((s) => s.trigger_reason === "wedged_90s");
+	assert.ok(wedged);
+	assert.equal(wedged.total, 2);
+	assert.equal(wedged.applied, 2);
+	assert.equal(wedged.succeeded, 1);
+	assert.equal(wedged.failed, 1);
+});
+
+test("advisor recommendations: graceful no-op on unknown id", async () => {
+	await bootstrap();
+	if (!isAvailable()) return;
+	markRecommendationApplied(null);
+	markRecommendationOutcome(null, { ok: true });
+	markRecommendationOutcome(999999, { ok: true });
+	// no throw = pass
+});
+
+// ---- v0.3.0 improvement requests ------------------------------------------
+
+test("improvement requests: create, dedup-by-title bumps votes, list filters", async () => {
+	await bootstrap();
+	if (!isAvailable()) {
+		assert.equal(createImprovementRequest({ title: "x" }), null);
+		return;
+	}
+	const id1 = createImprovementRequest({
+		source: "postmortem",
+		category: "skill",
+		title: "Add craft.iron-pickaxe skill",
+		description: "Bot has iron ingots but no skill to craft tier-3 pickaxe.",
+		priority: 2,
+	});
+	assert.ok(id1);
+
+	// duplicate title → bumps votes, returns same id
+	const id2 = createImprovementRequest({
+		source: "reflect",
+		category: "skill",
+		title: "Add craft.iron-pickaxe skill",
+		priority: 2,
+	});
+	assert.equal(id2, id1, "dedup returns original id");
+
+	const list = listImprovements({ status: "open", category: "skill" });
+	const row = list.find((r) => r.id === id1);
+	assert.ok(row);
+	assert.equal(row.votes, 2, "votes bumped by duplicate");
+
+	markImprovementStatus(id1, { status: "implemented", notes: "Shipped in v0.3.1" });
+	const updated = listImprovements({ status: "implemented" });
+	assert.ok(updated.some((r) => r.id === id1));
+	const stillOpen = listImprovements({ status: "open" });
+	assert.ok(!stillOpen.some((r) => r.id === id1));
+});
+
+test("improvement requests: priority and status ordering", async () => {
+	await bootstrap();
+	if (!isAvailable()) return;
+	const a = createImprovementRequest({ source: "manual", title: "low-prio thing", priority: 5 });
+	const b = createImprovementRequest({ source: "manual", title: "high-prio thing", priority: 1 });
+	const list = listImprovements({ status: "open" });
+	const ai = list.findIndex((r) => r.id === a);
+	const bi = list.findIndex((r) => r.id === b);
+	assert.ok(bi < ai, "priority 1 listed before priority 5");
+});
+
 // Cleanup: close DB and remove tmp dir.
 test("teardown", () => {
 	closeStore();

runtime/knowledge/schema.sql

@@ -179,3 +179,63 @@ CREATE TABLE IF NOT EXISTS code_changes (
   outcome         TEXT,                      -- 'applied'|'rolled_back'|'rejected'
   notes           TEXT
 );
+
+----------------------------------------------------------------------
+-- Advisor recommendations (v0.3.0+ fast LLM trail)
+-- Every time runtime/coach/advisor-trigger.js asks the fast LLM and
+-- the answer is cached on ctx, we write a row here. When the reflex
+-- consumes the recommendation and dispatches, we attach the dispatch
+-- result later via outcome_ok / outcome_code. The history is the
+-- ground truth for trigger-tuner.js stats and for the operator's
+-- "what is the LLM suggesting and is it actually helping" question.
+----------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS advisor_recommendations (
+  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts                  INTEGER NOT NULL,
+  trigger_reason      TEXT NOT NULL,           -- 'wedged_*', 'repeat_*', 'preempt_retry_*', 'emergency_*'
+  planned_skill       TEXT,                    -- what manifesto/curriculum was about to dispatch
+  recommended_skill   TEXT,                    -- what the LLM said to do instead
+  action              TEXT NOT NULL,           -- 'switch_skill' | 'continue' | 'wait'
+  rationale           TEXT,
+  active_need         TEXT,                    -- 'L2 tools_wood' etc.
+  tokens_in           INTEGER,
+  tokens_out          INTEGER,
+  latency_ms          INTEGER,
+  applied             INTEGER NOT NULL DEFAULT 0,  -- 1 if reflex actually dispatched recommended_skill
+  outcome_ok          INTEGER,                  -- NULL until dispatch finishes
+  outcome_code        TEXT,
+  outcome_at          INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_advisor_ts        ON advisor_recommendations(ts);
+CREATE INDEX IF NOT EXISTS idx_advisor_trigger   ON advisor_recommendations(trigger_reason);
+CREATE INDEX IF NOT EXISTS idx_advisor_outcome   ON advisor_recommendations(outcome_ok);
+
+----------------------------------------------------------------------
+-- Improvement requests (v0.3.0+)
+-- The LLM (postmortem / reflect / advisor) can flag situations where
+-- the bot lacked the right skill or feature. Instead of trying to
+-- self-patch (which we explicitly disabled), it writes an entry here.
+-- The operator reads `scripts/list-improvements.js` and decides what
+-- to implement. Implemented entries get marked so the bot stops
+-- re-flagging the same gap.
+----------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS improvement_requests (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts              INTEGER NOT NULL,
+  source          TEXT NOT NULL,                -- 'postmortem'|'reflect'|'advisor'|'tuner'|'manual'
+  category        TEXT,                          -- 'skill'|'tuning'|'perception'|'planning'|'social'|'other'
+  title           TEXT NOT NULL,
+  description     TEXT,
+  context         TEXT,                          -- JSON: position, snapshot tail, related lesson ids
+  priority        INTEGER NOT NULL DEFAULT 3,    -- 1..5 (1=urgent, 5=nice-to-have)
+  status          TEXT NOT NULL DEFAULT 'open',  -- 'open'|'in_progress'|'implemented'|'rejected'|'duplicate'
+  duplicate_of    INTEGER,                       -- another row id if dup
+  votes           INTEGER NOT NULL DEFAULT 1,    -- bumped each time the bot re-flags same gap
+  implemented_at  INTEGER,
+  notes           TEXT,
+  FOREIGN KEY (duplicate_of) REFERENCES improvement_requests(id)
+);
+CREATE INDEX IF NOT EXISTS idx_improvements_status   ON improvement_requests(status);
+CREATE INDEX IF NOT EXISTS idx_improvements_priority ON improvement_requests(priority);
+CREATE INDEX IF NOT EXISTS idx_improvements_source   ON improvement_requests(source);
+CREATE INDEX IF NOT EXISTS idx_improvements_ts       ON improvement_requests(ts);