squadrant 0.9.0

package/plugin/skills/where-i-am/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: where-i-am
+description: Print a tight "where am I on this project?" orientation report — a "right now" punchline plus Done (and what it means) / In progress / Next / Watch. Use when context-switching into a long-running project, resuming after a compact, or whenever you ask "where was I / what's the status / /wim / /where-i-am".
+---
+
+# Where I Am
+
+Answer **"where am I on this project?"** in a short, scannable report instead of a wall of text. Built for switching between long-running projects without losing the thread.
+
+Read-only. This skill **writes nothing** and **consumes nothing** — pure orientation.
+
+## Output shape
+
+Open with a one-line punchline, then the four sections in order:
+
+```markdown
+**Right now →** <what you're actively doing / waiting on this moment, and your immediate next move>
+
+## ✅ Done — and what it means
+- <completed work> → <why it matters / what it unblocks>
+
+## ⏳ In progress
+- <work actively moving> — <state / owner: crew fixing, waiting on CI, mid-refactor>
+
+## ▶️ Next
+- ⬜ <the next not-yet-started step(s)>
+
+## ⚠️ Watch
+- <blockers, fragile state, gotchas, "don't forget", contradictions between sources>
+```
+
+Status markers — use inline when listing the steps of a track: ✅ done · ⏳ in progress · ⬜ not started.
+
+Rules for the report:
+- **`Right now →` is the most important line** — the fast-orientation cue. Always include it; one line.
+- **Bullets, not paragraphs.** A handful per section, most-relevant first.
+- Each **Done** bullet pairs *what happened* with *why it matters* (`→`). A commit without significance is noise.
+- **In progress vs Next:** ⏳ is work already moving (a crew is on it, a branch is open, you're mid-edit); ⬜ Next is not yet started. Don't conflate them — the whole point is knowing what's live vs queued.
+- **Multi-track projects** (e.g. a feature track + a bugfix track running in parallel): group bullets under bold track labels (`**Reorg track:**`, `**Bug-fix track:**`) inside the sections.
+- If a section is genuinely empty, write `- — nothing` rather than padding.
+- Synthesize, don't dump. Never paste raw git log / observation lists — distill them.
+
+## Source priority (current → durable)
+
+Lead with the live session; use durable sources to fill gaps and cross-check.
+
+1. **Current session context — primary.** What *this* conversation has done, decided, and left open. Freshest signal, especially mid-task.
+2. **claude-mem recent observations** — the narrative across prior sessions (use the `mem-search` skill, or the recent-context already injected at session start).
+3. **Handoff + latest daily-log** — explicit `nextSteps` / `blockedItems` / `decisions` and `Tomorrow` / `Blocked`.
+4. **git** — ground truth of where the code actually sits.
+
+When the session is thin (e.g. right after a compact / brand-new session), lean harder on 2–4. When sources **disagree** — git shows work the session doesn't mention, or claude-mem says a thing shipped that the branch contradicts — that contradiction is a **⚠️ Watch** item, not noise.
+
+## How to build it
+
+**1. Resolve the current project** (degrade gracefully if not a squadrant project):
+
+```bash
+PROJECT_JSON=$(node -e '
+  const fs=require("fs"),os=require("os"),path=require("path");
+  const cfg=JSON.parse(fs.readFileSync(os.homedir()+"/.config/squadrant/config.json","utf8"));
+  const cwd=process.cwd();
+  let best=null;
+  for (const [name,p] of Object.entries(cfg.projects||{})) {
+    if (cwd===p.path || cwd.startsWith(p.path+"/")) {
+      if (!best || p.path.length>best.path.length) best={name,...p};
+    }
+  }
+  process.stdout.write(JSON.stringify(best||{}));
+' 2>/dev/null)
+echo "$PROJECT_JSON"
+```
+
+If empty `{}`: not inside a known squadrant project — build the report from **session context + git only**, and skip steps 2–3 below.
+
+Otherwise note `name` and `spokeVault` for the next steps.
+
+**2. Read the handoff WITHOUT consuming it** (note the `--keep` — never drop the `--keep`, or you destroy the next session's startup context):
+
+```bash
+~/.config/squadrant/scripts/read-handoff.sh "<spokeVault>" --keep
+```
+
+`{"exists": false}` means none — fine, skip it.
+
+**3. Read the latest daily-log** (if any):
+
+```bash
+ls -t "<spokeVault>"/daily-logs/*.md 2>/dev/null | head -1
+```
+
+Read that one file for `Completed` / `In Progress` / `Blocked` / `Tomorrow`.
+
+**4. Read git ground-truth:**
+
+```bash
+git -C "<project path or PWD>" status -sb && echo "---" && git -C "<project path or PWD>" log --oneline -8
+```
+
+**5. claude-mem** — if recent observations weren't already injected this session, pull them with the `mem-search` skill scoped to the project name.
+
+**6. Synthesize** all of the above into the `Right now →` line plus the four sections and print. Lead with the session, resolve disagreements into **⚠️ Watch**. Stop there — do not start acting on "Next" unless the user asks.

package/plugin/skills/wiki-ops/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: wiki-ops
+description: Compile discovered knowledge into persistent, cross-referenced wiki pages in spoke vaults. Use after learning something notable, at task completion, and during session shutdown.
+---
+
+# Wiki Operations
+
+## Overview
+
+The wiki is your project's compiled knowledge base. Unlike learnings (individual observations, possibly ephemeral), wiki pages are **persistent, cross-referenced, and indexed**.
+
+- **Learnings** = raw observations ("I found that X causes Y")
+- **Wiki pages** = compiled knowledge ("How X works", "Architecture of Y", "Patterns for Z")
+
+## When to Ingest
+
+1. **After task completion** — if you discovered how a system works, document it
+2. **After resolving a tricky bug** — document the root cause and fix pattern
+3. **When a learning is marked useful 2+ times** — promote it to a wiki page
+4. **During session shutdown** — review what you learned, compile if notable
+5. **When you notice a gap** — if you searched the wiki and didn't find what you needed, create the page after you find the answer
+
+## Creating/Updating a Wiki Page
+
+```bash
+~/.config/squadrant/scripts/wiki-ingest.sh "{spokeVaultPath}" "{slug}" "{title}" "{category}" "{body}" "{tags}" "{source}"
+```
+
+**Parameters:**
+- `slug`: URL-friendly name (e.g., `auth-flow`, `cairo-contract-patterns`)
+- `title`: Human-readable title
+- `category`: One of: `Architecture`, `Patterns`, `APIs`, `Configuration`, `Debugging`, `Conventions`, `Dependencies`, `Deployment`
+- `body`: Full markdown content (can be multi-paragraph)
+- `tags`: Comma-separated keywords
+- `source`: How this knowledge was discovered (e.g., "crew debugging issue #42")
+
+**Example:**
+```bash
+~/.config/squadrant/scripts/wiki-ingest.sh "/path/to/spoke" "starknet-account-deploy" "StarkNet Account Deployment" "Patterns" "Account deployment on StarkNet requires a two-step process:
+
+1. Compute the address from the class hash and constructor args
+2. Fund the computed address with ETH
+3. Call deploy_account
+
+Common pitfall: the salt must match between compute and deploy." "starknet,deployment,account" "crew debugging deploy failures"
+```
+
+## Querying the Wiki
+
+Before starting a new task, check if the wiki has relevant knowledge:
+
+```bash
+~/.config/squadrant/scripts/wiki-query.sh "{spokeVaultPath}" "{keyword}"
+```
+
+For a quick overview:
+```bash
+~/.config/squadrant/scripts/wiki-query.sh "{spokeVaultPath}" "{keyword}" --titles-only
+```
+
+To browse the full index:
+```bash
+cat "{spokeVaultPath}/wiki/index.md"
+```
+
+## Viewing Recent Changes
+
+```bash
+~/.config/squadrant/scripts/wiki-log.sh "{spokeVaultPath}" 10
+```
+
+## Promoting Learnings to Wiki
+
+When reviewing learnings and you find one that's been useful multiple times:
+
+1. Read the learning file
+2. Expand the observation into a full wiki page with context, examples, and related links
+3. Ingest via wiki-ingest.sh
+4. The original learning remains (it's the "source" reference)
+
+## Cross-Referencing
+
+When writing wiki page body content, reference related pages using `[[slug]]` syntax:
+```
+See also [[auth-flow]] for the authentication architecture.
+```
+
+After ingesting, check if existing pages should reference the new one.
+
+## Quality Guidelines
+
+- **Be specific**: "StarkNet account deployment requires 3 steps" > "Deployment is complex"
+- **Include examples**: Code snippets, command sequences, config fragments
+- **Note caveats**: Version-specific behavior, known limitations
+- **Cite sources**: Which task/issue/exploration revealed this knowledge
+- **Keep pages focused**: One concept per page, link to related pages

package/plugin/skills/wim/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: wim
+description: Shortcut for /where-i-am — print the tight "where am I on this project?" orientation report (Done / Next / Watch). Use when the user types /wim or asks where they are on the project.
+---
+
+# wim — shortcut for /where-i-am
+
+Shorthand alias. **Invoke the `where-i-am` skill** (via the Skill tool) and follow it exactly. All logic lives there — this file intentionally holds none, so the two never drift.

package/scripts/acceptance-interactive-codex.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Manual acceptance walk-through for spec §4.10 (squadrant interactive codex).
+# Run from the repo root after `npm run build`. Drives the full end-to-end
+# flow including a daemon-bounce reattach.
+set -euo pipefail
+
+PROJECT="${PROJECT:-SMOKE}"
+CWD="${CWD:-$(mktemp -d -t squadrant-iv-codex-XXXXXX)}"
+
+echo "=== squadrant interactive-codex acceptance (spec §4.10) ==="
+echo "Project: $PROJECT   cwd: $CWD"
+echo
+
+echo "=== 1. fresh build + relink ==="
+npm run build
+echo "    build OK"
+echo
+
+echo "=== 2. open a chat ==="
+echo "    squadrant crew chat --provider codex --project $PROJECT --cwd $CWD"
+echo
+echo "Manually, in the opened cmux workspace tab:"
+echo "  a. type: please write the string ACCEPT-OK to a file named demo.txt in the cwd"
+echo "  b. when the [approval] prompt appears, answer with: approve"
+echo "  c. wait for [done — type a follow-up or Ctrl-C], then type: thanks"
+echo "  d. observe a second [done] line"
+echo "  e. type: please run \"ls\" in this directory"
+echo "  f. press Ctrl-C mid-turn to verify SIGINT → turn/interrupt round-trips"
+echo
+echo "Verify in the host shell:"
+echo "  squadrant crew status $PROJECT <task-id>     # state is 'awaiting-input' (NOT 'done') after each turn"
+echo "  cat $CWD/demo.txt                          # contains ACCEPT-OK"
+echo
+
+echo "=== 3. simulate daemon bounce in another shell ==="
+echo "    launchctl kickstart -kp gui/\$(id -u)/com.squadrant.daemon"
+echo
+echo "Then check the cmux tab: expect a '(attached)' line within a few seconds"
+echo "and that the next 'say' continues on the SAME thread (codex remembers the"
+echo "earlier file write and 'thanks' exchange). This proves spec §5 / closes the"
+echo "interactive-codex slice of #86."
+echo
+
+echo "=== 4. gate promotion (HITL slice, spec §4.9) ==="
+echo "Open a new chat with --provider codex; ask codex to write a file in a path"
+echo "that needs approval, then IMMEDIATELY close the cmux tab without answering."
+echo "Wait 6 seconds, then run:"
+echo "    squadrant crew status $PROJECT <task-id>"
+echo "Expect 'gates' array containing one pending gate."
+echo "Resolve from the Captain:"
+echo "    squadrant crew reply $PROJECT <task-id> approve --gate <gateId>"
+echo "Re-attach to verify the turn completes:"
+echo "    squadrant crew attach <task-id>"
+echo
+
+echo "=== done — capture output to /tmp/iv-codex-acceptance.txt for the PR ==="

package/scripts/capture-skill.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Usage: capture-skill.sh <spoke-vault-path> <skill-name> <description> <body>
+# Captures a successful task pattern as a reusable skill (CAPTURED evolution)
+set -euo pipefail
+VAULT="${1:?Usage: capture-skill.sh <vault-path> <skill-name> <description> <body>}"
+SKILL_NAME="${2:?}"
+DESCRIPTION="${3:?}"
+BODY="${4:?}"
+DATE=$(date +"%Y-%m-%d")
+SKILL_DIR="${VAULT}/skills/${SKILL_NAME}"
+SKILL_FILE="${SKILL_DIR}/SKILL.md"
+
+mkdir -p "${SKILL_DIR}"
+
+if [ -f "$SKILL_FILE" ]; then
+  echo "Skill '${SKILL_NAME}' already exists at ${SKILL_FILE} — use fix-skill.sh to update it"
+  exit 1
+fi
+
+cat > "$SKILL_FILE" << EOF
+---
+name: ${SKILL_NAME}
+description: ${DESCRIPTION}
+captured: ${DATE}
+origin: auto-captured
+times_used: 0
+times_successful: 0
+---
+
+${BODY}
+EOF
+echo "Captured skill: $SKILL_FILE"

package/scripts/claude-iv-smoke.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// Daemon-level smoke for the claude interactive control-plane wiring.
+//
+// Runs against a PRIVATE temp-socket squadrantd started from the freshly-built
+// dist code in this branch — does NOT touch the shared system daemon (which
+// has other captains' tasks in flight; cannot bounce). Does NOT spawn a real
+// Claude process either (the smoke runner is itself a squadrant crew — no
+// nested crew spawns). Posts the same socket frames that runCrewSpawn would
+// post for a real Claude crew and verifies state transitions end-to-end.
+//
+// Invocation: node scripts/claude-iv-smoke.mjs
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { createConnection } from "node:net";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { startSquadrantd } from "../dist/control/squadrantd.js";
+
+const PROJECT = "smoke";
+const tmp = mkdtempSync(join(tmpdir(), "claude-iv-smoke-"));
+const SOCK = join(tmp, "c.sock");
+const h = startSquadrantd({ stateRoot: join(tmp, "state"), sockPath: SOCK, sweepMs: 0 });
+
+function rpc(req) {
+  return new Promise((resolve, reject) => {
+    const conn = createConnection(SOCK);
+    let buf = "";
+    conn.setEncoding("utf-8");
+    conn.on("connect", () => conn.write(JSON.stringify(req) + "\n"));
+    conn.on("data", (c) => {
+      buf += c;
+      const i = buf.indexOf("\n");
+      if (i < 0) return;
+      const line = buf.slice(0, i);
+      conn.end();
+      try {
+        const m = JSON.parse(line);
+        if (m.ok) resolve(m.reply);
+        else reject(new Error(m.error));
+      } catch (e) { reject(e); }
+    });
+    conn.on("error", reject);
+  });
+}
+
+async function step(label, fn) {
+  process.stdout.write(`\n--- ${label} ---\n`);
+  const r = await fn();
+  process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+  return r;
+}
+
+async function main() {
+  const taskId = randomUUID();
+  const now = Date.now();
+
+  // 1. Dispatch — daemon stores submitted, launchInteractive emits task.started.
+  const dispatched = await step("1. dispatch claude interactive", () =>
+    rpc({
+      kind: "dispatch",
+      record: {
+        id: taskId,
+        project: PROJECT,
+        provider: "claude",
+        mode: "interactive",
+        state: "submitted",
+        task: "smoke test — verify the daemon wires for claude interactive",
+        cwd: "/Users/q3labsadmin/me/claude-cockpit",
+        createdAt: now,
+        lastHeartbeat: now,
+        lastEvent: "dispatch",
+        heartbeatBudgetMs: 60000,
+        attempts: [{ attemptId: randomUUID(), startedAt: now, lastHeartbeatAt: now }],
+      },
+    }),
+  );
+  if (dispatched.state !== "submitted")
+    throw new Error(`expected state=submitted at dispatch ack, got ${dispatched.state}`);
+
+  // Brief settle for the async task.started emit.
+  await new Promise((r) => setTimeout(r, 50));
+
+  // 2. Status should show working now (task.started landed).
+  const afterStart = await step("2. status after launchInteractive emits task.started", () =>
+    rpc({ kind: "status", project: PROJECT, id: taskId }),
+  );
+  if (afterStart.state !== "working")
+    throw new Error(`expected state=working after task.started, got ${afterStart.state}`);
+
+  // 3. Simulate Stop hook → task.progress (liveness only — anti-#2576).
+  const afterProgress = await step("3. POST task.progress (simulating Stop hook from cmux tab)", () =>
+    rpc({
+      kind: "event",
+      project: PROJECT,
+      event: { type: "task.progress", id: taskId, note: "stop" },
+    }),
+  );
+  if (afterProgress.state !== "working")
+    throw new Error(`bare Stop hook MUST NOT advance state (anti-#2576). Got: ${afterProgress.state}`);
+  if (afterProgress.lastEvent !== "task.progress")
+    throw new Error(`expected lastEvent=task.progress, got ${afterProgress.lastEvent}`);
+
+  // 4. Simulate explicit `squadrant crew signal done` → task.done with resultRef.
+  const afterDone = await step("4. POST task.done (simulating 'squadrant crew signal done')", () =>
+    rpc({
+      kind: "event",
+      project: PROJECT,
+      event: { type: "task.done", id: taskId, resultRef: "/tmp/smoke-result.txt" },
+    }),
+  );
+  if (afterDone.state !== "done")
+    throw new Error(`expected state=done after explicit signal, got ${afterDone.state}`);
+
+  // 5. Status read confirms terminal state without any pane scrape.
+  const final = await step("5. status read — captain learns 'done' WITHOUT scraping", () =>
+    rpc({ kind: "status", project: PROJECT, id: taskId }),
+  );
+  if (final.state !== "done")
+    throw new Error(`final read mismatch: ${final.state}`);
+  if (final.resultRef !== "/tmp/smoke-result.txt")
+    throw new Error(`final resultRef mismatch: ${final.resultRef}`);
+
+  process.stdout.write("\n✔ ALL ASSERTIONS PASSED — claude interactive control-plane wiring works end-to-end.\n");
+  process.stdout.write(`  taskId: ${taskId}\n`);
+}
+
+main()
+  .then(() => { h.stop(); rmSync(tmp, { recursive: true, force: true }); process.exit(0); })
+  .catch((e) => {
+    process.stderr.write(`✘ SMOKE FAILED: ${e.message}\n`);
+    try { h.stop(); rmSync(tmp, { recursive: true, force: true }); } catch { /* noop */ }
+    process.exit(1);
+  });

package/scripts/fix-skill.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Usage: fix-skill.sh <spoke-vault-path> <skill-name> <new-body>
+# Fixes a broken skill in-place (FIX evolution) — backs up the old version
+set -euo pipefail
+VAULT="${1:?Usage: fix-skill.sh <vault-path> <skill-name> <new-body>}"
+SKILL_NAME="${2:?}"
+NEW_BODY="${3:?}"
+DATE=$(date +"%Y-%m-%d")
+SKILL_DIR="${VAULT}/skills/${SKILL_NAME}"
+SKILL_FILE="${SKILL_DIR}/SKILL.md"
+
+if [ ! -f "$SKILL_FILE" ]; then
+  echo "Skill '${SKILL_NAME}' not found at ${SKILL_FILE}"
+  exit 1
+fi
+
+# Backup old version
+BACKUP="${SKILL_DIR}/SKILL.${DATE}.bak.md"
+cp "$SKILL_FILE" "$BACKUP"
+
+# Extract existing frontmatter fields, bump version info
+OLD_DESC=$(grep '^description:' "$SKILL_FILE" | sed 's/^description: //')
+OLD_TIMES_USED=$(grep '^times_used:' "$SKILL_FILE" | sed 's/^times_used: //' || echo "0")
+OLD_TIMES_SUCCESS=$(grep '^times_successful:' "$SKILL_FILE" | sed 's/^times_successful: //' || echo "0")
+
+cat > "$SKILL_FILE" << EOF
+---
+name: ${SKILL_NAME}
+description: ${OLD_DESC}
+captured: ${DATE}
+origin: fixed
+times_used: ${OLD_TIMES_USED}
+times_successful: ${OLD_TIMES_SUCCESS}
+last_fixed: ${DATE}
+---
+
+${NEW_BODY}
+EOF
+echo "Fixed skill: $SKILL_FILE (backup: $BACKUP)"

package/scripts/gen-codex-types.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Regenerate the codex app-server protocol bindings.
+# Requires codex-cli ≥0.130.0 on PATH.
+set -euo pipefail
+OUT="src/control/codex/protocol"
+rm -rf "$OUT"
+mkdir -p "$OUT"
+codex app-server generate-ts --experimental --out "$OUT"
+cat > "$OUT/README.md" <<'MD'
+# codex app-server protocol bindings (auto-generated)
+
+Generated by `npm run codex:gen-types` (`scripts/gen-codex-types.sh`).
+**DO NOT EDIT BY HAND.** Re-run the generator to update.
+
+Source: `codex app-server generate-ts --experimental --out <here>` against
+`codex-cli ≥0.130.0`. See `docs/specs/2026-05-20-squadrant-interactive-codex-design.md` §3.3.
+MD
+echo "Generated $OUT"

package/scripts/mailbox-injector-smoke.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// scripts/mailbox-injector-smoke.mjs
+//
+// E2E smoke for mailbox-injector refactor (replaces #109/#111 socket push).
+// Spins up a real squadrantd on a temp socket + stateRoot, drives a few
+// task.done events through the daemon, then verifies:
+//   1. defaultNotify writes structured entries to <stateRoot>/inbox/<project>.log
+//   2. readFromCursor yields each entry exactly once, in order
+//   3. writeCursor persists, readCursor returns the saved seq
+//   4. After a simulated "injector offline" window, resuming from the cursor
+//      reads only the entries added during the outage (no duplicates, no gaps)
+//
+// Uses startSquadrantd + sendRequest directly (same pattern as
+// scripts/smoke-push-notify.mjs) rather than env vars — the daemon's CLI
+// surface takes stateRoot/sockPath as arguments, not env vars.
+
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const distEntry = pathToFileURL(join(__dirname, "..", "dist", "control", "squadrantd.js")).href;
+const distProto = pathToFileURL(join(__dirname, "..", "dist", "control", "protocol.js")).href;
+const distMailbox = pathToFileURL(join(__dirname, "..", "dist", "control", "mailbox.js")).href;
+
+const { startSquadrantd } = await import(distEntry);
+const { sendRequest } = await import(distProto);
+const mailbox = await import(distMailbox);
+
+const evidencePath = join(__dirname, "..", ".mailbox-injector-smoke.local");
+const evidence = [];
+const record = (m) => { evidence.push(m); process.stdout.write(m + "\n"); };
+
+const dir = mkdtempSync(join(tmpdir(), "mailbox-smoke-"));
+const stateRoot = join(dir, "state");
+const sock = join(dir, "c.sock");
+
+const handle = startSquadrantd({ stateRoot, sockPath: sock, sweepMs: 0 });
+
+const baseRec = (id, overrides = {}) => ({
+  id, project: "demo", provider: "claude", mode: "headless",
+  state: "submitted", task: "mailbox smoke", cwd: "/",
+  createdAt: 1, lastHeartbeat: 1, lastEvent: "",
+  heartbeatBudgetMs: 60000,
+  attempts: [{ attemptId: "a0", startedAt: 1, lastHeartbeatAt: 1 }],
+  ...overrides,
+});
+
+let failures = 0;
+const assert = (cond, label) => {
+  if (cond) { record(`  ✓ ${label}`); }
+  else { record(`  ✗ ${label}`); failures++; }
+};
+
+try {
+  record(`# Mailbox + injector smoke — ${new Date().toISOString()}`);
+  record(`state: ${stateRoot}`);
+  record(`socket: ${sock}`);
+
+  record("\n[1] dispatch + task.done → mailbox file gets one entry");
+  await sendRequest(sock, { kind: "seed", record: baseRec("smoke-1abcdef0", { state: "working" }) });
+  await sendRequest(sock, { kind: "event", project: "demo",
+    event: { type: "task.done", id: "smoke-1abcdef0", resultRef: "/r1" } });
+  await new Promise((r) => setTimeout(r, 150));
+
+  const logPath = join(stateRoot, "inbox", "demo.log");
+  assert(existsSync(logPath), `mailbox file created at ${logPath}`);
+  const lines1 = readFileSync(logPath, "utf-8").trim().split("\n").filter(Boolean);
+  assert(lines1.length === 1, `exactly one entry (got ${lines1.length})`);
+  const entry1 = JSON.parse(lines1[0]);
+  assert(entry1.seq === 1, `seq=1 (got ${entry1.seq})`);
+  assert(entry1.kind === "task.done", `kind=task.done (got ${entry1.kind})`);
+  assert(entry1.taskId === "smoke-1abcdef0", `taskId matches`);
+
+  record("\n[2] simulate injector reading from cursor");
+  const items = [];
+  for await (const it of mailbox.readFromCursor({ stateRoot, project: "demo", fromSeq: 1 })) items.push(it);
+  assert(items.length === 1, `injector reads 1 entry from cursor (got ${items.length})`);
+  await mailbox.writeCursor({ stateRoot, project: "demo", subscriber: "captain", lastAckedSeq: 1 });
+  const cursor = await mailbox.readCursor({ stateRoot, project: "demo", subscriber: "captain" });
+  assert(cursor?.lastAckedSeq === 1, `cursor advanced to 1 (got ${cursor?.lastAckedSeq})`);
+
+  record("\n[3] simulate injector 'offline' — dispatch more events");
+  await sendRequest(sock, { kind: "seed", record: baseRec("smoke-2feedface", { state: "working" }) });
+  await sendRequest(sock, { kind: "event", project: "demo",
+    event: { type: "task.done", id: "smoke-2feedface", resultRef: "/r2" } });
+  await sendRequest(sock, { kind: "seed", record: baseRec("smoke-3deadbeef", { state: "working" }) });
+  await sendRequest(sock, { kind: "event", project: "demo",
+    event: { type: "task.blocked", id: "smoke-3deadbeef", question: "what now?" } });
+  await new Promise((r) => setTimeout(r, 200));
+
+  record("\n[4] injector resumes — reads only new events, in order, no duplicates");
+  const items2 = [];
+  for await (const it of mailbox.readFromCursor({ stateRoot, project: "demo", fromSeq: 2 })) items2.push(it);
+  assert(items2.length === 2, `replay yields exactly 2 new entries (got ${items2.length})`);
+  assert(items2[0]?.seq === 2 && items2[1]?.seq === 3,
+    `seqs are 2,3 (got ${items2.map((x) => x.seq).join(",")})`);
+  assert(items2[0]?.kind === "task.done", `seq=2 is task.done`);
+  assert(items2[1]?.kind === "task.blocked", `seq=3 is task.blocked`);
+
+  record("\n[5] liveness events (task.started, task.progress) do NOT write to mailbox");
+  // firePush gates on ATTENTION_STATES = {done, blocked, failed, stalled}.
+  // task.started / task.progress drive working state → must be suppressed.
+  await sendRequest(sock, { kind: "seed", record: baseRec("smoke-4cafebabe", { state: "submitted" }) });
+  await sendRequest(sock, { kind: "event", project: "demo",
+    event: { type: "task.started", id: "smoke-4cafebabe" } });
+  await sendRequest(sock, { kind: "event", project: "demo",
+    event: { type: "task.progress", id: "smoke-4cafebabe" } });
+  await sendRequest(sock, { kind: "event", project: "demo",
+    event: { type: "task.progress", id: "smoke-4cafebabe" } });
+  await new Promise((r) => setTimeout(r, 200));
+
+  const linesAfter = readFileSync(logPath, "utf-8").trim().split("\n").filter(Boolean);
+  assert(linesAfter.length === 3,
+    `mailbox still has 3 entries after liveness traffic (got ${linesAfter.length}) — liveness suppressed`);
+
+  record(`\n${failures === 0 ? "✔ ALL SMOKE ASSERTIONS PASSED" : `✗ ${failures} FAILURES`}`);
+} finally {
+  handle.stop();
+  writeFileSync(evidencePath, evidence.join("\n") + "\n");
+  record(`evidence: ${evidencePath}`);
+  process.exit(failures > 0 ? 1 : 0);
+}

package/scripts/mark-learning-useful.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Usage: mark-learning-useful.sh <learning-file-path>
+# Increments times_useful counter on a learning
+set -euo pipefail
+FILE="${1:?Usage: mark-learning-useful.sh <learning-file-path>}"
+
+if [ ! -f "$FILE" ]; then
+  echo "Learning file not found: $FILE"
+  exit 1
+fi
+
+# Increment times_useful
+CURRENT=$(grep '^times_useful:' "$FILE" | sed 's/^times_useful: //')
+NEW=$((${CURRENT:-0} + 1))
+sed -i '' "s/^times_useful: .*/times_useful: ${NEW}/" "$FILE"
+
+# Increment times_loaded
+LOADED=$(grep '^times_loaded:' "$FILE" | sed 's/^times_loaded: //')
+NEW_LOADED=$((${LOADED:-0} + 1))
+sed -i '' "s/^times_loaded: .*/times_loaded: ${NEW_LOADED}/" "$FILE"
+
+echo "Marked useful (${NEW}x): $FILE"