@inetafrica/open-claudia 2.8.0 → 2.9.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v2.9.1
+- **Post-turn reviewer no longer rewrites pack sections blind — context starvation fixed.** The reviewer prompt showed only the pack *index* (name + description), so a State rewrite was regenerated from the turn text alone and silently destroyed durable facts the turn didn't restate; worse, with no project name in the turn text it could attribute the work to the wrong pack entirely (observed live: an AQUELLE product-shot turn filed under Alpha Protein, wiping a promoted root-cause fact). The runner now passes the turn's **active packs** (recall-surfaced ∪ explicitly opened) into `reviewTurn`; the prompt includes their **full current Stance/Procedure/State + recent journal**, with two new rules: attribute updates to an active pack unless the turn clearly names another, and treat section rewrites as **merges** — carry forward every still-true fact, drop only what the turn contradicted or completed.
+- **Structural enforcement, not just prompt guidance.** `applyAction` drops section rewrites (State/Stance/Procedure) targeting any pack whose current content the reviewer did not see — journal lines still land; the announce line notes the drop. Applies to the update path, the exists-on-create path, and the versioned-duplicate fold.
+- **Provenance guard extended.** A user-authored Procedure now gets the same intent-wins protection as Stance (an automated writer never silently replaces it). State stays rewritable by design, but replacing a user-authored State is now flagged in the reviewer's announcement (⚠️) so the overwrite is visible instead of silent.
+
+## v2.9.0
+- **Hybrid async approvals — a destructive run no longer burns the turn or dead-ends on a late press.** v2.8.0's chat approval blocked the CLI for 5 minutes and treated timeout as denial, which had two UX failures: an undecided window wasted minutes of live turn, and a button pressed after the window hit a dead-end (terse auto-ack, no agent reaction — the record was already denied). The flow is now two-phase. **Fast path**: the CLI waits ~90s; an inline Approve runs immediately, Deny refuses — unchanged semantics, just a tighter window. **Async path**: if undecided at 90s, the CLI marks the record `detached` and exits code 5 with instructions to end the turn ("pending your Approve/Deny — do NOT retry"); the record stays open for 24h. When the button is eventually pressed, the `apr:` handler sees the detached record and **schedules an immediate wakeup** in the originating channel carrying the decision and the exact command, so the agent reacts either way (runs it, or acknowledges the denial).
+- **One-shot approval tokens, fail-closed on every branch.** The woken agent redeems the decision with `tool run <name> <args> --approval <apr_id>`. `approvals.consume()` requires ALL of: status `approved`, never consumed before (single use — a replay is refused), within 24h of request, and a command line **byte-identical** to what the user saw on the buttons (a mismatch refuses without burning the token). `--approval` is honored on top-level runs only — a nested/composed tool can't smuggle a token — and redemption stamps `approvedVia: "chat-approval"` + exports `OPEN_CLAUDIA_APPROVED_TIER=destructive` exactly like an inline approve, so composition inheritance is unchanged. Undecided, denied, expired, unknown, or mismatched never runs.
+- Approval prompt and system-prompt docs updated for the two-phase flow; new `test-approval-async.js` covers the full lifecycle (detach semantics, pending/denied/unknown refusals, exact-match redemption, replay refusal, token not burned on mismatch, 24h expiry, 1000-char command cap, 90s default window).
+
 ## v2.8.0
 - **Per-verb manifests — the gate now knows each verb's blast radius (Phase 5).** A tool may declare its verbs in the header (`verb: <name> [args] | <tier> | <doc>` — one line per verb); `tool run` then resolves the risk tier **per invoked verb** instead of whole-tool: `spaces unread` runs freely while `spaces upload` demands `--yes`, and `prod-k8s cert-status` is read-only while `cert-renew` stays write-gated. An **undeclared verb on a manifest tool is refused outright** regardless of flags (declare it before using it), `help`/no-verb is always read-only, and manifest-less tools keep the old whole-tool gate unchanged (fully backward compatible — older runners ignore `verb:` lines). `tool scaffold --verbs "list:read-only:doc,create:write:doc"` generates the manifest lines, a dispatcher entry per verb, and a TOOL.md verbs block; `tool show` lists the declared manifest. Migrated all 8 live verb-CLIs (clickhouse, inet-central-cli, inet-ops, kazee-chat, kticket, metabase, prod-k8s, spaces — 41 declared verbs) in the tools repo.
 - **Chat approval with the EXACT payload — destructive runs escalate to inline Approve/Deny.** `--yes-destructive` acknowledged the agent's *paraphrase* of a destructive action; now an unflagged destructive top-level `tool run` inside a bot task POSTs the literal resolved command line to the requesting channel via a new loopback `approval-request` kind — the user sees `open-claudia tool run <name> <args>` verbatim with ✅ Approve / ⛔ Deny buttons (owner-only, idempotent: a second press can't overturn the first). The CLI polls the file-backed record (`core/approvals.js`) and **fails closed**: timeout (5 min) or deny = refusal at exit 3; only an explicit approve proceeds, stamped `approvedVia: "chat-approval"` with `OPEN_CLAUDIA_APPROVED_TIER=destructive` exported for composition. Every run's history entry now records the acknowledged tier — auditable forever.

package/bin/tool.js

@@ -353,7 +353,17 @@ async function run(args) {
       if (!name) { console.error("Usage: tool run <name> [args...]"); process.exitCode = 1; return; }
       const t = tools.findTool(name);
       if (!t) { console.error(`No tool named "${name}". Run: open-claudia tool list`); process.exitCode = 1; return; }
-      const toolArgs = rest.slice(1);
+      let toolArgs = rest.slice(1);
+
+      // Async-approval token (--approval apr_x): redeemed one-shot against the
+      // exact command line WITHOUT the token flag, so what's checked is what
+      // was shown to the user. Stripped before spawn — tools never see it.
+      let approvalId = "";
+      const aprIdx = toolArgs.indexOf("--approval");
+      if (aprIdx >= 0) {
+        approvalId = toolArgs[aprIdx + 1] || "";
+        toolArgs = [...toolArgs.slice(0, aprIdx), ...toolArgs.slice(aprIdx + 2)];
+      }
 
       // Risk-tier gate, resolved per verb when the tool declares a manifest:
       // write needs --yes, destructive needs --yes-destructive. Undeclared
@@ -361,24 +371,50 @@ async function run(args) {
       // calling this tool) gate on the tier the OUTERMOST invocation approved
       // instead — argv flags can't fabricate approval.
       const gate = tools.runGate(t, toolArgs, process.env);
+      const commandLine = ["open-claudia tool run", t.name, ...toolArgs].join(" ");
       let approvedVia = "";
-      if (!gate.ok) {
+
+      if (approvalId) {
+        const approvals = require("../core/approvals");
+        if (String(process.env.OPEN_CLAUDIA_TOOL_STACK || "").trim()) {
+          console.error("⛔ --approval tokens are only honored on top-level runs, not nested tool calls.");
+          process.exitCode = 3; return;
+        }
+        const redeemed = approvals.consume(approvalId, commandLine);
+        if (!redeemed.ok) {
+          console.error(`⛔ Approval ${approvalId} rejected: ${redeemed.reason}. The run stays blocked.`);
+          process.exitCode = 3; return;
+        }
+        approvedVia = "chat-approval";
+        console.error(`✅ Approval ${approvalId} redeemed (single use) — running.`);
+      } else if (!gate.ok) {
         // Chat-approval fallback: an unflagged destructive top-level run inside
         // a bot task escalates to the requesting channel with the EXACT command
-        // and inline Approve/Deny. Anything but an explicit approve = refusal.
+        // and inline Approve/Deny. Fast path: block ~90s for an inline decision.
+        // No decision in time → detach and exit; the button press later fires a
+        // wakeup carrying a one-shot --approval token. Anything but an explicit
+        // approve = the command never runs.
         const canAsk = gate.tier === "destructive" && !gate.nested && !gate.undeclared
           && process.env.OC_SEND_URL && process.env.OC_SEND_TOKEN && process.env.OC_CHANNEL_ID && process.env.OC_CHANNEL_ADAPTER;
         if (!canAsk) { console.error(gate.message); process.exitCode = 3; return; }
-        const commandLine = ["open-claudia tool run", t.name, ...toolArgs].join(" ");
         console.error(`Destructive run without --yes-destructive — asking for chat approval of the exact command...`);
         let decision = "denied";
+        let reqId = "";
         try {
           const { postJson } = require("./loopback-client");
           const res = await postJson("approval-request", {
             tool: t.name, verb: tools.invokedVerb(toolArgs), tier: gate.tier, command: commandLine,
           });
+          reqId = res.id;
           const approvals = require("../core/approvals");
           decision = await approvals.waitForDecision(res.id);
+          if (decision === "timeout") {
+            approvals.detach(res.id);
+            console.error(`⏳ No decision yet — approval ${res.id} stays open for 24h (detached).`);
+            console.error(`End the turn and tell the user the run is pending their Approve/Deny. When they press a button, ` +
+              `a wakeup will fire with the outcome — do NOT retry or re-request this command in the meantime.`);
+            process.exitCode = 5; return;
+          }
         } catch (e) {
           console.error(`Chat approval unavailable (${e.message}).`);
         }

package/core/actions.js

@@ -305,12 +305,43 @@ async function handleAction(envelope) {
     const id = parts[1];
     const choice = parts[2] === "ok" ? "approved" : "denied";
     const approvals = require("./approvals");
+    const wasPending = approvals.read(id)?.status === "pending";
     const rec = approvals.decide(id, choice, String(envelope.channelId));
     if (!rec) return send("That approval request has expired or was cleaned up — the run stays blocked.");
     // If a second press disagreed, rec.status still holds the FIRST decision.
+    const label = `${rec.tool}${rec.verb ? " " + rec.verb : ""}`;
+    if (rec.detached && wasPending) {
+      // The CLI gave up its fast-path wait and exited — no live turn is
+      // listening. Wake the agent so it can redeem (or acknowledge) the
+      // decision. The one-shot token in consume() keeps this fail-closed.
+      const prompt = rec.status === "approved"
+        ? `[Tool approval ${rec.id}] The user APPROVED the pending destructive run:\n${rec.command}\n` +
+          `Run it now EXACTLY as:\n${rec.command} --approval ${rec.id}\n` +
+          `The token is single-use and bound to that exact command — do not alter it. Report the result to the user.`
+        : `[Tool approval ${rec.id}] The user DENIED the pending destructive run:\n${rec.command}\n` +
+          `Do NOT run it. Acknowledge the denial to the user and adjust course.`;
+      try {
+        scheduler.addJob({
+          kind: "wakeup",
+          adapter: rec.adapter || (adapter && adapter.id) || "",
+          adapterType: adapter && adapter.type,
+          channelId: String(rec.channelId || envelope.channelId),
+          prompt,
+          label: `Tool approval ${rec.status}: ${label}`.slice(0, 60),
+          source: "approval",
+          fireAt: Date.now() + 2000,
+        });
+      } catch (e) {
+        return send(`Decision recorded (${rec.status}) but I couldn't wake the agent: ${e.message}`);
+      }
+      await send(rec.status === "approved"
+        ? `✅ Approved — waking the agent to run ${label} now.`
+        : `⛔ Denied — ${label} stays blocked; letting the agent know.`);
+      return;
+    }
     await send(rec.status === "approved"
-      ? `✅ Approved — ${rec.tool}${rec.verb ? " " + rec.verb : ""} will run now.`
-      : `⛔ Denied — ${rec.tool}${rec.verb ? " " + rec.verb : ""} will not run.`);
+      ? `✅ Approved — ${label} will run now.`
+      : `⛔ Denied — ${label} will not run.`);
     return;
   }
   if (d.startsWith("tt:")) {

package/core/approvals.js

@@ -4,12 +4,15 @@
 // --yes-destructive flag acknowledges a summary — here the user approves the
 // literal command that will execute, not the agent's paraphrase of it.
 //
-// Mechanics: file-backed records under CONFIG_DIR/approvals. The CLI (a bot
-// subprocess) POSTs approval-request to the bot's loopback server, which sends
-// the button message and creates the pending record; the CLI then polls the
-// record file until the actions.js "apr:" callback flips its status, or the
-// timeout lapses (timeout = denied — fail-closed, unlike the guard's
-// fail-open, because this path only exists for destructive actions).
+// Mechanics (hybrid async): file-backed records under CONFIG_DIR/approvals.
+// The CLI (a bot subprocess) POSTs approval-request to the bot's loopback
+// server, which sends the button message and creates the pending record. The
+// CLI then polls the record for a short fast-path window; if the user decides
+// in time the run proceeds (or refuses) inline. Otherwise the CLI marks the
+// record "detached" and exits — the agent's turn ends cleanly, and when the
+// button is eventually pressed, actions.js schedules a wakeup so the agent can
+// consume the approval as a ONE-SHOT token bound to the exact command string
+// (single use, 24h TTL, fail-closed: undecided or mismatched never runs).
 
 const fs = require("fs");
 const path = require("path");
@@ -71,8 +74,9 @@ function decide(id, status, by = "") {
 }
 
 // Poll until decided or timeout. Timeout resolves as "timeout" — the caller
-// must treat anything other than "approved" as a refusal.
-async function waitForDecision(id, { timeoutMs = 300000, pollMs = 1500 } = {}) {
+// must treat anything other than "approved" as a refusal (or detach and go
+// async).
+async function waitForDecision(id, { timeoutMs = 90000, pollMs = 1500 } = {}) {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
     const rec = read(id);
@@ -82,4 +86,33 @@ async function waitForDecision(id, { timeoutMs = 300000, pollMs = 1500 } = {}) {
   }
 }
 
-module.exports = { APPROVALS_DIR, create, read, decide, waitForDecision };
+// The CLI gave up its fast-path wait and exited; the record stays pending.
+// actions.js uses this flag to know a later button press must wake the agent
+// (an attached waiter reacts by itself, a detached one cannot).
+function detach(id) {
+  const rec = read(id);
+  if (!rec || rec.status !== "pending") return rec;
+  rec.detached = true;
+  rec.detachedAt = new Date().toISOString();
+  fs.writeFileSync(fileOf(id), JSON.stringify(rec, null, 2), { mode: 0o600 });
+  return rec;
+}
+
+// One-shot token redemption for the async path. Fail-closed on every branch:
+// only an approved, un-consumed, un-expired record whose stored command is
+// byte-identical to what is about to run can be consumed — and only once.
+function consume(id, commandLine) {
+  const rec = read(id);
+  if (!rec) return { ok: false, reason: "unknown or expired approval id" };
+  if (rec.status !== "approved") return { ok: false, reason: `approval is ${rec.status}, not approved` };
+  if (rec.consumedAt) return { ok: false, reason: "approval already consumed (single use)" };
+  if (Date.now() - Date.parse(rec.requestedAt) > MAX_AGE_MS) return { ok: false, reason: "approval expired (24h)" };
+  if (String(commandLine || "").slice(0, 1000) !== rec.command) {
+    return { ok: false, reason: "command does not match the approved payload" };
+  }
+  rec.consumedAt = new Date().toISOString();
+  fs.writeFileSync(fileOf(id), JSON.stringify(rec, null, 2), { mode: 0o600 });
+  return { ok: true, record: rec };
+}
+
+module.exports = { APPROVALS_DIR, create, read, decide, waitForDecision, detach, consume };

package/core/loopback.js

@@ -477,7 +477,7 @@ async function handleJson(req, res, url, kind) {
         `<pre>${String(payload.command).slice(0, 800).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")}</pre>`,
         ``,
         `Tool: ${payload.tool}${payload.verb ? ` · verb: ${payload.verb}` : ""} · tier: ${rec.tier}`,
-        `This is the literal command that will execute. Times out (denied) in 5 minutes.`,
+        `This is the literal command that will execute. Decide within ~90s to run it inline; after that the agent moves on, but your Approve/Deny stays valid for 24h and wakes it back up.`,
       ].join("\n");
       const keyboard = { inline_keyboard: [[
         { text: "✅ Approve", callback_data: `apr:${rec.id}:ok` },

package/core/pack-review.js

@@ -58,7 +58,34 @@ function formatAnnouncement(lines) {
   return [header, ...lines].join("\n\n");
 }
 
-function buildReviewPrompt(userText, assistantText) {
+// Full current content of the packs a turn actually worked with, rendered
+// into the review prompt so section rewrites are merges (old content visible)
+// instead of blind regenerations from the turn text — a blind State rewrite
+// silently destroys durable facts the turn didn't restate.
+const ACTIVE_PACK_MAX = 4;
+const ACTIVE_SECTION_CHARS = 1500;
+
+function renderActivePacks(activePacks) {
+  const dirs = (Array.isArray(activePacks) ? activePacks : []).slice(0, ACTIVE_PACK_MAX);
+  const blocks = [];
+  for (const dir of dirs) {
+    let p = null;
+    try { p = packs.readPack(dir); } catch (e) {}
+    if (!p) continue;
+    const sec = p.sections || {};
+    const journal = String(sec.Journal || "").split("\n").filter((l) => l.trim()).slice(-3).join("\n");
+    const parts = [`### ${p.dir}: ${p.name} — ${p.description || ""}`];
+    if (String(sec.Stance || "").trim()) parts.push(`Stance:\n${clip(sec.Stance.trim(), ACTIVE_SECTION_CHARS)}`);
+    if (String(sec.Procedure || "").trim()) parts.push(`Procedure:\n${clip(sec.Procedure.trim(), ACTIVE_SECTION_CHARS)}`);
+    if (String(sec.State || "").trim()) parts.push(`State (current):\n${clip(sec.State.trim(), ACTIVE_SECTION_CHARS)}`);
+    if (journal) parts.push(`Journal (recent):\n${journal}`);
+    blocks.push(parts.join("\n"));
+  }
+  return blocks.join("\n\n");
+}
+
+function buildReviewPrompt(userText, assistantText, activePacks) {
+  const activeBlock = renderActivePacks(activePacks);
   const index = packs.listPacks().map((p) => {
     const ab = p.kind === "ability" ? " ◆ability" : "";
     const prov = p.kind === "ability" && p.learned_on
@@ -93,7 +120,11 @@ A LESSON is a single always-loaded rule (NOT topic-gated like packs/entities —
 
 Existing packs:
 ${index}
+${activeBlock ? `
+Packs ACTIVE during this turn — their FULL CURRENT content. The turn's work almost certainly belongs to one of these:
 
+${activeBlock}
+` : ""}
 Known entities:
 ${entityIndex}
 
@@ -112,6 +143,8 @@ ${clip(assistantText)}
 
 Decide. Rules:
 - Bias toward action: if the turn did real work on an identifiable topic (a named system, project, server, app, person, or domain), record it — at minimum a journal line. Most working turns deserve one. Reserve empty actions for small talk, pure status checks, and turns that contain nothing new.
+- ATTRIBUTION: prefer updating one of the ACTIVE packs above. The turn text often does not name its project (pronouns, follow-ups, pasted URLs) — never attribute the work to a different pack from the index on thematic similarity alone when an active pack fits the work.
+- 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).
 - 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.
 - 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.
@@ -189,7 +222,7 @@ function findDuplicatePack({ dir, name, description, tags }) {
   return null;
 }
 
-function applyAction(a) {
+function applyAction(a, activeSet = null) {
   if (!a || typeof a !== "object") return null;
   const guard = guardCheck(a);
   if (guard.flagged) {
@@ -198,11 +231,17 @@ function applyAction(a) {
   if (a.action === "update" && a.pack) {
     const existing = packs.readPack(a.pack);
     if (!existing) return null;
+    // Structural enforcement of merge-not-regenerate: the reviewer only saw
+    // the full current sections of the turn's ACTIVE packs, so a section
+    // rewrite on any other pack is blind (generated from the turn text alone)
+    // 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);
     const r = packs.updatePack(a.pack, {
       journal: a.journal || "",
-      state: typeof a.state === "string" ? a.state : "",
-      stance: typeof a.stance === "string" ? a.stance : "",
-      procedure: typeof a.procedure === "string" ? a.procedure : "",
+      state: !blind && typeof a.state === "string" ? a.state : "",
+      stance: !blind && typeof a.stance === "string" ? a.stance : "",
+      procedure: !blind && typeof a.procedure === "string" ? a.procedure : "",
     }, "reviewer");
     // Cross-project reuse: only abilities carry applied_on, so ignore the field
     // on context packs (keeps project trackers churn-free).
@@ -212,7 +251,15 @@ function applyAction(a) {
         if (packs.recordApplied(a.pack, proj)) appliedTo = proj;
       }
     }
-    return { kind: "update", dir: a.pack, name: existing.name, note: a.journal || (appliedTo ? `reused on ${appliedTo}` : "state updated"), protectedStance: !!r.protectedStance, appliedTo };
+    return {
+      kind: "update", dir: a.pack, name: existing.name,
+      note: a.journal || (appliedTo ? `reused on ${appliedTo}` : "state updated"),
+      protectedStance: !!r.protectedStance,
+      protectedProcedure: !!r.protectedProcedure,
+      overwroteUserState: !!r.overwroteUserState,
+      blindSkipped: blind && [a.state, a.stance, a.procedure].some((s) => typeof s === "string" && s.trim()),
+      appliedTo,
+    };
   }
   if (a.action === "create" && (a.dir || a.name)) {
     const dir = packs.slugify(a.dir || a.name);
@@ -223,7 +270,8 @@ function applyAction(a) {
       : [];
     const projects = applied_on.length ? applied_on : (learned_on ? [learned_on] : []);
     if (packs.readPack(dir)) {
-      packs.updatePack(dir, { journal: a.journal || "", state: a.state || "" }, "reviewer");
+      const blind = activeSet instanceof Set && !activeSet.has(dir);
+      packs.updatePack(dir, { journal: a.journal || "", 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" };
     }
@@ -232,7 +280,8 @@ function applyAction(a) {
     // they are activity-named and cross-project by design).
     const dupeDir = kind === "context" ? findDuplicatePack({ dir, name: a.name, description: a.description, tags: a.tags }) : null;
     if (dupeDir && packs.readPack(dupeDir)) {
-      packs.updatePack(dupeDir, { journal: a.journal || "", state: a.state || "" }, "reviewer");
+      const blind = activeSet instanceof Set && !activeSet.has(dupeDir);
+      packs.updatePack(dupeDir, { journal: a.journal || "", 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" };
     }
@@ -319,7 +368,7 @@ function shouldSkipReview({ userText, assistantText, signals = {} }) {
 
 // Fire-and-forget. `announce` is an async (text) => void bound to the
 // originating channel; failures are logged, never thrown into the turn.
-function reviewTurn({ userText, assistantText, channelId, announce, signals }) {
+function reviewTurn({ userText, assistantText, channelId, announce, signals, activePacks }) {
   if (!enabled()) return;
   const skip = shouldSkipReview({ userText, assistantText, signals });
   if (skip) {
@@ -329,7 +378,8 @@ function reviewTurn({ userText, assistantText, channelId, announce, signals }) {
     return;
   }
 
-  const prompt = buildReviewPrompt(redactSensitive(String(userText || "")), redactSensitive(String(assistantText || "")));
+  const activeSet = Array.isArray(activePacks) && activePacks.length ? new Set(activePacks) : null;
+  const prompt = buildReviewPrompt(redactSensitive(String(userText || "")), redactSensitive(String(assistantText || "")), activePacks);
 
   spawnSubagent(prompt, {
     model: REVIEW_MODEL,
@@ -343,7 +393,7 @@ function reviewTurn({ userText, assistantText, channelId, announce, signals }) {
     const usedIds = []; // nodes this turn's work demonstrably touched
     for (const a of decision.actions) {
       try {
-        const r = applyAction(a);
+        const r = applyAction(a, activeSet);
         if (r && (r.kind === "update" || r.kind === "create") && r.dir) usedIds.push(`pack:${r.dir}`);
         if (r && r.kind === "skipped") {
           lines.push(`🛡️ Skipped a memory write that looked like an injected instruction (${r.reason}).`);
@@ -352,7 +402,11 @@ function reviewTurn({ userText, assistantText, channelId, announce, signals }) {
         } else if (r && r.kind === "create") {
           lines.push(`📦 New pack: ${r.name}${r.parent ? ` (filed under ${r.parent})` : ""}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`);
         } else if (r) {
-          lines.push(`✏️ ${r.name} — ${clipWords(r.note, 180)}${r.appliedTo ? ` 🧩 (now also applies to ${r.appliedTo})` : ""}\n↳ open-claudia pack show ${r.dir}`);
+          const marks = [];
+          if (r.appliedTo) marks.push(` 🧩 (now also applies to ${r.appliedTo})`);
+          if (r.overwroteUserState) marks.push(" ⚠️ replaced a user-written State — check it kept your facts");
+          if (r.blindSkipped) marks.push(" (section rewrite dropped: pack wasn't active this turn — journal only)");
+          lines.push(`✏️ ${r.name} — ${clipWords(r.note, 180)}${marks.join("")}\n↳ open-claudia pack show ${r.dir}`);
         }
       } catch (e) {
         console.warn(`[pack-review] apply failed: ${e.message}`);

package/core/packs.js

@@ -393,8 +393,26 @@ function updatePack(dir, { description, tags, stance, procedure, state, journal,
       applied.push("Stance");
     }
   }
-  if (typeof procedure === "string" && procedure.trim()) { pack.sections.Procedure = procedure.trim(); applied.push("Procedure"); }
-  if (typeof state === "string" && state.trim()) { pack.sections.State = state.trim(); applied.push("State"); }
+  let protectedProcedure = false;
+  if (typeof procedure === "string" && procedure.trim()) {
+    // Same intent-wins rule as Stance: a user-authored Procedure is a verified
+    // how-to — an automated writer never silently replaces it.
+    if (origin !== "user" && provenanceOf(dir, "Procedure") === "user") {
+      protectedProcedure = true;
+    } else {
+      pack.sections.Procedure = procedure.trim();
+      applied.push("Procedure");
+    }
+  }
+  // State stays rewritable by design (it tracks "now"), but replacing a
+  // user-authored State is flagged so the caller can announce the overwrite
+  // instead of it happening silently.
+  let overwroteUserState = false;
+  if (typeof state === "string" && state.trim()) {
+    if (origin !== "user" && provenanceOf(dir, "State") === "user") overwroteUserState = true;
+    pack.sections.State = state.trim();
+    applied.push("State");
+  }
   if (typeof journal === "string" && journal.trim()) {
     const entries = pack.sections.Journal.split("\n").filter((l) => l.trim());
     const line = journal.trim().replace(/\n+/g, " ");
@@ -409,6 +427,8 @@ function updatePack(dir, { description, tags, stance, procedure, state, journal,
   writePack(pack);
   if (applied.length) setProvenance(dir, applied, origin);
   pack.protectedStance = protectedStance;
+  pack.protectedProcedure = protectedProcedure;
+  pack.overwroteUserState = overwroteUserState;
   return pack;
 }
 

package/core/runner.js

@@ -1041,8 +1041,13 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
   // reflects what was read, not what was pushed. (consumeLastInjected is
   // drained here to keep the per-turn buffer from leaking into the next turn.)
   let turnRecallTier = "";
+  // Pack dirs surfaced (recall-matched) for this turn — joined with
+  // openedThisTurn at end-of-turn to tell the post-turn reviewer which packs
+  // this turn's work belongs to (attribution + safe State rewrites).
+  let surfacedPackDirs = [];
   try {
     const injected = require("./system-prompt").consumeLastInjected();
+    if (injected && Array.isArray(injected.packDirs)) surfacedPackDirs = injected.packDirs;
     if (injected && injected.recall) {
       const r = injected.recall;
       turnRecallTier = String(r.tier || "");
@@ -1537,6 +1542,14 @@ async function runClaude(prompt, cwd, replyToMsgId, opts = {}) {
         userText: prompt,
         assistantText,
         channelId,
+        // Packs this turn demonstrably worked with: surfaced by recall for the
+        // incoming message, or explicitly opened by the agent. The reviewer
+        // sees their full current sections and must attribute updates here —
+        // prevents cross-project misattribution and blind State rewrites.
+        activePacks: [...new Set([
+          ...surfacedPackDirs,
+          ...[...openedThisTurn].filter((n) => n.startsWith("pack:")).map((n) => n.slice(5)),
+        ])],
         signals: { tier: turnRecallTier, wrote: toolUses.some((t) => WRITE_TOOLS.has(t)) },
         announce: (text) => chatContext.run(store, () => send(text)),
       });

package/core/system-prompt.js

@@ -110,7 +110,7 @@ Operational work — hitting an API, mutating a live system, driving an interfac
 Raw shell one-liners and heredocs are for probing and diagnosis only — never the operational action itself. If a tool is broken, fix it or journal the defect (\`tool note <name> --issue "..."\`); do not route around it with a script.
 
 - Risk gate: read-only tools run freely; write-tier needs \`--yes\`; destructive needs \`--yes-destructive\`. The flag is your mechanical acknowledgment AFTER the user approves the action — it never replaces asking first.
-- Per-verb manifest: a tool that declares \`verb:\` header lines is gated verb-by-verb — each verb runs at its own declared tier, and an undeclared verb is refused outright (declare it in the header before using it). An unflagged destructive run inside a bot task escalates to chat with the EXACT command and Approve/Deny buttons; anything but an explicit approve is a refusal.
+- Per-verb manifest: a tool that declares \`verb:\` header lines is gated verb-by-verb — each verb runs at its own declared tier, and an undeclared verb is refused outright (declare it in the header before using it). An unflagged destructive run inside a bot task escalates to chat with the EXACT command and Approve/Deny buttons and waits ~90s: an inline Approve runs it, Deny refuses. If the window lapses (exit code 5, "pending"), the approval detaches but stays valid 24h — END the turn telling the user the run awaits their button press; do NOT retry or re-request it. When they later press a button you're woken with the outcome: if approved, run the EXACT command with \`--approval <id>\` appended (one-shot token, top-level runs only, bound byte-for-byte to the approved command — never alter or reuse it); if denied, acknowledge and move on.
 - Tools carry their own memory: TOOL.md (Interface · Known issues · State · Journal) is the manual, state.json records every run (per-verb health), and every change is a git commit. Keep TOOL.md truthful as you work; update the tool in place when behaviour changes.
 - Preauth, least-privilege: keyring creds are injected ONLY into \`tool run\` subprocesses, and only the keys a tool declares via \`--requires\` (\`open-claudia keyring list\` shows names) — your own shell and sub-agents hold NO creds. Reference creds as \`$inet_central_user\` etc. inside tool sources and declare every one; never write a secret into a tool file (saves are refused).
 - Deny-gate: raw shell commands that act on known production surfaces (platform APIs, prod hosts, in-cluster mongo, GitLab host shell) are blocked mid-flight with a redirect to the covering tool — that block is the system working, not an obstacle to route around. Genuine one-off no tool covers yet? \`open-claudia keyring exec --reason "<why>" -- <cmd>\` runs with full creds and logs the bypass for audit; scaffold the tool if you'd ever run it twice.
@@ -442,10 +442,10 @@ function tryUseRecallBudget(budget, text) {
 // What the last promptWithDynamicContext call freshly injected (not the
 // deduped repeats) — consumed by the runner to announce recalls in chat,
 // mirroring the write-side announcements.
-let lastInjected = { packs: [], entities: [], recall: null };
+let lastInjected = { packs: [], packDirs: [], entities: [], recall: null };
 function consumeLastInjected() {
   const out = lastInjected;
-  lastInjected = { packs: [], entities: [], recall: null };
+  lastInjected = { packs: [], packDirs: [], entities: [], recall: null };
   return out;
 }
 
@@ -743,7 +743,7 @@ function voiceReplyGuidance() {
 }
 
 async function promptWithDynamicContext(prompt, opts = {}) {
-  lastInjected = { packs: [], entities: [], recall: null };
+  lastInjected = { packs: [], packDirs: [], entities: [], recall: null };
   try {
     const { userText, contextText } = recallMatchParts(prompt);
     let historyText = "";
@@ -770,6 +770,10 @@ async function promptWithDynamicContext(prompt, opts = {}) {
     const toolBlock = result.toolBlock || "";
     const episodeBlock = result.episodeBlock || "";
     const why = result.why || {};
+    // Pack DIRS surfaced for this turn (matched, whether or not the body was
+    // freshly injected or deduped) — consumed by the post-turn reviewer so it
+    // knows which packs the turn's work belongs to and can see their content.
+    lastInjected.packDirs = (result.packMatches || []).map((m) => m.dir).filter(Boolean);
     lastInjected.recall = {
       engine: engine.name || recall.activeEngineName(settings),
       gated: !!result.gated,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {
@@ -9,7 +9,7 @@
   "scripts": {
     "setup": "node setup.js",
     "start": "node bot.js",
-    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-runner-watchdog-static.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-journal-dedupe.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tooling-mode.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-manifest.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-evolution.js"
+    "test": "OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node -e \"require('./vault'); console.log('OK')\" && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-runner-watchdog-static.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-usage-accounting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-engine.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-discoverer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-project-transcripts-smoke.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-abilities.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-extraction.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-couse.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-transfer.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-tiers.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-ability-merge-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-learning-e2e.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-pack-nesting.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-journal-dedupe.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-read-signal.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tools.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-graph.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-guard.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tooling-mode.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-tool-manifest.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-recall-evolution.js && OPEN_CLAUDIA_TEST=1 WORKSPACE=/tmp/open-claudia-test CLAUDE_PATH=node node test-approval-async.js"
   },
   "files": [
     "bot.js",
@@ -49,7 +49,8 @@
     "test-tool-graph.js",
     "test-tool-guard.js",
     "test-tooling-mode.js",
-    "test-tool-manifest.js"
+    "test-tool-manifest.js",
+    "test-approval-async.js"
   ],
   "keywords": [
     "claude",

package/test-approval-async.js

@@ -0,0 +1,76 @@
+// Hybrid async approvals: when the CLI's fast-path wait lapses it detaches
+// and exits, and a later button press is redeemed as a ONE-SHOT token bound
+// to the exact command string. Every branch here is fail-closed — only an
+// approved, un-consumed, un-expired, byte-identical command runs, and only
+// once.
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "approval-async-test-"));
+process.env.APPROVALS_DIR = path.join(tmp, "approvals");
+
+const approvals = require("./core/approvals");
+
+(async () => {
+  const CMD = "open-claudia tool run fleet purge n1";
+
+  // ── detach: pending record gains the flag; decided records are untouched ──
+  const rec = approvals.create({ tool: "fleet", verb: "purge", tier: "destructive", command: CMD, channelId: "c1", adapter: "tg" });
+  const det = approvals.detach(rec.id);
+  assert.strictEqual(det.detached, true, "pending record detaches");
+  assert.ok(det.detachedAt, "detach is timestamped");
+  assert.strictEqual(approvals.read(rec.id).status, "pending", "detach does not decide");
+
+  const decided = approvals.create({ tool: "fleet", verb: "purge", tier: "destructive", command: CMD, channelId: "c1", adapter: "tg" });
+  approvals.decide(decided.id, "denied", "c1");
+  const det2 = approvals.detach(decided.id);
+  assert.notStrictEqual(det2.detached, true, "decided record cannot be detached");
+
+  // ── consume: only approved records redeem ──
+  assert.strictEqual(approvals.consume(rec.id, CMD).ok, false, "pending record cannot be consumed");
+  assert.ok(/pending/.test(approvals.consume(rec.id, CMD).reason));
+  assert.strictEqual(approvals.consume(decided.id, CMD).ok, false, "denied record cannot be consumed");
+
+  // ── late decide on a detached record still works, then redeems exactly once ──
+  approvals.decide(rec.id, "approved", "c1");
+  const bad = approvals.consume(rec.id, CMD + " --extra");
+  assert.strictEqual(bad.ok, false, "command mismatch refused");
+  assert.ok(/does not match/.test(bad.reason));
+  assert.strictEqual(approvals.read(rec.id).consumedAt, undefined, "failed consume does not burn the token");
+
+  const good = approvals.consume(rec.id, CMD);
+  assert.strictEqual(good.ok, true, "exact command redeems");
+  assert.ok(good.record.consumedAt, "redemption is stamped");
+
+  const replay = approvals.consume(rec.id, CMD);
+  assert.strictEqual(replay.ok, false, "second consume refused (single use)");
+  assert.ok(/already consumed/.test(replay.reason));
+
+  // ── unknown id fails closed ──
+  assert.strictEqual(approvals.consume("apr_nope", CMD).ok, false, "unknown id refused");
+
+  // ── expiry: an approved token older than 24h cannot redeem ──
+  const old = approvals.create({ tool: "fleet", verb: "purge", tier: "destructive", command: CMD, channelId: "c1", adapter: "tg" });
+  approvals.decide(old.id, "approved", "c1");
+  const f = path.join(approvals.APPROVALS_DIR, `${old.id}.json`);
+  const j = JSON.parse(fs.readFileSync(f, "utf-8"));
+  j.requestedAt = new Date(Date.now() - 25 * 60 * 60 * 1000).toISOString();
+  fs.writeFileSync(f, JSON.stringify(j));
+  const expired = approvals.consume(old.id, CMD);
+  assert.strictEqual(expired.ok, false, "expired token refused");
+  assert.ok(/expired/.test(expired.reason));
+
+  // ── long commands: stored payload is capped at 1000 chars and matching respects the cap ──
+  const longCmd = "open-claudia tool run fleet purge " + "x".repeat(1200);
+  const lrec = approvals.create({ tool: "fleet", verb: "purge", tier: "destructive", command: longCmd, channelId: "c1", adapter: "tg" });
+  approvals.decide(lrec.id, "approved", "c1");
+  assert.strictEqual(approvals.consume(lrec.id, longCmd).ok, true, "capped command still matches its own approval");
+
+  // ── waitForDecision default fast-path window is 90s (not the old 5 min) ──
+  const src = fs.readFileSync(path.join(__dirname, "core", "approvals.js"), "utf-8");
+  assert.ok(/timeoutMs = 90000/.test(src), "fast-path default is 90s");
+
+  console.log("approval async OK");
+})().catch((e) => { console.error(e); process.exit(1); });