[feat] Persist nudge echoes as session entries (survive restarts, grep-able log)

[ranxianglei]

Summary

With debug: true, nudge injections are echoed to the TUI via ctx.ui.notify() → pi's showStatus() → a transient dim Text child appended to chatContainer. These echoes are never written to the session log, so:

1. Every process restart (pi --session <id> resume, agent process restart) runs chatContainer.clear() + rebuildChatFromMessages() (pi interactive-mode.js), wiping the entire injection history from view.
2. ~/.pi/acp.log keeps only the first physical line of each nudge: log.ts:50 formats entries as a single line (`${ts()} [${level}] [${scope}] ${body}\n`), and the multi-line nudge body spills onto subsequent untagged physical lines — so grep nudge-injected shows only the headline ("⚠️ Context limit reached — compress now..."), not the tier/breakdown/ranges that make the entry useful.

Observed impact: in a long-running session with 5 process starts (sid 01a07b3c-ab19-7b19-8290-f7967a8221a6, see #325), the user could not reconstruct which nudges had fired and when — on-screen evidence was gone after each restart, and the log was not grep-able for full nudge content.

Request

Make nudge injections durable and auditable:

Primary: persist a compact nudge record as a session entry on injection (the if (turn.nudge?.shouldInject) block in src/index.ts), surviving restarts and visible in TUI scrollback + session file. Precedent: /acp and /acp-status are already shown as persistent custom messages (commit 0ff701e, issue #255).

Constraints:

• Keep the persisted record short (e.g. [ACP nudge] EMERGENCY 95% · T1 · top range m00120–m00168) — the full multi-line nudge text must NOT be added to model context (it would pollute context every turn).
• If pi's session-entry mechanism always feeds entries back into model context, prefer a display-only entry type; otherwise gate persistence behind the existing debug flag.

Secondary (small): escape newlines when writing debug events to acp.log (one physical line per entry) so nudge-injected / nudge-suppressed entries are self-contained and grep-able.

Repro / evidence

• Any session with debug: true in ~/.pi/acp.json: trigger a nudge (usage above band), observe the on-screen block, restart pi → block gone; grep nudge-injected ~/.pi/acp.log → headline only.
• Session sid 01a07b3c-ab19-7b19-8290-f7967a8221a6: 4 emergency injections (acp.log lines 13504-05, 13848-49, 13922-23, 14122) across 5 process starts; none recoverable from TUI or log after restart.
• Related: [bug] Post-compression sent-view undercounts prompt by ~70–80K → false idle → host-floor emergency re-nudge loop #325 (post-compression sent-view undercount driving repeated emergency injections in that session).

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Triage: valid, no duplicates — implementing.

Verified both gaps against source:

1. No session entry exists today — the nudge path only does ctx.ui.notify() (transient showStatus() Text child) plus debug.event("nudge-injected") to acp.log. Nothing is ever appended to the session, so restarts (chatContainer.clear() + rebuildChatFromMessages()) wipe the history. Confirmed at src/index.ts:332-375.
2. Log headline-only — log.ts fmt() passes raw strings through unescaped, so the multi-line nudge body spills onto untagged physical lines after the nudge-injected headline.

Design decision (matches your "prefer a display-only entry type" constraint): use pi's appendEntry(customType, data) — a type:"custom" session entry — not pi.sendMessage. I checked why: pi's sendCustomMessage routes through agent.steer() whenever the agent is mid-streaming, which is always true inside the context event handler — so /acp's pi.sendMessage precedent (commit 0ff701e) cannot be reused mid-turn without hijacking the running turn. appendEntry is a pure synchronous append to the session file: never sent to the LLM, survives restarts, and re-renders in scrollback via a registered entry renderer (registerEntryRenderer, documented as "do not participate in LLM context"). So persistence needs no debug gating — zero context cost.

Plan:

• On actual injection (!alreadyShown branch of src/index.ts): persist one compact record per turn, e.g. [ACP nudge] EMERGENCY 95% · T1 · top range m00120–m00168 (one per turnKey — emergency nudges re-fire every LLM call until retry-capped, so per-event persistence would flood the session file; the full timeline stays in acp.log).
• Register a dim-text entry renderer so records show in TUI scrollback across restarts.
• Secondary: escape \n/\r in log.ts field formatting → one physical line per entry, grep nudge-injected ~/.pi/acp.log becomes self-contained.
• Tests for record formatting, log escaping, and once-per-turn persistence.

PR coming shortly.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Implemented — PR: #329

Triage: valid feature, no duplicates (#325 is the related-but-distinct undercount bug; #269/#316 cover nudge enforcement, not persistence). Both parts implemented: persistent nudge records + single-line acp.log entries.

Key API findings (verified against pi-coding-agent 0.83.0 source):

• The /acp precedent (commit 0ff701e) can't be reused here: pi.sendMessage({customType}) while streaming falls back to steer() in agent-session — it would inject the record as steering input mid-turn. Slash commands only work because they run idle.
• So I used pi.appendEntry("acp-nudge", {text}): pure sync append of a {type:"custom"} entry to the session JSONL. Display-only by construction — entriesToCoreMessages projects only type:"custom_message" entries into the sent view, so the record never reaches the model. This satisfies your "prefer a display-only entry type" constraint, so persistence is NOT gated behind debug (there's zero context cost).
• TUI visibility requires a registered entry renderer (addCustomEntryToChat drops unrendered custom entries); the restart-rebuild path includes them, so after registering one, records are visible both live and after pi --session <id> resume.

Design:

• On injection, appends exactly your example format: [ACP nudge] EMERGENCY 95% · T1 · top range m00120–m00168 (pct from kernel contextUsage, tier from nudge.tier, top range = highest-tokens viable range). Full multi-line nudge text stays out of the session file.
• Deduped per user turn: emergency nudges re-inject on every LLM call until retry-capped — without dedup the session file would gain one record per fire. Marking happens only after a successful append, so a failed append retries next fire.
• Renderer draws a dim boxed line (pi-tui Box/Text). pi-tui is pinned exactly 0.83.0 as a devDependency and bundled inline by tsup — dist stays zero-runtime-deps (verified no bare import remains in the bundle; smoke-loaded the built file in plain node).
• Secondary fix: log.ts now escapes \r/\n in string fields (incl. Error.stack) → every acp.log entry occupies one physical line, so grep nudge-injected returns the full body.

Verification: typecheck ✅ · 469 tests pass (4 new: record-format unit vs your exact example, emergency overflow integration asserting one record per turn across three fires, renderer unit, log single-line) ✅ · build ✅ (dist 627 KB).

Note for #325: this makes the repeated-emergency symptom at least auditable (one persisted line per user turn), but the root cause there — post-compression sent-view undercount — still needs its own fix.