@gcunharodrigues/wrxn 0.14.0 → 0.16.0

package/manifest.json

@@ -528,6 +528,11 @@
       "class": "seeded",
       "profile": "project"
     },
+    {
+      "path": ".env.example",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".wrxn/sync.cjs",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"

package/payload/.claude/hooks/session-start.cjs

@@ -201,6 +201,99 @@ function holdForHandoff({ root, capMs = HOLD_CAP_MS, now = Date.now, sleep } = {
   }
 }
 
+// ── baton-staleness guard (#51) ─────────────────────────────────────────────────
+// The handoff baton is surfaced as the resume point with no health check, so a baton frozen by a failed
+// SessionEnd synth (no-engine / error) is shown as current — silently (real incident 2026-06-22→23: the
+// baton froze ~20h while .synth.log logged no-engine from later sessions). This guard reads the synth log +
+// the baton mtime and, when the latest synth attempt failed and it is NOT a same-session double-spawn (the
+// session that wrote the baton failing again right after — #45), surfaces a visible warning. The DECISION is
+// pure (no IO, no clock — the holdDecision idiom); the hook does the IO and formats the age where it holds
+// the clock. NO polling/sleeping — one file read + one stat.
+
+const SYNTH_LOG_REL = ['.wrxn', 'continuity', '.synth.log'];
+
+// A synth row is a FAILURE iff its outcome is `no-engine` or an `error…` string (`wrote`/`trivial` = healthy).
+function isFailure(outcome) {
+  const o = String(outcome || '');
+  return o === 'no-engine' || /^error/.test(o);
+}
+
+// Parse the tab-separated synth log into chronological rows { timestampMs, sessionId, outcome }, dropping
+// any line we cannot resolve (malformed / unparseable timestamp) — "newest-resolvable last". The sessionId
+// (field 1, `-` when absent) is what discriminates a double-spawn from genuine rot. PURE + total, never throws.
+function parseSynthLog(text) {
+  const rows = [];
+  for (const line of String(text || '').split('\n')) {
+    if (!line.trim()) continue;
+    const f = line.split('\t');
+    if (f.length < 6) continue; // not a full outcome row → skip (fail-open)
+    const ts = Date.parse(f[0]);
+    if (!Number.isFinite(ts)) continue; // unresolvable timestamp → drop
+    rows.push({ timestampMs: ts, sessionId: f[1], outcome: f.slice(5).join('\t').trim() });
+  }
+  return rows;
+}
+
+// Human age for the warning line (computed where the clock is, so batonStaleness stays clock-free). PURE.
+function formatAge(ms) {
+  const m = Math.max(0, Math.round(Number(ms) / 60000));
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h`;
+  const d = Math.floor(h / 24);
+  const rem = h % 24;
+  return rem ? `${d}d ${rem}h` : `${d}d`;
+}
+
+// Sanitize the echoed synth outcome before it is interpolated into the orientation block (sec-F1). An
+// `error: …` row carries a FREE-FORM message, so a crafted/corrupt log row could smuggle control chars or a
+// forged `</wrxn-orientation>` close tag into additionalContext. Strip control chars (incl CR/LF/tab), drop
+// angle brackets so no tag can be forged, and cap the length. PURE + total. (Mirrors memory-synth's
+// sanitizeLogField idiom — each install-only hook is self-contained, node stdlib only.)
+function sanitizeOutcome(s) {
+  return String(s == null ? '' : s)
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f-\x9f]/g, '')
+    .replace(/[<>]/g, '')
+    .slice(0, 120);
+}
+
+/**
+ * Pure baton-staleness decision (#51). Given the baton's last-write time and the synth-log rows
+ * (chronological, newest-resolvable last, each carrying its sessionId), return the FAILING outcome to name
+ * in the warning, or null when the baton is healthy/fresh. Warn IFF the newest row failed (`no-engine` |
+ * `error…`) AND the baton predates that newest row AND it is NOT a same-session double-spawn.
+ *
+ * Double-spawn vs genuine-rot is discriminated by SESSION ID, NOT by timestamp. The session that wrote the
+ * CURRENT baton is the session of the MOST-RECENT `wrote` row (every successful synth logs a `wrote` row in
+ * runHandoff's finally, a few ms AFTER it set the baton mtime — so that row's timestamp is ALWAYS ≥ the baton
+ * mtime, and a timestamp test can never tell the two apart). The #45 double-spawn logs `wrote` then a spurious
+ * `no-engine` ~2s later under the SAME session → suppress. A genuine freeze has later failures from DIFFERENT
+ * sessions (real incident 2026-06-22→23: baton written by 6898c0a9, then 7b69b97c / 39e5754b no-engine hours
+ * later) → warn. A missing/`-` session id on either side cannot confirm a double-spawn → default to warn (a
+ * loud false-positive beats silent rot). PURE + total: no IO, no clock, never throws.
+ * @param {{ batonMtimeMs:number, rows:Array<{timestampMs:number, sessionId?:string, outcome:string}> }} [input]
+ * @returns {string|null} the failing outcome to name, or null when healthy
+ */
+function batonStaleness({ batonMtimeMs, rows } = {}) {
+  if (!Array.isArray(rows) || rows.length === 0) return null; // no rows → nothing to judge
+  if (typeof batonMtimeMs !== 'number' || !Number.isFinite(batonMtimeMs)) return null; // no usable mtime
+  const newest = rows[rows.length - 1];
+  if (!newest || !isFailure(newest.outcome)) return null; // latest run healthy → fresh
+  if (Number.isFinite(newest.timestampMs) && newest.timestampMs <= batonMtimeMs) return null; // baton at/after newest → fresh
+  // The session that wrote the CURRENT baton = the session of the most-recent `wrote` row.
+  let wroteSession;
+  for (const r of rows) {
+    if (r && r.outcome === 'wrote') wroteSession = r.sessionId;
+  }
+  const sameSession =
+    !!wroteSession && wroteSession !== '-' &&
+    !!newest.sessionId && newest.sessionId !== '-' &&
+    wroteSession === newest.sessionId;
+  if (sameSession) return null; // same-session double-spawn → not stale
+  return newest.outcome; // genuine rot (or unconfirmable) → name the failing outcome
+}
+
 function main() {
   let consumed = '';
   try {
@@ -241,6 +334,24 @@ function main() {
   const baton = readBaton(root);
   if (baton && baton.trim()) {
     parts.push('', 'Resume — deliberate handoff baton (.wrxn/continuity/latest.md):', baton.trim());
+    // #51: warn if the latest SessionEnd synth failed and no successful write has refreshed the baton since
+    // — a frozen baton must not be surfaced as current silently. Fail-open: any read/stat/parse fault → no
+    // warning, never a throw. Pure file reads + a stat only (no polling/sleeping beyond the hold cap above).
+    try {
+      const rows = parseSynthLog(readFileOr(path.join(root, ...SYNTH_LOG_REL), ''));
+      const batonMtimeMs = fs.statSync(path.join(root, '.wrxn', 'continuity', 'latest.md')).mtimeMs;
+      const failing = batonStaleness({ batonMtimeMs, rows });
+      if (failing) {
+        const age = formatAge(Date.now() - batonMtimeMs);
+        const outcome = sanitizeOutcome(failing); // sec-F1: never echo a raw log field into the orientation
+        parts.push(
+          '',
+          `WARNING — stale handoff baton: the latest memory-synth run failed ("${outcome}") and the baton has not been refreshed for ${age}. It may not reflect the last session — see .wrxn/continuity/.synth.log.`,
+        );
+      }
+    } catch {
+      /* fail-open: a staleness-check fault must never block orientation (#51 AC3) */
+    }
   } else {
     parts.push('', 'Resume — no prior handoff.');
   }
@@ -261,4 +372,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { holdDecision, holdForHandoff, HOLD_CAP_MS, stampStartHead, resolveGitHead, BASELINE_DIR_REL };
+module.exports = { holdDecision, holdForHandoff, HOLD_CAP_MS, stampStartHead, resolveGitHead, BASELINE_DIR_REL, batonStaleness };

package/payload/.env.example

@@ -0,0 +1,6 @@
+# WRXN memory-synth — secret config. Copy this file to `.env` and fill in the value below.
+# `.env` is gitignored (the secret is never committed); this `.env.example` is the tracked template.
+#
+# GEMINI_API_KEY powers the `gemini` engine for handoff + dream synthesis — the shipped DEFAULT
+# primary for both. Without it, synth falls back to `claude`, which uses your CLI auth (no key needed).
+GEMINI_API_KEY=

package/payload/.wrxn/dream.cjs

@@ -390,7 +390,11 @@ const NEGATIVE_FILTERS = [
   // a transient environment / setup failure — not a durable property of the system. (The bare adjectives
   // `transient`/`intermittent` are intentionally NOT here: they false-positive on DI-lifetime decisions
   // like "services are registered transient" — the concrete error codes below carry the failure intent.)
-  { reason: 'negative_filter_transient_failure', re: /\b(econnrefused|enoent|eaddrinuse|etimedout|connection refused|connection reset|timed out|time-?out|flak(e|y|ey)|rate[- ]?limit(ed)?|http 5\d\d|50[234]|port (already )?in use|address already in use|network (error|issue|glitch)|dns (error|failure))\b/ },
+  // SAME discipline for rate-limiting: the bare noun "rate limit" / adjective "rate-limited" is NOT matched
+  // (it false-positives on rate limiting AS A FEATURE — a token-bucket decision, a "rate-limited tier").
+  // Only the ERROR sense matches: a passive/verb "got rate-limited", a transitive "rate-limited us", or a
+  // "rate-limit(ed) error" / "rate limit exceeded" cue — the transient war-story, never the design.
+  { reason: 'negative_filter_transient_failure', re: /\b(econnrefused|enoent|eaddrinuse|etimedout|connection refused|connection reset|timed out|time-?out|flak(e|y|ey)|(?:got|get|getting|gets|was|were|been|being|keeps?|kept|repeatedly) rate[- ]?limited|rate[- ]?limited (?:us|me|them|by|again)|rate[- ]?limit(?:ed|ing)? (?:error|errors|exceeded)|http 5\d\d|50[234]|port (already )?in use|address already in use|network (error|issue|glitch)|dns (error|failure))\b/ },
   // a smoke / sanity / happy-path RESULT — proves nothing durable. Gated on a result word so a forward
   // decision ("we adopt smoke tests", "the happy path must stay fast") is NOT a false positive.
   { reason: 'negative_filter_smoke_test', re: /\bhello[- ]?world\b|\b(smoke[- ]?tests?|sanity[- ]?checks?|happy path)\s+(pass(ed|es|ing)?|ran|run|succeed(ed|s)?|works?|worked|green)\b/ },

package/payload/.wrxn/memory-synth.cjs

@@ -25,12 +25,13 @@ const https = require('https');
 const { spawnSync } = require('child_process');
 
 // ── default tiering (PRD) ──────────────────────────────────────────────────────
-// handoff + dream default to claude/claude-sonnet-4-6, falling back to gemini/gemini-3.1-flash-lite.
+// handoff + dream default to gemini/gemini-3.1-flash-lite, falling back to claude/claude-sonnet-4-6.
 // The seeded memory.config.json is this object serialized; an operator edits it and `wrxn update`
-// preserves it (seeded class).
+// preserves it (seeded class). Claude stays the fallback so a keyless fresh install still writes a
+// baton via the operator's CLI auth (no GEMINI_API_KEY → gemini gated → claude carries it).
 const DEFAULT_TASK = {
-  primary: { engine: 'claude', model: 'claude-sonnet-4-6' },
-  fallback: { engine: 'gemini', model: 'gemini-3.1-flash-lite' },
+  primary: { engine: 'gemini', model: 'gemini-3.1-flash-lite' },
+  fallback: { engine: 'claude', model: 'claude-sonnet-4-6' },
 };
 const DEFAULTS = {
   tasks: {
@@ -389,10 +390,13 @@ function defaultSleep(ms) {
  * Run a single engine through the invoker; return `{ text, attempts }` (text null when no output). A
  * `gemini` engine with no API key fails WITHOUT calling the invoker (no key → no request, attempts 0). A
  * transient `ok:false` is retried up to ENGINE_ATTEMPTS with a fixed backoff via the injected sleep; the
- * first non-empty text wins. An invoker that throws is caught → counts as a failed attempt, then null.
+ * first text that is non-empty AND passes the optional task `validate` predicate wins. A non-empty text
+ * that FAILS `validate` (unusable output — e.g. dream prose the gate can't parse) is a failed attempt →
+ * retried, then null, so synthesizeDetailed advances to the fallback. No validator → any non-empty wins.
+ * An invoker that throws is caught → counts as a failed attempt, then null.
  * @returns {Promise<{ text: string|null, attempts: number }>}
  */
-async function runEngine(engine, { prompt, blob, apiKey, invoke, sleep = defaultSleep }) {
+async function runEngine(engine, { prompt, blob, apiKey, invoke, sleep = defaultSleep, validate }) {
   if (!engine || !engine.engine) return { text: null, attempts: 0 };
   let spec;
   if (engine.engine === 'claude') {
@@ -414,12 +418,30 @@ async function runEngine(engine, { prompt, blob, apiKey, invoke, sleep = default
     } catch {
       text = null; // an invoker throw is a transient failure for this attempt (degrade, never throw).
     }
-    if (text) return { text, attempts };
+    // success = non-empty AND task-usable (validate). No validator → permissive: any non-empty text wins.
+    if (text && (!validate || validate(text))) return { text, attempts };
     if (i < ENGINE_ATTEMPTS - 1) sleep(ENGINE_BACKOFF_MS); // back off before the next attempt (not after the last). sleep is synchronous (Atomics.wait / injected no-op) — no await.
   }
   return { text: null, attempts };
 }
 
+// ── per-task engine-success validators (synth-robustness #50) ───────────────────
+// An engine attempt succeeds only when its text is non-empty AND passes the task's validator, so an engine
+// that returns non-empty-but-UNUSABLE output exhausts its retries and synthesizeDetailed advances to the
+// fallback — instead of the unusable primary "winning" while the downstream gate parses zero proposals and
+// writes nothing. A task with NO registered validator is permissive (any non-empty text wins, exactly as
+// before), so every existing caller is preserved.
+const TASK_VALIDATORS = {
+  // dream output is usable only if the gate (parseProposals) reads ≥1 proposal from it, OR it is an explicit
+  // abstain — a deliberate "nothing to record" is a valid answer, NOT a reason to churn through the fallback.
+  dream: (text) => parseProposals(text).length > 0 || /abstain/i.test(text),
+};
+
+// Resolve a task's engine-success validator; an unregistered task is permissive (any non-empty text wins).
+function validatorFor(task) {
+  return TASK_VALIDATORS[task] || (() => true);
+}
+
 /**
  * Synthesize text for `task` from `prompt` + `blob`, resolving the engine per task (primary → fallback),
  * also reporting WHICH engine produced the text and HOW MANY attempts the producing engine spent (the
@@ -430,9 +452,10 @@ async function runEngine(engine, { prompt, blob, apiKey, invoke, sleep = default
  */
 async function synthesizeDetailed({ task, prompt, blob, config, apiKey, invoke = defaultInvoke, sleep }) {
   const { primary, fallback } = resolveTask(config || DEFAULTS, task);
+  const validate = validatorFor(task); // task-aware success: dream needs parseable proposals; handoff is permissive.
   let attempts = 0;
   for (const engine of [primary, fallback]) {
-    const r = await runEngine(engine, { prompt, blob, apiKey, invoke, sleep });
+    const r = await runEngine(engine, { prompt, blob, apiKey, invoke, sleep, validate });
     attempts += r.attempts;
     if (r.text) return { text: r.text, engine: engine && engine.engine, attempts };
   }

package/payload/.wrxn/memory.config.json

@@ -1,12 +1,12 @@
 {
   "tasks": {
     "handoff": {
-      "primary": { "engine": "claude", "model": "claude-sonnet-4-6" },
-      "fallback": { "engine": "gemini", "model": "gemini-3.1-flash-lite" }
+      "primary": { "engine": "gemini", "model": "gemini-3.1-flash-lite" },
+      "fallback": { "engine": "claude", "model": "claude-sonnet-4-6" }
     },
     "dream": {
-      "primary": { "engine": "claude", "model": "claude-sonnet-4-6" },
-      "fallback": { "engine": "gemini", "model": "gemini-3.1-flash-lite" }
+      "primary": { "engine": "gemini", "model": "gemini-3.1-flash-lite" },
+      "fallback": { "engine": "claude", "model": "claude-sonnet-4-6" }
     }
   }
 }