feat(v0.3.0): auto-trigger fast-advisor + token usage tracking

Closes the awareness → LLM → action loop that the rc.1/2/3 sequence
left as a followup. When the bot is wedged, looping, or just suffered
a preempt-then-retry, the reflex fires advise() in the background;
when the recommendation lands it overrides the next dispatch.

Async by design: advise() takes 5-15s on TimeWeb's hosted endpoint —
too slow for a synchronous reflex tick. tickAdvisor() is fire-and-
forget, the result lands on ctx.advisorRecommendation, and the *next*
tick reads and consumes it. Recommendations age out after 60s.

Components:

- runtime/coach/advisor-trigger.js — policy + async fire path
  - tickAdvisor(ctx, {plannedSkillId}) checks three triggers:
    1. wedged > 60s (no significant move)
    2. last 4+ dispatches are the same skill AND it's planned again
    3. preempt within last 30s + same skill being retried
  - 90s trigger cooldown, single-in-flight guard
  - consumeFreshRecommendation(ctx) reads/clears the cache
- runtime/reflex.js — curriculumReflex calls tickAdvisor() every tick
  and consumes a fresh recommendation BEFORE dispatching. ctx flag
  disableAdvisor=true for tests.
- runtime/bot.js — dispatchAction maintains a rolling 8-slot
  reflexCtx.recentSkillIds for the loop-detection trigger.

Token usage:

- runtime/llm/provider.js — normaliseUsage() reads OpenAI/TimeWeb-
  style {prompt_tokens, completion_tokens, total_tokens} from the
  response. Returned on every complete() result and logged at info
  level as "in=Nt/out=Mt".
- runtime/coach/fast-advisor.js — getUsageSnapshot() aggregates
  total tokens across all calls in the session.

Measured on live TimeWeb endpoint (gpt-5.4-mini agent):
  per call: ~705 input + 45 output = ~750 tokens
  rate limit: 6 calls/hour
  worst case at full budget: ~108K tokens/day
  estimated cost (OpenAI gpt-5-mini reference price): ~$0.60/month

Well within any reasonable budget — model can run hot 24/7.

Smoke verified: scripts/check-timeweb.js probe 4 produces
  trigger fired: true (wedged_90s)
  recommendation: recovery.tunnel-out
  rationale: "Stuck wedged for 90s; exploration is failing."
  latency: 5302ms

Tests: 345 green (was 332, +13 advisor-trigger).

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

runtime/coach/advisor-trigger.js

@@ -0,0 +1,164 @@
+// Auto-trigger policy for the fast tactical advisor.
+//
+// The advisor is too slow for synchronous use inside a reflex tick
+// (5-15s via TimeWeb's hosted agent endpoint). The strategy here is
+// asynchronous: when conditions warrant tactical advice, fire-and-forget
+// an advise() call; when the result eventually arrives, cache it on
+// ctx.advisorRecommendation. The next reflex tick reads that cache and
+// can substitute the recommended skill before dispatching.
+//
+// Triggers (any one, AND-ed with the not-recently-asked cooldown):
+//
+//   1. Wedged > 60s — bot's position hasn't shifted ≥16 blocks in over
+//      a minute (already tracked by reflex.js as lastSignificantMoveAt)
+//   2. Last 4+ dispatches were the same skill — clear loop signal
+//   3. Last awareness preempt was very recent AND followed by same
+//      skill being dispatched again — env-shock-blind retry
+//
+// The recommendation has a TTL (60s). After that it's stale and the
+// reflex falls back to manifesto / curriculum. This keeps the system
+// reactive — advice ages out, fresh data drives fresh advice.
+
+import { advise, isAvailable as advisorAvailable } from "./fast-advisor.js";
+import { isRegistered } from "../skill-registry.js";
+import { info, warn } from "../log.js";
+
+const TRIGGER_COOLDOWN_MS = 90_000;
+const RECOMMENDATION_TTL_MS = 60_000;
+const WEDGED_THRESHOLD_MS = 60_000;
+const REPEAT_THRESHOLD = 4;
+const PREEMPT_WINDOW_MS = 30_000;
+
+let _lastTriggerAt = 0;
+let _inFlight = false;
+
+export function _resetForTest() {
+	_lastTriggerAt = 0;
+	_inFlight = false;
+}
+
+export function getTriggerState() {
+	return {
+		lastTriggerAt: _lastTriggerAt,
+		inFlight: _inFlight,
+	};
+}
+
+/**
+ * tickAdvisor(ctx) → maybe-fires advise() in background.
+ *
+ * Called from reflex AFTER it has chosen a plannedSkillId but BEFORE
+ * dispatching. Does NOT block — the in-flight call resolves later and
+ * writes ctx.advisorRecommendation. The caller decides whether to
+ * consume a fresh recommendation on this tick or wait for the next.
+ */
+export function tickAdvisor(ctx, { plannedSkillId } = {}) {
+	if (!advisorAvailable()) return { fired: false, reason: "disabled" };
+	if (_inFlight) return { fired: false, reason: "in_flight" };
+
+	const now = Date.now();
+	if (now - _lastTriggerAt < TRIGGER_COOLDOWN_MS) {
+		return { fired: false, reason: "cooldown" };
+	}
+
+	// Drop a recommendation that's already aged out.
+	if (ctx.advisorRecommendation && now - ctx.advisorRecommendation.at > RECOMMENDATION_TTL_MS) {
+		ctx.advisorRecommendation = null;
+	}
+
+	const reason = detectTrigger(ctx, now, plannedSkillId);
+	if (!reason) return { fired: false, reason: "no_trigger" };
+
+	_lastTriggerAt = now;
+	_inFlight = true;
+	const snapshot = ctx.snapshot ?? null;
+	const recentSkillIds = (ctx.recentSkillIds ?? []).slice(-8);
+
+	info("advisor-trigger", `firing because ${reason} (planned=${plannedSkillId ?? "?"})`);
+	// Fire-and-forget. The promise's resolution writes ctx.advisorRecommendation.
+	advise({ snapshot, reason, recentSkillIds, lessonsTail: ctx.recentLessons ?? [], force: true })
+		.then((result) => {
+			_inFlight = false;
+			if (result.ok && result.action === "switch_skill" && isRegistered(result.skillId)) {
+				ctx.advisorRecommendation = {
+					at: Date.now(),
+					skillId: result.skillId,
+					action: "switch_skill",
+					rationale: result.rationale,
+					triggerReason: reason,
+					latencyMs: result.latencyMs,
+					usage: result.usage ?? null,
+				};
+				info("advisor-trigger", `recommendation cached: ${result.skillId} (${result.latencyMs}ms, in=${result.usage?.in ?? "?"}t/out=${result.usage?.out ?? "?"}t)`);
+			} else if (result.ok && (result.action === "wait" || result.action === "continue")) {
+				ctx.advisorRecommendation = {
+					at: Date.now(),
+					action: result.action,
+					rationale: result.rationale,
+					triggerReason: reason,
+					latencyMs: result.latencyMs,
+					usage: result.usage ?? null,
+				};
+				info("advisor-trigger", `recommendation: ${result.action} (${result.latencyMs}ms)`);
+			} else if (!result.ok) {
+				warn("advisor-trigger", `advise failed: ${result.code} (${result.detail})`);
+			}
+		})
+		.catch((e) => {
+			_inFlight = false;
+			warn("advisor-trigger", `advise threw: ${e?.message ?? e}`);
+		});
+
+	return { fired: true, reason };
+}
+
+function detectTrigger(ctx, now, plannedSkillId) {
+	// 1. Wedged > threshold
+	if (ctx.lastSignificantMoveAt && (now - ctx.lastSignificantMoveAt) > WEDGED_THRESHOLD_MS) {
+		return `wedged_${Math.round((now - ctx.lastSignificantMoveAt) / 1000)}s`;
+	}
+	// 2. Repeat-skill loop
+	const recent = ctx.recentSkillIds ?? [];
+	if (recent.length >= REPEAT_THRESHOLD) {
+		const tail = recent.slice(-REPEAT_THRESHOLD);
+		const allSame = tail.every((id) => id === tail[0]);
+		if (allSame && plannedSkillId === tail[0]) {
+			return `repeat_${REPEAT_THRESHOLD}_${tail[0]}`;
+		}
+	}
+	// 3. Recent preempt followed by same skill again
+	if (ctx.lastPreempt && now - ctx.lastPreempt.at < PREEMPT_WINDOW_MS) {
+		const lastDispatched = recent[recent.length - 1];
+		if (lastDispatched && lastDispatched === plannedSkillId) {
+			return `preempt_retry_${ctx.lastPreempt.reason}`;
+		}
+	}
+	return null;
+}
+
+/**
+ * consumeFreshRecommendation(ctx) → { skillId, action, rationale } | null
+ *
+ * Returns a recommendation if one is currently cached and fresh, and
+ * clears it so subsequent ticks don't re-apply the same advice.
+ */
+export function consumeFreshRecommendation(ctx) {
+	const rec = ctx.advisorRecommendation;
+	if (!rec) return null;
+	if (Date.now() - rec.at > RECOMMENDATION_TTL_MS) {
+		ctx.advisorRecommendation = null;
+		return null;
+	}
+	if (rec.action !== "switch_skill" || !rec.skillId) {
+		// 'continue' / 'wait' don't replace dispatch; surface for telemetry only
+		return null;
+	}
+	ctx.advisorRecommendation = null;
+	return rec;
+}
+
+// Test exports
+export const __testing = {
+	TRIGGER_COOLDOWN_MS, RECOMMENDATION_TTL_MS, WEDGED_THRESHOLD_MS,
+	REPEAT_THRESHOLD, PREEMPT_WINDOW_MS, detectTrigger,
+};

runtime/coach/advisor-trigger.test.js

@@ -0,0 +1,216 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+	tickAdvisor,
+	consumeFreshRecommendation,
+	getTriggerState,
+	_resetForTest,
+	__testing,
+} from "./advisor-trigger.js";
+import { _resetForTest as resetAdvisor } from "./fast-advisor.js";
+
+const { detectTrigger, WEDGED_THRESHOLD_MS, REPEAT_THRESHOLD, PREEMPT_WINDOW_MS, RECOMMENDATION_TTL_MS } = __testing;
+
+const API_KEY = "TIMEWEB_API_KEY";
+const MODEL = "TIMEWEB_MODEL";
+
+function withEnv(env, fn) {
+	const prev = {};
+	for (const k of Object.keys(env)) {
+		prev[k] = process.env[k];
+		if (env[k] === undefined) delete process.env[k];
+		else process.env[k] = env[k];
+	}
+	return Promise.resolve(fn()).finally(() => {
+		for (const [k, v] of Object.entries(prev)) {
+			if (v === undefined) delete process.env[k];
+			else process.env[k] = v;
+		}
+	});
+}
+
+function stubFetch(reply, latency = 0) {
+	const orig = globalThis.fetch;
+	globalThis.fetch = async () => {
+		if (latency) await new Promise((r) => setTimeout(r, latency));
+		return {
+			ok: true,
+			json: async () => ({
+				choices: [{ message: { content: typeof reply === "string" ? reply : JSON.stringify(reply) } }],
+				usage: { prompt_tokens: 1500, completion_tokens: 40, total_tokens: 1540 },
+			}),
+		};
+	};
+	return () => { globalThis.fetch = orig; };
+}
+
+test("detectTrigger: returns null when nothing matches", () => {
+	const r = detectTrigger({ recentSkillIds: [] }, Date.now(), "gather.logs");
+	assert.equal(r, null);
+});
+
+test("detectTrigger: wedged > 60s fires", () => {
+	const now = Date.now();
+	const r = detectTrigger(
+		{ recentSkillIds: ["x"], lastSignificantMoveAt: now - WEDGED_THRESHOLD_MS - 5000 },
+		now,
+		"explore.far",
+	);
+	assert.match(r, /^wedged_\d+s/);
+});
+
+test("detectTrigger: 4 same dispatches in row + same planned → repeat", () => {
+	const now = Date.now();
+	const r = detectTrigger(
+		{ recentSkillIds: ["explore.far", "explore.far", "explore.far", "explore.far"] },
+		now,
+		"explore.far",
+	);
+	assert.match(r, /^repeat_4_explore\.far/);
+});
+
+test("detectTrigger: same skill repeated but planned is different → no repeat trigger", () => {
+	const now = Date.now();
+	const r = detectTrigger(
+		{ recentSkillIds: ["explore.far", "explore.far", "explore.far", "explore.far"] },
+		now,
+		"gather.logs",
+	);
+	assert.equal(r, null);
+});
+
+test("detectTrigger: recent preempt + same skill re-planned → preempt_retry", () => {
+	const now = Date.now();
+	const r = detectTrigger(
+		{
+			recentSkillIds: ["gather.logs"],
+			lastPreempt: { at: now - 5000, reason: "forced_move" },
+		},
+		now,
+		"gather.logs",
+	);
+	assert.equal(r, "preempt_retry_forced_move");
+});
+
+test("detectTrigger: old preempt (> window) does not trigger", () => {
+	const now = Date.now();
+	const r = detectTrigger(
+		{
+			recentSkillIds: ["gather.logs"],
+			lastPreempt: { at: now - PREEMPT_WINDOW_MS - 5000, reason: "forced_move" },
+		},
+		now,
+		"gather.logs",
+	);
+	assert.equal(r, null);
+});
+
+test("tickAdvisor: disabled when TIMEWEB_API_KEY missing", async () => {
+	await withEnv({ [API_KEY]: undefined }, () => {
+		_resetForTest();
+		const r = tickAdvisor({ recentSkillIds: [] }, { plannedSkillId: "x" });
+		assert.equal(r.fired, false);
+		assert.equal(r.reason, "disabled");
+	});
+});
+
+test("tickAdvisor: no_trigger when ctx has nothing interesting", async () => {
+	await withEnv({ [API_KEY]: "k", [MODEL]: "m" }, () => {
+		_resetForTest();
+		resetAdvisor();
+		const r = tickAdvisor({ recentSkillIds: [] }, { plannedSkillId: "gather.logs" });
+		assert.equal(r.fired, false);
+		assert.equal(r.reason, "no_trigger");
+	});
+});
+
+test("tickAdvisor: fires on wedged trigger and caches recommendation", async () => {
+	const restore = stubFetch({
+		action: "switch_skill",
+		skill_id: "survive.flee",
+		rationale: "Wedged here, retreat instead.",
+	});
+	try {
+		await withEnv({ [API_KEY]: "k", [MODEL]: "m" }, async () => {
+			_resetForTest();
+			resetAdvisor();
+			const ctx = {
+				recentSkillIds: ["explore.far"],
+				lastSignificantMoveAt: Date.now() - 120_000,
+			};
+			const r = tickAdvisor(ctx, { plannedSkillId: "explore.far" });
+			assert.equal(r.fired, true);
+			assert.match(r.reason, /^wedged_/);
+			assert.equal(getTriggerState().inFlight, true);
+
+			// Wait for the in-flight promise to settle.
+			await new Promise((res) => setTimeout(res, 20));
+			assert.equal(getTriggerState().inFlight, false);
+			assert.ok(ctx.advisorRecommendation, "recommendation cached");
+			assert.equal(ctx.advisorRecommendation.skillId, "survive.flee");
+			assert.equal(ctx.advisorRecommendation.usage.total, 1540);
+		});
+	} finally { restore(); }
+});
+
+test("tickAdvisor: cooldown blocks second trigger right after", async () => {
+	const restore = stubFetch({ action: "continue", rationale: "ok" });
+	try {
+		await withEnv({ [API_KEY]: "k", [MODEL]: "m" }, async () => {
+			_resetForTest();
+			resetAdvisor();
+			const ctx = {
+				recentSkillIds: ["explore.far"],
+				lastSignificantMoveAt: Date.now() - 120_000,
+			};
+			const r1 = tickAdvisor(ctx, { plannedSkillId: "explore.far" });
+			assert.equal(r1.fired, true);
+			await new Promise((res) => setTimeout(res, 20));
+			const r2 = tickAdvisor(ctx, { plannedSkillId: "explore.far" });
+			assert.equal(r2.fired, false);
+			assert.equal(r2.reason, "cooldown");
+		});
+	} finally { restore(); }
+});
+
+test("consumeFreshRecommendation: returns + clears switch_skill recommendation", () => {
+	_resetForTest();
+	const ctx = {
+		advisorRecommendation: {
+			at: Date.now(),
+			action: "switch_skill",
+			skillId: "survive.flee",
+			rationale: "x",
+		},
+	};
+	const r = consumeFreshRecommendation(ctx);
+	assert.ok(r);
+	assert.equal(r.skillId, "survive.flee");
+	assert.equal(ctx.advisorRecommendation, null);
+});
+
+test("consumeFreshRecommendation: stale (> TTL) recommendation dropped", () => {
+	_resetForTest();
+	const ctx = {
+		advisorRecommendation: {
+			at: Date.now() - RECOMMENDATION_TTL_MS - 1000,
+			action: "switch_skill",
+			skillId: "survive.flee",
+		},
+	};
+	const r = consumeFreshRecommendation(ctx);
+	assert.equal(r, null);
+	assert.equal(ctx.advisorRecommendation, null);
+});
+
+test("consumeFreshRecommendation: continue/wait recommendations are not consumed for skill swap", () => {
+	_resetForTest();
+	const ctx = {
+		advisorRecommendation: { at: Date.now(), action: "continue", rationale: "ok" },
+	};
+	const r = consumeFreshRecommendation(ctx);
+	assert.equal(r, null);
+	// stays cached for telemetry
+	assert.ok(ctx.advisorRecommendation);
+});

runtime/coach/fast-advisor.js

@@ -23,14 +23,33 @@ const COOLDOWN_MS = 30_000;
 
 let _callTimes = [];
 let _lastCallAt = 0;
+let _tokensIn = 0;
+let _tokensOut = 0;
+let _calls = 0;
 
 export function isAvailable() {
 	return llmAvailable();
 }
 
+export function getUsageSnapshot() {
+	const now = Date.now();
+	const hourAgo = now - 3600_000;
+	const recentCalls = _callTimes.filter((t) => t > hourAgo).length;
+	return {
+		callsLastHour: recentCalls,
+		callsTotal: _calls,
+		tokensInTotal: _tokensIn,
+		tokensOutTotal: _tokensOut,
+		hourlyBudget: HOURLY_BUDGET,
+	};
+}
+
 export function _resetForTest() {
 	_callTimes = [];
 	_lastCallAt = 0;
+	_tokensIn = 0;
+	_tokensOut = 0;
+	_calls = 0;
 }
 
 /**
@@ -69,6 +88,11 @@ export async function advise({
 	_lastCallAt = now;
 
 	const res = await complete({ system, user, json: true });
+	_calls += 1;
+	if (res.usage) {
+		_tokensIn += res.usage.in;
+		_tokensOut += res.usage.out;
+	}
 	if (!res.ok) {
 		warn("advisor", `complete failed: ${res.code} (${res.detail})`);
 		return { ok: false, code: res.code, detail: res.detail, latencyMs: res.latencyMs };
@@ -93,6 +117,7 @@ export async function advise({
 				rationale,
 				raw: parsed,
 				latencyMs: res.latencyMs,
+				usage: res.usage,
 			};
 		}
 		info("advisor", `switch_skill → ${skillId} (${rationale.slice(0, 80)})`);
@@ -103,15 +128,16 @@ export async function advise({
 			rationale,
 			raw: parsed,
 			latencyMs: res.latencyMs,
+			usage: res.usage,
 		};
 	}
 
 	if (action === "continue" || action === "wait") {
 		info("advisor", `${action} (${rationale.slice(0, 80)})`);
-		return { ok: true, action, rationale, raw: parsed, latencyMs: res.latencyMs };
+		return { ok: true, action, rationale, raw: parsed, latencyMs: res.latencyMs, usage: res.usage };
 	}
 
-	return { ok: false, code: "bad_action", detail: action || "missing", raw: parsed, latencyMs: res.latencyMs };
+	return { ok: false, code: "bad_action", detail: action || "missing", raw: parsed, latencyMs: res.latencyMs, usage: res.usage };
 }
 
 function buildSystemPrompt() {