feat: ctx pad undo, out-of-band audit channel (ctxctl), OS-native memory pressure

[josealekhine]

Summary

This branch lands four independent pieces of work that grew together
on a single feature branch:

1. ctx pad undo — a snapshot-on-mutate safety net for the
   encrypted scratchpad.
2. An out-of-band audit channel, shipped as a separate
   maintainer-only binary (ctxctl) rather than inside the
   user-facing ctx binary.
3. OS-native memory-pressure detection in the resource hook,
   replacing broken occupancy-percentage triggers.
4. Typed, text-free audit errors with rendering moved to the
   ctxctl edge.

Each is described below. The audit channel evolved within the branch
(it was first built inside ctx, then extracted into ctxctl); the
net state delivered to main is described here, not the
commit-by-commit churn.

What's in this PR

1. ctx pad undo — scratchpad safety net (Phase 1)

Spec: specs/pad-undo-snapshot.md

• Every destructive ctx pad operation snapshots the prior pad blob
  to .context/scratchpad.history/ before overwriting.
• New ctx pad undo subcommand restores the most recent snapshot.
• Snapshots are the existing pad bytes byte-for-byte (no
  re-encryption), so plaintext and encrypted modes get the same net.
• Bounded retention ring: 20 snapshots or 30 days, whichever trips
  first. Prune failures degrade to a warning; the safety net never
  blocks a write.
• undo is itself a snapshotting mutation, so ctx pad undo; ctx pad undo acts as a redo. Empty history prints a friendly message and
  exits 0 (quiet on fresh projects).
• Phase 2 (--list / --to / --prune / --clear, .ctxrc
  retention tuning, skill/recipe docs) is tracked separately.

2. Out-of-band audit channel via ctxctl

Specs: specs/audit-channel.md, specs/ctxctl-bootstrap.md

The audit channel decouples discipline enforcement from the in-band
commit cadence: a separate Claude Code session runs an audit skill,
drops a structured report into .context/audit/<kind>.md, and a
UserPromptSubmit hook verbatim-relays it on the next turn.

It lives in ctxctl, a maintainer/contributor binary kept out of
the shipped ctx binary, so end users never carry an audit hook they
have no producer for.

• Separate Go module at tools/ctxctl/ (module
  github.com/ActiveMemory/ctx/tools/ctxctl); its go.mod requires
  the ctx module via replace ../.., and the repo-root go.work
  links both. ctx's go.mod never requires ctxctl, so ctx can
  never import it.
• Commands: ctxctl audit list | show | dismiss plus the
  ctxctl audit-relay hook.
• ctxctl owns its user-facing English as plain Go constants (no YAML
  i18n / desc engine).
• _ctx-surface-audit skill + docs/recipes/audit-channel.md show
  the pattern (ctx dogfoods an internal auditor over its own
  internal/ tree).
• Makefile: make ctxctl, make install-ctxctl,
  make reinstall-ctxctl (installs to /usr/local/bin/ctxctl).
• Import-graph guard (internal/compliance/ctxctl_isolation_test.go)
  asserts cmd/ctx depends on no internal/ctxctl/... package and
  that the shipped hooks.json carries no audit hook.

3. OS-native memory pressure

No dedicated spec — correctness fix; rationale in .context/DECISIONS.md (2026-05-27)

Replaces the broken occupancy-percentage DANGER triggers
(swap_used/total, memory_used/total) with the kernel's own
pressure signal:

• macOS: sysctl kern.memorystatus_vm_pressure_level.
• Linux: /proc/pressure/memory PSI (some.avg10 >= 10 ->
  Warning, full.avg10 >= 10 -> Danger).
• Other platforms: report PressureSupported=false (Windows
  detection filed as a follow-up).
• The dead, always-OK doctor swap row and its orphaned constants are
  removed; PSI thresholds are named in config/stats for one-place
  retuning.

4. Typed audit errors

Spec: specs/ctxctl-bootstrap.md

internal/ctxctl/err/audit returns typed, text-free errors
(ReadReportError, ParseReportError, WriteDismissalError,
ReadDismissalError, UnknownIDError, plus ErrIDRequired /
ErrNoFrontmatter / ErrUnterminatedFrontmatter sentinels). The
user-facing English moved to tools/ctxctl, which renders the errors
at the command edge through a sole printer (SilenceErrors on the
root, mirroring ctx's internal/write/err.With). This brings the
implementation into full alignment with the spec's "all ctxctl text
lives under tools/ctxctl" rule.

Docs

• docs/recipes/audit-channel.md + recipes index: the channel is
  maintainer-only via ctxctl, with a repo-local hook.
• New "Maintainer Tooling: ctxctl" section in
  docs/home/contributing.md documenting build/install.
• Rendered docs site (site/**) and Atom feed regenerated.

Testing

• make lint: 0 issues (ctx module) and 0 issues (ctxctl
  module).
• make test: green (ctx module); tools/ctxctl module tests pass.
• go build clean on both modules.
• Behavioral coverage: pad snapshot/undo/retention; audit
  list/show/dismiss/relay (incl. dismissal-digest re-surfacing and
  stale-report prefixing); audit error rendering (unknown id, missing
  id, malformed-report parse path); per-platform pressure parsing.

Notes for reviewers

• The audit channel is not in the shipped ctx binary — it is
  ctxctl, a separate module. Reviewing the net tree is easier than
  the add-then-extract commit sequence.
• tools/ctxctl is a second module; CI / local checks must cover it
  in addition to the main module.
• .gitignore un-ignores go.work / go.work.sum (now tracked for
  the workspace) and ignores the built ctxctl binaries.

Follow-ups (tracked in .context/TASKS.md)

• Realign the installed plugin's hooks.json with the cwd-anchored
  binary (fixes a per-prompt help-dump from version skew) — high.
• ctx system <unknown>: emit a verbatim relay instead of a silent
  help dump + exit 0 — medium.
• Windows-native memory-pressure detection — medium/exploratory.
• ctx <add> --json ingest (design parked in
  specs/ctx-add-json-ingest.md) — medium.
• ctx pad undo Phase 2 flags + retention tuning.