shadok-ai 0.14.7 → 0.14.8

package/context/ledger-reflex.md

@@ -18,19 +18,27 @@ Then let it steer you:
   ("de mémoire, à faire — dis-moi si c'est déjà réglé"), don't assert;
 - rows printed under **"related rows — they may NOT answer your question"** are
   leads, not an answer: you are still in the UNKNOWN case above;
-- a **stale** record (days old) → confirm before acting.
+- a **stale** record (days old) → confirm before acting; the age shown is when
+  the claim was last CONFIRMED, not when the text was last edited;
+- a row tagged **`· fact`** has no lifecycle — `current` or `stale`, never
+  "done": don't read its status as a position in open → resolved, and don't
+  close it because surrounding work finished. A **`· decision`** stands until
+  something supersedes it.
 
 **You are also pushed the changes.** Ahead of each turn you are given — a user
 message, or a scheduled/automated run — you may receive a
-`⟦ledger · N updates since your last message⟧` block listing what sibling agents
-resolved or decided since you last heard — each line `• [id] entity — status`.
-Treat it as current status (don't re-raise what it shows resolved). It is the
-push half; `check` is still there for older or specific items the block didn't
-carry.
+`⟦ledger · N updates⟧` block listing what sibling agents resolved or decided
+since you last heard — `• [id] entity — status ↳ what happened`, all on one
+line. Treat it as current status
+(don't re-raise what it shows resolved). It is the push half; `check` is still
+there for older or specific items the block didn't carry.
 
 When you **resolve, decide, or change** something notable, record it so the next
 agent doesn't redo it:
-`node ~/.claude/skills/shadok-ledger/ledger.mjs record --entity "<name>" --status <resolved|open|in-progress|decided> --note "<line>" --source "<PR#/who>"`.
+`node ~/.claude/skills/shadok-ledger/ledger.mjs record --entity "<name>" --status <resolved|open|in-progress> --note "<line>" --source "<PR#/who>"`.
+Open the note with the sentence that says WHAT happened — it is what siblings get
+pushed. For something with no lifecycle, pass `--kind fact` or `--kind decision`
+instead of a status; to say you re-checked a row and nothing moved, `--verified`.
 To update an item you saw in the block, quote its handle instead of retyping the
 name: `… record --id <id> --status resolved --note "<line>"`.
 

package/context/ledger-skill/SKILL.md

@@ -37,7 +37,14 @@ you nothing.
   the search found no row that answers you, only rows sharing some words. You
   are still in the UNKNOWN case above. Read them as leads (they may point at the
   right topic under another name), never as a status to assert.
-- a **stale** row (many days old) → hedge and confirm before acting.
+- a **stale** row (many days old) → hedge and confirm before acting. The age
+  shown is when the row's claim was last **confirmed**, not when its text was
+  last edited.
+- a row tagged **`· fact`** has no lifecycle: it is `current` or `stale`, never
+  "done". Do not read its status as a position in open → resolved, and do not
+  close it because the work around it finished — it stays true.
+- a row tagged **`· decision`** is a standing decision, not a phase of a task.
+  It holds until something supersedes it.
 
 This fires on status-dependent claims (a bug being open, a PR unmerged, a task
 undone, a campaign live). A **durable lesson/constraint** ("don't buy the
@@ -49,13 +56,46 @@ Record it so the next agent doesn't redo it:
 
 ```
 node ~/.claude/skills/shadok-ledger/ledger.mjs record \
-  --entity "<name>" --status <resolved|open|in-progress|decided> \
+  --entity "<name>" --status <resolved|open|in-progress> \
   --note "<one line>" --source "<PR#, session, who>"
 ```
 
 Re-recording the same entity **supersedes** its row (no duplicates). Log facts —
 resolutions, decisions, state changes, launched actions — never chatter.
 
+**Open the note with the one sentence that says what happened.** Its first
+sentence is what siblings are shown in the `⟦ledger⟧` block pushed ahead of their
+messages — the entity name alone cannot tell them what changed about it. Put the
+consequence first, details after.
+
+## Is it a task, a fact, or a decision?
+
+A **task** has a lifecycle, so a status is the right thing to carry and closing
+it is normal. That is the default and needs no flag. The other two do:
+
+```
+… record --entity "nightly import window" --kind fact \
+    --note "Runs 03:00-03:40 Europe/Paris, after the extraction job."
+… record --entity "ledger stays a state table" --kind decision \
+    --note "Supersede, not append, so size is bounded by live topics."
+```
+
+`--kind` replaces `--status` for these two (they get `current` / `decided`), because
+neither has phases to report. This matters: a **fact** marked `resolved` stops
+being read by anything that filters on open work, while remaining perfectly true
+— which is how a job finished on the 9th was still believed pending on the 12th.
+
+When you re-check a row and nothing has changed, say so instead of rewriting it:
+
+```
+… record --id <id> --verified
+```
+
+That refreshes its freshness only. It deliberately does **not** enter anyone's
+pushed block — "I looked, nothing moved" is not news. Conversely, editing a note
+does **not** refresh freshness: only a status (or `--verified`) counts as having
+looked.
+
 Every row has a short **id** (shown as `[id]` in `check`/`list` and in the ledger
 block pushed ahead of your messages). To update a row you already saw, quote its
 id instead of retyping the name — no risk of a typo forking a second row:

package/context/ledger-skill/ledger-core.d.mts

@@ -0,0 +1,34 @@
+// Types for the skill's pure core, so the SERVER can import the one source of
+// the ledger's logic instead of growing a second copy of it (CLAUDE.md: this
+// file is the single source, no duplication to drift). The core itself stays
+// plain .mjs — it is copied verbatim into ~/.claude/skills/ at every boot and
+// must run with no build step of its own.
+export interface LedgerCoreRow {
+  id?: string;
+  entity: string;
+  status: string;
+  kind?: string;
+  note?: string;
+  source?: string;
+  updatedAt?: number;
+  verifiedAt?: number;
+}
+export type LedgerKind = "task" | "fact" | "decision";
+export const KINDS: LedgerKind[];
+export function normEntity(s: unknown): string;
+export function normKind(k: unknown): LedgerKind | null;
+export function rowKind(entry: unknown): LedgerKind;
+export function resolveId<T extends LedgerCoreRow>(entries: T[], idOrPrefix: unknown): T | null;
+export function upsertEntry<T extends LedgerCoreRow>(
+  entries: T[],
+  patch: Partial<LedgerCoreRow> & { verified?: boolean },
+  now: number,
+  newId?: string,
+): T[];
+export function tokenize(s: unknown): string[];
+export function searchEntries<T extends LedgerCoreRow>(
+  entries: T[],
+  query: string,
+  opts?: { strong?: number; weak?: number },
+): { strong: T[]; weak: T[] };
+export function ageDays(entry: { updatedAt?: number; verifiedAt?: number }, now: number): number;

package/context/ledger-skill/ledger-core.mjs

@@ -26,6 +26,52 @@ export function resolveId(entries, idOrPrefix) {
   return pre.length === 1 ? pre[0] : null;
 }
 
+/* --------------------------------------------------------------------- *
+ * A row's KIND: a task, a fact, or a decision.
+ *
+ * The table used to treat all three identically, and they are not the same
+ * object. A TASK has a lifecycle, so a status is the right thing to carry and
+ * closing it is normal. A FACT has no lifecycle — only a date on which someone
+ * last confirmed it — so closing it makes it DISAPPEAR WHILE IT STAYS TRUE,
+ * which is how a finished job was still believed pending three days later. And
+ * `decided` was never a phase of the open → in-progress → resolved lifecycle it
+ * sat next to: it is a kind wearing a status's clothes.
+ *
+ * Design: docs/superpowers/specs/2026-10-13-ledger-kind-and-headline.md
+ * --------------------------------------------------------------------- */
+
+export const KINDS = ["task", "fact", "decision"];
+
+/** The status a kind with NO lifecycle gets when none is given, so an agent is
+ *  never pushed into inventing a word for a thing that has no phases. Keeping
+ *  `status` always present is what leaves every existing reader — the pushed
+ *  delta, the GUI viewer, a consumer's recap filter — working untouched. */
+const KIND_STATUS = { fact: "current", decision: "decided" };
+
+/**
+ * Validate a `--kind`: one of KINDS, or null when absent. An unknown one THROWS
+ * rather than being stored — a typo that silently became a fourth kind would be
+ * invisible for exactly as long as nobody went looking.
+ */
+export function normKind(k) {
+  const s = String(k ?? "").trim().toLowerCase();
+  if (!s) return null;
+  if (!KINDS.includes(s)) throw new Error(`unknown kind "${k}" — use one of: ${KINDS.join(", ")}`);
+  return s;
+}
+
+/**
+ * What kind a row IS — read, never written back. An absent `kind` reads as
+ * `decision` when the status is `decided` (that is what the word already meant)
+ * and as `task` otherwise, so the rows recorded before this existed keep their
+ * bytes and still render correctly. Assert only what you saw.
+ */
+export function rowKind(entry) {
+  const k = String(entry?.kind ?? "").trim().toLowerCase();
+  if (KINDS.includes(k)) return k;
+  return normEntity(entry?.status) === "decided" ? "decision" : "task";
+}
+
 /**
  * Upsert a row, two ways:
  *  - `patch.id` present → UPDATE that exact row in place (resolved via resolveId),
@@ -35,20 +81,54 @@ export function resolveId(entries, idOrPrefix) {
  *    its id (the handle is durable across every write), or create a new row with
  *    `newId`.
  * `now` (epoch ms) and `newId` are injected so the core stays pure/testable.
+ *
+ * Two clocks, because an EDIT is not an OBSERVATION. `updatedAt` is when the row
+ * was last written; `verifiedAt` is when its claim was last confirmed, and it is
+ * what the staleness hedge reads. Rewriting a note used to rejuvenate a row
+ * nobody had re-checked in a month, which silently switched that hedge off:
+ *
+ *   create ................................ both move
+ *   --status given (even the same value) .. both move — re-asserting a status
+ *                                           IS confirming it
+ *   --note / --source / --entity only ..... updatedAt moves, verifiedAt does NOT
+ *   --verified alone ...................... verifiedAt moves, updatedAt does NOT
+ *
+ * That last line is deliberate: a row whose `updatedAt` does not move stays out
+ * of every sibling's pushed delta, and "I re-checked, nothing changed" is not
+ * news — pushing it to every agent is the noise a state table exists to avoid.
+ * A row that predates `verifiedAt` inherits its old `updatedAt` as the moment it
+ * was last observed, which is the truth and makes the migration lazy, per row.
  */
 export function upsertEntry(entries, patch, now, newId) {
+  const kind = normKind(patch.kind); // refuses an unknown kind before anything is written
+  const statusGiven = patch.status != null && String(patch.status).trim() !== "";
+
   if (patch.id != null && String(patch.id).trim()) {
     const cur = resolveId(entries, patch.id);
     if (!cur) throw new Error(`no ledger entry with id "${patch.id}"`);
+    // `kind` is a property of the ENTITY, not of this write: keep the stored one
+    // when none is given, like the id.
+    const effKind = kind ?? normKind(cur.kind);
+    // Promoting a row to a lifecycle-less kind supplies that kind's status, so
+    // `--id X --kind fact` does not leave a stale `resolved` on a fact.
+    const status = statusGiven
+      ? String(patch.status).trim()
+      : kind && kind !== rowKind(cur) && KIND_STATUS[kind]
+        ? KIND_STATUS[kind]
+        : cur.status;
+    const edited =
+      statusGiven || kind != null || patch.note != null || patch.source != null || patch.entity != null;
+    const observed = statusGiven || patch.verified === true || status !== cur.status;
     const row = {
       id: cur.id,
       entity:
         patch.entity != null && String(patch.entity).trim() ? String(patch.entity).trim() : cur.entity,
-      status:
-        patch.status != null && String(patch.status).trim() ? String(patch.status).trim() : cur.status,
+      status,
+      ...(effKind ? { kind: effKind } : {}),
       ...((patch.note ?? cur.note) ? { note: String(patch.note ?? cur.note).trim() } : {}),
       ...((patch.source ?? cur.source) ? { source: String(patch.source ?? cur.source).trim() } : {}),
-      updatedAt: now,
+      updatedAt: edited ? now : (cur.updatedAt ?? now),
+      verifiedAt: observed ? now : (cur.verifiedAt ?? cur.updatedAt ?? now),
     };
     return [...entries.filter((e) => e.id !== cur.id), row];
   }
@@ -56,13 +136,20 @@ export function upsertEntry(entries, patch, now, newId) {
   const key = normEntity(patch.entity);
   if (!key) throw new Error("entity is required");
   const existing = entries.find((e) => normEntity(e.entity) === key);
+  const effKind = kind ?? normKind(existing?.kind);
+  const status = statusGiven
+    ? String(patch.status).trim()
+    : (effKind && KIND_STATUS[effKind]) || String(patch.status ?? "").trim();
+  const observed = statusGiven || patch.verified === true || status !== existing?.status;
   const row = {
     id: existing?.id ?? newId,
     entity: String(patch.entity).trim(),
-    status: String(patch.status ?? "").trim(),
+    status,
+    ...(effKind ? { kind: effKind } : {}),
     ...(patch.note ? { note: String(patch.note).trim() } : {}),
     ...(patch.source ? { source: String(patch.source).trim() } : {}),
     updatedAt: now,
+    verifiedAt: observed ? now : (existing?.verifiedAt ?? existing?.updatedAt ?? now),
   };
   return [...entries.filter((e) => normEntity(e.entity) !== key), row];
 }
@@ -181,7 +268,12 @@ export function searchEntries(entries, query, opts = {}) {
   };
 }
 
-/** Whole days since a row was last touched — the freshness the reflex hedges on. */
+/**
+ * Whole days since the row's claim was last CONFIRMED — the freshness the reflex
+ * hedges on. `verifiedAt` first: reading `updatedAt` meant any edit, down to a
+ * reworded note, reset the age of a row nobody had re-checked. Falls back to
+ * `updatedAt` for the rows recorded before the field existed.
+ */
 export function ageDays(entry, now) {
-  return Math.floor((now - (entry.updatedAt ?? now)) / 86_400_000);
+  return Math.floor((now - (entry.verifiedAt ?? entry.updatedAt ?? now)) / 86_400_000);
 }

package/context/ledger-skill/ledger.mjs

@@ -10,7 +10,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
-import { upsertEntry, searchEntries, ageDays, resolveId, normEntity } from "./ledger-core.mjs";
+import { upsertEntry, searchEntries, ageDays, resolveId, normEntity, rowKind, KINDS } from "./ledger-core.mjs";
 
 const FILE =
   (process.env.SHADOK_LEDGER_FILE || "").trim() ||
@@ -42,11 +42,17 @@ function mintId(rows) {
   return crypto.randomBytes(4).toString("hex");
 }
 
+/** Flags that take NO value, listed rather than guessed: inferring "the next arg
+ *  starts with -- so this one is a boolean" would misread `--note "--foo"`. */
+const BOOL_FLAGS = new Set(["verified"]);
+
 /** `--key value` pairs → object. Values may be quoted by the shell already. */
 function parseFlags(args) {
   const out = {};
   for (let i = 0; i < args.length; i++) {
-    if (args[i].startsWith("--")) out[args[i].slice(2)] = args[++i] ?? "";
+    if (!args[i].startsWith("--")) continue;
+    const key = args[i].slice(2);
+    out[key] = BOOL_FLAGS.has(key) ? true : (args[++i] ?? "");
   }
   return out;
 }
@@ -54,8 +60,17 @@ function parseFlags(args) {
 function fmt(e, now) {
   const age = ageDays(e, now);
   const when = age <= 0 ? "today" : age === 1 ? "1d ago" : `${age}d ago`;
+  const kind = rowKind(e);
+  // Say "verified" wherever the two clocks have parted company — and always for
+  // a fact, whose whole state IS its freshness. A bare age next to a row last
+  // confirmed a month ago but reworded yesterday is the lie this removes.
+  const parted = e.verifiedAt && e.updatedAt && e.verifiedAt !== e.updatedAt;
+  const stamp = kind === "fact" || parted ? `verified ${when}` : when;
+  // `task` is the default and the overwhelming majority: tagging it would be
+  // noise on every line. The two that change how a status must be READ are named.
+  const tag = kind === "task" ? "" : ` · ${kind}`;
   const handle = e.id ? `[${e.id}] ` : "";
-  const head = `• ${handle}${e.entity} — ${e.status} (${when}${e.source ? ` · ${e.source}` : ""})`;
+  const head = `• ${handle}${e.entity} — ${e.status}${tag} (${stamp}${e.source ? ` · ${e.source}` : ""})`;
   return e.note ? `${head}\n    ${e.note}` : head;
 }
 
@@ -89,11 +104,18 @@ if (cmd === "check") {
   // Two shapes: create/supersede by --entity (+ --status), or update an existing
   // row by its --id handle (change any of status/note/source; entity optional).
   const byId = f.id != null && String(f.id).trim();
-  const idHasNoFields = f.status == null && f.note == null && f.source == null && f.entity == null;
-  if (byId ? idHasNoFields : !f.entity || !f.status) {
+  const idHasNoFields =
+    f.status == null && f.note == null && f.source == null && f.entity == null &&
+    f.kind == null && f.verified == null;
+  // A fact or a decision has no lifecycle, so `--kind` stands in for `--status`:
+  // requiring one would only invite an invented word.
+  const hasStatus = !!f.status || !!f.kind;
+  if (byId ? idHasNoFields : !f.entity || !hasStatus) {
     console.error(
       'usage: ledger record --entity "<name>" --status <resolved|open|in-progress|decided> [--note "<line>"] [--source "<ref>"]\n' +
-        '   or: ledger record --id <handle> [--status <…>] [--note "<line>"] [--source "<ref>"]',
+        `   or: ledger record --entity "<name>" --kind <${KINDS.join("|")}> [--note "<line>"] [--source "<ref>"]\n` +
+        '   or: ledger record --id <handle> [--status <…>] [--kind <…>] [--note "<line>"] [--source "<ref>"]\n' +
+        '   or: ledger record --id <handle> --verified     (still true/current — nothing else changed)',
     );
     process.exit(2);
   }
@@ -102,7 +124,15 @@ if (cmd === "check") {
   try {
     rows = upsertEntry(
       rows0,
-      { id: f.id, entity: f.entity, status: f.status, note: f.note, source: f.source },
+      {
+        id: f.id,
+        entity: f.entity,
+        status: f.status,
+        kind: f.kind,
+        verified: f.verified === true,
+        note: f.note,
+        source: f.source,
+      },
       now,
       mintId(rows0),
     );
@@ -112,7 +142,8 @@ if (cmd === "check") {
   }
   save(rows);
   const row = byId ? resolveId(rows, f.id) : rows.find((r) => normEntity(r.entity) === normEntity(f.entity));
-  console.log(`recorded: ${row.entity} — ${row.status} [${row.id}]`);
+  const k = rowKind(row);
+  console.log(`recorded: ${row.entity} — ${row.status}${k === "task" ? "" : ` · ${k}`} [${row.id}]`);
 } else if (cmd === "list") {
   const rows = searchEntries(load(), "").strong;
   console.log(rows.length ? rows.map((e) => fmt(e, now)).join("\n") : "(ledger empty)");

package/dist/ledger.d.ts

@@ -18,9 +18,16 @@ export interface LedgerRow {
     id?: string;
     entity: string;
     status: string;
+    /** `task` | `fact` | `decision` — absent on every row recorded before it
+     *  existed, which `rowKind` reads rather than rewriting them. */
+    kind?: string;
     note?: string;
     source?: string;
+    /** When the row was last WRITTEN. */
     updatedAt?: number;
+    /** When its claim was last CONFIRMED — the freshness, which an edit must not
+     *  move. Absent on older rows; `ageDays` falls back to `updatedAt`. */
+    verifiedAt?: number;
 }
 /** The per-instance ledger file, keyed by the launch dir (same encoding as
  *  channels/crons). Distinct launch dirs → distinct ledgers. */
@@ -46,17 +53,45 @@ export declare function deltaSince(rows: LedgerRow[], watermark: number, cap: nu
     rows: LedgerRow[];
     total: number;
 };
-/** The delta block the agent sees ahead of a human prompt. English (it is
- *  written into the transcript — repo side). One line per row: `• [id] entity —
- *  status (source)`; an overflow line when capped. */
+/**
+ * The one line of the note that says WHAT happened, DERIVED rather than asked
+ * for. The block used to carry `[id] entity — status` and nothing else, so the
+ * entity *label* was the whole payload — and a label written as a topic name
+ * ("report regeneration, 15 test accounts") cannot say what changed about it.
+ * That is how work finished on the 9th was still believed pending on the 12th.
+ *
+ * Derived, because the alternative — a mandatory `--headline` — asks every agent
+ * for writing discipline (which nothing enforces) and covers none of the rows
+ * already recorded. The note's first sentence needs neither.
+ */
+export declare function headline(note: string | undefined, max?: number): string;
+/**
+ * The delta block the agent sees ahead of a prompt. English (it is written into
+ * the transcript — repo side). ONE line, within `BLOCK_MAX` (see above): per row
+ * `• [id] entity — status (source)`, the kind when it is not the default `task`,
+ * and `↳ <headline>` for what actually happened. Rows that do not fit the budget
+ * become the overflow pointer rather than a second line.
+ */
 export declare function formatLedgerBlock(rows: LedgerRow[], total: number): string;
-/** Prepend the block as its own leading lines. Idempotent. */
+/** Prepend the block as its own leading line. Idempotent. */
 export declare function markLedgerBlock(text: string, block: string): string;
-/** Does this text open with a pushed ledger block? */
+/** Does this text open with a pushed ledger block?
+ *
+ *  `⟧` CLOSES the header, it no longer ENDS the line: a one-line block continues
+ *  with its rows after it. Testing `endsWith` here was the first thing the
+ *  one-line format broke, and it fails open — detection returns false, nothing
+ *  is stripped, and the whole block is shown to the user in the chat. The old
+ *  multi-line shape satisfies this test too, so replayed transcripts are
+ *  unaffected. */
 export declare function hasLedgerBlock(text: string): boolean;
-/** Remove a leading ledger block — its header line and the contiguous `• ` bullet
- *  lines that follow it — leaving whatever came after (e.g. the ⟦platform⟧ header
- *  and the user's message). A plain message is returned untouched. */
+/** Remove a leading ledger block, leaving whatever came after (the ⟦platform⟧
+ *  header and the user's message). A plain message is returned untouched.
+ *
+ *  The block is one line now, so that is usually all this drops — but it must
+ *  keep understanding the HISTORICAL multi-line shape (header, `• ` bullets,
+ *  indented `↳` headlines), because `loadHistory` replays transcripts written
+ *  before the format changed and a block it fails to strip is a block the user
+ *  reads in the chat. */
 export declare function stripLedgerBlock(text: string): string;
 /** Where this instance stores its agents' ledger watermarks. Beside the table,
  *  same launch-dir encoding, distinct name — writing one must never clobber the

package/dist/ledger.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
+import { rowKind } from "../context/ledger-skill/ledger-core.mjs";
 /** The per-instance ledger file, keyed by the launch dir (same encoding as
  *  channels/crons). Distinct launch dirs → distinct ledgers. */
 export function ledgerFileFor(cwd) {
@@ -87,42 +88,150 @@ export function deltaSince(rows, watermark, cap) {
     return { rows: changed.slice(0, cap), total: changed.length };
 }
 const LEDGER_HEAD = "⟦ledger · ";
-/** The delta block the agent sees ahead of a human prompt. English (it is
- *  written into the transcript — repo side). One line per row: `• [id] entity —
- *  status (source)`; an overflow line when capped. */
+/* ------------------------------------------------------------------ *
+ * The block is ONE LINE, and that is a correctness requirement, not a style.
+ *
+ * `pilot.submit` puts the text into the TUI as a bracketed PASTE, and Claude
+ * Code collapses a paste past a threshold into a `<pasted_content>` wrapper —
+ * which its own system prompt tells the model is material the user pasted from
+ * somewhere else, to be acted on only where the user's own message asks. With a
+ * multi-line block the human's message is INSIDE that wrapper, so it stops being
+ * an instruction. Measured end to end: an agent answered "your last message
+ * contained only pasted text, with no request of your own alongside it… I
+ * haven't acted on that line", and refused a direct order.
+ *
+ * Both thresholds measured against a live agent and confirmed on 486 real human
+ * prompts from this machine's transcripts:
+ *
+ *   lines  1–3 → 0 of 324 wrapped        chars  430 on one line → not wrapped
+ *   lines  4+  → ~30% of 162 wrapped     chars  910 on one line → wrapped
+ *
+ * A prompt is `⟦web⟧ header` + the message, so a one-line human message leaves
+ * the block exactly one line of room. The old multi-line block spent 2+ and put
+ * EVERY non-empty delta over the cliff: 85 real prompts, 24% of those carrying a
+ * block, had the human's message neutralised this way. Hence: one line, and a
+ * character budget inside it.
+ * ------------------------------------------------------------------ */
+/** Marks what follows the row, inline: "and here is what happened". */
+const CONT_MARK = "↳";
+/** Historical multi-line blocks, still replayed out of old transcripts. */
+const CONT_LINE = /^\s*↳ /;
+/** How much of a note reaches the block. */
+const HEADLINE_MAX = 120;
+/** Below this, a sentence boundary is not believed — see `headline`. */
+const HEADLINE_MIN = 24;
+/**
+ * The whole block's character ceiling. Chosen from the measurement above with
+ * room left for the ⟦web⟧ header and an ordinary message: a long enough single
+ * line collapses into a paste just as a fourth line does, so the budget is what
+ * keeps the one-line rule from being defeated by content. Rows that do not fit
+ * collapse into the overflow pointer, which is what it has always been for.
+ */
+const BLOCK_MAX = 320;
+/**
+ * The one line of the note that says WHAT happened, DERIVED rather than asked
+ * for. The block used to carry `[id] entity — status` and nothing else, so the
+ * entity *label* was the whole payload — and a label written as a topic name
+ * ("report regeneration, 15 test accounts") cannot say what changed about it.
+ * That is how work finished on the 9th was still believed pending on the 12th.
+ *
+ * Derived, because the alternative — a mandatory `--headline` — asks every agent
+ * for writing discipline (which nothing enforces) and covers none of the rows
+ * already recorded. The note's first sentence needs neither.
+ */
+export function headline(note, max = HEADLINE_MAX) {
+    const flat = String(note ?? "").replace(/\s+/g, " ").trim();
+    if (!flat)
+        return "";
+    // A period ends a sentence only when whitespace follows it: this table is full
+    // of "claude-code-2.1.285" and "PR#259 / v0.13.4", and splitting on a bare dot
+    // would cut every one of them in half. And a boundary that would leave almost
+    // nothing is not one — "e.g. the nightly job" is one sentence, not "e.g.".
+    let first = flat;
+    const bound = /[.!?](?=\s)/g;
+    for (let m = bound.exec(flat); m; m = bound.exec(flat)) {
+        if (m.index + 1 >= HEADLINE_MIN) {
+            first = flat.slice(0, m.index + 1);
+            break;
+        }
+    }
+    first = first.trim();
+    if (first.length <= max)
+        return first;
+    const cut = first.slice(0, max);
+    const sp = cut.lastIndexOf(" ");
+    // Break on a word unless that would throw away most of the line.
+    return (sp > max * 0.6 ? cut.slice(0, sp) : cut).trimEnd() + "…";
+}
+/**
+ * The delta block the agent sees ahead of a prompt. English (it is written into
+ * the transcript — repo side). ONE line, within `BLOCK_MAX` (see above): per row
+ * `• [id] entity — status (source)`, the kind when it is not the default `task`,
+ * and `↳ <headline>` for what actually happened. Rows that do not fit the budget
+ * become the overflow pointer rather than a second line.
+ */
 export function formatLedgerBlock(rows, total) {
-    const head = `${LEDGER_HEAD}${total} update${total === 1 ? "" : "s"} since your last message⟧`;
-    const lines = rows.map((r) => {
+    let line = `${LEDGER_HEAD}${total} update${total === 1 ? "" : "s"}⟧`;
+    let shown = 0;
+    for (const r of rows) {
         const handle = r.id ? `[${r.id}] ` : "";
         const src = r.source ? ` (${r.source})` : "";
-        return `• ${handle}${r.entity} — ${r.status}${src}`;
-    });
-    if (rows.length < total)
-        lines.push(`• (+${total - rows.length} more — run: ledger list)`);
-    return [head, ...lines].join("\n");
+        // A `fact` has no lifecycle and a `decision` is not a phase of one, so the
+        // reader must not take their status for a position in open → resolved.
+        // `task` is the default and nearly the whole table: tagging it would be noise.
+        const kind = rowKind(r);
+        const tag = kind === "task" ? "" : ` · ${kind}`;
+        const bare = ` • ${handle}${r.entity} — ${r.status}${tag}${src}`;
+        // Always carry at least one row: an empty block would say a delta arrived
+        // and name nothing, which is worse than a long line.
+        if (shown > 0 && line.length + bare.length > BLOCK_MAX)
+            break;
+        line += bare;
+        shown++;
+        const h = headline(r.note);
+        if (h && line.length + h.length + 3 <= BLOCK_MAX)
+            line += ` ${CONT_MARK} ${h}`;
+    }
+    if (shown < total)
+        line += ` • (+${total - shown} more — run: ledger list)`;
+    // Defensive: one oversized entity must not be able to defeat the one-line rule
+    // by length, which costs exactly as much as a second line would.
+    return line.length > BLOCK_MAX * 2 ? line.slice(0, BLOCK_MAX * 2 - 1) + "…" : line;
 }
-/** Prepend the block as its own leading lines. Idempotent. */
+/** Prepend the block as its own leading line. Idempotent. */
 export function markLedgerBlock(text, block) {
     if (hasLedgerBlock(text))
         return text;
     return `${block}\n${text}`;
 }
-/** Does this text open with a pushed ledger block? */
+/** Does this text open with a pushed ledger block?
+ *
+ *  `⟧` CLOSES the header, it no longer ENDS the line: a one-line block continues
+ *  with its rows after it. Testing `endsWith` here was the first thing the
+ *  one-line format broke, and it fails open — detection returns false, nothing
+ *  is stripped, and the whole block is shown to the user in the chat. The old
+ *  multi-line shape satisfies this test too, so replayed transcripts are
+ *  unaffected. */
 export function hasLedgerBlock(text) {
     if (typeof text !== "string")
         return false;
     const first = text.split("\n", 1)[0];
-    return first.startsWith(LEDGER_HEAD) && first.endsWith("⟧");
+    return first.startsWith(LEDGER_HEAD) && first.includes("⟧");
 }
-/** Remove a leading ledger block — its header line and the contiguous `• ` bullet
- *  lines that follow it — leaving whatever came after (e.g. the ⟦platform⟧ header
- *  and the user's message). A plain message is returned untouched. */
+/** Remove a leading ledger block, leaving whatever came after (the ⟦platform⟧
+ *  header and the user's message). A plain message is returned untouched.
+ *
+ *  The block is one line now, so that is usually all this drops — but it must
+ *  keep understanding the HISTORICAL multi-line shape (header, `• ` bullets,
+ *  indented `↳` headlines), because `loadHistory` replays transcripts written
+ *  before the format changed and a block it fails to strip is a block the user
+ *  reads in the chat. */
 export function stripLedgerBlock(text) {
     if (!hasLedgerBlock(text))
         return text;
     const lines = text.split("\n");
     let i = 1; // drop the header line
-    while (i < lines.length && lines[i].startsWith("• "))
+    while (i < lines.length && (lines[i].startsWith("• ") || CONT_LINE.test(lines[i])))
         i++;
     return lines.slice(i).join("\n");
 }