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; }