dsh-engramory 0.2.6 → 0.2.7

package/index.js

@@ -1,530 +1,655 @@
-/**
- * dsh-engramory — the Engramory memory discipline as a DeepSeek Harness plugin.
- *
- * Two things the always-on AGENTS.md block cannot do on its own:
- *
- *   1. A DETERMINISTIC index cap. dsh's `ctx.tools.guard()` is a synchronous,
- *      monotonic refusal — once a guard returns a reason, no later waterfall
- *      listener can turn it back into an allow. That makes it a stronger seam than
- *      most hosts expose, and it is why the 200-line / 25 KB limit can be enforced
- *      here rather than merely asked for. Without a shim like this one, everywhere
- *      except Claude Code the cap degrades to "rules plus a checker the agent has to
- *      remember to run".
- *   2. Skill delivery that does not depend on install paths. Registering at runtime
- *      sidesteps the five-root scan entirely, so the protocol is present because the
- *      plugin is loaded, not because a directory happened to be right.
- *
- * The decision table mirrors hooks/engramory_index_guard.py: deny only a write that
- * ENDS over a cap AND grew past the current file — a shrinking rewrite always passes,
- * so an over-cap index can be compacted incrementally (210 → 205 → 198). Only known
- * mutating tools are gated; `read` and unknown tools are never refused (the first cut
- * gated everything that named the index, which blocked recall of an over-cap index at
- * exactly the moment compaction was needed).
- *
- * Zero dependencies, no build step: plain ESM, node: builtins only.
- */
-import { readFileSync, realpathSync } from 'node:fs'
-import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path'
-
-export const name = 'engramory'
-
-// `tools` carries the cap and is the plugin's only declared dependency. Cordis reads
-// `inject` as an array of service names (or an object KEYED by them) and treats every
-// entry as a hard wait — the `{ required, optional }` shape is older-Cordis syntax that
-// the build dsh vendors resolves as services literally named "required"/"optional",
-// which never appear, so the plugin sat pending forever (issue #8). `skills` is
-// deliberately NOT declared: the cap must mount even on a profile with no skill
-// registry, so apply() probes it at runtime instead.
-export const inject = ['tools']
-
-/** Mirrors hooks/engramory_index_guard.py — the caps are the protocol's, not this port's. */
-const DEFAULT_INDEX_NAME = 'MEMORY.md'
-const DEFAULT_MAX_LINES = 200
-const DEFAULT_MAX_BYTES = 25600
-
-/** Tools that replace a file wholesale, so the post-write text is in the arguments. */
-const WHOLE_FILE_WRITES = new Set(['write'])
-
-/**
- * Tools that mutate a file in place. Only tools named here (plus
- * `str_replace_editor`'s write commands, handled explicitly) count as partial
- * writes. Unknown tools pass through: this guard is a discipline rail, not a
- * security boundary (SECURITY.md), and a false refusal of `read` costs more than a
- * miss — the next whole-file write is measured exactly regardless.
- */
-const PARTIAL_WRITES = new Set(['edit', 'str_replace', 'insert'])
-
-export function apply(ctx, config = {}) {
-  // `indexPath` pins the guard to ONE file. Without it the only signal is the
-  // basename, so an unrelated MEMORY.md in any other project is gated too — a real
-  // refusal on a file that is not a memory index at all, with no way to opt out
-  // (renaming `indexName` would just unguard the real index). The Claude Code hook
-  // has had ENGRAMORY_INDEX_PATH for exactly this; this is its counterpart.
-  //
-  // The key and the basename are computed ONCE here: guards run on every tool call
-  // and must stay cheap, so the per-call path stays a string compare and the single
-  // realpath() only happens when the basename already matched.
-  const indexPath = typeof config.indexPath === 'string' && config.indexPath.trim()
-    ? config.indexPath.trim()
-    : undefined
-  const settings = {
-    indexName: indexNameOf(config.indexName),
-    indexPath,
-    indexKey: indexPath === undefined ? undefined : pathKey(indexPath),
-    // When pinned, the name to match is the pinned file's own basename.
-    matchName: (indexPath === undefined
-      ? indexNameOf(config.indexName)
-      : basename(indexPath)).toLowerCase(),
-    maxLines: positive(config.maxLines, DEFAULT_MAX_LINES),
-    maxBytes: positive(config.maxBytes, DEFAULT_MAX_BYTES),
-  }
-
-  // dsh 0.2 resolves a relative file path against the calling SESSION's working
-  // directory, which its `working_directory` tool moves away from the process's own
-  // cwd. Measured against process.cwd(), a bare `MEMORY.md` after a cd is the wrong
-  // file or none: an edit of the real index passed unmeasured, and a shrinking rewrite
-  // of an over-cap index was judged against an empty file and refused. The service is
-  // optional (0.1.x has none) and may mount late, so — like `skills` below — it is
-  // picked up reactively and never makes the cap wait.
-  let workingDirectory
-  ctx.inject(['workingDirectory'], (inner) => {
-    inner.effect(() => {
-      const service = inner.workingDirectory
-      workingDirectory = service
-      return () => {
-        if (workingDirectory === service) workingDirectory = undefined
-      }
-    })
-  })
-  const sessionCwd = (exec) => {
-    try {
-      const dir = workingDirectory?.get(exec.agent.session)
-      return typeof dir === 'string' && isAbsolute(dir) ? dir : undefined
-    } catch {
-      return undefined // no agent, no session, or a service shape this port predates
-    }
-  }
-
-  ctx.tools.guard((exec) => refuseOversizedIndex(exec, settings, sessionCwd))
-
-  // The skill registry is optional AND may activate after this plugin — fiber order
-  // between unrelated providers is not guaranteed, so a one-shot probe here would
-  // silently skip registration on such boots. ctx.inject() is Cordis' reactive form:
-  // the callback runs once `skills` is available (however late), re-runs if the
-  // registry reloads, and never makes the cap wait. A bare `ctx.skills` read at THIS
-  // level would throw (undeclared service — issue #8's second crash); inside the
-  // callback the service is declared, so the read is legal.
-  if (config.registerSkill !== false) {
-    ctx.inject(['skills'], (inner) => {
-      const skill = config.skill ?? builtinSkillBody()
-      // effect() ties the registration to the child fiber: it is disposed when the
-      // registry unloads, so a reload cannot accumulate duplicate registrations.
-      inner.effect(() => inner.skills.register({
-        name: 'engramory',
-        description:
-          'Curated file-based long-term memory: recall through MEMORY.md at the start of ' +
-          'a task, save durable user/feedback/project/reference facts, run a curation ' +
-          'checkpoint when a task finishes, and sync before compacting or opening a ' +
-          'fresh thread. A turn that starts no work — a greeting, an acknowledgement — ' +
-          'is not a task and needs none of this, but never judge that by length: a ' +
-          'one-word reply continuing work underway inherits that task.',
-        whenToUse:
-          'Starting or resuming work, learning something durable worth a future session, ' +
-          'finishing a task — including one that leaves nothing worth saving, since the ' +
-          'checkpoint is still a decision to make — or approaching a ' +
-          'compact/clear/new-thread boundary. Not for a bare greeting, ' +
-          'acknowledgement, or reaction, which starts no task — but a terse reply ' +
-          'that continues work underway does, and material already in hand (a ' +
-          'pasted diff to review) does not make work a non-task. Unsure? Treat it ' +
-          'as a task.',
-        source: 'runtime',
-        content: skill,
-      }))
-    })
-  }
-}
-
-/**
- * The cap itself. Returning a string denies the call; `undefined` lets it through.
- *
- * Guards are synchronous by contract, so this stays cheap: one basename comparison
- * rejects the overwhelming majority of calls before anything is measured, and the
- * only I/O is a single read of the index on a gated write.
- */
-function refuseOversizedIndex(exec, settings, sessionCwd) {
-  const args = exec?.arguments
-  if (!args || typeof args !== 'object') return undefined
-
-  // dsh's file tools carry the target as `file_path`; `str_replace_editor` calls it
-  // `path`. Compare basenames case-INsensitively: on the case-insensitive
-  // filesystems most stores live on (Windows/macOS), `memory.md` IS the guarded
-  // index, and an exact compare let that spelling through. (Same trade-off as the
-  // Python guard: on a case-sensitive FS this can gate an unrelated lowercase twin —
-  // rename it, or point `indexName` elsewhere.)
-  const filePath = typeof args.file_path === 'string' ? args.file_path
-    : typeof args.path === 'string' ? args.path
-      : undefined
-  if (filePath === undefined) return undefined
-  if (basename(filePath).toLowerCase() !== settings.matchName) return undefined
-
-  const tool = typeof exec.name === 'string' ? exec.name : ''
-
-  // Nothing below can refuse a read, a view, or an unknown tool, so leave before the
-  // pinned-path check: pathKey() touches the filesystem and a guard runs on EVERY tool
-  // call. Ordering it here keeps the common case a pair of string compares.
-  const gated = WHOLE_FILE_WRITES.has(tool)
-    || PARTIAL_WRITES.has(tool)
-    || (tool === 'str_replace_editor'
-      && (args.command === 'create' || args.command === 'str_replace'
-        || args.command === 'insert'))
-  if (!gated) return undefined
-  // Every read and identity check below uses the file the host will actually touch.
-  let target
-  try {
-    target = hostPath(sessionCwd(exec), filePath)
-  } catch {
-    return undefined // a relative path and no cwd left to resolve it (deleted under us)
-  }
-  // If the guard is pinned to one file, this is where an unrelated same-named file in
-  // another project drops out.
-  if (settings.indexKey !== undefined && pathKey(target) !== settings.indexKey) {
-    return undefined
-  }
-
-  if (WHOLE_FILE_WRITES.has(tool)) {
-    if (typeof args.content !== 'string') return undefined
-    return verdict(args.content, readIfPossible(target), filePath, settings)
-  }
-  if (tool === 'str_replace_editor' && args.command === 'create') {
-    if (typeof args.file_text !== 'string') return undefined
-    return verdict(args.file_text, readIfPossible(target), filePath, settings)
-  }
-
-  const partial = PARTIAL_WRITES.has(tool)
-    || (tool === 'str_replace_editor'
-      && (args.command === 'str_replace' || args.command === 'insert'))
-  if (!partial) return undefined // read / view / list / unknown: never refused
-
-  const currentBuf = readIfPossible(target)
-  if (currentBuf === undefined) return undefined
-  const current = currentBuf.toString('utf8')
-  const simulated = simulateEdit(current, args)
-  if (simulated !== undefined) {
-    return verdict(simulated, currentBuf, filePath, settings)
-  }
-
-  // The edit's result genuinely cannot be reconstructed from its arguments. Honest,
-  // cheap rule: if the index is ALREADY over, refuse to mutate it blind — and name
-  // the open door, because "compact first" while refusing edits reads as a dead end.
-  const breach = measure(current, settings)
-  if (!breach) return undefined
-  return (
-    `${displayName(settings)} is already over the Engramory cap (${breach}) and this ` +
-    `edit's result cannot be measured. Compact it with a whole-file write instead: ` +
-    `a rewrite that SHRINKS the index always passes, even while still over the cap. ` +
-    `Pointer-ify over-long lines, merge duplicates, archive cold notes — the index ` +
-    `is a table of contents, and anything past the cap silently stops being recalled.` +
-    notMyIndexHint(settings)
-  )
-}
-
-/**
- * Mirrors the Python guard's deny rule: refuse only when a dimension ends OVER its
- * cap AND grew past the current file, so a shrinking/keeping write on an over-cap
- * index always passes and incremental compaction stays possible. A missing or
- * unreadable current file counts as empty — a first write past the cap is refused.
- */
-function verdict(text, currentBuf, filePath, settings) {
-  const lines = countLines(text)
-  const bytes = Buffer.byteLength(text, 'utf8')
-  // Current byte size comes from the RAW buffer, mirroring how the Python guard
-  // sizes the on-disk file: decoding first inflated a non-UTF-8 index ~3x (every
-  // bad byte becomes a 3-byte U+FFFD), which made a genuinely growing write look
-  // like a shrink and pass. Newlines survive a lossy decode, so the line count may
-  // use the decoded text.
-  const curLines = currentBuf === undefined ? 0 : countLines(currentBuf.toString('utf8'))
-  const curBytes = currentBuf === undefined ? 0 : currentBuf.length
-  const over = []
-  if (lines > settings.maxLines && lines > curLines) {
-    over.push(`${lines} lines > ${settings.maxLines}`)
-  }
-  if (bytes > settings.maxBytes && bytes > curBytes) {
-    over.push(`${bytes} bytes > ${settings.maxBytes}`)
-  }
-  if (!over.length) return undefined
-  return (
-    `This write would put ${basename(filePath)} over the Engramory index cap ` +
-    `(${over.join(', ')}). The index is loaded every session and the host only reads ` +
-    `so far, so anything past the cap silently stops being recalled. Compact before ` +
-    `writing: move detail into the linked note files, merge duplicates, archive cold ` +
-    `notes, and keep every line to "one short hook + link". A write that SHRINKS the ` +
-    `index always passes, so you can compact step by step.` + notMyIndexHint(settings)
-  )
-}
-
-
-/**
- * The name to show in a refusal. `indexPath` wins over `indexName` when both are set,
- * so quoting the ignored one would send a user looking for the wrong file.
- */
-function displayName(settings) {
-  return settings.indexPath === undefined
-    ? settings.indexName
-    : basename(settings.indexPath)
-}
-
-
-/**
- * Without `indexPath` the guard matches on basename alone, so it can land on a file
- * that is not a memory index at all. Say so in the refusal: a user who hits this
- * needs the way out, not just the cap.
- */
-function notMyIndexHint(settings) {
-  if (settings.indexPath !== undefined) return ''
-  return (
-    ` (If this file is NOT your memory index, set this plugin's \`indexPath\` config ` +
-    `to your real index's absolute path so only that file is gated.)`
-  )
-}
-
-/**
- * Reconstruct a partial edit's post-write text when its arguments carry enough to
- * do it (`old_str`/`new_str`, or the Claude-style `old_string`/`new_string`).
- * Mirrors the Python guard's Edit simulation: replace the unique occurrence, or all
- * of them under a replace-all flag; an absent or ambiguous old-string means the
- * real tool errors and changes nothing, so the current text is the honest
- * prediction. Returns undefined when the shape isn't recognised.
- *
- * Matching happens on LF-normalised text and the result goes back in the file's own
- * line endings, as dsh's local backend does it (`applyLiteralEdit` /
- * `restoreLineEndings` in @deepseek-ai/dsh-fs-local). Matching the raw text let a CRLF
- * index — common on Windows — read every LF `old_string` as "not found", predict no
- * change, and pass an edit dsh then applied.
- */
-function simulateEdit(current, args) {
-  const oldRaw = firstString(args.old_str, args.old_string)
-  if (oldRaw === undefined || oldRaw === '') return undefined
-  const oldStr = lf(oldRaw)
-  const newStr = lf(firstString(args.new_str, args.new_string) ?? '')
-  // dsh decodes with TextDecoder, which drops a leading BOM — from the text it
-  // matches, from the sample it detects line endings on, and from what it writes back.
-  const decoded = current.startsWith('') ? current.slice(1) : current
-  const text = lf(decoded)
-  const first = text.indexOf(oldStr)
-  if (first === -1) return current // the real tool errors: nothing changes
-  let edited
-  if (args.replace_all === true || args.replaceAll === true) {
-    edited = text.split(oldStr).join(newStr)
-  } else {
-    const second = text.indexOf(oldStr, first + oldStr.length)
-    if (second !== -1) return current // ambiguous: the real tool errors, nothing changes
-    edited = text.slice(0, first) + newStr + text.slice(first + oldStr.length)
-  }
-  // Normalised once more before expanding, as dsh's restoreLineEndings does: a lone
-  // `\r` meeting an inserted `\n` at the seam is one CRLF, not `\r\r\n`.
-  return crlfDominates(decoded) ? lf(edited).split('\n').join('\r\n') : edited
-}
-
-function lf(text) {
-  return text.replaceAll('\r\n', '\n')
-}
-
-/** dsh's own call (`detectLineEndings`): CRLF wins on a majority in the first 4096 chars. */
-function crlfDominates(raw) {
-  const sample = raw.slice(0, 4096)
-  const crlf = sample.split('\r\n').length - 1
-  return crlf > sample.split('\n').length - 1 - crlf
-}
-
-function firstString(...values) {
-  for (const v of values) {
-    if (typeof v === 'string') return v
-  }
-  return undefined
-}
-
-/** Returns a human-readable breach description, or `null` when the text is within caps. */
-function measure(text, { maxLines, maxBytes }) {
-  const lines = countLines(text)
-  const bytes = Buffer.byteLength(text, 'utf8')
-  const over = []
-  if (lines > maxLines) over.push(`${lines} lines > ${maxLines}`)
-  if (bytes > maxBytes) over.push(`${bytes} bytes > ${maxBytes}`)
-  return over.length ? over.join(', ') : null
-}
-
-/** Trailing-newline-insensitive, matching how the Python guard counts. */
-function countLines(text) {
-  if (!text) return 0
-  return text.split('\n').length - (text.endsWith('\n') ? 1 : 0)
-}
-
-/**
- * A missing or unreadable index is not a breach: the guard's job is to stop an
- * oversized index, never to block work because a path could not be read. Returns the
- * RAW buffer — byte comparisons must use on-disk bytes (see verdict), decode at the
- * call sites that need text.
- */
-function readIfPossible(filePath) {
-  try {
-    return readFileSync(filePath)
-  } catch {
-    return undefined
-  }
-}
-
-function positive(value, fallback) {
-  if (!Number.isFinite(value)) return fallback
-  const floored = Math.floor(value)
-  return floored > 0 ? floored : fallback
-}
-
-/**
- * The path the host's own file tools would touch for `p`, mirroring dsh's local
- * backend (`localDisplayPath` in @deepseek-ai/dsh-fs-local): resolve against `cwd`,
- * except that on POSIX a spelling with a `..` segment is kept as written, so a `..`
- * after a symlinked segment stays physical — collapsing it could measure a different
- * file than the one the write lands on. Without a session directory (`cwd`
- * undefined), the process's is used, and only when `p` needs one: process.cwd()
- * throws once that directory is deleted, and an absolute path must not care.
- */
-function hostPath(cwd, p) {
-  const resolved = () => (cwd === undefined ? resolve(p) : resolve(cwd, p))
-  if (process.platform === 'win32') return resolved()
-  const raw = isAbsolute(p) ? p : `${cwd ?? process.cwd()}${sep}${p}`
-  return /(?:^|[\\/])\.\.(?:[\\/]|$)/u.test(raw) ? raw : resolved()
-}
-
-/**
- * Normalise a path for identity comparison. `realpath` resolves symlinks and `..` so
- * two spellings of the same file compare equal, but it throws for a path with no file
- * behind it yet — and a plain `resolve` fallback is NOT interchangeable with it: an
- * index pinned before it exists, under a symlinked ancestor, would be keyed by its
- * alias at config time and by the link's target on every later call. The keys would
- * never match again and the guard would silently stop guarding its own index.
- *
- * So resolve the deepest ancestor that DOES exist and re-attach the missing tail:
- * the same file then keys identically whether or not it exists yet. Case is folded on
- * Windows only, mirroring `os.path.normcase` in the Python guard — folding it on Linux
- * would make an unrelated `memory.md` collide with the pinned index. (Known limit:
- * `toLowerCase` is not NTFS's exact case-folding table, same as the Python guard.)
- */
-function pathKey(p) {
-  let head = resolve(p)
-  const tail = []
-  for (;;) {
-    try {
-      head = realpathSync(head)
-      break
-    } catch {
-      const parent = dirname(head)
-      if (parent === head) break // hit the root with nothing resolvable
-      tail.unshift(basename(head))
-      head = parent
-    }
-  }
-  const out = tail.length ? join(head, ...tail) : head
-  return process.platform === 'win32' ? out.toLowerCase() : out
-}
-
-
-/**
- * An empty or non-string indexName must fall back, not silently disable the cap:
- * the numeric caps already recover from nonsense values, and this field is the one
- * that decides whether the guard fires at all.
- */
-function indexNameOf(value) {
-  return typeof value === 'string' && value.trim() ? value.trim() : DEFAULT_INDEX_NAME
-}
-
-/**
- * The always-on block states the discipline; this is the on-demand detail the model
- * pulls when it is actually about to recall, write, or sync. Kept deliberately short —
- * the full protocol is SKILL.md in the Engramory repo, and a skill body that has to be
- * read before it is useful is a skill that will not be read.
- */
-function builtinSkillBody() {
-  return [
-    '# Engramory — curated file-based memory',
-    '',
-    'One canonical store: `MEMORY.md` is an index of pointers, one line per memory;',
-    'each fact lives in its own small markdown file beside it. Never put content in',
-    'the index, and never keep a second parallel store for handoffs. The ACTIVE',
-    'store is flat — the four type names are values of the `type:` field, not',
-    'subdirectories to create; `archive/` is the one reserved subdirectory, for',
-    'notes retired out of the index.',
-    '',
-    '## Recall',
-    '',
-    'A turn, a message, or a session is NOT BY ITSELF a task: a greeting, an',
-    'acknowledgement, or a reaction starts none, so it gets no recall and no',
-    'checkpoint. A task is user-directed work whose CORRECT handling could depend',
-    'on what the store holds — read-only work (analysis, diagnosis, planning,',
-    'review)',
-    'counts, and changing a file is not required. HAVING THE MATERIAL IN HAND does',
-    'not make work a non-task: a diff pasted for review is still a task. NEVER INFER',
-    'THIS FROM LENGTH: a one-word reply that picks an option or carries on work',
-    'underway inherits that task. Still unclear? Treat it as a task.',
-    '',
-    'At the start of a task, read the index and open only the notes whose hooks look',
-    'relevant. Treat what you recall as background that may be stale: re-verify any',
-    'file, flag, or version against the repo before acting on it.',
-    '',
-    '## Write',
-    '',
-    'Before writing, confirm the fact is not already in the repo, git history, or the',
-    'instruction files, and that it is not a secret value. Search the index and update',
-    'an existing note rather than adding a near-duplicate. A new note is one atomic',
-    'fact with frontmatter:',
-    '',
-    '```markdown',
-    '---',
-    'name: <kebab-case-slug>',
-    'description: <one sharp line — this is what future-you reads to decide to open it>',
-    'type: user | feedback | project | reference',
-    'scope: global | repo        # optional: does this still hold in another repo?',
-    'created: YYYY-MM-DD',
-    'updated: YYYY-MM-DD',
-    '---',
-    '```',
-    '',
-    '`feedback` and `project` notes MUST carry a `**Why:**` line and a',
-    '`**How to apply:**` line. Add exactly one pointer line to the index, and delete',
-    'memories that turn out to be wrong.',
-    '',
-    'Store settled facts, never current state: "2.0 shipped on 2026-01-15" is durable;',
-    '"the current version is X", the tip commit, or a passing test count will rot —',
-    'record where to read those instead.',
-    '',
-    'An unfinished task may keep AT MOST ONE live `project` note holding its goal,',
-    'status, decisions, constraints, blockers, and next step together — the single',
-    'exception to one-file-one-fact, and a ceiling rather than a quota: a task that',
-    'needs no resumable state keeps no note. Update it IN PLACE. Never a dated',
-    'series (`state-2026-01-15.md`, `state-2026-01-16.md`, …), never a second',
-    'handoff log indexed beside it, and retire its transient state once it ends.',
-    '',
-    '## When a task finishes',
-    '',
-    'Run one curation checkpoint. It is a judgement, not a write: promote what is',
-    'durable, retire the transient state the CURRENT task left on its own live',
-    '`project` note if it has one, and when nothing is worth keeping, write',
-    'nothing and say so. Never append a per-turn log TO THE STORE, and never touch',
-    'a file just to mark it fresh — a timestamp is not a memory.',
-    '',
-    '## Sync',
-    '',
-    'Before a deliberate compact, clear, or new thread: scan the task, dedup and update,',
-    'refresh project state, promote only reusable feedback, retire completed transient',
-    'state, then report what was added, updated, archived, and skipped.',
-    '',
-    '## The cap is enforced here',
-    '',
-    'This host denies a write that would GROW the index past 200 lines / 25 KB. That is',
-    'a real refusal, not a warning — but a write that shrinks the index always passes,',
-    'so compact first, step by step if needed: the index is loaded every session, and',
-    'anything past the cap silently stops being recalled.',
-    '',
-    'Never write credentials, keys, tokens, or cookies into memory — record only where',
-    'the secret lives.',
-  ].join('\n')
-}
+/**
+ * dsh-engramory — the Engramory memory discipline as a DeepSeek Harness plugin.
+ *
+ * Two things the always-on AGENTS.md block cannot do on its own:
+ *
+ *   1. A DETERMINISTIC index cap. dsh's `ctx.tools.guard()` is a synchronous,
+ *      monotonic refusal — once a guard returns a reason, no later waterfall
+ *      listener can turn it back into an allow. That makes it a stronger seam than
+ *      most hosts expose, and it is why the 200-line / 25 KB limit can be enforced
+ *      here rather than merely asked for. Without a shim like this one, everywhere
+ *      except Claude Code the cap degrades to "rules plus a checker the agent has to
+ *      remember to run".
+ *   2. Skill delivery that does not depend on install paths. Registering at runtime
+ *      sidesteps the five-root scan entirely, so the protocol is present because the
+ *      plugin is loaded, not because a directory happened to be right.
+ *
+ * The decision table mirrors hooks/engramory_index_guard.py: deny only a write that
+ * ENDS over a cap AND grew past the current file — a shrinking rewrite always passes,
+ * so an over-cap index can be compacted incrementally (210 → 205 → 198). Only known
+ * mutating tools are gated; `read` and unknown tools are never refused (the first cut
+ * gated everything that named the index, which blocked recall of an over-cap index at
+ * exactly the moment compaction was needed).
+ *
+ * Zero dependencies, no build step: plain ESM, node: builtins only.
+ */
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, statSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path'
+
+export const name = 'engramory'
+
+// `tools` carries the cap and is the plugin's only declared dependency. Cordis reads
+// `inject` as an array of service names (or an object KEYED by them) and treats every
+// entry as a hard wait — the `{ required, optional }` shape is older-Cordis syntax that
+// the build dsh vendors resolves as services literally named "required"/"optional",
+// which never appear, so the plugin sat pending forever (issue #8). `skills` is
+// deliberately NOT declared: the cap must mount even on a profile with no skill
+// registry, so apply() probes it at runtime instead.
+export const inject = ['tools']
+
+/** Mirrors hooks/engramory_index_guard.py — the caps are the protocol's, not this port's. */
+const DEFAULT_INDEX_NAME = 'MEMORY.md'
+const DEFAULT_MAX_LINES = 200
+const DEFAULT_MAX_BYTES = 25600
+
+/**
+ * The most the guard reads to measure the current index (#21). Guards run on the host's
+ * main thread, so an unbounded read of whatever answers to the index's name — a symlink
+ * to /dev/zero, a multi-gigabyte file — stalls or exhausts the host. Past this the index
+ * is long since over the cap, and its byte size comes from the filesystem instead.
+ * The ceiling holds even against an absurd `maxBytes` (4 × 1e308 is Infinity).
+ */
+const MIN_READ_LIMIT = 1024 * 1024
+const MAX_READ_LIMIT = 16 * 1024 * 1024
+
+/** Tools that replace a file wholesale, so the post-write text is in the arguments. */
+const WHOLE_FILE_WRITES = new Set(['write'])
+
+/**
+ * Tools that mutate a file in place. Only tools named here (plus
+ * `str_replace_editor`'s write commands, handled explicitly) count as partial
+ * writes. Unknown tools pass through: this guard is a discipline rail, not a
+ * security boundary (SECURITY.md), and a false refusal of `read` costs more than a
+ * miss — the next whole-file write is measured exactly regardless.
+ */
+const PARTIAL_WRITES = new Set(['edit', 'str_replace', 'insert'])
+
+export function apply(ctx, config = {}) {
+  // `indexPath` pins the guard to ONE file. Without it the only signal is the
+  // basename, so an unrelated MEMORY.md in any other project is gated too — a real
+  // refusal on a file that is not a memory index at all, with no way to opt out
+  // (renaming `indexName` would just unguard the real index). The Claude Code hook
+  // has had ENGRAMORY_INDEX_PATH for exactly this; this is its counterpart.
+  //
+  // The key and the basename are computed ONCE here: guards run on every tool call
+  // and must stay cheap, so the per-call path stays a string compare and the single
+  // realpath() only happens when the basename already matched.
+  const indexPath = typeof config.indexPath === 'string' && config.indexPath.trim()
+    ? config.indexPath.trim()
+    : undefined
+  const settings = {
+    indexName: indexNameOf(config.indexName),
+    indexPath,
+    indexKey: indexPath === undefined ? undefined : pathKey(indexPath),
+    // When pinned, the name to match is the pinned file's own basename.
+    matchName: (indexPath === undefined
+      ? indexNameOf(config.indexName)
+      : basename(indexPath)).toLowerCase(),
+    maxLines: positive(config.maxLines, DEFAULT_MAX_LINES),
+    maxBytes: positive(config.maxBytes, DEFAULT_MAX_BYTES),
+  }
+  settings.readLimit = Math.min(MAX_READ_LIMIT, Math.max(MIN_READ_LIMIT, 4 * settings.maxBytes))
+
+  // dsh 0.2 resolves a relative file path against the calling SESSION's working
+  // directory, which its `working_directory` tool moves away from the process's own
+  // cwd. Measured against process.cwd(), a bare `MEMORY.md` after a cd is the wrong
+  // file or none: an edit of the real index passed unmeasured, and a shrinking rewrite
+  // of an over-cap index was judged against an empty file and refused. The service is
+  // optional (0.1.x has none) and may mount late, so — like `skills` below — it is
+  // picked up reactively and never makes the cap wait.
+  let workingDirectory
+  ctx.inject(['workingDirectory'], (inner) => {
+    inner.effect(() => {
+      const service = inner.workingDirectory
+      workingDirectory = service
+      return () => {
+        if (workingDirectory === service) workingDirectory = undefined
+      }
+    })
+  })
+  const sessionCwd = (exec) => {
+    try {
+      const dir = workingDirectory?.get(exec.agent.session)
+      return typeof dir === 'string' && isAbsolute(dir) ? dir : undefined
+    } catch {
+      return undefined // no agent, no session, or a service shape this port predates
+    }
+  }
+
+  // A guard that throws breaks the host's tool call; only an UNEXPECTED exception can
+  // get here (an edit whose simulated result exceeds V8's string limit, say), and like
+  // the Python guard it fails open — the host could not perform such an edit either.
+  ctx.tools.guard((exec) => {
+    try {
+      return refuseOversizedIndex(exec, settings, sessionCwd)
+    } catch {
+      return undefined
+    }
+  })
+
+  // The skill registry is optional AND may activate after this plugin — fiber order
+  // between unrelated providers is not guaranteed, so a one-shot probe here would
+  // silently skip registration on such boots. ctx.inject() is Cordis' reactive form:
+  // the callback runs once `skills` is available (however late), re-runs if the
+  // registry reloads, and never makes the cap wait. A bare `ctx.skills` read at THIS
+  // level would throw (undeclared service — issue #8's second crash); inside the
+  // callback the service is declared, so the read is legal.
+  if (config.registerSkill !== false) {
+    ctx.inject(['skills'], (inner) => {
+      const skill = config.skill ?? builtinSkillBody()
+      // effect() ties the registration to the child fiber: it is disposed when the
+      // registry unloads, so a reload cannot accumulate duplicate registrations.
+      inner.effect(() => inner.skills.register({
+        name: 'engramory',
+        description:
+          'Curated file-based long-term memory: recall through MEMORY.md at the start of ' +
+          'a task, save durable user/feedback/project/reference facts, run a curation ' +
+          'checkpoint when a task finishes, and sync before compacting or opening a ' +
+          'fresh thread. A turn that starts no work — a greeting, an acknowledgement — ' +
+          'is not a task and needs none of this, but never judge that by length: a ' +
+          'one-word reply continuing work underway inherits that task.',
+        whenToUse:
+          'Starting or resuming work, learning something durable worth a future session, ' +
+          'finishing a task — including one that leaves nothing worth saving, since the ' +
+          'checkpoint is still a decision to make — or approaching a ' +
+          'compact/clear/new-thread boundary. Not for a bare greeting, ' +
+          'acknowledgement, or reaction, which starts no task — but a terse reply ' +
+          'that continues work underway does, and material already in hand (a ' +
+          'pasted diff to review) does not make work a non-task. Unsure? Treat it ' +
+          'as a task.',
+        source: 'runtime',
+        content: skill,
+      }))
+    })
+  }
+}
+
+/**
+ * The cap itself. Returning a string denies the call; `undefined` lets it through.
+ *
+ * Guards are synchronous by contract, so this stays cheap: every tool that cannot
+ * write leaves on string compares; a write pays a path resolution, and a write to the
+ * index one bounded read of it.
+ */
+function refuseOversizedIndex(exec, settings, sessionCwd) {
+  const args = exec?.arguments
+  if (!args || typeof args !== 'object') return undefined
+
+  // dsh's file tools carry the target as `file_path`; `str_replace_editor` calls it
+  // `path`.
+  const filePath = typeof args.file_path === 'string' ? args.file_path
+    : typeof args.path === 'string' ? args.path
+      : undefined
+  if (filePath === undefined) return undefined
+
+  const tool = typeof exec.name === 'string' ? exec.name : ''
+
+  // Nothing below can refuse a read, a view, or an unknown tool, so leave before
+  // anything touches the filesystem: a guard runs on EVERY tool call, and this keeps
+  // the common case a few string compares.
+  const gated = WHOLE_FILE_WRITES.has(tool)
+    || PARTIAL_WRITES.has(tool)
+    || (tool === 'str_replace_editor'
+      && (args.command === 'create' || args.command === 'str_replace'
+        || args.command === 'insert'))
+  if (!gated) return undefined
+  // Every read and identity check below uses the file the host will actually touch.
+  let target
+  try {
+    target = hostPath(sessionCwd(exec), filePath)
+  } catch {
+    return undefined // a relative path and no cwd left to resolve it (deleted under us)
+  }
+  // Is this the index? Decided on the file the write lands on, not the name it was
+  // called by: dsh follows a symlink, so `idx.md -> MEMORY.md` writes the index (#20).
+  // Pinned, that is identity — which is also where an unrelated same-named file in
+  // another project drops out. Unpinned, the name of the path or of what it resolves
+  // to, compared case-INsensitively: on the case-insensitive filesystems most stores
+  // live on (Windows/macOS), `memory.md` IS the guarded index. (Same trade-off as the
+  // Python guard: on a case-sensitive FS this can gate an unrelated lowercase twin —
+  // rename it, or pin `indexPath`.)
+  const named = (p) => basename(p).toLowerCase() === settings.matchName
+  const isIndex = settings.indexKey !== undefined
+    ? pathKey(target) === settings.indexKey
+    : named(filePath) || named(pathKey(target))
+  if (!isIndex) return undefined
+
+  if (WHOLE_FILE_WRITES.has(tool)) {
+    if (typeof args.content !== 'string') return undefined
+    return verdict(args.content, readIndex(target, settings.readLimit), filePath, settings)
+  }
+  if (tool === 'str_replace_editor' && args.command === 'create') {
+    if (typeof args.file_text !== 'string') return undefined
+    return verdict(args.file_text, readIndex(target, settings.readLimit), filePath, settings)
+  }
+
+  const partial = PARTIAL_WRITES.has(tool)
+    || (tool === 'str_replace_editor'
+      && (args.command === 'str_replace' || args.command === 'insert'))
+  if (!partial) return undefined // read / view / list / unknown: never refused
+
+  // Unreadable, or past the read limit: an edit's result cannot be simulated without
+  // the whole text, and refusing it blind would refuse the compacting ones too. Let it
+  // through, as for any index the guard cannot read; whole-file writes stay measured.
+  const currentBuf = readIndex(target, settings.readLimit)
+  if (currentBuf === undefined || !Buffer.isBuffer(currentBuf)) return undefined
+  const current = currentBuf.toString('utf8')
+  const simulated = simulateEdit(current, args, settings.readLimit)
+  if (typeof simulated === 'string') {
+    return verdict(simulated, currentBuf, filePath, settings)
+  }
+  if (simulated !== undefined) {
+    // Too long to build: judged on lower bounds of its size, by the same grow-past-the-
+    // cap rule as verdict(). A bound that clears both tests refuses only what the full
+    // result would; one that does not lets the edit through unmeasured.
+    const over = []
+    if (simulated.newlines > settings.maxLines && simulated.newlines > countLines(current)) {
+      over.push(`at least ${simulated.newlines} lines > ${settings.maxLines}`)
+    }
+    if (simulated.bytes > settings.maxBytes && simulated.bytes > currentBuf.length) {
+      over.push(`at least ${simulated.bytes} bytes > ${settings.maxBytes}`)
+    }
+    return over.length ? capRefusal(over, filePath, settings) : undefined
+  }
+
+  // The edit's result genuinely cannot be reconstructed from its arguments. Honest,
+  // cheap rule: if the index is ALREADY over, refuse to mutate it blind — and name
+  // the open door, because "compact first" while refusing edits reads as a dead end.
+  const breach = measure(current, settings)
+  if (!breach) return undefined
+  return (
+    `${displayName(settings)} is already over the Engramory cap (${breach}) and this ` +
+    `edit's result cannot be measured. Compact it with a whole-file write instead: ` +
+    `a rewrite that SHRINKS the index always passes, even while still over the cap. ` +
+    `Pointer-ify over-long lines, merge duplicates, archive cold notes — the index ` +
+    `is a table of contents, and anything past the cap silently stops being recalled.` +
+    notMyIndexHint(settings)
+  )
+}
+
+/**
+ * Mirrors the Python guard's deny rule: refuse only when a dimension ends OVER its
+ * cap AND grew past the current file, so a shrinking/keeping write on an over-cap
+ * index always passes and incremental compaction stays possible. A missing or
+ * unreadable current file counts as empty — a first write past the cap is refused.
+ * One too large to read (see readIndex) is sized by the filesystem, with a line count
+ * no write can exceed: only its byte growth can be refused, and every shrink passes.
+ */
+function verdict(text, currentBuf, filePath, settings) {
+  const lines = countLines(text)
+  const bytes = Buffer.byteLength(text, 'utf8')
+  // Current byte size comes from the RAW buffer, mirroring how the Python guard
+  // sizes the on-disk file: decoding first inflated a non-UTF-8 index ~3x (every
+  // bad byte becomes a 3-byte U+FFFD), which made a genuinely growing write look
+  // like a shrink and pass. Newlines survive a lossy decode, so the line count may
+  // use the decoded text.
+  const unread = currentBuf !== undefined && !Buffer.isBuffer(currentBuf)
+  const curLines = currentBuf === undefined ? 0
+    : unread ? Infinity : countLines(currentBuf.toString('utf8'))
+  const curBytes = currentBuf === undefined ? 0 : unread ? currentBuf.bytes : currentBuf.length
+  const over = []
+  if (lines > settings.maxLines && lines > curLines) {
+    over.push(`${lines} lines > ${settings.maxLines}`)
+  }
+  if (bytes > settings.maxBytes && bytes > curBytes) {
+    over.push(`${bytes} bytes > ${settings.maxBytes}`)
+  }
+  return over.length ? capRefusal(over, filePath, settings) : undefined
+}
+
+function capRefusal(over, filePath, settings) {
+  return (
+    `This write would put ${basename(filePath)} over the Engramory index cap ` +
+    `(${over.join(', ')}). The index is loaded every session and the host only reads ` +
+    `so far, so anything past the cap silently stops being recalled. Compact before ` +
+    `writing: move detail into the linked note files, merge duplicates, archive cold ` +
+    `notes, and keep every line to "one short hook + link". A write that SHRINKS the ` +
+    `index always passes, so you can compact step by step.` + notMyIndexHint(settings)
+  )
+}
+
+
+/**
+ * The name to show in a refusal. `indexPath` wins over `indexName` when both are set,
+ * so quoting the ignored one would send a user looking for the wrong file.
+ */
+function displayName(settings) {
+  return settings.indexPath === undefined
+    ? settings.indexName
+    : basename(settings.indexPath)
+}
+
+
+/**
+ * Without `indexPath` the guard matches on basename alone, so it can land on a file
+ * that is not a memory index at all. Say so in the refusal: a user who hits this
+ * needs the way out, not just the cap.
+ */
+function notMyIndexHint(settings) {
+  if (settings.indexPath !== undefined) return ''
+  return (
+    ` (If this file is NOT your memory index, set this plugin's \`indexPath\` config ` +
+    `to your real index's absolute path so only that file is gated.)`
+  )
+}
+
+/**
+ * Reconstruct a partial edit's post-write text when its arguments carry enough to
+ * do it (`old_str`/`new_str`, or the Claude-style `old_string`/`new_string`).
+ * Mirrors the Python guard's Edit simulation: replace the unique occurrence, or all
+ * of them under a replace-all flag; an absent or ambiguous old-string means the
+ * real tool errors and changes nothing, so the current text is the honest
+ * prediction. Returns undefined when the shape isn't recognised, and `{ bytes, newlines }`
+ * — lower bounds of the result's size — when it is too long to build.
+ *
+ * Matching happens on LF-normalised text and the result goes back in the file's own
+ * line endings, as dsh's local backend does it (`applyLiteralEdit` /
+ * `restoreLineEndings` in @deepseek-ai/dsh-fs-local). Matching the raw text let a CRLF
+ * index — common on Windows — read every LF `old_string` as "not found", predict no
+ * change, and pass an edit dsh then applied.
+ */
+function simulateEdit(current, args, limit) {
+  const oldRaw = firstString(args.old_str, args.old_string)
+  if (oldRaw === undefined || oldRaw === '') return undefined
+  const newRaw = firstString(args.new_str, args.new_string) ?? ''
+  // dsh decodes with TextDecoder, which drops a leading BOM — from the text it
+  // matches, from the sample it detects line endings on, and from what it writes back.
+  const decoded = current.startsWith('\uFEFF') ? current.slice(1) : current
+  // Normalising CRLF at most halves a string, so an old_string over twice the text's
+  // length cannot be in it: the real tool errors, nothing changes. Checked before it
+  // is normalised, so an argument the size of the heap is never copied (#21).
+  if (oldRaw.length > 2 * decoded.length) return current
+  const text = lf(decoded)
+  const oldStr = lf(oldRaw)
+  const first = text.indexOf(oldStr)
+  if (first === -1) return current // the real tool errors: nothing changes
+  const all = args.replace_all === true || args.replaceAll === true
+  if (!all && text.indexOf(oldStr, first + oldStr.length) !== -1) {
+    return current // ambiguous: the real tool errors, nothing changes
+  }
+  const matches = all ? occurrences(text, oldStr) : 1
+  // Sized before it is built: replace_all multiplies new_string by every match, and
+  // building the result just to measure it could cost the host gigabytes — or abort it
+  // outright on heap exhaustion, which no catch survives. new_string is measured as it
+  // will be once normalised, without normalising it: each CRLF in it loses its CR.
+  const crlfs = occurrences(newRaw, '\r\n')
+  const length = text.length + matches * (newRaw.length - crlfs - oldStr.length)
+  if (length > limit) {
+    // Exact for the LF text, and so lower bounds for what dsh writes: restoring CRLF
+    // only adds bytes, and never changes the line count. UTF-8 sizes add up only for
+    // well-formed text: a lone surrogate counts three bytes, but two meeting at a
+    // replacement seam encode as one four-byte pair. With one anywhere, fall back to
+    // the length — every UTF-16 unit is at least one byte, paired or not.
+    const wellFormed = !LONE_SURROGATE.test(text) && !LONE_SURROGATE.test(newRaw)
+      && !LONE_SURROGATE.test(oldStr)
+    return {
+      bytes: wellFormed
+        ? Buffer.byteLength(text)
+          + matches * (Buffer.byteLength(newRaw) - crlfs - Buffer.byteLength(oldStr))
+        : length,
+      newlines: occurrences(text, '\n')
+        + matches * (occurrences(newRaw, '\n') - occurrences(oldStr, '\n')),
+    }
+  }
+  const newStr = lf(newRaw) // no longer than the result, so within the limit
+  // A function replacer, so a `$&` in new_string stays literal.
+  const edited = all
+    ? text.replaceAll(oldStr, () => newStr)
+    : text.slice(0, first) + newStr + text.slice(first + oldStr.length)
+  // Normalised once more before expanding, as dsh's restoreLineEndings does: a lone
+  // `\r` meeting an inserted `\n` at the seam is one CRLF, not `\r\r\n`.
+  return crlfDominates(decoded) ? lf(edited).replaceAll('\n', '\r\n') : edited
+}
+
+/** A high surrogate with no low after it, or a low with no high before it. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/
+
+/** Non-overlapping occurrences of `needle`, counted rather than split out. */
+function occurrences(text, needle) {
+  let n = 0
+  for (let i = text.indexOf(needle); i !== -1; i = text.indexOf(needle, i + needle.length)) n++
+  return n
+}
+
+function lf(text) {
+  return text.replaceAll('\r\n', '\n')
+}
+
+/** dsh's own call (`detectLineEndings`): CRLF wins on a majority in the first 4096 chars. */
+function crlfDominates(raw) {
+  const sample = raw.slice(0, 4096)
+  const crlf = sample.split('\r\n').length - 1
+  return crlf > sample.split('\n').length - 1 - crlf
+}
+
+function firstString(...values) {
+  for (const v of values) {
+    if (typeof v === 'string') return v
+  }
+  return undefined
+}
+
+/** Returns a human-readable breach description, or `null` when the text is within caps. */
+function measure(text, { maxLines, maxBytes }) {
+  const lines = countLines(text)
+  const bytes = Buffer.byteLength(text, 'utf8')
+  const over = []
+  if (lines > maxLines) over.push(`${lines} lines > ${maxLines}`)
+  if (bytes > maxBytes) over.push(`${bytes} bytes > ${maxBytes}`)
+  return over.length ? over.join(', ') : null
+}
+
+/**
+ * Trailing-newline-insensitive, matching how the Python guard counts. Counted, not
+ * split: the text is whatever a tool call carried, and an array of its lines would
+ * cost a second copy of it.
+ */
+function countLines(text) {
+  if (!text) return 0
+  return occurrences(text, '\n') + 1 - (text.endsWith('\n') ? 1 : 0)
+}
+
+/**
+ * A missing or unreadable index is not a breach: the guard's job is to stop an
+ * oversized index, never to block work because a path could not be read. Returns the
+ * RAW buffer — byte comparisons must use on-disk bytes (see verdict), decode at the
+ * call sites that need text — or `{ bytes }` for a regular file past `limit`.
+ *
+ * Only a regular file is read, and never more than `limit + 1` bytes (#21). The read
+ * runs on the host's main thread, and a plain readFileSync would block forever on a
+ * FIFO (opening one waits for a writer, hence O_NONBLOCK — absent on Windows, which has
+ * no FIFOs on disk) or keep allocating on a symlink to /dev/zero. Anything that is not
+ * a regular file counts as unreadable. A stat comes first, so a device is never even
+ * opened (some drivers block in open itself); the descriptor is checked again, since
+ * the path can be swapped between the two.
+ */
+function readIndex(filePath, limit) {
+  let fd
+  try {
+    if (!statSync(filePath).isFile()) return undefined
+    fd = openSync(filePath, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0))
+    const stat = fstatSync(fd)
+    if (!stat.isFile()) return undefined
+    const chunks = []
+    let total = 0
+    for (;;) {
+      const chunk = Buffer.allocUnsafe(Math.min(65536, limit + 1 - total))
+      const got = readSync(fd, chunk, 0, chunk.length, null)
+      if (got === 0) return Buffer.concat(chunks, total)
+      chunks.push(chunk.subarray(0, got))
+      total += got
+      if (total > limit) return { bytes: Math.max(stat.size, total) }
+    }
+  } catch {
+    return undefined
+  } finally {
+    if (fd !== undefined) {
+      try { closeSync(fd) } catch { /* nothing left to do */ }
+    }
+  }
+}
+
+function positive(value, fallback) {
+  if (!Number.isFinite(value)) return fallback
+  const floored = Math.floor(value)
+  return floored > 0 ? floored : fallback
+}
+
+/**
+ * The path the host's own file tools would touch for `p`, mirroring dsh's local
+ * backend (`localDisplayPath` in @deepseek-ai/dsh-fs-local): resolve against `cwd`,
+ * except that on POSIX a spelling with a `..` segment is kept as written, so a `..`
+ * after a symlinked segment stays physical — collapsing it could measure a different
+ * file than the one the write lands on. Without a session directory (`cwd`
+ * undefined), the process's is used, and only when `p` needs one: process.cwd()
+ * throws once that directory is deleted, and an absolute path must not care.
+ */
+function hostPath(cwd, p) {
+  const resolved = () => (cwd === undefined ? resolve(p) : resolve(cwd, p))
+  if (process.platform === 'win32') return resolved()
+  const raw = isAbsolute(p) ? p : `${cwd ?? process.cwd()}${sep}${p}`
+  return /(?:^|[\\/])\.\.(?:[\\/]|$)/u.test(raw) ? raw : resolved()
+}
+
+/**
+ * Normalise a path for identity comparison. `realpath` resolves symlinks and `..` so
+ * two spellings of the same file compare equal, but it throws for a path with no file
+ * behind it yet — and a plain `resolve` fallback is NOT interchangeable with it: an
+ * index pinned before it exists, under a symlinked ancestor, would be keyed by its
+ * alias at config time and by the link's target on every later call. The keys would
+ * never match again and the guard would silently stop guarding its own index.
+ *
+ * So resolve the deepest ancestor that DOES exist and re-attach the missing tail:
+ * the same file then keys identically whether or not it exists yet. Case is folded on
+ * Windows only, mirroring `os.path.normcase` in the Python guard — folding it on Linux
+ * would make an unrelated `memory.md` collide with the pinned index. (Known limit:
+ * `toLowerCase` is not NTFS's exact case-folding table, same as the Python guard.)
+ *
+ * On POSIX an absolute spelling is kept as written and walked by the OS
+ * (`realpathSync.native` is realpath(3)): Node's JS realpathSync resolve()s first, which
+ * collapses a `..` after a symlinked segment lexically — to the parent of the LINK,
+ * where dsh, walking it physically, reaches the parent of its TARGET. `link/../idx.md`
+ * then named another file than the one written (#20). Windows resolves `..` lexically
+ * anyway, as dsh does there, so it keeps the JS form.
+ */
+function pathKey(p) {
+  const posix = process.platform !== 'win32'
+  const real = posix ? realpathSync.native : realpathSync
+  let head = posix && isAbsolute(p) ? p : resolve(p)
+  const tail = []
+  for (;;) {
+    try {
+      head = real(head)
+      break
+    } catch {
+      const parent = dirname(head)
+      if (parent === head) break // hit the root with nothing resolvable
+      tail.unshift(basename(head))
+      head = parent
+    }
+  }
+  const out = tail.length ? join(head, ...tail) : head
+  return process.platform === 'win32' ? out.toLowerCase() : out
+}
+
+
+/**
+ * An empty or non-string indexName must fall back, not silently disable the cap:
+ * the numeric caps already recover from nonsense values, and this field is the one
+ * that decides whether the guard fires at all.
+ */
+function indexNameOf(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : DEFAULT_INDEX_NAME
+}
+
+/**
+ * The always-on block states the discipline; this is the on-demand detail the model
+ * pulls when it is actually about to recall, write, or sync. Kept deliberately short —
+ * the full protocol is SKILL.md in the Engramory repo, and a skill body that has to be
+ * read before it is useful is a skill that will not be read.
+ */
+function builtinSkillBody() {
+  return [
+    '# Engramory — curated file-based memory',
+    '',
+    'One canonical store: `MEMORY.md` is an index of pointers, one line per memory;',
+    'each fact lives in its own small markdown file beside it. Never put content in',
+    'the index, and never keep a second parallel store for handoffs. The ACTIVE',
+    'store is flat — the four type names are values of the `type:` field, not',
+    'subdirectories to create; `archive/` is the one reserved subdirectory, for',
+    'notes retired out of the index.',
+    '',
+    '## Recall',
+    '',
+    'A turn, a message, or a session is NOT BY ITSELF a task: a greeting, an',
+    'acknowledgement, or a reaction starts none, so it gets no recall and no',
+    'checkpoint. A task is user-directed work whose CORRECT handling could depend',
+    'on what the store holds — read-only work (analysis, diagnosis, planning,',
+    'review)',
+    'counts, and changing a file is not required. HAVING THE MATERIAL IN HAND does',
+    'not make work a non-task: a diff pasted for review is still a task. NEVER INFER',
+    'THIS FROM LENGTH: a one-word reply that picks an option or carries on work',
+    'underway inherits that task. Still unclear? Treat it as a task.',
+    '',
+    'At the start of a task, read the index and open only the notes whose hooks look',
+    'relevant. Treat what you recall as background that may be stale: re-verify any',
+    'file, flag, or version against the repo before acting on it.',
+    '',
+    '## Write',
+    '',
+    'Before writing, confirm the fact is not already in the repo, git history, or the',
+    'instruction files, and that it is not a secret value. Search the index and update',
+    'an existing note rather than adding a near-duplicate. A new note is one atomic',
+    'fact with frontmatter:',
+    '',
+    '```markdown',
+    '---',
+    'name: <kebab-case-slug>',
+    'description: <one sharp line — this is what future-you reads to decide to open it>',
+    'type: user | feedback | project | reference',
+    'scope: global | repo        # optional: does this still hold in another repo?',
+    'created: YYYY-MM-DD',
+    'updated: YYYY-MM-DD',
+    '---',
+    '```',
+    '',
+    '`feedback` and `project` notes MUST carry a `**Why:**` line and a',
+    '`**How to apply:**` line. Add exactly one pointer line to the index, and delete',
+    'memories that turn out to be wrong.',
+    '',
+    'Store settled facts, never current state: "2.0 shipped on 2026-01-15" is durable;',
+    '"the current version is X", the tip commit, or a passing test count will rot —',
+    'record where to read those instead.',
+    '',
+    'An unfinished task may keep AT MOST ONE live `project` note holding its goal,',
+    'status, decisions, constraints, blockers, and next step together — the single',
+    'exception to one-file-one-fact, and a ceiling rather than a quota: a task that',
+    'needs no resumable state keeps no note. Update it IN PLACE. Never a dated',
+    'series (`state-2026-01-15.md`, `state-2026-01-16.md`, …), never a second',
+    'handoff log indexed beside it, and retire its transient state once it ends.',
+    '',
+    '## When a task finishes',
+    '',
+    'Run one curation checkpoint. It is a judgement, not a write: promote what is',
+    'durable, retire the transient state the CURRENT task left on its own live',
+    '`project` note if it has one, and when nothing is worth keeping, write',
+    'nothing and say so. Never append a per-turn log TO THE STORE, and never touch',
+    'a file just to mark it fresh — a timestamp is not a memory.',
+    '',
+    '## Sync',
+    '',
+    'Before a deliberate compact, clear, or new thread: scan the task, dedup and update,',
+    'refresh project state, promote only reusable feedback, retire completed transient',
+    'state, then report what was added, updated, archived, and skipped.',
+    '',
+    '## The cap is enforced here',
+    '',
+    'This host denies a write that would GROW the index past 200 lines / 25 KB. That is',
+    'a real refusal, not a warning — but a write that shrinks the index always passes,',
+    'so compact first, step by step if needed: the index is loaded every session, and',
+    'anything past the cap silently stops being recalled.',
+    '',
+    'Never write credentials, keys, tokens, or cookies into memory — record only where',
+    'the secret lives.',
+  ].join('\n')
+}