ceiling-guard 0.5.3__tar.gz

ceiling_guard-0.5.3/CHANGELOG.md

@@ -0,0 +1,533 @@
+# Changelog
+
+All notable changes to Ceiling 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.3] - 2026-08-30
+
+Found by running the command lines a user actually types, from a clean install,
+on two machines. Every item below was reachable by an ordinary mistake or by
+ordinary use; none needed a hostile input.
+
+### Fixed
+- **`cg wrap` silently truncated the wrapped agent's output.** The wrapper's
+  first duty is to relay what the child wrote, and it was dropping most of it.
+  `proc.wait()` returns the moment the child exits, but the output can still be
+  sitting in the pipe; the code then set a `stop` flag that made the reader
+  thread `break` **mid-drain**, discarding whatever had not been read.
+
+  Measured on x86/WSL2, same machine, same minute: a child emitting 500 lines
+  came back as **45, then 30, then 59**. On the ARM dev box it was
+  intermittent -- 500, 395, 500 -- which is exactly why a single manual
+  spot-check "confirmed" it worked and the defect survived 0.5.0, 0.5.1 and
+  0.5.2. The faster the machine, the further the child runs ahead of the
+  reader, so better hardware lost more. For `cg wrap -- claude -p` the lost
+  bytes are the agent's answer.
+
+  The reader now drains to EOF on its own; `stop` reverts to being a bounded
+  abort for the case where a surviving grandchild holds the pipe open
+  (`CG_DRAIN_TIMEOUT`, default 10s), and says so on stderr rather than
+  truncating quietly. A pump exception no longer disappears into
+  `except Exception: pass` either -- that was a second, silent path to the same
+  data loss. Pinned by matrix row 24 / `tests/test_wrap_output.py` (12 checks),
+  which counts lines rather than grepping for a substring, because the broken
+  build reliably produced the FIRST lines.
+
+- **OpenAI/Codex reported a confident `0.0% ok` while the account was at 96%.**
+  Codex writes `used_percent: 0.0` as a *placeholder* as well as a
+  measurement: a short session emits one `token_count` event before the server
+  has sent real numbers. Taking the newest record blindly turned that into a
+  fresh, wrong, reassuring reading -- a false *low* on the exact signal this
+  tool exists to watch. The staleness gate could not help: the reading really
+  was fresh.
+
+  Measured on a live Plus account: 96%/62% at 18:47, then `0.0/0.0` at 23:39;
+  and 100%/47% -> `0.0/0.0` **36 seconds apart**. A 7-day rolling window cannot
+  shed 47 points in 36 seconds. 197 of 208 session files never report a zero.
+
+  The rule is physical, not heuristic: usage cannot fall to zero before its
+  window has reset, so an all-zero record is refused while an older record
+  still shows usage in a window whose own `resets_at` has not passed. The
+  reading falls back to the last credible one, which is then correctly old and
+  correctly `IGNORED` -- fail closed rather than falsely comfortable. A genuine
+  post-reset zero is still believed. Both directions pinned in
+  `tests/test_quota.py`.
+
+- **Ctrl-C never reached the wrapped agent under nohup, systemd or CI.** The
+  signal handlers were installed *after* the child was spawned, which is fine
+  interactively and wrong everywhere else. A shell starting a job in the
+  background without job control sets SIGINT to `SIG_IGN`, and while handled
+  signals reset to `SIG_DFL` across exec, **ignored ones stay ignored** -- so
+  the child inherited `SIG_IGN`, and a POSIX shell cannot un-ignore a signal
+  that was ignored at startup. The agent's own `trap ... INT` became a no-op.
+
+  Measured: SIGTERM to `cg` reached the child (exit 98); SIGINT did not, and
+  the child ran to completion while `cg` waited out the whole run. From a
+  terminal it always looked right, because there SIGINT starts `SIG_DFL` --
+  the failure was confined to the unattended context the tool exists for.
+  Handlers now go on before `Popen`. `tests/test_wrap_signals.py` launches
+  `cg` with SIGINT explicitly ignored, and fails 3/8 against the previous
+  commit.
+
+- **`cg install` put site-packages on `PYTHONPATH`** in the generated systemd
+  unit. Meaningless for an installed copy and leaky, since `PYTHONPATH` is
+  inherited by every child and outranks its own paths. Emitted now only from a
+  source checkout.
+
+- **`tests/test_quota.py --live` crashed on any machine that had Codex.** It
+  formatted every consumption value with a thousands separator, but Codex's
+  consumption carries strings, so `f"{v:,}"` raised. The docs point users at
+  that exact command to verify their own setup, and it could only fail on the
+  machines it was written for.
+
+- **A typo in any numeric environment knob was fatal on import.** All eight are
+  read at module import, so `CG_MAX_CONNS=abc` took the daemon down with a
+  traceback naming a line in `config.py` rather than the variable just set.
+  They now fall back to the default and say which variable was wrong.
+
+  The quieter half mattered more: out-of-range values were accepted silently.
+  `CG_QUOTA_CONFIRM_POLLS=0` made the `_over_polls < QUOTA_CONFIRM_POLLS` gate
+  vacuously false, so **one** measured reading became enough to terminate a
+  session -- the confirm-the-crossing property switched off by a
+  plausible-looking number. `CG_MAX_CONNS=0` left a daemon that looked alive
+  and served nobody. Knobs that guard a property now carry a floor
+  (`config.env_num`). Matrix row 23 / `tests/test_env_knobs.py` (56 checks).
+
+- **A corrupt or wrong file at `db =` crashed both `cg history` and the
+  daemon** with a raw `sqlite3.DatabaseError`. Both now explain what was found
+  and what to do. Deliberately **not** auto-recovered: the common way to reach
+  this is a `db =` aimed at the wrong path, and recreating it would turn a typo
+  into data loss.
+
+- **`cg wrap -- <typo>` printed a `FileNotFoundError` traceback.** Now follows
+  shell convention: `command not found` / exit **127**, `permission denied` /
+  exit **126**.
+
+- **A malformed `config.toml` printed a `tomllib` traceback.** Now names the
+  file and the line, and exits 2.
+
+- **A corrupt quota cache crashed `cg quota`** with `TypeError: float - str`
+  from `stale_seconds`. Unknown age is now treated as stale, which is the
+  fail-closed answer used everywhere else in that module.
+
+- **Burn could hard-fire on healthy batched token reporting.** The rate's
+  denominator was the spread of the samples in the window, floored at 30s:
+  `max(30.0, now - tokens[0][0])`. For the normal shape of a client that
+  accounts usage at the END of a call -- one frame carrying the whole batch --
+  `tokens[0][0]` IS now, so the span collapsed to 30s and the entire batch was
+  attributed to thirty seconds. A healthy 60-second call reporting 20,001
+  tokens read as **40,002 tok/min**, over the 40,000 default, and `burn` has no
+  confirmation gate: a hard-level false positive on a session doing nothing
+  wrong. The denominator is now the period actually observed, capped by the
+  window being summed. Verified: 20,001 over 60s reads 20,001/min; a genuine
+  120k/min runaway is unchanged; burn recall stays 100% at 62s to hard **on
+  the nine-archetype release corpus** (the figure is not claimed for
+  `phase_change`, which is measured separately under `--known-fail`).
+
+- **A peer could clear `shadow` for its own session, and a reload promoted
+  everything it asked for.** `UNTRUSTED_KEYS` stripped `action` but not
+  `shadow` -- so a socket peer that could not ask to be terminated could still
+  take itself out of observe-only, which is the switch deciding whether any
+  verdict is carried out. Separately, HELLO resolved peer overrides with
+  `trusted=False`, but `Sess` kept the RAW overrides and SIGHUP re-resolved
+  them with the default `trusted=True`: an operator running `cg reload`
+  silently granted the peer `action="terminate"` and `shadow=false`. Both
+  closed; both pinned in `tests/test_authority.py`.
+
+- **The confirm-the-crossing floor was one short of confirming anything.** The
+  gate reads `_over_polls < QUOTA_CONFIRM_POLLS`, and `_over_polls` is already
+  1 on the first over-threshold reading -- so the `minimum=1` added earlier
+  today made the test `1 < 1`, false, and enforcement proceeded on a single
+  measurement. The floor that actually preserves the property is 2.
+
+### Added
+- **`cg statusline`** -- one short plan-window reading for a shell prompt or
+  tmux bar. Loads no config, contacts no daemon, exits 0 on every path, and
+  prints `-` rather than a percentage that was true an hour ago.
+
+### Known
+- **`cg install` is shaped for a source checkout under systemd.** It embeds
+  whichever Python ran it, detects only that `systemctl` exists rather than
+  that a user session works, discards the result of `loginctl enable-linger`,
+  declares success without running `cg doctor`, has no uninstall or repair,
+  and on Windows prints instructions and returns success having installed
+  nothing. **`pipx install ceiling-guard` then `cg quota` / `cg wrap` is the
+  supported path for anyone who is not already in the repo**; the daemon and
+  its unit are for operators who want persistent supervision. Installer work is
+  0.5.4 and is deliberately not in this tag — the wheels currently on PyPI drop
+  the agent's answer and report `0.0% ok` at 96%, and getting those off the
+  index matters more than installer polish.
+
+### Known open (measured, not fixed)
+- **A retransmitted PROGRESS frame double-counts spend.** `add_call`,
+  `add_tokens`, `add_outcome` and depth are applied on every frame, not only
+  when `seq` advances, so the same frame applied twice adds its tokens twice.
+  `client._send` retries a frame after a reconnect, so this is reachable, and a
+  daemon restart makes it worse: the durable token carry is restored but
+  `sess.seq` starts at zero.
+
+  The obvious fix -- ignore any frame whose `seq` does not advance -- is
+  **wrong for this codebase** and was not applied. A frozen `seq` carrying
+  fresh tokens is exactly what "burn with no progress" means; `demo_agent.py
+  burn` sends precisely that, and matrix row 7 depends on it. Content-hash
+  dedupe fails for the same reason: those frames are byte-identical by design.
+
+  Telling a retransmission from a genuine repeat needs a frame identity the
+  protocol does not currently carry. The fix is a monotonic frame id, ignored
+  by the daemon when already applied and treated as always-new when absent, so
+  older clients keep working. That is a protocol addition and is deliberately
+  not being rushed.
+
+- **`decay` fires on a healthy phase change, and the corpus could not see it.**
+  Every healthy archetype in `tests/bench_accuracy.py` held roughly one pace
+  throughout, so the frozen baseline always resembled the work being judged.
+  Real sessions do not behave that way: an agent reads a dozen files at a
+  second each, then runs five test suites at three minutes each. That freezes a
+  ~1s baseline and makes every legitimate 200s call a 200x "collapse".
+
+  A `phase_change` archetype has been added, and with it the bench now reports
+  what was always true: **decay fires on 100% of those sessions** (warn level;
+  a direct probe reaches HARD with steady 200s+ gaps), and measured decay
+  recall drops from 100% to **90%** because the fault generator now also runs
+  against a slow-paced archetype. `./tests/bench_accuracy.py` therefore FAILS
+  its gate on this commit.
+
+  This is deliberate. The archetype is realistic, the numbers are real, and the
+  previous 100%/0.0% was partly an artefact of a corpus that did not contain
+  this shape. A loosen-only baseline re-learn was tried and made both numbers
+  worse, so it was reverted rather than shipped. The honest position is that
+  the zero-false-positive claim holds for the archetypes measured, and this
+  archetype is not yet among the ones it holds for.
+
+### Changed
+- `docs/quota-accuracy.md`: the two OpenAI rows are **withdrawn as evidence**.
+  They recorded `0.00%` agreeing with a UI at 0% and called it *exact* -- but
+  `0.00%` is what the adapter produced whether or not it worked, so the check
+  passed identically for a working and a broken adapter. An unfalsifiable check
+  is worse than none; it occupied the row where real evidence should have been.
+- `docs/quota-adapters.md`: the Codex path is verified against a real install
+  (NucBox, 208 session files, 1233 rate-limit events) for **parsing**, and
+  explicitly not for accuracy.
+
+### Added
+- `tests/test_wrap_output.py`, `tests/test_env_knobs.py`,
+  `tests/test_wrap_signals.py` -- matrix rows 23 and 24. The matrix is now 24
+  rows reporting 25 checks (row 24 covers wrapper output and signals
+  separately), passing on aarch64/Python 3.13.5 and x86-64/Python 3.12.3.
+
+## [0.5.2] - 2026-08-29
+
+Third patch in a day. The cadence is ugly; the reason is that 0.5.1's leading
+Claude command could not capture Anthropic, so the published page documented an
+on-ramp that did not work.
+
+### Fixed
+- **The documented Claude on-ramp captured nothing.** The README said to run
+  `cg wrap -- claude -p "whatever you were going to run anyway"` and then
+  `cg quota` would show the Anthropic rows. It did not. Claude publishes its
+  plan window only as a `rate_limit_event` in `--output-format stream-json`;
+  plain `claude -p` prints text, so nothing carrying `unifiedWindows` ever
+  crossed the wire and `cg quota` stayed empty forever.
+
+  Every earlier test of this path passed those flags itself, so the gap never
+  appeared. It took installing from PyPI into a clean venv, pointing
+  `CG_QUOTA_CACHE` at an empty directory, and running the README's literal
+  command to find it.
+
+  `cg wrap` now adds `--output-format stream-json --verbose` when the child is
+  `claude`, is running with `-p`, and the user has not chosen a format
+  themselves. It renders the stream back to plain text, so the answer arrives
+  looking exactly as it would have, and it says on stderr that it did this
+  rather than silently rewriting the command line. An explicit
+  `--output-format`, an interactive session with no `-p`, and any non-Claude
+  child are all left untouched.
+
+  This makes `cg wrap` a shim for `claude -p` rather than a transparent sleeve
+  like `timeout` or `nice`, and the docs now say so instead of claiming the
+  command runs unchanged. The alternative was documenting the flags, which
+  makes the on-ramp longer than the job it wraps. Known gaps, deliberately not
+  guessed at: a `claude` invoked under another name is not recognised, and
+  print-mode reached by anything other than `-p`/`--print` is not detected.
+- **A renderer miss would have been silent.** We ask Claude for a format the
+  user did not, so if its event shape moves -- `result` renamed,
+  `message.content` restructured -- the run still succeeds while the answer
+  stops appearing. On child exit, if the injected stream produced nothing
+  printable, the raw events are dumped to stderr with an explanation. The
+  child's exit code is untouched: the job may have worked, and the renderer is
+  our problem rather than its.
+- **The rendered answer printed twice.** The text appears both as the
+  assistant's `text` block and again in the terminal `result` event. The
+  renderer now prefers the streamed text and falls back to `result` only when
+  no text block was seen.
+
+## [0.5.1] - 2026-08-29
+
+Documentation only. No behaviour change.
+
+### Fixed
+- **The README told people to install from a private repository.** The first
+  code block offered `pipx install git+https://github.com/ak2tx/ceiling-guard`
+  as an alternative; that URL 404s until the repo is public. Removed, so the
+  only advertised path is the one that works.
+- **The opening named ChatGPT as an audience the next section excludes.** A
+  browser-only subscription leaves no local record for this tool to read, and
+  saying "Claude, ChatGPT or Grok" in the first sentence promised a reader
+  something the provider table then took away. It now names the CLIs.
+- **Restored the three sentences that carry the claim.** "Thirty seconds is
+  Codex and Grok. Claude is wrap the job you were going to run. A browser-only
+  subscription is not a user of this tool." A rewrite dropped them; the table
+  underneath is only the evidence, and without the claim a Claude user infers
+  they should see numbers straight after `pipx install`.
+- The plan-window section re-pitched the opening, with a second copy of the
+  situation and a second sample table. It now carries only the mechanics.
+- The status footer still said rows #20 and #21 had not run on the Pi. #22
+  exists too.
+
+## [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 ceiling-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/ceiling-guard/releases/tag/v0.4.2

ceiling_guard-0.5.3/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.

ceiling_guard-0.5.3/Dockerfile

@@ -0,0 +1,47 @@
+# Ceiling 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"]

ceiling_guard-0.5.3/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.