continuity-guard 0.5.0__tar.gz

continuity_guard-0.5.0/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+All notable changes to Continuity Guard are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the project uses a
+simple `MAJOR.MINOR.PATCH` scheme.
+
+## [0.5.0] - 2026-08-29
+
+### Fixed
+- **`pipx install` could not run the documented integration paths.** The wheel
+  ships `packages = ["continuity_guard"]`, so `tools/` was never in it, while
+  README and `docs/integrating.md` told users to run `python -m tools.cg_proxy`
+  and `tools/cg_supervise.py`. Both raised `ModuleNotFoundError` on every
+  installed copy. Worse, `cg_supervise` holds the ONLY `write_cache("anthropic")`
+  call, so `cg quota` could never show a Claude percentage after a clean
+  install -- the README's own opening example was unreachable for the user it
+  addressed. Every test and campaign run executes from a checkout where
+  `tools/` is simply on the path, which is why nothing caught it.
+
+  The proxy and supervisor now live in the package as `continuity_guard.proxy`
+  and `continuity_guard.supervise`, with `cg-proxy` and `cg-supervise` console
+  entry points. `tools/*.py` remain as thin shims so existing invocations by
+  path -- systemd units, running phase-1 loops -- keep working unchanged.
+
+### Added
+- **`cg wrap`** -- run a CLI agent under the watchdog with no code and no
+  config: `cg wrap -- claude -p "..."`. Observe-only regardless of profile,
+  and it says so on the first line before it does anything. Arming stays a
+  separate deliberate act in the daemon's configuration.
+
+### Changed
+- Version 0.5.0 rather than 0.4.3. Wrap-up that actually reaches the agent,
+  three working ceilings, named plan windows, a socket that is not a kill
+  oracle, spend that survives a restart, and confirm-polls on quota are not a
+  patch release, and shipping them under 0.4.2 would confuse anyone who
+  installed last week.
+- Docs reconciled with HEAD: `HANDOFF.md` tree pointer, its 19/19 vs 21/21
+  contradiction, and its claim that the socket is `0666` "on purpose" (false
+  since the authority fix, and dangerous as guidance); README's matrix listing
+  stopped at row 18 under a "21 checks" heading; `docs/quota-adapters.md` still
+  said adapters were unimplemented, Codex unverified, and Claude published no
+  percentage -- all three now settled and marked as the research record.
+
+## [Unreleased]
+
+### Changed
+- **The handoff claim is narrowed to what it can actually deliver.** The docs
+  described "every long session ends with its state written down" and "the thing
+  that means I never lose a run". Neither survives contact with the mechanism:
+  what is preserved is the run's observed reach and its *enumerable* progress,
+  not the agent's understanding — the unarticulated hypothesis, the discarded
+  approach and why. That is context, it dies with the context, and summarising
+  it is lossy in a way the reader cannot audit. The claim is now "a warm start
+  on enumerable work, and a guarantee that the run's reach is never unknown",
+  with the two limits that follow from it stated: task shape dominates the
+  value, and findings decay (measured — two of four findings in one handoff were
+  already fixed hours later, and a third was wrong on its own terms). See
+  README "What the handoff is and is not" and `docs/wrapup-signal.md` "The
+  claim, narrowed to what holds".
+- **Handoffs carry findings, not an index.** The agent-written document listed
+  which areas were touched and nothing about what was found, which is a
+  bookmark: a successor could not continue from it without redoing the work.
+  It now carries the task, condensed findings with observed-at stamps, what was
+  ruled out, what remains, and the exact command that resumes past the work
+  already done. Ceiling-aware — a budget does not "reset", and saying so sent a
+  reader to wait for something that never comes.
+
+### Security
+- **An armed daemon could be made to terminate arbitrary processes.** Four
+  facts combined: the Unix socket was created world-writable (`0o666`);
+  `protocol.sanitize()` type-checked HELLO fields but did not authorise them,
+  so peer-supplied `overrides` became effective policy *including* `action`;
+  and `actions._identity_ok()` fell back to "is anything alive with this PID"
+  whenever `start_time` was absent. Any local account could announce another
+  process's PID with `start_time=0` and a policy that terminated on the first
+  frame, and the daemon would signal that process and its group — a kill
+  primitive for everything the daemon's user could signal. Found by a
+  high-reasoning review of `daemon.py`/`detectors.py`, then confirmed
+  end-to-end before it was believed.
+
+  Four independent fixes, because an operator will eventually widen one of them
+  for a good reason: the socket defaults to `0o600` (`CG_SOCKET_MODE` widens it
+  deliberately); operator-only keys are stripped from peer overrides and the
+  removal is logged; termination requires a verified `start_time` where the
+  platform can supply one, and refuses rather than assuming where it cannot;
+  and the announced PID must be the connecting peer or a descendant of it
+  (`SO_PEERCRED`), failing which termination is disarmed for that session while
+  observation continues. `tests/test_authority.py` reproduces the original
+  exploit — the victim process dies against the pre-fix code and survives
+  after.
+
+### Fixed
+- **The hard backstop could be widened by a learned baseline, breaking
+  invariant 4.** `_adaptive_floor` applied its `is_backstop` guard only to the
+  flat learning margin, so `max(configured, base * adaptive_k)` widened the
+  hard ceiling anyway — both while learning and after the baseline froze. A
+  30-minute hard silence ceiling with `adaptive_k = 6` and one learned
+  20-minute gap became **120 minutes**: a frozen process sat undetected for two
+  hours under a configuration that asked for thirty. The guard is now a single
+  unconditional return, since the bug was a branch that forgot it.
+- **Ceilings reset when the daemon restarted.** Every HELLO built a fresh
+  session with `total_tokens = 0` and a new clock, so a client reconnecting
+  after a restart (systemd `Restart=always`, an OOM) got a full budget and a
+  fresh deadline and could spend the whole allowance twice. Accumulated spend
+  and the original start time are now persisted (`session_carry`) and restored
+  on reconnect, bounded by age so a session id reused days later starts clean.
+- **EOF was recorded as death without checking the process.** A supervisor
+  exiting or a TCP reset produced EOF while the agent ran on; that was written
+  to the ledger as a death and could drive `flap`. Where the PID is checkable
+  and still alive, the daemon now says what it actually observed.
+- **Unbounded idle connections.** A peer could open connections, never send a
+  HELLO, and hold them; there was no cap and no handshake timeout, so fds and
+  buffers grew until real agents could not connect. The fuzzer closes its
+  sockets, so its churn never built this up. Now capped (`CG_MAX_CONNS`, 512)
+  with a handshake timeout (`CG_HANDSHAKE_TIMEOUT`, 60s).
+- **Short writes were treated as delivered.** `conn.send()` on a non-blocking
+  socket returns a byte count that was discarded, so under output-buffer
+  pressure a truncated WRAPUP was logged as sent — the client drops the
+  malformed line and never learns a ceiling is near.
+- **Silent `status.json` write failures** left `cg status` stale while looking
+  authoritative. Reported once, and again when it changes.
+- **Three stale claims, found by the tool reviewing itself.** A ceiling-stopped
+  accuracy run handed over four reviews; three carried findings and all three
+  were real: `TESTING.md:24` unpacked a `v0.4.1` tarball, `README.md:393` quoted
+  `any-level FP 0.6%` where the measured figure is 0.1%, and
+  `tests/run_matrix.sh:2` still described "19 realtime checks" after row #20
+  landed. The last was introduced by the commit that added that row.
+- **The ceiling wrap-up signal never reached the agent.** `progress()` only
+  writes to the socket, so the sole reader was the process-wide link watcher,
+  whose loop sleeps `WATCH_INTERVAL` (5s) before its first pass.
+  `should_wrap_up()` — the call the documentation tells agents to make —
+  answered from a field that had not been populated yet, so an agent that
+  checked the signal after its work and exited raced the timer and lost. It
+  only appeared to work when a unit of work happened to be long enough for a
+  tick to land inside it. `should_wrap_up()` and `headroom()` now drain the
+  socket first. Found against a real Claude plan window; see
+  `docs/wrapup-signal.md` for the timeline and the before/after table.
+- **Handoffs printed the window reset time as a raw epoch** (`resets
+  1787993400`) — the single field a reader most needs off that document. Now
+  rendered as a local timestamp. The wire frame still carries the integer.
+- **`[account]` was ignored on SIGHUP.** `_reload()` rebuilt profiles and
+  defaults but never re-read the block, so a reload logged success and changed
+  neither the threshold, the grace, the poll interval, nor the background
+  classification.
+- **`_quota_sent` held one value per session name and was never cleaned up.**
+  Broken twice over. The plan-window signal and the configured-ceiling signal
+  wrote the same key, so one silently unblocked the other — measured live, a
+  budget wrap-up stayed suppressed until the quota poll happened to overwrite
+  it, arriving at 5,839 tokens against a 1,700 cap instead of at 2,014. And
+  because nothing removed an entry, a session reusing a name that had already
+  been warned could never be warned again for the daemon's lifetime: a fail-open
+  on the one signal that exists to save work. Now a set per session, cleared on
+  close.
+- **The account block was logged only when a value changed**, making silence
+  mean both "reloaded, nothing moved" and "never reloaded at all" — the
+  ambiguity that hid the bug above. The effective settings are now stated on
+  every reload and once at startup.
+
+### Added
+- **`[account] windows`** — name which plan windows may bind. The daemon has
+  always used the *highest* window, which is right when you want protection from
+  whichever allowance runs out first, but it made "warn me at 15% of my session"
+  inexpressible: a 7d weekly sitting at 66% binds first, so every threshold below
+  that fires on the first poll having done no work, and writes an empty handoff.
+  Measured twice before this existed. An unmatched name binds nothing and the
+  daemon says so once per provider — silently protecting nobody looks exactly
+  like nothing being near a ceiling.
+- **`budget` and `deadline` now signal.** `docs/wrapup-signal.md` has named
+  them the signallable ceilings since the feature was designed — "fired when a
+  ceiling detector returns warn" — but the only path that ever sent a WRAPUP
+  frame was the plan-window poll. A session with a token cap or a wall-clock cap
+  got a log line and then, at `hard`, a termination, with no chance in between
+  to save its work: two of the three ceilings the document claimed to cover were
+  silent. `daemon._ceiling_wrapup()`, reported with real headroom (tokens
+  remaining to `hard`, or seconds).
+- **Matrix check #20 — the ceiling signal reaches the agent.** Two tests, both
+  regression-proven against the broken code rather than merely passing against
+  the fixed code. `tests/test_wrapup_race.py` (client visibility, link watcher
+  disabled entirely so the drain does the work rather than a lucky tick): 6 of 9
+  fail before the fix, 9/9 after. `tests/test_ceiling_signal.py` (real daemon;
+  `budget` and `deadline` delivery, and suppression not outliving a session):
+  0 of 9 before, 9/9 after. The matrix is now 20 checks.
+
+## [0.4.2] - 2026-08-27
+
+First release published to PyPI. `pipx install continuity-guard`.
+
+### Added
+- **Cross-platform transport.** The daemon now listens on a Unix domain socket
+  on Linux/macOS and on `127.0.0.1:9099` on Windows; `socket = "tcp://HOST:PORT"`
+  (or `":PORT"`, or `CG_TCP_PORT`) forces TCP anywhere. `continuity_guard/transport.py`
+  is the single resolver used by the daemon, the client, the CLI, and the fuzzer.
+- **`cg` command-line interface** — `init`, `install`, `run`, `status`, `watch`,
+  `history`, `profiles`, `reload`, `doctor`. `cg install` writes a systemd
+  `--user` unit on Linux, a launchd agent on macOS, and prints NSSM instructions
+  on Windows.
+- **Packaging.** `pyproject.toml` with zero runtime dependencies, `cg` and
+  `cg-daemon` entry points, wheel + sdist, and a `Dockerfile` (python:3.12-slim,
+  non-root, baked default config).
+- **`protocol.sanitize()`** — every decoded frame is normalised to well-typed
+  fields or `None` before it reaches a detector.
+- **`decay.hard_floor`** — an absolute backstop (default 200s) under the
+  adaptive decay detector, so the terminate level can never be pulled down by a
+  learned baseline.
+- **`Store.prune`** — history tables are bounded and checkpointed hourly from
+  the daemon; `PRAGMA wal_checkpoint(TRUNCATE)` runs every prune, not only when
+  rows were deleted.
+- **Client reconnect.** A session whose daemon restarts under it (systemd
+  `Restart=always`, an OOM kill) re-connects and re-HELLOs with the same
+  identity, throttled and silent.
+- **`docs/integrating.md`** — the four integration paths (proxy, library,
+  supervisor, callbacks), per-agent supervisor recipes, and the three wiring
+  footguns that cause a healthy agent to be killed.
+- **`tests/soak_stability.py`** — a multi-day leak *assertion*: drives heavy
+  connection churn at a throwaway daemon, samples RSS / fds / threads / WAL, and
+  exits non-zero on a memory slope, an fd leak, thread growth, or a stalled
+  checkpoint.
+- **`tests/fuzz_protocol.py`** — hostile-input fuzzing folded into the matrix as
+  check 19; runs against both Unix and TCP transports.
+
+### Fixed
+- **`decay` hard-level false positives** went from 1.2% to 0.0% at high sample
+  counts (recall unchanged) after adding `hard_floor`.
+- **Daemon crashes on hostile input** — a non-integer `pid`, deeply nested
+  JSON, and binary garbage each previously reached an unhandled exception in the
+  selector loop. `decode()` now catches `RecursionError`; framing is wrapped;
+  `sanitize()` runs first.
+- **Accept backlog** under a connection flood — `_accept` now drains the whole
+  backlog per wakeup and the listen queue is 256.
+- **`cg_proxy` gzip bug** — the proxy forwarded `Accept-Encoding: gzip` but
+  stripped `Content-Encoding`, producing a client-side decode error. It now
+  forces `Accept-Encoding: identity` upstream.
+- **CLI f-string** used a PEP 701 nested-same-quote form that fails on the
+  minimum supported Python (3.11).
+- **`config.example.toml`** is now shipped inside the package, so `cg init`
+  works from a `pip`/`pipx` install.
+
+### Evidence
+- Matrix **19/19** (18 realtime checks + protocol fuzz) on Raspberry Pi 5
+  (aarch64) and x86-64 Linux, Python 3.12/3.13.
+- Adversarial corpus (default profile, 3600 healthy + 4000 faulty):
+  **hard-level false positives 0.0%**, recall 100% on all ten fault classes.
+- Phase-1 shadow-mode soak across two hosts, ~13 models and 5 integration
+  paths: **zero genuine healthy sessions would have been terminated**
+  (one harness artifact, annotated, ledger kept append-only).
+
+## [0.4.1] and earlier
+
+Pre-PyPI reference builds, distributed as tarballs. 18-check matrix, adaptive
+`decay` without `hard_floor`, Unix-socket transport only. See `git log` for the
+full history.
+
+[0.4.2]: https://github.com/ak2tx/continuity-guard/releases/tag/v0.4.2

continuity_guard-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Bug reports and small fixes are welcome. Before a larger change, open an issue
+— the answer may be that it was tried and measured and did not work, and
+`docs/` will say which measurement.
+
+## The one rule
+
+**A change to detector or protocol semantics is not done until it is
+measured.** This project is a watchdog: it can end someone's work. An
+improvement that is only argued for is a regression waiting to be found by a
+user at three in the morning.
+
+Definition of done:
+
+```bash
+./tests/run_matrix.sh          # 22 checks against real processes, ~14 min
+python3 tests/bench_accuracy.py  # hard-level FP 0.0%, recall 100%
+```
+
+plus a short note in the repo saying what changed and **which measurement
+justified it**. If a measurement contradicts a design intuition, trust the
+measurement and write down which intuition was wrong. `docs/` is full of
+those; they are the most useful pages in it.
+
+## Two instruments, and which is authoritative for what
+
+| | use it for | it cannot see |
+|---|---|---|
+| `tests/bench_accuracy.py` | tuning. Thousands of sessions in seconds against a simulated clock, on nine deliberately adversarial *healthy* workloads | a real process, a real `SIGSTOP`, a real kill |
+| `tests/run_matrix.sh` | enforcement. 22 checks against real processes | high-N false-positive rates |
+
+Run **both** after any detector change. Shipping something validated only by
+the benchmark once let a stopped process go undetected; real hardware caught
+it, not the model.
+
+Row #22 installs the built wheel into a clean venv and runs the commands the
+README names, from outside the checkout. It exists because for the whole life
+of 0.4.2 the two documented integration paths were missing from the wheel and
+every test passed anyway — they all ran from a checkout where `tools/` was
+simply on the path.
+
+## Invariants
+
+`HANDOFF.md` lists seven. Each was learned by breaking it. Do not regress
+them, and if you think one is wrong, bring the measurement.
+
+The first is the one that matters most: **hard-level false positives must be
+zero.** Warn-level noise is survivable; spurious termination is not.
+
+## Style
+
+Match the surrounding code. Comments explain *why*, especially why something
+is not the obvious approach — a comment that says what the line does is noise,
+one that records the failure that shaped it is the reason the file is
+maintainable.
+
+Zero runtime dependencies. Python 3.11+. Keep it that way.

continuity_guard-0.5.0/Dockerfile

@@ -0,0 +1,47 @@
+# Continuity Guard -- the daemon (and, with a command override, the proxy).
+# Zero Python dependencies, so this stays small.
+#
+#   docker build -t continuity-guard .
+#
+#   # daemon: mount a config and a dir for the socket + state
+#   docker run -d --name cg \
+#     -v "$PWD/config.toml:/etc/continuity-guard/config.toml:ro" \
+#     -v cg-state:/var/lib/continuity-guard \
+#     continuity-guard
+#
+#   # proxy in the same network namespace as the daemon container
+#   docker run -d --name cg-proxy --network container:cg \
+#     -v cg-state:/var/lib/continuity-guard \
+#     continuity-guard \
+#     python -m tools.cg_proxy --upstream http://host.docker.internal:11434 --port 8111
+#
+# The daemon writes its socket where the config's `socket =` points; keep that
+# on the shared volume (e.g. /var/lib/continuity-guard/cg.sock) so the proxy,
+# supervisor, or library in another container can reach it.
+
+FROM python:3.12-slim AS base
+
+RUN useradd --system --create-home --home-dir /home/cg cg
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY continuity_guard ./continuity_guard
+COPY tools ./tools
+
+RUN pip install --no-cache-dir . \
+ && mkdir -p /etc/continuity-guard /var/lib/continuity-guard \
+ && chown -R cg /var/lib/continuity-guard
+
+# default config location; override by mounting your own or setting CG_CONFIG
+ENV CG_CONFIG=/etc/continuity-guard/config.toml \
+    PYTHONUNBUFFERED=1 \
+    PYTHONPATH=/app
+USER cg
+
+# a sane default config baked in (shadow mode, socket on the shared volume)
+RUN mkdir -p /home/cg/.config && \
+    printf 'socket = "/var/lib/continuity-guard/cg.sock"\ndb = "/var/lib/continuity-guard/state.db"\n[defaults]\nshadow = true\n' \
+    > /home/cg/default-config.toml
+
+# if no config is mounted, fall back to the baked default
+ENTRYPOINT ["sh", "-c", "exec cg-daemon -c \"${CG_CONFIG}\" 2>/dev/null || exec cg-daemon -c /home/cg/default-config.toml"]

continuity_guard-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ak2tx LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

continuity_guard-0.5.0/MANIFEST.in

@@ -0,0 +1,17 @@
+include LICENSE
+include CHANGELOG.md
+include README.md
+include TESTING.md
+# A security policy must travel with the source it describes -- someone
+auditing an sdist offline should not have to find the repo to learn how to
+report a finding or what the threat model is.
+include SECURITY.md
+include CONTRIBUTING.md
+include Dockerfile
+include config.example.toml
+recursive-include continuity_guard *.toml
+recursive-include docs *.md
+recursive-include tests *.py *.sh *.toml
+recursive-include tools *.py *.sh
+recursive-include systemd *
+prune **/__pycache__