@inetafrica/open-claudia 3.5.71 → 3.5.73

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 3.5.73
+
+3.5.72 with a smaller bot image, from Sumeet's bot resource plan of 31 Oct. No code changes.
+
+- **One copy of the app in the image** (`Dockerfile`): files are copied in already owned by the bot user instead of being re-written by recursive chmod/chown, which stored /app three times.
+- **No leftover download caches**: each npm install clears its cache in the same step.
+- **One Claude install** that the bot user can run (npm into /usr/local), checked at build time; agent-browser keeps only its linux-x64 binary.
+
+## 3.5.72
+
+3.5.71 plus the memory fixes tested on Sumeet's Mac from 22 to 28 Oct, released to every bot on his card of 31 Oct ("Release to all bots now, without the Maia rename"). The Maia rename stays on the Mac.
+
+- **Topic lessons ride with their pack** (`core/dream.js`, `core/system-prompt.js`): a lesson tied to a pack loads when that pack does; the nightly dream reads the whole day, not only the last hours.
+- **Settings in .env reach the recall pins** (`core/config.js`, `core/recall/tuning.js`): an operator pin such as `RECALL_MIN_RELEVANCE_SCORE=55` in .env now holds, and the dream cannot move a pinned knob.
+- **Prompt fixes** (`core/system-prompt.js`, `core/help/background.md`, `core/session-core.js`, `core/providers/claude.js`): the tool named for a domain wins tool hints; foreground turns hide Claude Code's own timers and monitors (they die with the turn); the background section is 6.9k -> 1.5k chars with the full how-to in `open-claudia help background`; core instruction edits reach resumed sessions once; `CLAUDE_AUTO_MEMORY=off` turns Claude Code's own memory off.
+- **Past conversations reach recall** (`core/recall/query.js`, `core/transcript-index.js`).
+- **Settled decisions stay in memory** and show ahead of a long Stance (`core/packs.js`, `core/system-prompt.js`).
+- **/engine x and /engine mem0** (`core/recall/external.js`): owner-only per-room switch to an outside memory search (`RECALL_X_CMD` / `RECALL_MEM0_CMD`, timeout `RECALL_EXTERNAL_TIMEOUT_MS`, read from .env too); a timeout, error or empty answer falls back to the discoverer for that turn. Default engine unchanged (discoverer).
+- **Nightly introspection retries once after a stall** and says what stalled; `watch-add --every` must be a 5-field cron.
+
+Tests: new `test-topic-lessons.js`, `test-env-pins.js`, `test-session-core.js`, `test-transcript-related.js`, `test-pack-decisions.js`, `test-recall-external.js`, `test-introspection-retry.js`, `test-watch-every-cron.js`.
+
 ## 3.5.71
 
 3.5.70 plus a fix to its one-time effort reset, found during the 3.5.70 fleet roll on 20 Oct.

package/Dockerfile

@@ -1,15 +1,30 @@
 # Release image. The slow system layer (apt + chromium, ~250 packages) lives
 # in Dockerfile.base, published as the `:base` tag — rebuilt only when that
 # file changes. This build is minutes: fresh agent CLIs + app source.
+#
+# Size rules (each RUN's leftovers are baked into the image forever):
+#   - every npm install cleans its download cache in the SAME RUN;
+#   - /app is written once, already owned by claudia (COPY --chown, npm ci as
+#     claudia) — no recursive chmod/chown, which would store a second and
+#     third copy of every file in /app as new layers.
 ARG BASE_IMAGE=git.coders.africa:5050/kazee/agent-space/open-claudia:base
 FROM ${BASE_IMAGE}
 
-# Install Claude Code CLI
-RUN curl -fsSL https://claude.ai/install.sh | sh || \
-    npm install -g @anthropic-ai/claude-code
+# Claude Code CLI, one install: the npm global in /usr/local, which is on PATH
+# and readable for the runtime user (1001, HOME=/data). This is the copy pods
+# were already running (/usr/local/bin/claude -> /usr/local/lib/node_modules/
+# @anthropic-ai/claude-code/bin/claude.exe). The old `claude.ai/install.sh | sh`
+# step ran as root and installs into /root/.local, which user 1001 can neither
+# see on PATH nor read — whenever it succeeded, `claude` would be missing in the
+# pod. The postinstall hardlinks the native binary over the bin/claude.exe stub;
+# the size check fails the build if only the stub is left.
+RUN npm install -g @anthropic-ai/claude-code \
+    && test "$(stat -c %s "$(readlink -f /usr/local/bin/claude)")" -gt 1000000 \
+    && npm cache clean --force && rm -rf /root/.npm /tmp/*
 
 # Install OpenAI Codex CLI for the codex backend (unpinned: each image build bakes the then-latest CLI)
-RUN npm install -g @openai/codex
+RUN npm install -g @openai/codex \
+    && npm cache clean --force && rm -rf /root/.npm /tmp/*
 
 # Browser automation for the agent: vercel-labs agent-browser (Rust CLI, token-efficient,
 # replaces Playwright MCP). Installed at build time as root so the non-root runtime user
@@ -17,31 +32,44 @@ RUN npm install -g @openai/codex
 # lives outside the /data VOLUME (build-time writes to /data are discarded at runtime).
 # Pinned: the live Browser view (core/browser-view.js) reads its session files and its
 # screen-stream protocol, which 0.38.x has (built-in stream per session, .stream port files).
-RUN npm install -g agent-browser@0.38.2
+# The package ships a prebuilt binary for every platform (~15-18 MB each); its postinstall
+# points /usr/local/bin/agent-browser at the one for this machine (glibc Linux), so the
+# other six are deleted here.
+RUN npm install -g agent-browser@0.38.2 \
+    && cd "$(npm root -g)/agent-browser/bin" \
+    && keep="agent-browser-linux-$(node -p process.arch)" \
+    && test -x "$keep" \
+    && find . -maxdepth 1 -type f -name 'agent-browser-*' ! -name "$keep" -delete \
+    && case "$(readlink -f /usr/local/bin/agent-browser)" in \
+         "$(pwd -P)/$keep"|"$(pwd -P)/agent-browser.js") ;; \
+         *) echo "agent-browser on PATH points somewhere unexpected" >&2; exit 1 ;; \
+       esac \
+    && npm cache clean --force && rm -rf /root/.npm /tmp/*
 ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium
 
-# Create app directory
+# Create app directory, owned by the runtime user so it can overlay new source
+# into /app for in-place /upgrade (core/handlers.js inPlaceTarballUpgrade).
 WORKDIR /app
+RUN chown claudia:claudia /app
 
-# Copy package files and install
-COPY package*.json ./
-RUN npm ci --production
+# Copy package files and install as claudia, so node_modules is claudia's
+# without a chown pass. The npm cache goes to a scratch dir removed in the same
+# RUN (nothing lands in /root/.npm or /data/.npm).
+COPY --chown=claudia:claudia package*.json ./
+USER claudia
+RUN npm ci --omit=dev --no-audit --no-fund --cache /tmp/oc-npm-cache \
+    && rm -rf /tmp/oc-npm-cache
 
-# Copy app source
-COPY . .
-
-# Ensure app files are readable regardless of host file perms
-RUN chmod -R a+rX /app
+# Copy app source (already claudia's: in-place /upgrade overlays it)
+COPY --chown=claudia:claudia . .
+USER root
 
 # Expose the open-claudia CLI on PATH so spawned agents can send files, manage tasks, etc.
-RUN chmod +x /app/bin/cli.js && ln -s /app/bin/cli.js /usr/local/bin/open-claudia
-
-# Let the runtime user overlay new source into /app for in-place /upgrade.
-RUN chown -R claudia:claudia /app
-
-# Entrypoint auto-configures from env vars on first run
+# Only the two scripts that must be executable are chmod'ed (git tracks both as 755;
+# this keeps it true for checkouts that lost the bit) — not a recursive pass over /app.
 COPY docker-entrypoint.sh /usr/local/bin/
-RUN chmod +x /usr/local/bin/docker-entrypoint.sh
+RUN chmod 755 /app/bin/cli.js /usr/local/bin/docker-entrypoint.sh \
+    && ln -s /app/bin/cli.js /usr/local/bin/open-claudia
 
 # Set up data directory ownership
 RUN mkdir -p /data/Workspace /data/.open-claudia /data/.claude && \

package/README.md

@@ -177,7 +177,7 @@ When you select a project, the last conversation is automatically resumed. Tap "
 |---------|-------------|
 | `/learn [<hint>]` | Capture the last piece of work into the matching context pack |
 | `/skills [show\|remove <name>]` | List, show, or remove legacy learned skills |
-| `/engine [classic\|discoverer]` | Switch the per-chat memory recall engine (default `discoverer`) |
+| `/engine [discoverer\|x\|mem0\|classic\|ask]` | Switch the per-chat memory recall engine (default `discoverer`; `x`/`mem0` run an external memory search, set by `RECALL_X_CMD`/`RECALL_MEM0_CMD`, and fall back to the discoverer on timeout, error or empty output) |
 | `/recall [on\|off]` | Toggle a per-turn "🧠 Recall this turn" debug line showing which packs/entities surfaced (and why, on discoverer) |
 | `/soul` | View/edit assistant identity and personality |
 | `/dreamsummary [on\|off]` | Toggle the post-dream memory summary in chat |

package/bin/cli.js

@@ -612,6 +612,13 @@ switch (command) {
     break;
   }
 
+  case "help": {
+    // Long how-tos live here, out of the always-loaded instructions.
+    const topic = String(args[1] || "").replace(/[^a-z-]/g, "");
+    const file = topic && path.join(botDir, "core", "help", `${topic}.md`);
+    if (file && fs.existsSync(file)) { process.stdout.write(fs.readFileSync(file, "utf8")); break; }
+  }
+  // falls through to the usage text
   default:
     console.log(`
 Open Claudia — AI Coding Assistant via Telegram

package/bin/schedule.js

@@ -184,6 +184,12 @@ async function runCronRemove(args) {
   } catch (e) { console.error(e.message); process.exit(1); }
 }
 
+// A duration such as "5m" here once left watches that never polled.
+function isFiveFieldCron(value) {
+  const fields = String(value).trim().split(/\s+/);
+  return fields.length === 5 && require("node-cron").validate(fields.join(" "));
+}
+
 async function runWatchAdd(args) {
   if (args.length < 2 || args[0] === "--help") { console.log(HELP); process.exit(args[0] === "--help" ? 0 : 2); }
   const rest = args.slice();
@@ -202,6 +208,10 @@ async function runWatchAdd(args) {
       process.exit(2);
     }
   }
+  if (schedule !== null && !isFiveFieldCron(schedule)) {
+    console.error(`--every needs a 5-field cron such as "*/5 * * * *" (every 5 minutes), not "${schedule}".`);
+    process.exit(2);
+  }
   const check = rest[0];
   const prompt = rest.slice(1).join(" ");
   if (!check || !prompt) { console.error("Usage: watch-add \"<check-cmd>\" \"<wake-prompt>\" [--every \"<cron>\"] [--repeat] [--timeout <when>]"); process.exit(2); }

package/core/actions.js

@@ -469,6 +469,7 @@ async function handleAction(envelope) {
   if (d.startsWith("eng:")) {
     const v = d.slice(4);
     const recall = require("./recall");
+    if (recall.OWNER_ONLY_ENGINES.includes(v) && !isChatOwner(envelope.channelId)) return send(`Owner only — the ${v} engine runs a local command.`);
     // The default engine is stored as null (so it shows "(default)"); any other
     // known engine is stored explicitly as an opt-out.
     state.settings.recallEngine = (v === recall.DEFAULT_ENGINE || !recall.listEngines().includes(v)) ? null : v;

package/core/config.js

@@ -43,6 +43,16 @@ function saveEnvKey(key, value) {
 
 const config = loadEnv();
 
+// One setting from the process env or, failing that, the bot's .env file.
+// loadEnv() returns a merged object and never writes process.env, so code that
+// reads process.env directly (operator pins, BOT_NAME) misses .env-only keys.
+function settingValue(key) {
+  const live = process.env[key];
+  if (live !== undefined && live !== "") return live;
+  const fromFile = config[key];
+  return fromFile === undefined || fromFile === "" ? undefined : fromFile;
+}
+
 function hasPathSeparator(value) {
   return value.includes("/") || value.includes("\\");
 }
@@ -367,6 +377,7 @@ function agentEnvSource() {
 
 module.exports = {
   config,
+  settingValue,
   parseEnvText,
   loadEnv,
   saveEnvKey,

package/core/day-seeds.js

@@ -16,8 +16,9 @@ const CONFIG_DIR = require("../config-dir");
 
 const SEEDS_DIR = process.env.DAY_SEEDS_DIR ? path.resolve(process.env.DAY_SEEDS_DIR) : path.join(CONFIG_DIR, "seeds");
 // Safety cap on a single day's file; if exceeded we trim from the front so the
-// most recent compactions always survive.
-const MAX_DAY_SEED_CHARS = Number(process.env.DAY_SEED_MAX_CHARS || 60000);
+// most recent compactions always survive. A busy day holds ~50 compactions of
+// ~4k chars each; at the old 60k cap every day lost its morning by evening.
+const MAX_DAY_SEED_CHARS = Number(process.env.DAY_SEED_MAX_CHARS || 400000);
 
 // Local calendar day (YYYY-MM-DD). Local, not UTC, so "what I worked on today"
 // lines up with the user's day and the 4am dream reads the right file.
@@ -91,8 +92,27 @@ function recentDaySeeds({ days = 2 } = {}) {
   return { dates: picked, text: texts.join("\n\n") };
 }
 
+// A whole-day view inside a char budget: every compaction keeps its time,
+// project and the head of its digest, so the reader sees the morning as well
+// as the evening instead of whichever end a plain cut keeps.
+function digestDaySeeds(text, budget = 30000) {
+  const t = String(text || "");
+  if (t.length <= budget) return t;
+  const parts = t.split(/\n(?=## \d{4}-\d{2}-\d{2}T)/).filter((p) => /^## \d{4}-/.test(p.trim()));
+  if (parts.length === 0) return t.slice(0, budget);
+  const share = Math.max(200, Math.floor(budget / parts.length) - 2);
+  const out = parts.map((p) => {
+    const lines = p.trim().split("\n");
+    const head = [lines[0], ...lines.slice(1).filter((l) => l.startsWith("Project: "))].join("\n");
+    const body = lines.slice(1).filter((l) => !/^(Project|Channel|Full brief): /.test(l)).join("\n").trim();
+    const room = Math.max(0, share - head.length - 1);
+    return `${head}\n${body.length > room ? body.slice(0, room) + "…" : body}`;
+  });
+  return out.join("\n\n").slice(0, budget);
+}
+
 module.exports = {
-  SEEDS_DIR, MAX_DAY_SEED_CHARS,
+  SEEDS_DIR, MAX_DAY_SEED_CHARS, digestDaySeeds,
   dayStamp, daySeedPath,
   appendDaySeed, readDaySeed, listDaySeedDates, recentDaySeeds,
 };

package/core/dream.js

@@ -270,6 +270,7 @@ function buildDreamPrompt({ sinceTs = null, fullSweep = true, clusters = [], evi
     `Stance${packs.provenanceOf(p.dir, "Stance") === "user" ? " (USER-AUTHORED — do not rewrite)" : ""}: ${p.sections.Stance}`,
     `Procedure: ${p.sections.Procedure}`,
     `State: ${p.sections.State}`,
+    ...(p.sections.Decisions ? [`Decisions (append-only, carried on merge):\n${p.sections.Decisions}`] : []),
     `Journal:\n${p.sections.Journal}`,
   ].join("\n"), MAX_PACK_CHARS)).join("\n\n") || "(none)";
 
@@ -503,11 +504,14 @@ function applyDream(decision, backupRoot) {
         continue;
       }
       const fromJournals = from.map((d) => packs.readPack(d).sections.Journal || "");
+      // Settled decisions of absorbed packs move to the survivor verbatim.
+      const fromDecisions = from.flatMap((d) => String(packs.readPack(d).sections.Decisions || "").split("\n").filter((l) => l.trim()));
       const mr = packs.updatePack(m.into, {
         stance: typeof m.stance === "string" ? m.stance : "",
         procedure: typeof m.procedure === "string" ? m.procedure : "",
         state: typeof m.state === "string" ? m.state : "",
         journal: m.journal || `absorbed ${from.join(", ")}`,
+        decisions: fromDecisions,
       }, "dream");
       const ju = packs.unionJournals(m.into, fromJournals);
       for (const d of from) {
@@ -739,7 +743,8 @@ function buildIntrospectionPrompt() {
 Today: ${new Date().toISOString().slice(0, 10)}
 
 ═══ WHAT YOU WORKED ON (compaction digests of the day's conversations) ═══
-${clip(seedText, 14000)}
+${seeds.text.trim() ? daySeeds.digestDaySeeds(seedText, 30000) : seedText}
+(Each compaction above is cut to its opening lines; the full digests are in ${daySeeds.SEEDS_DIR}/<date>.md.)
 
 ═══ YOUR CURRENT SELF ═══
 Persona (your voice):
@@ -792,6 +797,19 @@ When done investigating, reply with ONLY this JSON (no prose, no code fences):
  "report": "<first-person chat message>"}`;
 }
 
+// Introspection stalls on some nights: the 12-minute cap hits with almost
+// nothing spent, while finished runs take 3-6 minutes. One timeout gets one
+// fresh run; a used-up limit or any other failure is not repeated.
+async function runIntrospectionWithRetry(runUtility, prompt, options, { log = console.warn } = {}) {
+  try {
+    return await runUtility(prompt, options);
+  } catch (e) {
+    if (e?.code !== "UTILITY_TIMEOUT") throw e;
+    log(`[dream] introspection timed out, retrying once: ${e.message}`);
+    return runUtility(prompt, options);
+  }
+}
+
 function parseIntrospection(text) {
   const raw = String(text || "").trim().replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "");
   const start = raw.indexOf("{");
@@ -1330,7 +1348,7 @@ async function runDreamMutation({ trigger = "manual", provider = null, runUtilit
     // A used-up limit stops this step too: it runs with the dream after the reset.
     if (introspectEnabled() && !limitWait) {
       try {
-        const introRun = await runUtility(buildIntrospectionPrompt(), dreamUtilityOptions("introspection", {
+        const introRun = await runIntrospectionWithRetry(runUtility, buildIntrospectionPrompt(), dreamUtilityOptions("introspection", {
           provider,
           cwd: CODE_ROOT,
           additionalReadOnlyDirectories: [CONFIG_DIR],
@@ -1822,7 +1840,7 @@ function initDream(adapters, deps = {}) {
 
 module.exports = {
   createDreamService, previewDream, runDream, initDream, buildDreamPrompt, parseDream, applyDream, manageAbilityTiers, nestPrefixFamilies, dreamTimeoutMs,
-  buildIntrospectionPrompt, parseIntrospection, applyIntrospection, writeDreamReport,
+  buildIntrospectionPrompt, parseIntrospection, applyIntrospection, writeDreamReport, runIntrospectionWithRetry,
   summaryDelta, healthOf, mergeClusters, selectDumpDirs, journalBackfillDedupe, staleTaskReport,
   dreamSummaryTarget, runScheduledDream, dreamOverdue, createDreamCatchUp, DREAM_CATCHUP_MS,
   createDreamLimitWait, dreamLimitWait, dreamFailNote, DREAM_LIMIT_MAX_WAITS,

package/core/handlers.js

@@ -1287,7 +1287,7 @@ register({
 });
 
 register({
-  name: "engine", description: "Switch memory recall engine", args: "[classic|discoverer|ask]",
+  name: "engine", description: "Switch memory recall engine", args: "[discoverer|x|mem0|classic|ask]",
   handler: async (env, { tail }) => {
     if (!authorized(env)) return;
     const { settings } = currentState();
@@ -1295,6 +1295,7 @@ register({
     const active = recall.activeEngineName(settings);
     if (tail) {
       const v = tail.trim().toLowerCase();
+      if (recall.OWNER_ONLY_ENGINES.includes(v) && !ownerEnv(env)) return send(`Owner only — the ${v} engine runs a local command.`);
       if (v === "default" || v === recall.DEFAULT_ENGINE) settings.recallEngine = null;
       else if (recall.listEngines().includes(v)) settings.recallEngine = v;
       else return send(`Unknown engine "${v}". Options: ${recall.listEngines().join(", ")}.`);
@@ -1305,9 +1306,12 @@ register({
       `Recall engine: ${active}${settings.recallEngine ? "" : " (default)"}\n\n` +
       "• discoverer — typed-edge graph + spreading activation + why-bullets (default)\n" +
       "• classic — keyword FTS + relevance judge (opt-out fallback)\n" +
-      "• ask — nothing auto-injected; I pull my own notes on demand and say so",
+      "• ask — nothing auto-injected; I pull my own notes on demand and say so\n" +
+      "• x — experimental: X memory facts search (falls back to discoverer)\n" +
+      "• mem0 — experimental: Mem0 search (falls back to discoverer)",
       { keyboard: { inline_keyboard: [
         [{ text: "Discoverer (default)", callback_data: "eng:discoverer" }, { text: "Classic", callback_data: "eng:classic" }],
+        [{ text: "X", callback_data: "eng:x" }, { text: "Mem0", callback_data: "eng:mem0" }],
         [{ text: "Ask (on-demand)", callback_data: "eng:ask" }],
       ] } },
     );

package/core/help/background.md

@@ -0,0 +1,51 @@
+## Background work
+You can persist work across turns and wake yourself up later. These survive bot restarts.
+
+Wake-ups and crons (real schedulers, not hallucinations — use them instead of saying "I'll check back later"):
+- `open-claudia schedule-wakeup <when> "<prompt>"` — one-shot. `<when>` is a duration like `30s`/`5m`/`2h`/`1d` or an ISO datetime. When it fires you wake up in this same conversation with the prompt as if the user typed it.
+- `open-claudia cron-add "<5-field cron>" "<prompt>"` — recurring.
+- `open-claudia cron-list` — list all wakeups + crons on this channel.
+- `open-claudia cron-remove <id>` — cancel one.
+
+Watches (a silent background monitor — poll a condition WITHOUT waking every tick; wake only when it actually happens). Use this instead of a minute-by-minute cron whenever you'd otherwise fire a turn just to check "is it done yet?" and stay quiet most times:
+- `open-claudia watch-add "<check-cmd>" "<wake-prompt>"` — the scheduler polls `<check-cmd>` as a shell command (default every minute). The poll is SILENT: nothing reaches the chat while the check keeps failing. The instant `<check-cmd>` exits 0, you wake in this same conversation with `<wake-prompt>`, exactly like a wakeup. Non-zero exit = still waiting = nothing happens. Default is ONE-SHOT (fires once, then removes itself); add `--repeat` to keep polling after each hit. `--every "<5-field cron>"` changes the poll cadence.
+- Every watch has a hard timeout — `--timeout <duration|ISO>` (default 2h). A watch that reaches its timeout without the check ever passing FIRES anyway on the next poll, with the prompt marked "Watch expired" so you know the condition did NOT happen. No watch can end silently, so you no longer need a separate backup wakeup for every watch — but size `--timeout` honestly to the work being watched.
+- `open-claudia watch-list` / `open-claudia watch-remove <id>` — inspect/cancel watches on this channel.
+- The owner has a global master switch: `/watch off` pauses ALL watch polling (and `/watch on` resumes). If `watch-list` shows the switch OFF, watches won't fire until it's back on.
+- Example: after kicking off a long external job, `open-claudia watch-add "test -f /tmp/build-done || exit 1" "the build finished — verify and report"` beats a wakeup guess, because it fires the moment it's actually done, not on a fixed timer. (Never use a watch to poll harness-tracked work you started — that notifies you automatically. Watches are for EXTERNAL state the harness can't see.)
+
+The selected coding-agent provider may expose native scheduling tools. Do NOT use those for Open Claudia wakeups or crons: a provider runs as a per-turn subprocess, so its timers do not belong to the long-running bot. Only the `open-claudia` CLI commands above are authoritative and survive.
+
+Persistent todo list with plans + subtasks (per channel; survives compaction and restart).
+
+Any provider-native reminder about task or plan tools refers to a separate, ephemeral todo system. Open Claudia work belongs in `open-claudia task` (the persistent, channel-scoped one). Do not double-track.
+
+Use a plan when work is likely to outlive a single turn — i.e. it may hit a compaction, a restart, or a scheduled wakeup before completing, or its progress is something the user will want to see between turns. The plan is a parent task whose children are the steps. As you work, mark each subtask in_progress when you begin and completed when done — this is how a resumed turn sees where you left off. Completed means removed: `task done` deletes the entry, and finishing the last subtask deletes the whole plan. The list only ever contains remaining work. The full pending tree is injected into the Runtime state block once per session (first turn after restart/compaction); later turns show just a count — run `open-claudia task list` when you need the tree again.
+
+Skip the plan for work that visibly completes within the current turn (e.g. running a few CLI commands in sequence and replying). A plan there is overhead the user has to read past.
+
+- `open-claudia task plan "<plan title>" "<step 1>" "<step 2>" "<step 3>" [--description "<why / success criteria>"]` — atomic create
+- `open-claudia task add "<content>" [--parent <plan-id>] [--description "..."]` — add a single task or subtask
+- `open-claudia task list` — renders as a tree
+- `open-claudia task start <id>` / `task done <id>` (completes AND removes; finishing the last subtask removes the plan) / `task remove <id>` (removing a plan removes its subtasks)
+
+For one-off work under 3 steps, skip the plan and just track it in your own response.
+
+Cross-channel relay (talk to other team members on their primary channel — see Team block above for names):
+- `open-claudia send-to --person "<name>" "<message>"` — sends to that person's primary channel.
+- `open-claudia send-to --adapter <type> --channel <id> "<message>"` — explicit channel target.
+- Be honest about provenance. If you are forwarding on someone's behalf, prefix the message: "From <speaker name>: ...". If you are reaching out autonomously (cron, wakeup, your own judgement), prefix with "Open Claudia: ...".
+- Use sparingly — every relay is logged to the audit trail. Don't message people unprompted unless the user asked you to or the context obviously calls for it.
+
+Thread hand-off (Kazee Chat, owner only — move work to another thread and wake it there):
+- `open-claudia handoff --thread <threadId> "<message>" [--chat <chatId>] [--title "<label>"]` — posts the message in that thread (visibly, as you, marked as a hand-off from this thread) and wakes that thread's conversation to start work on it now; it waits behind a turn already running there. `--chat` defaults to this chat.
+- Use it when the user asks for work to move to, or continue in, another thread. A thread's id is the part after `#thread:` in its conversation key (`transcript-search --all` hits show the key). The woken thread is told how to hand back. Refused on a non-owner's turn, into the thread you are in, and after 3 hand-offs in a row with no person writing in between.
+
+Recent activity lookup (read other chats' transcripts on demand — don't try to carry everything in context):
+- `open-claudia recent --person "<name>" [--limit 20]`
+- `open-claudia recent --adapter <type> --channel <id> [--limit 20]`
+
+People management (owner-only commands; safe to call to inspect):
+- `open-claudia people list` / `people show <id-or-name>` — read-only, anyone can call.
+- `open-claudia people note <id-or-name> "<note>"` — record something the team should remember.
+- `open-claudia intros list` / `intros approve <id>` / `intros reject <id>` — owner-gated.

package/core/lessons.js

@@ -175,6 +175,33 @@ function injectedLessons() {
   return out;
 }
 
+// Lessons tied to one topic (their src names the pack) that the always-loaded
+// block did not carry. The char budget keeps that block to the most
+// reinforced few, so most lessons would otherwise never reach a turn; they
+// ride along with their pack when its topic comes up instead.
+function topicLessons(dir, { exclude = null, max = 3, maxChars = 900 } = {}) {
+  if (!dir) return [];
+  const lessons = readLessons().filter((l) => l.src === dir);
+  if (lessons.length === 0) return [];
+  const skip = exclude || new Set(injectedLessons().map((l) => l.id));
+  const meta = reconcileMeta(lessons);
+  const ranked = lessons.filter((l) => !skip.has(l.id)).sort((a, b) => {
+    const ma = meta[a.id] || {}, mb = meta[b.id] || {};
+    return (mb.reinforced || 0) - (ma.reinforced || 0)
+      || String(mb.created || "").localeCompare(String(ma.created || ""));
+  });
+  const out = [];
+  let used = 0;
+  for (const l of ranked) {
+    if (out.length >= max) break;
+    const line = `- ${l.text}`;
+    if (used + line.length + 1 > maxChars) continue;
+    out.push({ ...l, ...(meta[l.id] || {}) });
+    used += line.length + 1;
+  }
+  return out;
+}
+
 // Add or reinforce a lesson. Dedupe is by normalized text (id), so the same
 // fact phrased the same way reinforces instead of duplicating. No eviction
 // here — the char budget bounds injection and dream enforces the count cap
@@ -277,7 +304,7 @@ module.exports = {
   LESSONS_FILE, LESSONS_META_FILE,
   MAX_LESSONS, MAX_LESSON_CHARS, MAX_LESSONS_CHARS,
   normalize, lessonId, parseLessons,
-  readLessons, listLessons, loadLessonsBlock, injectedLessons, lessonLine,
+  readLessons, listLessons, loadLessonsBlock, injectedLessons, topicLessons, lessonLine,
   readMeta, writeMeta, reconcileMeta,
   addLesson, editLesson, removeLesson, saveLessonsRaw, lessonsExist,
 };

package/core/pack-guard.js

@@ -76,7 +76,7 @@ function scanForInjection(text, { strict = true } = {}) {
 // Scan the sections of a pending pack write. Strict on the auto-injected
 // sections, lenient on Journal. Returns the first hit, or { flagged: false }.
 function scanSections(sections = {}) {
-  const strictKeys = ["stance", "procedure", "state", "description"];
+  const strictKeys = ["stance", "procedure", "state", "decisions", "description"];
   for (const key of strictKeys) {
     const r = scanForInjection(sections[key], { strict: true });
     if (r.flagged) return { ...r, section: key };

package/core/pack-review.js

@@ -94,10 +94,12 @@ function renderActivePacks(activePacks) {
     if (stateTxt) {
       const words = stateTxt.split(/\s+/).length;
       const budget = words > 150
-        ? ` — OVER BUDGET: this State must come back under 150 words; tighten wording and drop completed/stale detail (never true facts this turn didn't mention)`
+        ? ` — OVER BUDGET: this State must come back under 150 words; tighten wording and drop completed/stale detail (never true facts this turn didn't mention; a settled decision moves to "decisions", never just dropped)`
         : "; target 150";
       parts.push(`State (current, ${words} words${budget}):\n${clip(stateTxt, ACTIVE_SECTION_CHARS)}`);
     }
+    const decided = String(sec.Decisions || "").trim();
+    if (decided) parts.push(`Decisions (settled, append-only):\n${clip(decided, ACTIVE_SECTION_CHARS)}`);
     if (journal) parts.push(`Journal (recent):\n${journal}`);
     blocks.push(parts.join("\n"));
   }
@@ -159,8 +161,9 @@ function buildReviewPrompt(userText, assistantText, activePacks, denyBlock) {
 A context pack is a living document about ONE topic (a project, a system, a recurring task, a domain). It has four sections:
 - Stance: how to think about the topic — preferences, framing, hard rules the user has expressed.
 - Procedure: verified how-to steps and commands.
-- State: where work on the topic stands NOW — decisions made, open questions, next steps. Replaces wholesale.
-- Journal: one-line dated log of what happened each session.
+- State: where work on the topic stands NOW — open questions, next steps, current status. Replaces wholesale every time, so it is NOT a safe home for anything that must last.
+- Decisions: settled facts the user decided or confirmed — dates, deadlines, prices, numbers, choices, owners, yes/no answers — one dated line each. Append-only: lines are never rewritten or dropped.
+- Journal: one-line dated log of what happened each session (only the last 30 lines are kept).
 
 An entity note is a short memory file about ONE specific named entity — a person, place, project, org, or system. It has:
 - Notes: current truth about the entity (who/what it is, role, preferences, relationships). Replaces wholesale.
@@ -213,6 +216,7 @@ Decide. Rules:
 - State/Stance/Procedure rewrites are MERGES, never regenerations: start from the pack's CURRENT content shown in the ACTIVE block above, carry forward every fact that is still true, drop only what this turn contradicted or completed, then fold in what changed. Never drop a durable fact merely because this turn did not mention it. If a pack's current content is NOT shown above, do not rewrite its sections — record a journal line only (section rewrites there are discarded).
 - LOCKED lines: a Stance line containing the word LOCKED is a constraint the user explicitly froze. NEVER weaken, reword, or drop a LOCKED line in a stance rewrite — carry it forward verbatim — unless THIS turn shows the user explicitly unlocking or changing it. COMPLIANCE CHECK: compare the assistant's reply against every LOCKED line in the ACTIVE packs above; if the reply violated one (did what the line forbids, or contradicted the locked choice), append a journal line on that pack recording it, e.g. "VIOLATION: reply used <X> where Stance locks <Y>." — violations must become visible, never silently absorbed.
 - UPDATE an existing pack when the turn touched that topic: append a journal line, and rewrite State if where-things-stand changed. Update Stance when the user expressed a lasting preference or rule; Procedure when a verified working method emerged.
+- DECISIONS: whenever the turn shows the user settling something — choosing an option, answering a decision card, fixing a date or deadline, setting a price, number, limit or owner — add ONE line per decision to that pack action's "decisions" array. Write it so it stands alone months later: who, when, and the exact values in the user's own terms (e.g. "Sumeet 7 Oct (card D-01): launch dates are dogfood 13 Nov 2026, private beta 4 Dec 2026, public launch 1 Feb 2027"). Include it even if State or the Journal also mentions it. Skip a decision already listed in the pack's Decisions above; if the user CHANGED an earlier decision, add the new one and say what it replaces. Decisions may be added to ANY pack, active or not. No settled decision in the turn → omit "decisions".
 - PROMOTE durable conclusions out of the Journal. A confirmed root-cause diagnosis, an established fact, or a settled design decision must go into Stance/Procedure/State (the parts always injected in full), NOT only a Journal line — Journal is truncated to the last few lines on injection, so a conclusion left only there will silently fall out of recall over time.
 - CREATE a pack ONLY when the turn worked on a durable topic that NO existing pack covers. Before creating, scan the existing packs above for one already about this project/system/domain — if one exists, UPDATE it instead. A new pack must be a genuinely DISTINCT topic, never a narrower facet, version, release, sub-feature, phase, or component of a topic an existing pack already owns. In particular: a release or version of a project (e.g. a pack named after "<project> v2.6.39") is a Journal line + State update on that project's EXISTING pack — NEVER its own pack. Likewise sub-features of one system belong in that system's pack, not in siblings. When unsure whether something is a new topic or a facet of an existing one, treat it as a facet and UPDATE. Do not create packs for one-off trivia.
 - ABILITY vs CONTEXT: most creates are context packs (a project/system tracker). Create an ability (kind:"ability") only for a genuinely reusable how-to as defined above, and always set learned_on + applied_on to the originating project dir. When a turn re-used an EXISTING ability on a NEW project, do NOT create anything — UPDATE that ability and put the new project dir in "applied_on" so the cross-project reuse is recorded.
@@ -227,8 +231,8 @@ Decide. Rules:
 
 Reply with ONLY a JSON object, no prose, no code fences:
 {"actions": [
-  {"action": "update", "pack": "<existing dir>", "journal": "<one sentence>", "subst": <0-10>, "state": "<full new State or null>", "stance": null, "procedure": null, "applied_on": ["<project dir, ONLY when this turn re-applied an existing ability to a new project>"]}
-  | {"action": "create", "dir": "<kebab-slug>", "name": "<title>", "description": "<one line: when this pack is relevant>", "tags": ["..."], "kind": "context|ability", "learned_on": "<originating project dir — abilities only>", "applied_on": ["<project dirs — abilities only>"], "stance": "<or empty>", "procedure": "<or empty>", "state": "<where things stand>", "journal": "<one sentence>", "subst": <0-10>}
+  {"action": "update", "pack": "<existing dir>", "journal": "<one sentence>", "subst": <0-10>, "state": "<full new State or null>", "decisions": ["<one settled decision per line, only when the turn settled one>"], "stance": null, "procedure": null, "applied_on": ["<project dir, ONLY when this turn re-applied an existing ability to a new project>"]}
+  | {"action": "create", "dir": "<kebab-slug>", "name": "<title>", "description": "<one line: when this pack is relevant>", "tags": ["..."], "kind": "context|ability", "learned_on": "<originating project dir — abilities only>", "applied_on": ["<project dirs — abilities only>"], "stance": "<or empty>", "procedure": "<or empty>", "state": "<where things stand>", "decisions": ["<settled decisions, if any>"], "journal": "<one sentence>", "subst": <0-10>}
 ],
 "entities": [
   {"name": "<canonical name>", "type": "person|place|project|org|system|thing", "aliases": ["..."], "description": "<one line: who/what this is>", "notes": "<full new Notes or null>", "log": "<one sentence observation>", "role": "<people only, or null>", "style": "<people only: how to talk to them, or null>", "knows": "<people only: what to assume they know, or null>"}
@@ -260,6 +264,7 @@ function guardCheck(a) {
     stance: a.stance,
     procedure: a.procedure,
     state: a.state,
+    decisions: Array.isArray(a.decisions) ? a.decisions.join("\n") : a.decisions,
     description: a.description,
     journal: a.journal,
   });
@@ -291,6 +296,14 @@ function findDuplicatePack({ dir, name, description, tags }) {
   return null;
 }
 
+const MAX_DECISIONS_PER_ACTION = 5;
+
+function decisionLines(a) {
+  return [].concat(a && a.decisions || [])
+    .filter((d) => typeof d === "string" && d.trim())
+    .slice(0, MAX_DECISIONS_PER_ACTION);
+}
+
 function applyAction(a, activeSet = null) {
   if (!a || typeof a !== "object") return null;
   const guard = guardCheck(a);
@@ -311,7 +324,10 @@ function applyAction(a, activeSet = null) {
     // and would destroy durable facts. Journal lines always land; section
     // rewrites are dropped for packs outside the active set.
     const blind = activeSet instanceof Set && !activeSet.has(a.pack);
+    // Decisions are append-only, so unlike section rewrites they are safe on
+    // a pack the reviewer did not see in full.
     const r = packs.updatePack(a.pack, {
+      decisions: decisionLines(a),
       journal: journalLine,
       state: !blind && typeof a.state === "string" ? a.state : "",
       stance: !blind && typeof a.stance === "string" ? a.stance : "",
@@ -346,7 +362,7 @@ function applyAction(a, activeSet = null) {
     const projects = applied_on.length ? applied_on : (learned_on ? [learned_on] : []);
     if (packs.readPack(dir)) {
       const blind = activeSet instanceof Set && !activeSet.has(dir);
-      packs.updatePack(dir, { journal: journalLine, state: blind ? "" : (a.state || "") }, "reviewer");
+      packs.updatePack(dir, { decisions: decisionLines(a), journal: journalLine, state: blind ? "" : (a.state || "") }, "reviewer");
       if (kind === "ability") for (const proj of projects) packs.recordApplied(dir, proj);
       return { kind: "update", dir, name: a.name || dir, note: a.journal || "state updated" };
     }
@@ -356,7 +372,7 @@ function applyAction(a, activeSet = null) {
     const dupeDir = kind === "context" ? findDuplicatePack({ dir, name: a.name, description: a.description, tags: a.tags }) : null;
     if (dupeDir && packs.readPack(dupeDir)) {
       const blind = activeSet instanceof Set && !activeSet.has(dupeDir);
-      packs.updatePack(dupeDir, { journal: journalLine, state: blind ? "" : (a.state || "") }, "reviewer");
+      packs.updatePack(dupeDir, { decisions: decisionLines(a), journal: journalLine, state: blind ? "" : (a.state || "") }, "reviewer");
       const ex = packs.readPack(dupeDir);
       return { kind: "update", dir: dupeDir, name: (ex && ex.name) || dupeDir, note: a.journal || "folded a new-pack proposal into the existing pack" };
     }
@@ -376,6 +392,7 @@ function applyAction(a, activeSet = null) {
       stance: a.stance || "",
       procedure: a.procedure || "",
       state: a.state || "",
+      decisions: decisionLines(a),
       journal: journalLine,
       kind,
       learned_on: kind === "ability" ? learned_on : "",