[WIP] feat: Compaction-resistant notepad

[quangdang46]

Gap #17 — Medium

Notes with priority levels that survive context compaction, restored via PreCompact hooks.

Source: oh-my-claudecode

What's needed:

• 3 priority levels: priority (permanent), working (session), manual
• PreCompact hook that serializes notepad state
• PostCompact hook that restores notepad
• Integration with agent turn loop

Reference: oh-my-claudecode docs/HOOKS.md (notepad section)

[quangdang46]

Implementation Plan: Compaction-Resistant Notepad (issue #380)

Generated from research across 9 reference repos + design discussion.
Goal: Give the jcode agent a file-backed, 3-tier notepad whose Priority tier is guaranteed to survive context compaction (and DCP pruning), re-injected automatically every turn.

---

1. Executive Summary

We add an internal notepad feature to jcode: a per-working-directory markdown file (.jcode/notepad.md) with three retention tiers — priority (permanent, always re-injected, capped), working (session, auto-pruned after N days), and manual (never auto-pruned). The agent reads/writes it via six tools (notepad_read, notepad_write_priority, notepad_write_working, notepad_write_manual, notepad_prune, notepad_stats).

Because the notepad lives in a file (outside the message list), it survives compaction by construction. The real work — and what every reference repo converges on — is re-injection: the Priority tier is rendered into the system prompt every turn (build_system_prompt_split), which is immune to both message compaction and DCP message-pruning. A PostCompact path additionally emits additional_context as belt-and-suspenders and runs a pi-agent-rust-style survival check that verifies the Priority marker is present after compaction.

This mirrors oh-my-claudecode's canonical design, ported to Rust with jcode's existing hook/compaction infrastructure, and is explicitly DCP-aware (DCP is a separate optional pre-pruning layer; compaction remains jcode's CompactionManager).

---

2. Architecture Decision

Chosen Approach: Internal feature (engine in jcode-base, tools in jcode-app-core), Priority re-injected via the system prompt.

• Engine (crates/jcode-base/src/notepad.rs): pure file I/O + section parsing + atomic write + advisory lock + prune/stats. Lives next to compaction.rs and session.rs.
• Tools (crates/jcode-app-core/src/tool/notepad.rs): six jcode_tool_core::Tool impls, registered in tool::Registry.
• Injection (crates/jcode-app-core/src/agent/prompting.rs): Priority tier appended as a <notepad-priority> system-prompt section every turn.
• Compaction hook (crates/jcode-app-core/src/agent/compaction.rs): on PostCompact, emit additional_context + run survival check.
• Config (crates/jcode-config-types/src/lib.rs): [notepad] block.

Why this approach

• Survives compaction and DCP without special-casing, because the system prompt is rebuilt each turn and is not a prunable/compactable message (DCP has a separate transform_system; compaction only touches the message list).
• Avoids the codex trap (their PostCompact cannot inject additionalContext); jcode already exposes additional_context / updated_system_message on HookSpecificOutput.
• Reuses jcode's existing PreCompact/PostCompact firing points — no new lifecycle needed.

Alternatives Considered

Approach	Source repo	Pros	Cons	Decision
External hook scripts (stdin/stdout) writing notes + injecting via hook output	oh-my-claudecode, oh-my-openagent	No core changes; user-customizable	Per-call process spawn latency; fragile for a core memory feature; injection limited to hook output channel	Rejected
Re-inject Priority as a normal user/assistant message after compaction	claude-code (buildPostCompactMessages)	Simple to insert	Gets pruned by DCP; can be re-compacted; pollutes transcript	Rejected
Evolving LLM-rewritten summary instead of explicit tiers	opencode (anchored summary)	One artifact, model-maintained	LLM told to "drop stale" → no permanent guarantee	Rejected (no "never lose" tier)
Internal engine + system-prompt injection of Priority + PostCompact additional_context + survival check	oh-my-claudecode (tiers) + pi-agent-rust (quality gate) + jcode hooks	Permanent guarantee; DCP/compaction-proof; Rust-native; reuses existing hooks	More core wiring than an external script	Chosen

---

3. Data Structures & Types

// crates/jcode-base/src/notepad.rs

use std::path::{Path, PathBuf};

/// Tunable notepad behaviour. Mirrors oh-my-claudecode DEFAULT_CONFIG.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[serde(default)]
pub struct NotepadConfig {
    /// Feature on/off.
    pub enabled: bool,
    /// Soft cap for the Priority tier (warn above this; it is always injected).
    pub priority_max_chars: usize,
    /// Working Memory entries older than this are pruned.
    pub working_memory_days: u32,
    /// Hard cap on total file size in bytes (write refused above this).
    pub max_total_size: usize,
    /// File name under the .jcode dir.
    pub filename: String,
}

impl Default for NotepadConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            priority_max_chars: 500,
            working_memory_days: 7,
            max_total_size: 8192,
            filename: "notepad.md".to_string(),
        }
    }
}

/// Which tier a read/write targets.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NotepadSection {
    Priority, // replace semantics, capped, always injected
    Working,  // append, timestamped, auto-pruned
    Manual,   // append, timestamped, never pruned
}

impl NotepadSection {
    pub fn header(self) -> &'static str {
        match self {
            NotepadSection::Priority => "## Priority Context",
            NotepadSection::Working => "## Working Memory",
            NotepadSection::Manual => "## MANUAL",
        }
    }
}

#[derive(Debug, Clone, serde::Serialize)]
pub struct NotepadStats {
    pub exists: bool,
    pub total_size: usize,
    pub priority_size: usize,
    pub working_memory_entries: usize,
    pub oldest_entry: Option<String>, // ISO-ish "YYYY-MM-DD HH:MM"
}

#[derive(Debug, Clone, serde::Serialize)]
pub struct PruneResult {
    pub pruned: usize,
    pub remaining: usize,
}

#[derive(Debug)]
pub enum NotepadError {
    LockTimeout,
    TooLarge { size: usize, max: usize },
    Io(std::io::Error),
}
impl std::fmt::Display for NotepadError { /* ... */ }
impl std::error::Error for NotepadError {}

/// Stateless handle bound to a working directory + config.
pub struct Notepad {
    root: PathBuf,        // the working directory
    cfg: NotepadConfig,
}

---

4. Pseudocode — Core Algorithm

FUNCTION write_priority(root, content, cfg):
    IF NOT cfg.enabled: RETURN Ok(no-op)
    path = root/.jcode/notepad.md
    ensure_dir(root/.jcode)
    ACQUIRE advisory_lock(path + ".lock"), timeout=5s   // swarm safety
        ON timeout: RETURN Err(LockTimeout)
    body = read_or_init(path)                            // create skeleton if missing
    warning = (len(content) > cfg.priority_max_chars) ? "<over cap>" : none
    new_body = replace_section(body, "## Priority Context", content)   // REPLACE
    IF byte_len(new_body) > cfg.max_total_size: RETURN Err(TooLarge)
    atomic_write(path, new_body)                         // tmp + rename
    RELEASE lock
    RETURN Ok(warning)

FUNCTION append_entry(root, section, content, cfg):     // working | manual
    ... acquire lock ...
    ts   = now("YYYY-MM-DD HH:MM")
    cur  = extract_section(body, section.header())
    entry = "<!-- WM:" + ts + " -->\n" + content + "\n"  // stable delimiter (stats-parseable)
    new  = replace_section(body, section.header(), cur + "\n" + entry)
    ... size check, atomic_write, release ...

FUNCTION prune(root, days, cfg):
    ... acquire lock ...
    entries = parse_entries(extract_section(body, "## Working Memory"))
    cutoff  = now - days
    kept    = entries WHERE entry.ts >= cutoff
    rebuild Working Memory from kept; atomic_write
    RETURN { pruned: len(entries)-len(kept), remaining: len(kept) }

// ---- injection (called every turn while building the system prompt) ----
FUNCTION priority_system_block(root):
    p = extract_section(read(path), "## Priority Context")
    IF p empty: RETURN none
    RETURN "<notepad-priority>\n" + p + "\n</notepad-priority>"

// ---- post-compaction survival guard (pi-agent-rust inspired) ----
FUNCTION after_compaction(root, rebuilt_system_prompt):
    p = extract_section(read(path), "## Priority Context")
    IF p non-empty AND rebuilt_system_prompt NOT CONTAINS p:
        LOG warn "notepad priority tier missing after compaction"
        emit HookSpecificOutput.additional_context = priority_system_block(root)
        record_loss(metric)
    ELSE:
        record_preserved(metric)

Edge branches covered: feature disabled (no-op), file missing (skeleton init), lock contention (timeout error, surfaced to tool), oversize write (refused), empty Priority (no injection), concurrent writers (serialized by lock).

---

5. Implementation Code

File: crates/jcode-base/src/notepad.rs (engine — new)

//! Compaction-resistant notepad engine.
//! Three markdown tiers in `.jcode/notepad.md`:
//!   ## Priority Context  — REPLACE, capped, always injected (permanent)
//!   ## Working Memory     — APPEND timestamped, auto-pruned after N days
//!   ## MANUAL             — APPEND timestamped, never pruned
//! Writes are atomic (tmp+rename) and serialized by an advisory lock for swarm safety.

use std::fs;
use std::io::Write;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};

// (types from §3 elided)

const SKELETON: &str = "# Notepad\n<!-- Auto-managed by jcode. Manual edits preserved in MANUAL. -->\n\n## Priority Context\n<!-- ALWAYS injected. Keep under priority_max_chars. Critical, durable facts only. -->\n\n## Working Memory\n<!-- Session notes. Auto-pruned. -->\n\n## MANUAL\n<!-- User content. Never auto-pruned. -->\n\n";

impl Notepad {
    pub fn new(root: impl Into<PathBuf>, cfg: NotepadConfig) -> Self {
        Self { root: root.into(), cfg }
    }

    fn dir(&self) -> PathBuf { self.root.join(".jcode") }
    fn path(&self) -> PathBuf { self.dir().join(&self.cfg.filename) }
    fn lock_path(&self) -> PathBuf { self.dir().join(format!("{}.lock", self.cfg.filename)) }

    fn read_or_init(&self) -> Result<String, NotepadError> {
        let p = self.path();
        if !p.exists() {
            fs::create_dir_all(self.dir()).map_err(NotepadError::Io)?;
            return Ok(SKELETON.to_string());
        }
        fs::read_to_string(&p).map_err(NotepadError::Io)
    }

    /// Advisory exclusive lock via lockfile create-exclusive spin (no extra deps).
    /// Returns a guard that removes the lockfile on drop. Use `fs2` if preferred.
    fn lock(&self) -> Result<LockGuard, NotepadError> {
        fs::create_dir_all(self.dir()).map_err(NotepadError::Io)?;
        let lp = self.lock_path();
        let deadline = Instant::now() + Duration::from_millis(5000);
        loop {
            match fs::OpenOptions::new().write(true).create_new(true).open(&lp) {
                Ok(_) => return Ok(LockGuard(lp)),
                Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {
                    if Instant::now() >= deadline { return Err(NotepadError::LockTimeout); }
                    std::thread::sleep(Duration::from_millis(25));
                }
                Err(e) => return Err(NotepadError::Io(e)),
            }
        }
    }

    fn atomic_write(&self, body: &str) -> Result<(), NotepadError> {
        if body.len() > self.cfg.max_total_size {
            return Err(NotepadError::TooLarge { size: body.len(), max: self.cfg.max_total_size });
        }
        let tmp = self.path().with_extension("md.tmp");
        let mut f = fs::File::create(&tmp).map_err(NotepadError::Io)?;
        f.write_all(body.as_bytes()).map_err(NotepadError::Io)?;
        f.sync_all().ok();
        fs::rename(&tmp, self.path()).map_err(NotepadError::Io) // atomic on same fs
    }

    // ---- public API ----

    pub fn set_priority(&self, content: &str) -> Result<Option<String>, NotepadError> {
        if !self.cfg.enabled { return Ok(None); }
        let _g = self.lock()?;
        let body = self.read_or_init()?;
        let warn = (content.chars().count() > self.cfg.priority_max_chars)
            .then(|| format!("Priority exceeds {} chars", self.cfg.priority_max_chars));
        let body = replace_section(&body, NotepadSection::Priority.header(), content);
        self.atomic_write(&body)?;
        Ok(warn)
    }

    pub fn append(&self, section: NotepadSection, content: &str) -> Result<(), NotepadError> {
        if !self.cfg.enabled { return Ok(()); }
        let _g = self.lock()?;
        let body = self.read_or_init()?;
        let cur = extract_section(&body, section.header()).unwrap_or_default();
        let ts = now_stamp(); // "YYYY-MM-DD HH:MM"
        let entry = format!("<!-- WM:{ts} -->\n{content}\n");
        let merged = if cur.trim().is_empty() { entry } else { format!("{cur}\n{entry}") };
        let body = replace_section(&body, section.header(), &merged);
        self.atomic_write(&body)
    }

    pub fn priority(&self) -> Option<String> {
        extract_section(&fs::read_to_string(self.path()).ok()?, NotepadSection::Priority.header())
            .filter(|s| !s.trim().is_empty())
    }

    /// System-prompt block (DCP/compaction-proof). None when empty/disabled.
    pub fn priority_system_block(&self) -> Option<String> {
        if !self.cfg.enabled { return None; }
        let p = self.priority()?;
        Some(format!("<notepad-priority>\n{}\n</notepad-priority>", p.trim()))
    }

    pub fn prune(&self, days: u32) -> Result<PruneResult, NotepadError> { /* parse WM, filter by cutoff, rewrite */ }
    pub fn stats(&self) -> NotepadStats { /* sizes + WM entry count + oldest */ }
    pub fn read_section(&self, s: NotepadSection) -> Option<String> { extract_section(&fs::read_to_string(self.path()).ok()?, s.header()) }
    pub fn read_all(&self) -> Option<String> { fs::read_to_string(self.path()).ok() }
}

struct LockGuard(PathBuf);
impl Drop for LockGuard { fn drop(&mut self) { let _ = fs::remove_file(&self.0); } }

/// Extract a section body from header to the next `## ` (or EOF), stripping HTML comments.
fn extract_section(content: &str, header: &str) -> Option<String> { /* line-scan; see tests */ }
/// Replace a section body, preserving its leading HTML comment.
fn replace_section(content: &str, header: &str, new_body: &str) -> String { /* line-scan rebuild */ }
fn now_stamp() -> String { chrono::Local::now().format("%Y-%m-%d %H:%M").to_string() }

Implementation note: extract_section/replace_section use a line scanner (split on \n, find the header line, copy until the next line starting with "## "). This is more robust than oh-my-claudecode's regex against nested ### entries; the unit tests in §8 pin the behaviour.

File: crates/jcode-app-core/src/tool/notepad.rs (tools — new)

//! Notepad MCP/agent tools — read + 3 writers + prune + stats.
use crate::tool::{ToolContext, ToolOutput};
use anyhow::Result;
use async_trait::async_trait;
use jcode_base::notepad::{Notepad, NotepadConfig, NotepadSection};
use jcode_tool_core::Tool;
use serde::Deserialize;
use serde_json::{json, Value};

fn notepad_for(ctx: &ToolContext) -> Notepad {
    // ctx exposes the session working directory (same source read/grep/ls tools use).
    let root = ctx.working_dir();                 // CONFIRM exact accessor on ToolContext
    let cfg = ctx.config().notepad.clone();        // [notepad] block, §6
    Notepad::new(root, cfg)
}

#[derive(Default)] pub struct NotepadWritePriorityTool;
#[derive(Deserialize)] struct WriteArgs { content: String }

#[async_trait]
impl Tool for NotepadWritePriorityTool {
    fn name(&self) -> &str { "notepad_write_priority" }
    fn description(&self) -> &str {
        "Replace the Priority Context tier. ALWAYS re-injected into context (survives compaction). \
         Keep it short and durable — critical facts only."
    }
    fn parameters_schema(&self) -> Value {
        json!({"type":"object","required":["content"],
               "properties":{"content":{"type":"string","description":"Replacement priority content (keep under ~500 chars)."}}})
    }
    async fn execute(&self, input: Value, ctx: ToolContext) -> Result<ToolOutput> {
        let a: WriteArgs = serde_json::from_value(input)?;
        match notepad_for(&ctx).set_priority(&a.content) {
            Ok(None)      => Ok(ToolOutput::text(format!("Priority updated ({} chars).", a.content.len()))),
            Ok(Some(w))   => Ok(ToolOutput::text(format!("Priority updated ({} chars). Warning: {w}", a.content.len()))),
            Err(e)        => Ok(ToolOutput::error(format!("notepad_write_priority failed: {e}"))),
        }
    }
}

// NotepadWriteWorkingTool / NotepadWriteManualTool: identical shape, call
//   notepad_for(&ctx).append(NotepadSection::Working|Manual, &a.content)

#[derive(Default)] pub struct NotepadReadTool;
#[derive(Deserialize)] struct ReadArgs { #[serde(default)] section: Option<String> }

#[async_trait]
impl Tool for NotepadReadTool {
    fn name(&self) -> &str { "notepad_read" }
    fn description(&self) -> &str { "Read the notepad: 'all' (default), 'priority', 'working', or 'manual'." }
    fn parameters_schema(&self) -> Value {
        json!({"type":"object","properties":{"section":{"type":"string","enum":["all","priority","working","manual"]}}})
    }
    async fn execute(&self, input: Value, ctx: ToolContext) -> Result<ToolOutput> {
        let a: ReadArgs = serde_json::from_value(input)?;
        let np = notepad_for(&ctx);
        let text = match a.section.as_deref().unwrap_or("all") {
            "priority" => np.read_section(NotepadSection::Priority),
            "working"  => np.read_section(NotepadSection::Working),
            "manual"   => np.read_section(NotepadSection::Manual),
            _           => np.read_all(),
        };
        Ok(ToolOutput::text(text.unwrap_or_else(|| "Notepad is empty.".into())))
    }
}

// NotepadPruneTool  -> np.prune(days).  NotepadStatsTool -> serialize np.stats().

pub fn notepad_tools() -> Vec<Box<dyn Tool>> {
    vec![
        Box::new(NotepadReadTool::default()),
        Box::new(NotepadWritePriorityTool::default()),
        Box::new(NotepadWriteWorkingTool::default()),
        Box::new(NotepadWriteManualTool::default()),
        Box::new(NotepadPruneTool::default()),
        Box::new(NotepadStatsTool::default()),
    ]
}

File: crates/jcode-app-core/src/agent/prompting.rs (injection — edit)

// inside build_system_prompt_split(...), after the base prompt is assembled:
if let Some(block) = notepad_priority_block_for_session(&self.session) {
    // Append as a dedicated system section. The system prompt is rebuilt every
    // turn and is NOT subject to message compaction or DCP message-pruning,
    // so the Priority tier is durable by construction.
    split.system.push_str("\n\n");
    split.system.push_str(&block);
}

fn notepad_priority_block_for_session(session: &Session) -> Option<String> {
    let root = session.working_dir.clone()?;
    let cfg = session.config.notepad.clone();
    jcode_base::notepad::Notepad::new(root, cfg).priority_system_block()
}

File: crates/jcode-app-core/src/agent/compaction.rs (PostCompact survival guard — edit)

// in poll_compaction_completion_event(), inside the PostCompact tokio::spawn block,
// before dispatch_hooks: attach the priority tier as additional_context so external
// hooks AND the next provider call both see it, and record a survival metric.
if let Some(block) = notepad_priority_block_for_session(&session_for_hook) {
    let mut specific = HookSpecificOutput::default();
    specific.hook_event_name = "PostCompact".into();
    specific.additional_context = Some(block);
    hook_input.hook_specific_output = Some(specific); // belt-and-suspenders re-inject
}

---

6. Configuration & Wiring

Config — add to crates/jcode-config-types/src/lib.rs:

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct Config {
    // ...existing fields...
    #[serde(default)]
    pub notepad: jcode_base::notepad::NotepadConfig,
}

config.toml:

[notepad]
enabled = true
priority_max_chars = 500
working_memory_days = 7
max_total_size = 8192
filename = "notepad.md"

Module registration:

• crates/jcode-base/src/lib.rs: pub mod notepad;
• crates/jcode-app-core/src/tool/mod.rs: add mod notepad; and, in Registry construction, extend the tool list with notepad::notepad_tools().

Tool gating: notepad tools are registered only when config.notepad.enabled (matches how DCP tools gate on the dcp feature). No network surface, no auth implications (local file only, within the working directory — path is fixed to <cwd>/.jcode/notepad.md, not user-supplied, so no path traversal).

DCP interaction: none required. DCP prunes the message list before CompactionManager; the notepad injects into the system prompt, which DCP augments via transform_system but does not prune. Confirmed: crates/jcode-base/src/compaction.rs has zero DCP references.

---

7. Repo References

Feature aspect	Repo	File	Link
3-tier notepad engine (canonical)	oh-my-claudecode	src/hooks/notepad/index.ts	https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/notepad/index.ts
6 tool surface + descriptions	oh-my-claudecode	src/tools/notepad-tools.ts	https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/tools/notepad-tools.ts
PreCompact checkpoint + injection + per-dir mutex	oh-my-claudecode	src/hooks/pre-compact/index.ts	https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/pre-compact/index.ts
Append-only write guard	oh-my-openagent	src/hooks/notepad-write-guard/index.ts	https://github.com/code-yeongyu/oh-my-openagent/blob/dev/src/hooks/notepad-write-guard/index.ts
Capture→restore→inject around compaction	oh-my-openagent	src/hooks/compaction-context-injector/hook.ts	https://github.com/code-yeongyu/oh-my-openagent/blob/dev/src/hooks/compaction-context-injector/hook.ts
Rust compaction structs + turn-boundary cut	pi-agent-rust	src/compaction.rs	https://github.com/Dicklesworthstone/pi_agent_rust/blob/main/src/compaction.rs#L102
Survival quality gate (preserved/loss)	pi-agent-rust	src/compaction.rs	https://github.com/Dicklesworthstone/pi_agent_rust/blob/main/src/compaction.rs#L406
Benchmark harness pattern	pi-agent-rust	examples/session_workload_bench.rs	https://github.com/Dicklesworthstone/pi_agent_rust/blob/main/examples/session_workload_bench.rs
PostCompact-can't-inject (anti-pattern to avoid)	codex	codex-rs/hooks/src/events/compact.rs	https://github.com/openai/codex/blob/main/codex-rs/hooks/src/events/compact.rs#L34
Post-compaction re-injection + system-reminder	claude-code	src/services/compact/compact.ts	https://github.com/claude-code-best/claude-code/blob/main/src/services/compact/compact.ts#L336
Plugin compaction hooks seam	opencode	packages/plugin/src/index.ts	https://github.com/anomalyco/opencode/blob/dev/packages/plugin/src/index.ts#L305
Ported notepad + memory directives w/ priority	oh-my-codex	src/mcp/memory-server.ts	https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/mcp/memory-server.ts
Priority-ordered always-loaded files	codebuff	common/src/constants/knowledge.ts	https://github.com/CodebuffAI/codebuff/blob/main/common/src/constants/knowledge.ts
jcode hook output injection fields	jcode	crates/jcode-hooks/src/types.rs	HookSpecificOutput.additional_context / updated_system_message
jcode compaction firing points	jcode	crates/jcode-app-core/src/agent/compaction.rs	PreCompact / PostCompact

---

8. Test Cases

crates/jcode-base/src/notepad_tests.rs (engine unit tests):

use super::notepad::*;
use tempfile::tempdir;

fn np(dir: &std::path::Path) -> Notepad { Notepad::new(dir, NotepadConfig::default()) }

#[test]
fn priority_is_replace_not_append() {
    let d = tempdir().unwrap();
    np(d.path()).set_priority("first").unwrap();
    np(d.path()).set_priority("second").unwrap();
    let p = np(d.path()).priority().unwrap();
    assert!(p.contains("second") && !p.contains("first"));
}

#[test]
fn working_is_append_and_timestamped() {
    let d = tempdir().unwrap();
    let n = np(d.path());
    n.append(NotepadSection::Working, "alpha").unwrap();
    n.append(NotepadSection::Working, "beta").unwrap();
    let w = n.read_section(NotepadSection::Working).unwrap();
    assert!(w.contains("alpha") && w.contains("beta"));
    assert_eq!(n.stats().working_memory_entries, 2);
}

#[test]
fn priority_over_cap_warns_but_writes() {
    let d = tempdir().unwrap();
    let mut cfg = NotepadConfig::default(); cfg.priority_max_chars = 5;
    let n = Notepad::new(d.path(), cfg);
    let warn = n.set_priority("way too long").unwrap();
    assert!(warn.is_some());
    assert!(n.priority().unwrap().contains("way too long"));
}

#[test]
fn manual_never_pruned_working_pruned() {
    let d = tempdir().unwrap();
    let n = np(d.path());
    // (helper writes an entry with an artificially old timestamp)
    write_old_entry(&n, NotepadSection::Working, "stale", days_ago = 30);
    write_old_entry(&n, NotepadSection::Manual,  "keepme", days_ago = 30);
    let r = n.prune(7).unwrap();
    assert_eq!(r.pruned, 1);
    assert!(n.read_section(NotepadSection::Manual).unwrap().contains("keepme"));
}

#[test]
fn priority_system_block_wraps_in_tags() {
    let d = tempdir().unwrap();
    np(d.path()).set_priority("DB=Postgres").unwrap();
    let b = np(d.path()).priority_system_block().unwrap();
    assert!(b.starts_with("<notepad-priority>") && b.contains("DB=Postgres"));
}

#[test]
fn disabled_is_noop() {
    let d = tempdir().unwrap();
    let mut cfg = NotepadConfig::default(); cfg.enabled = false;
    let n = Notepad::new(d.path(), cfg);
    n.set_priority("x").unwrap();
    assert!(n.priority_system_block().is_none());
}

Edge Cases

#[test] fn read_missing_file_returns_none();                 // notepad never created
#[test] fn empty_priority_yields_no_injection();             // priority_system_block == None
#[test] fn oversize_write_is_refused_with_TooLarge();        // body > max_total_size
#[test] fn concurrent_appends_are_serialized_no_corruption();// 8 threads append, count == 8
#[test] fn lock_timeout_surfaces_error();                    // hold lock, second writer -> LockTimeout
#[test] fn malformed_existing_file_is_tolerated();           // missing headers -> re-init skeleton sections

Integration Test — survives real compaction

crates/jcode-app-core/src/agent_tests.rs:

#[tokio::test]
async fn priority_survives_compaction_via_system_prompt() {
    // 1. build an Agent with notepad enabled + a tiny token budget
    // 2. notepad_write_priority "INVARIANT: use Postgres"
    // 3. push enough messages to force compaction (force_compact_with / hard_compact_with)
    // 4. assert messages_for_provider() produced a CompactionEvent (compaction happened)
    // 5. assert build_system_prompt_split(None).system contains "INVARIANT: use Postgres"
    //    AND "<notepad-priority>"
}

#[tokio::test]
#[cfg(feature = "dcp")]
async fn priority_survives_with_dcp_enabled() {
    // same as above but with DcpPlugin::new_aggressive(); assert priority block still present
    // (DCP prunes messages, not the system prompt)
}

---

9. Benchmarks

Harness: criterion micro-benchmarks in crates/jcode-base/benches/notepad_bench.rs (+ an integration timing in the agent crate), modeled on pi-agent-rust examples/session_workload_bench.rs.

What to Measure

Metric	Baseline	Target	How to Measure
set_priority latency (warm file)	n/a (new)	< 1 ms p50	criterion, tmpfs notepad
append latency	n/a	< 1 ms p50	criterion
priority_system_block (read+wrap)	n/a	< 200 µs p50	criterion; this runs every turn
Added system-prompt tokens	n/a	≤ priority_max_chars/4 (~125 tok @500 chars)	tokenizer count of injected block
Per-turn overhead of injection	system-prompt build time	< 2% increase	bench build_system_prompt_split with/without notepad
Compaction-survival rate (Priority)	claude-code best-effort	100% (hard guarantee)	integration test asserts presence post-compaction over N runs
Concurrent-write throughput	n/a	≥ 1k serialized writes/s, 0 corruption	8-thread append bench + integrity check

Benchmark Code (sketch)

use criterion::{criterion_group, criterion_main, Criterion};
use jcode_base::notepad::{Notepad, NotepadConfig};

fn bench_inject(c: &mut Criterion) {
    let d = tempfile::tempdir().unwrap();
    let n = Notepad::new(d.path(), NotepadConfig::default());
    n.set_priority(&"x".repeat(500)).unwrap();
    c.bench_function("priority_system_block", |b| b.iter(|| n.priority_system_block()));
}
criterion_group!(notepad, bench_inject);
criterion_main!(notepad);

---

10. Migration / Rollout

• Greenfield: no existing notepad → no data migration. First write creates .jcode/notepad.md.
• Feature flag: [notepad] enabled (default true); set false to fully disable (tools unregistered, no injection). Ship behind enabled=false for the first canary build if desired, then flip.
• Backwards compatible: the file format embeds HTML-comment delimiters (<!-- WM:ts -->) and a stable header set; new fields are additive.
• .gitignore: recommend adding .jcode/notepad.md and .jcode/notepad.md.lock (notes are local working memory, not source). Document in README.
• No provider/network change, no auth surface.

---

11. Known Limitations & Future Work

• Only the Priority tier is auto-injected; Working/Manual are read on demand (token-cost tradeoff, matches oh-my-claudecode). Future: optional "inject recent N working entries".
• Append-only enforcement is by tool design; a Write to .jcode/notepad.md could still clobber it. Future: port oh-my-openagent's notepad-write-guard as a PreToolUse hook.
• Lockfile-based advisory lock is robust for same-host swarm; stale lock after a hard crash is cleaned by the 5 s timeout path but could be improved with PID/heartbeat (or switch to fs2 OS locks).
• No semantic relevance ranking (claude-code memdir / oh-my-pi retain-recall). Out of scope for [WIP] feat: Compaction-resistant notepad #380.
• Cross-session vs cross-compaction: current scope is per-working-dir file (survives both). Per-session scoping is a future config option.
• PreCompact could also fold Working Memory into the summary prompt (oh-my-pi preCompactionContext pattern) — future enhancement.

12. Success Criteria Checklist

• notepad_write_priority / _working / _manual / notepad_read / notepad_prune / notepad_stats registered and callable.
• Priority = replace + capped + warns over cap; Working = append + timestamped + auto-pruned; Manual = append + never pruned.
• Priority tier present in build_system_prompt_split output after a forced compaction (the core guarantee) — integration test green.
• Priority tier present with dcp feature enabled — DCP integration test green.
• Atomic write + advisory lock: 8-thread concurrent append test shows 0 corruption, correct count.
• Engine unit tests + edge cases all pass; cargo build and cargo test -p jcode-base -p jcode-app-core clean; cargo build --features dcp clean.
• Benchmarks recorded; per-turn injection overhead < 2%.
• No regressions in existing compaction tests (agent_tests.rs, compaction_tests.rs).