@inetafrica/open-claudia 3.0.26 → 3.0.28

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## v3.0.28 — /upgrade stops crying wolf on a slow roll
+
+- **A client-side `/upgrade` timeout is no longer reported as a failure.** When the bot runs inside an AgentSpace pod, `/upgrade` calls the control plane, which triggers a fire-and-forget rollout and returns 202. If the pod is mid-roll its own in-flight request gets cut off, so the 15s HTTP wait would expire and the bot announced "Upgrade request failed … timeout" — a false negative that invited repeated re-runs (and a storm of redundant rollouts, seen as 11 ReplicaSets in 7 minutes). A timed-out request now surfaces as **pending** ("sent but the reply timed out — likely because I'm already restarting; give it a minute"), and the request timeout is raised 15s → 30s.
+- **Pairs with a control-plane probe fix (the actual root cause).** The pod's `/health` probes carried no `timeoutSeconds`, so k8s defaulted it to 1s; a cold-start event-loop stall past 1s flapped the liveness probe and SIGTERM'd the pod in a restart loop. That fix — explicit `timeoutSeconds: 5` on every probe and liveness `failureThreshold` 3 → 5 — ships in the agent-space control plane and reaches existing pods on their next reconcile (`/cluster sync`).
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change; Docker image builds identically (FROM the pre-baked `:base`). Existing pods pick this up on their next approved upgrade.
+
+## v3.0.27 — Agency ledger, advisory "what's next", owner-guardrail capture, and a reboot that waits for the turn to end
+
+- **`/agenda` — one read-only work list across everything (Track B0).** A new aggregator normalises your persistent tasks, `spaces mine`, and connector inbox/notifications into a single list (source, title, status, due, staleness, blocked-on, last-touched). Pure visibility — it reads, it never acts. `/agency` is an alias.
+- **`/next` — the bot proposes what it would pick, and does nothing (Track B1, advisory).** A triage→rank→judge pipeline (deterministic prefilter → algorithmic rank → a small judge on the ambiguous top-N) says "here's what I'd do next and why." It acts on nothing without you — bounded autonomy (B2+) stays gated behind a shadow-mode review, exactly as planned.
+- **Owner-guardrail capture — say a rule mid-chat and it sticks (Track C0/C1).** When *you* say "from now on, always X" / "never Y" / "stop doing Z", a post-turn detector turns it into an always-loaded lesson immediately — no code change, no deploy. High-confidence phrasings are auto-captured with an announcement and a one-tap **Undo**; softer ones ask first (Save / No). Hard owner gate: a standing rule is **never** captured from an external speaker, and captured rules layer *above* lessons but can never override the code-fixed hard rules. Default-on; set `GUARDRAIL_CAPTURE=off` to disable.
+- **Always-on prompt budget — instrumented, not yet trimmed (Track X0).** Every real turn now measures the fixed always-on floor (soul, lessons, runtime state, slash list) versus the variable recall payload, recorded to telemetry so we can baseline cost before capping it. Pure measurement — the prompt itself is unchanged, so caching is unaffected. Exposed via `agency ledger` / `prompt-budget` CLIs and the recall stats.
+- **A reboot that never interrupts a turn.** The Telegram long-poll has a 10-minute wedge backstop that self-exits for a clean restart when polling is truly stuck. It now checks first whether any turn is running, queued, or compacting — and if so **defers** the exit, keeps attempting in-place recovery, and only restarts once the process is idle (all replies delivered). If polling self-heals meanwhile, no restart happens at all. Recovery only touches the poll socket, so an in-flight turn's subprocess and its outbound sends are untouched.
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change; Docker image builds identically (FROM the pre-baked `:base`). Existing pods pick this up on their next approved upgrade. `GUARDRAIL_CAPTURE` is the one new (optional, default-on) env knob.
+
 ## v3.0.26 — Spaces replies actually post (and stop saying "Queued.")
 
 - **An engaged Spaces reply no longer fails with 400 "Parent comment not found."** Core threads every agent reply under the triggering message id — a Telegram-ism. On Spaces that id is a *notification* id, not a comment id, so the backend rejected the whole post and the bot silently failed to answer any mention. `send()` now only threads under an explicit `comment:`-prefixed id and otherwise posts a top-level task comment; if a stale/deleted parent still 400s, it retries once at top level so the reply always lands.

package/bin/agency-ledger.js

@@ -0,0 +1,91 @@
+// open-claudia agency ledger [--json] [--source task|spaces|notification] [--limit N] [--no-spaces] [--ids]
+// open-claudia agency next   [--json] [--judge] [--no-record]   (advisory: what to do next)
+// open-claudia agenda    (alias for `agency ledger`)
+//
+// Read-only aggregated work list (Track B0) + advisory deliberation (Track B1):
+// persistent per-channel tasks + Spaces tasks assigned to me + connector inbox
+// notifications, normalized and ranked. `next` PROPOSES a single best action and
+// why — it acts on nothing.
+
+const path = require("path");
+const { context } = require("./loopback-client");
+
+const HELP = `
+Aggregated, read-only view of everything on your plate — plus an advisory pick.
+
+  open-claudia agenda [--json] [--source <s>] [--limit N] [--no-spaces] [--ids]
+  open-claudia agency ledger [ ... ]        (same as agenda)
+  open-claudia agency next [--json] [--judge] [--no-record]
+
+Ledger sources: persistent tasks (this channel) · Spaces tasks assigned to me ·
+connector notifications. Ranked overdue → due-soon → in-progress → recently-touched.
+
+  --json           machine-readable output
+  --source <s>     ledger filter: task | spaces | notification
+  --limit N        max rows per source (default 10)
+  --no-spaces      skip the Spaces fetch (local tasks + notifications only)
+  --ids            show entry ids
+
+next (advisory deliberation — proposes, never acts):
+  --judge          let a cheap model disambiguate a close top-N (default: deterministic)
+  --no-record      don't append to the shadow-mode log
+`;
+
+function takeFlag(args, name) {
+  const i = args.indexOf(`--${name}`);
+  if (i < 0) return null;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+}
+
+async function loadLedger(rest) {
+  const ledger = require(path.join(__dirname, "..", "core", "agency", "ledger"));
+  const ctx = context();
+  const result = await ledger.collect({
+    adapter: ctx.adapterId,
+    channelId: ctx.channelId,
+    includeSpaces: !rest.includes("--no-spaces"),
+  });
+  return { ledger, ctx, result };
+}
+
+async function runLedger(rest) {
+  const json = rest.includes("--json");
+  const showIds = rest.includes("--ids");
+  const source = takeFlag(rest, "source");
+  const limit = Number(takeFlag(rest, "limit")) || 10;
+
+  const { ledger, result } = await loadLedger(rest);
+  const out = source
+    ? { ...result, entries: (result.entries || []).filter((e) => e.source === source) }
+    : result;
+
+  if (json) { console.log(JSON.stringify(out, null, 2)); return; }
+  console.log(ledger.render(out, { now: result.generatedAt, limitPerSource: limit, showIds }));
+}
+
+async function runDeliberate(rest) {
+  const json = rest.includes("--json");
+  const useJudge = rest.includes("--judge");
+  const record = !rest.includes("--no-record");
+
+  const { ctx, result } = await loadLedger(rest);
+  const deliberate = require(path.join(__dirname, "..", "core", "agency", "deliberate"));
+  const proposal = await deliberate.deliberate(result, { now: result.generatedAt, useJudge });
+  if (record) {
+    try { deliberate.record(proposal, { channel: ctx.adapterId ? `${ctx.adapterId}:${ctx.channelId}` : null }); } catch (e) {}
+  }
+  if (json) { console.log(JSON.stringify(proposal, null, 2)); return; }
+  console.log(deliberate.render(proposal));
+}
+
+async function run(args) {
+  const sub = args[0];
+  if (sub === "--help" || sub === "help") { console.log(HELP); return; }
+  if (sub === "next" || sub === "deliberate") return runDeliberate(args.slice(1));
+  if (sub === "ledger") return runLedger(args.slice(1));
+  return runLedger(args.slice(0)); // `agenda` alias / bare flags
+}
+
+module.exports = { run, HELP };

package/bin/cli.js

@@ -365,6 +365,21 @@ switch (command) {
     require("./recall").run(args.slice(1));
     break;
   }
+  case "agency": {
+    Promise.resolve(require("./agency-ledger").run(args.slice(1)))
+      .catch((e) => { console.error(`agency command failed: ${e.message}`); process.exitCode = 1; });
+    break;
+  }
+  case "agenda": {
+    Promise.resolve(require("./agency-ledger").run(args.slice(1)))
+      .catch((e) => { console.error(`agenda command failed: ${e.message}`); process.exitCode = 1; });
+    break;
+  }
+  case "prompt-budget":
+  case "always-on": {
+    require("./prompt-budget").run(args.slice(1));
+    break;
+  }
 
   case "dream": {
     require("./dream").run(args.slice(1));

package/bin/prompt-budget.js

@@ -0,0 +1,49 @@
+// open-claudia prompt-budget [--json]
+//
+// Inspect the always-on prompt floor: the fixed token cost (soul + lessons +
+// runtime state + slash-command list + tool headlines + relationship/mandate)
+// carried on every turn, plus the variable recall payload. Baselines Track X of
+// the architecture plan so the floor can be capped as systems multiply.
+
+const path = require("path");
+
+const HELP = `
+Inspect the always-on prompt budget.
+
+  open-claudia prompt-budget [--json]     Rolling always-on floor + per-component breakdown
+
+Measured per real user turn into prompt-budget.jsonl with a rolling summary in
+prompt-budget-summary.json. Token counts are a local ~4-chars/token estimate —
+consistent for tracking growth, not an exact provider tokenization.
+`;
+
+function fmt(n) {
+  n = Math.round(n || 0);
+  return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n);
+}
+
+function run(args) {
+  const sub = args[0];
+  if (sub === "--help" || sub === "help") { console.log(HELP); process.exit(0); }
+  const budget = require(path.join(__dirname, "..", "core", "prompt-budget"));
+  const s = budget.summary();
+  if (args.includes("--json")) { console.log(JSON.stringify(s, null, 2)); return; }
+  console.log("Always-on prompt budget");
+  console.log("───────────────────────");
+  console.log(`Turns measured:      ${s.turns}`);
+  console.log(`Avg always-on:       ${fmt(s.avgAlwaysOnTokens)} tok`);
+  console.log(`Peak always-on:      ${fmt(s.maxAlwaysOnTokens)} tok`);
+  console.log(`Avg recall payload:  ${fmt(s.avgRecallTokens)} tok`);
+  console.log(`Avg total prompt:    ${fmt(s.avgTotalTokens)} tok`);
+  const comp = s.componentAvgTokens || {};
+  const rows = Object.entries(comp).sort((a, b) => b[1] - a[1]);
+  if (rows.length) {
+    console.log("");
+    console.log("Avg tokens by component (largest first):");
+    for (const [k, v] of rows) console.log(`  ${k.padEnd(16)} ${fmt(v)}`);
+  }
+  if (s.updatedAt) console.log(`\nUpdated:             ${s.updatedAt}`);
+  if (!s.turns) console.log("\n(no turns measured yet — populates after the next real user turn)");
+}
+
+module.exports = { run, HELP };

package/bin/recall.js

@@ -32,6 +32,12 @@ function stats(args) {
   console.log(`Nodes opened (📖):    ${s.opens}`);
   console.log(`Avg latency:         ${s.avgLatencyMs}ms`);
   console.log(`Cost:                $${s.costUsd}`);
+  try {
+    const budget = require(path.join(__dirname, "..", "core", "prompt-budget")).summary();
+    if (budget.turns) {
+      console.log(`Always-on floor:     ${budget.avgAlwaysOnTokens} tok avg (peak ${budget.maxAlwaysOnTokens}) — see \`open-claudia prompt-budget\``);
+    }
+  } catch (e) {}
   if (s.updatedAt) console.log(`Updated:             ${s.updatedAt}`);
 }
 

package/channels/telegram/adapter.js

@@ -41,6 +41,7 @@ class TelegramAdapter {
     this._healTimer = null;      // one active recovery in flight at a time
     this._healthyTimer = null;   // fires once polling's been quiet long enough
     this._wedgedSince = 0;       // start of the current unrecovered error streak
+    this._deferredExitLogAt = 0; // throttle the "deferring restart, turn in progress" log (1/min)
     this._lastHiccupLog = 0;     // throttle the transient-error log (1/min)
     this._healBackoff = 0;       // grows per consecutive heal, capped
     this._pollWatchdogTimer = null; // detects a silent first/active getUpdates stall
@@ -139,6 +140,14 @@ class TelegramAdapter {
     await Promise.race([stopped, new Promise((r) => setTimeout(r, 5000))]);
   }
 
+  // Is ANY turn running/preparing/compacting/queued, for any user? The wedge-exit
+  // backstop consults this so a reboot never interrupts in-flight work. Isolated
+  // as a method (lazy require to dodge a load-time cycle) so tests can stub it.
+  _anyTurnActive() {
+    try { return require("../../core/state").anyTurnActive(); }
+    catch (e) { return false; }
+  }
+
   async _heal() {
     this._healTimer = null;
     // Backstop only: if polling has been unbroken-wedged for 10 minutes, a
@@ -149,9 +158,22 @@ class TelegramAdapter {
       // Never fires during a 409 streak: that's a token fight, not a network
       // wedge, and exiting busts the prompt cache (full uncached re-bill of the
       // conversation window on the next turn).
-      console.error("Polling wedged >10min — exiting for a clean restart.");
-      try { require("../../core/restart-reason").recordExitReason("Telegram polling wedged >10min (long-poll unrecoverable) — self-exit for a clean restart", { code: 1 }); } catch (e) {}
-      process.exit(1);
+      if (this._anyTurnActive()) {
+        // A turn is in flight — never reboot mid-turn: it kills in-progress work
+        // and breaks the seamless resume the user expects. Defer the exit, keep
+        // attempting in-place recovery below, and let a later heal exit once the
+        // process is idle. If polling self-heals meanwhile, the wedge clears and
+        // no exit ever happens. (Recovery only touches the poll socket — the
+        // running turn's subprocess and its outbound sends dial their own.)
+        if (!this._deferredExitLogAt || Date.now() - this._deferredExitLogAt > 60000) {
+          this._deferredExitLogAt = Date.now();
+          console.error("Polling wedged >10min but a turn is in progress — deferring restart until idle.");
+        }
+      } else {
+        console.error("Polling wedged >10min — exiting for a clean restart.");
+        try { require("../../core/restart-reason").recordExitReason("Telegram polling wedged >10min (long-poll unrecoverable) — self-exit for a clean restart", { code: 1 }); } catch (e) {}
+        process.exit(1);
+      }
     }
     try {
       await this._stopPollingClean("stale Telegram long-poll recovery");
@@ -169,6 +191,7 @@ class TelegramAdapter {
       if (this._wedgedSince) console.log("Polling healthy again.");
       this._wedgedSince = 0;
       this._healBackoff = 0;
+      this._deferredExitLogAt = 0;
     }, 30000);
   }
 

package/core/actions.js

@@ -513,6 +513,31 @@ async function handleAction(envelope) {
       : `⛔ Denied — ${label} will not run.`);
     return;
   }
+  if (d.startsWith("grd:")) {
+    // Guardrail capture buttons (Track C). Owner-only: standing rules layer
+    // above lessons and are never editable by an external speaker.
+    if (!isChatOwner(envelope.channelId)) return send("Owner only — standing rules are restricted.");
+    const guardrail = require("./guardrail");
+    const parts = d.split(":");
+    const verb = parts[1];
+    const arg = parts.slice(2).join(":");
+    if (verb === "save") {
+      const r = guardrail.confirmPending(arg);
+      if (!r.ok) return send("That rule prompt expired — say it again if you still want it kept.");
+      return send(r.added
+        ? `📌 Done — I'll keep "${String(r.text).slice(0, 160)}" loaded as a standing rule.`
+        : `📌 Already a standing rule — reinforced.`);
+    }
+    if (verb === "no") {
+      guardrail.dropPending(arg);
+      return send("Okay — not making that a standing rule.");
+    }
+    if (verb === "undo") {
+      const r = guardrail.undo(arg);
+      return send(r.ok ? "↩️ Undone — removed that standing rule." : "That rule was already gone.");
+    }
+    return;
+  }
   if (d.startsWith("tt:")) {
     state.settings.showToolTrace = d.slice(3) === "on";
     saveState();

package/core/agency/deliberate.js

@@ -0,0 +1,332 @@
+// Agency deliberation — advisory "what should I do next?" (Track B1).
+//
+// Consumes the read-only ledger (core/agency/ledger) and PROPOSES a single best
+// next action with a transparent reason. It acts on nothing — B1 is advisory
+// only; the act/schedule loop is B2+ (gated behind a shadow-mode review).
+//
+// Pipeline: triage (deterministic prefilter cuts the backlog to what could
+// matter now) → rank (explainable algorithmic score) → optional judge (a cheap
+// model disambiguates a close top-N and refines the action type). Default-
+// silence: if nothing clears the confidence floor, it proposes nothing.
+//
+// The judge is injectable and OFF by default, so deliberation is deterministic,
+// network-free, and safe to run repeatedly in shadow mode. When enabled it can
+// never break the proposal — any judge failure falls back to the deterministic
+// pick.
+
+const path = require("path");
+const fs = require("fs");
+const configDir = require(path.join(__dirname, "..", "..", "config-dir"));
+
+const DAY_MS = 86400000;
+const ACTIONS = ["act", "schedule", "ask", "park"];
+
+// Tunables — deliberately conservative so shadow mode stays quiet unless
+// something genuinely warrants attention.
+const CONFIDENCE_FLOOR = 25;   // below this top score → propose nothing
+const CLEAR_MARGIN = 20;       // top beats second by this → skip the judge
+const DUE_SOON_DAYS = 3;
+const CANDIDATE_STALE_DAYS = 30;
+const TOP_N = 5;
+
+// --- shadow log (mirrors core/prompt-budget storage pattern) ------------
+const LOG_FILE = path.join(configDir, "agency-deliberation.jsonl");
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+function shadowEnabled() {
+  const v = String(process.env.AGENCY_SHADOW || "on").toLowerCase();
+  return v !== "off" && v !== "0" && v !== "false";
+}
+
+function toMs(v) {
+  if (!v) return 0;
+  if (typeof v === "number") return v;
+  const t = Date.parse(v);
+  return Number.isFinite(t) ? t : 0;
+}
+
+function daysUntil(due, now) {
+  const dueMs = toMs(due);
+  if (!dueMs) return null;
+  return (dueMs - now) / DAY_MS;
+}
+
+// --- triage: cut the backlog to what could plausibly matter now ---------
+// Notifications are awareness, not work to "pick" — excluded from candidates.
+// An item survives triage if it is overdue, due soon, already in progress,
+// high priority, or a fresh owner assignment. Everything else is background
+// (parked by default) so a 300-item list collapses to a handful.
+function isCandidate(e, now) {
+  if (e.source === "notification") return false;
+  if (e.status === "done") return false;
+  if (e.overdue) return true;
+  const d = daysUntil(e.due, now);
+  if (d != null && d <= DUE_SOON_DAYS) return true;
+  if (e.status === "in_progress") return true;
+  if (e.priority === "high") return true;
+  if (e.source === "spaces" && e.staleDays != null && e.staleDays <= CANDIDATE_STALE_DAYS) return true;
+  return false;
+}
+
+// --- rank: explainable score + the signals that fired -------------------
+function scoreOf(e, now) {
+  const signals = [];
+  let score = 0;
+
+  if (e.overdue) {
+    const over = Math.min(Math.max(0, -(daysUntil(e.due, now) || 0)), 30);
+    score += 100 + over * 2;
+    signals.push({ k: "overdue", w: 100 + over * 2, label: `overdue ${Math.round(over)}d` });
+  } else {
+    const d = daysUntil(e.due, now);
+    if (d != null && d <= DUE_SOON_DAYS) {
+      const w = 60 - Math.max(0, d) * 12;
+      score += w;
+      signals.push({ k: "due-soon", w, label: d < 1 ? "due today" : `due in ${Math.round(d)}d` });
+    } else if (d != null) {
+      const w = Math.max(4, 20 - Math.min(d, 30));
+      score += w;
+      signals.push({ k: "has-due", w, label: `due in ${Math.round(d)}d` });
+    }
+  }
+
+  if (e.status === "in_progress") {
+    score += 30;
+    signals.push({ k: "in-progress", w: 30, label: "already in progress" });
+  }
+  if (e.priority === "high") {
+    score += 25;
+    signals.push({ k: "priority", w: 25, label: "high priority" });
+  } else if (e.priority === "medium") {
+    score += 8;
+    signals.push({ k: "priority", w: 8, label: "medium priority" });
+  }
+
+  // Unblocks others: a plan/task with open subtasks gates that downstream work.
+  const openSubs = (e.meta && typeof e.meta.subtasks === "number")
+    ? Math.max(0, e.meta.subtasks - (e.meta.subtasksDone || 0)) : 0;
+  if (openSubs > 0) {
+    score += 15;
+    signals.push({ k: "unblocks", w: 15, label: `unblocks ${openSubs} subtask${openSubs > 1 ? "s" : ""}` });
+  }
+
+  // Staleness: mild nudge for neglected-but-active work; mild penalty for very
+  // cold items so abandoned cruft doesn't float up on staleness alone.
+  if (e.staleDays != null) {
+    if (e.staleDays > CANDIDATE_STALE_DAYS && !e.overdue) {
+      score -= 10;
+      signals.push({ k: "cold", w: -10, label: `untouched ${Math.round(e.staleDays)}d` });
+    } else if (e.staleDays > 7 && (e.status === "in_progress" || e.overdue)) {
+      score += 6;
+      signals.push({ k: "neglected", w: 6, label: `neglected ${Math.round(e.staleDays)}d` });
+    }
+  }
+
+  if (e.meta && e.meta.space) signals.push({ k: "context", w: 0, label: e.meta.space });
+
+  signals.sort((a, b) => Math.abs(b.w) - Math.abs(a.w));
+  return { score, signals };
+}
+
+// Deterministic action-type guess (the judge can override when enabled).
+function guessAction(e, now) {
+  if (e.source === "spaces") {
+    // Assigned work: if it's overdue/soon it likely needs a nudge to the
+    // assignee/owner; otherwise it's work to do.
+    if (e.overdue || (daysUntil(e.due, now) ?? 99) <= DUE_SOON_DAYS) return "ask";
+    return "act";
+  }
+  if (e.status === "in_progress") return "act";
+  const d = daysUntil(e.due, now);
+  if (d != null && d > DUE_SOON_DAYS) return "schedule";
+  return "act";
+}
+
+// --- default judge: cheap model, injectable, never fatal ----------------
+// Uses the low tier so it maps to Haiku (or the provider's cheapest). purpose
+// "recall" is reused only because it is the established cheap per-turn judgment
+// lane; spawnUtilityAgent does not log recall metrics, so nothing is polluted.
+async function defaultJudge(top, ctx) {
+  let spawnUtilityAgent;
+  try { ({ spawnUtilityAgent } = require("../utility-agent")); }
+  catch (e) { return null; }
+
+  const lines = top.map((c, i) =>
+    `${i + 1}. [${c.id}] (${c.source}) ${c.title} — signals: ${c.signals.map((s) => s.label).join(", ") || "none"}`,
+  ).join("\n");
+  const prompt = [
+    "You are triaging the assistant owner's work queue. Pick the SINGLE item to do next.",
+    "Prefer items that are overdue, unblock others, or are already in progress. Be decisive.",
+    "",
+    "Candidates:",
+    lines,
+    "",
+    'Reply with JSON only: {"pickId": "<id>", "actionType": "act|schedule|ask|park", "why": "<one short sentence>", "confidence": "high|medium|low"}',
+  ].join("\n");
+
+  const outputSchema = {
+    type: "object",
+    required: ["pickId", "actionType", "why"],
+    properties: {
+      pickId: { type: "string" },
+      actionType: { type: "string", enum: ACTIONS },
+      why: { type: "string" },
+      confidence: { type: "string", enum: ["high", "medium", "low"] },
+    },
+    additionalProperties: true,
+  };
+
+  try {
+    const r = await spawnUtilityAgent(prompt, {
+      purpose: "recall",
+      tier: "low",
+      readOnly: true,
+      allowedTools: [],
+      outputSchema,
+      timeoutMs: 30000,
+    });
+    if (r && r.ok && r.json && r.json.pickId) return r.json;
+  } catch (e) { /* fall through to deterministic */ }
+  return null;
+}
+
+// --- deliberate: the pipeline -------------------------------------------
+async function deliberate(ledger, opts = {}) {
+  const now = opts.now || (ledger && ledger.generatedAt) || Date.now();
+  const entries = (ledger && ledger.entries) || [];
+  const counts = (ledger && ledger.counts) || null;
+
+  const ranked = entries
+    .filter((e) => isCandidate(e, now))
+    .map((e) => ({ ...e, ...scoreOf(e, now) }))
+    .sort((a, b) => b.score - a.score);
+
+  const base = {
+    generatedAt: now,
+    proposed: false,
+    pick: null,
+    actionType: null,
+    why: [],
+    confidence: "low",
+    method: "deterministic",
+    candidateCount: ranked.length,
+    candidates: ranked.slice(0, TOP_N).map((c) => ({ id: c.id, source: c.source, title: c.title, score: Math.round(c.score) })),
+    counts,
+  };
+
+  if (!ranked.length || ranked[0].score < CONFIDENCE_FLOOR) return base;
+
+  const top = ranked.slice(0, TOP_N);
+  let pick = ranked[0];
+  let actionType = guessAction(pick, now);
+  let method = "deterministic";
+  let judgeWhy = null;
+  const margin = ranked.length > 1 ? ranked[0].score - ranked[1].score : Infinity;
+  let confidence = margin >= CLEAR_MARGIN ? "high" : "medium";
+
+  const useJudge = opts.useJudge === true && ranked.length > 1 && margin < CLEAR_MARGIN;
+  if (useJudge) {
+    const judge = opts.judge || defaultJudge;
+    let verdict = null;
+    try { verdict = await judge(top, { now }); } catch (e) { verdict = null; }
+    if (verdict && verdict.pickId) {
+      const chosen = top.find((c) => c.id === verdict.pickId);
+      if (chosen) {
+        pick = chosen;
+        if (ACTIONS.includes(verdict.actionType)) actionType = verdict.actionType;
+        if (verdict.why) judgeWhy = String(verdict.why);
+        if (["high", "medium", "low"].includes(verdict.confidence)) confidence = verdict.confidence;
+        method = "judge";
+      }
+    }
+  }
+
+  const why = pick.signals.filter((s) => s.w !== 0 || s.k === "context").map((s) => s.label);
+
+  return {
+    ...base,
+    proposed: true,
+    pick: {
+      id: pick.id, source: pick.source, kind: pick.kind, title: pick.title,
+      status: pick.status, due: pick.due, priority: pick.priority,
+      score: Math.round(pick.score), meta: pick.meta,
+    },
+    actionType,
+    why,
+    judgeWhy,
+    confidence,
+    method,
+  };
+}
+
+// --- shadow record: append one line per real deliberation ---------------
+function record(proposal, meta = {}) {
+  if (!shadowEnabled() || !proposal) return;
+  try {
+    const row = {
+      at: new Date().toISOString(),
+      proposed: !!proposal.proposed,
+      pickId: proposal.pick ? proposal.pick.id : null,
+      source: proposal.pick ? proposal.pick.source : null,
+      title: proposal.pick ? proposal.pick.title : null,
+      actionType: proposal.actionType || null,
+      confidence: proposal.confidence || null,
+      method: proposal.method || null,
+      score: proposal.pick ? proposal.pick.score : null,
+      candidateCount: proposal.candidateCount || 0,
+      channel: meta.channel || null,
+    };
+    try {
+      const st = fs.statSync(LOG_FILE);
+      if (st.size > MAX_LOG_BYTES) fs.renameSync(LOG_FILE, `${LOG_FILE}.1`);
+    } catch (e) {}
+    fs.appendFileSync(LOG_FILE, JSON.stringify(row) + "\n");
+  } catch (e) { /* best effort */ }
+}
+
+// --- render: advisory text (no action taken) ----------------------------
+const ACTION_VERB = {
+  act: "Do it now",
+  schedule: "Schedule it",
+  ask: "Nudge / ask",
+  park: "Park it",
+};
+
+function render(proposal) {
+  if (!proposal || !proposal.proposed) {
+    return "Nothing pressing to pick right now — nothing overdue, due soon, or in progress that clears the bar. 🟢";
+  }
+  const p = proposal.pick;
+  const conf = proposal.confidence ? ` · ${proposal.confidence} confidence` : "";
+  const via = proposal.method === "judge" ? " · judged" : "";
+  const lines = [];
+  lines.push(`Next up (advisory${conf}${via})`);
+  lines.push("─".repeat(18));
+  lines.push(`${p.title}`);
+  lines.push(`  ${ACTION_VERB[proposal.actionType] || proposal.actionType} · ${p.source}${p.id ? ` · ${p.id}` : ""}`);
+  if (proposal.judgeWhy) lines.push(`  Why: ${proposal.judgeWhy}`);
+  else if (proposal.why && proposal.why.length) lines.push(`  Why: ${proposal.why.join(" · ")}`);
+  if (proposal.candidateCount > 1) {
+    lines.push("");
+    lines.push(`Considered ${proposal.candidateCount}; runners-up:`);
+    for (const c of proposal.candidates.slice(1, 4)) lines.push(`  · ${c.title}  (${c.score})`);
+  }
+  lines.push("");
+  lines.push("Advisory only — I won't act on this without your go-ahead.");
+  return lines.join("\n");
+}
+
+module.exports = {
+  deliberate,
+  render,
+  record,
+  scoreOf,
+  isCandidate,
+  guessAction,
+  defaultJudge,
+  shadowEnabled,
+  LOG_FILE,
+  ACTIONS,
+  CONFIDENCE_FLOOR,
+  CLEAR_MARGIN,
+};