terum-capture 0.7.0__tar.gz

terum_capture-0.7.0/.gitattributes

@@ -0,0 +1,11 @@
+# The CI runner executes these files on Linux. A CRLF-terminated shell line becomes
+# `$'\r': command not found`, and a CRLF `run:` block in a workflow breaks the same way — a
+# failure mode with nothing to do with the code under test. Windows checkouts here currently
+# have core.autocrlf=true, which normalizes on commit, but that is a per-machine setting; pin
+# it in the repo so it does not depend on how a contributor's git happens to be configured.
+*.sh text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+# .py too: CI runs these with `python <file>`, but scripts/ carries a shebang and a CRLF there
+# breaks `./scripts/check_error_streams.py` with a bare "bad interpreter" on Linux.
+*.py text eol=lf

terum_capture-0.7.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,50 @@
+name: Bug report
+description: Something broke — install, setup, capture, or update
+labels: [bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: terum-capture version
+      description: Output of `terum-capture --version`
+      placeholder: "0.6.1"
+    validations:
+      required: true
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      description: OS and Python version (`python3 --version`)
+      placeholder: "macOS 26.2, Python 3.12.4"
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - install.sh / installation
+        - setup / project picker
+        - capture (Stop hook / missing sessions)
+        - update / self-updater
+        - delivery hook (UserPromptSubmit)
+        - other
+    validations:
+      required: true
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: >
+        What you did, what you expected, and what happened instead. Paste
+        terminal output if you have it — but scrub anything you don't want
+        public (transcript content, tokens, URLs with IDs).
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. ...
+        2. ...

terum_capture-0.7.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature request
+description: Propose an improvement to the CLI
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that terum-capture doesn't support?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: What should happen instead? CLI sketches welcome.
+    validations:
+      required: true

terum_capture-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+# Publishes to PyPI when a GitHub release is published. Uses PyPI trusted
+# publishing (OIDC) — no long-lived API token lives in this repo's secrets.
+#
+# One-time setup before this workflow can succeed: register this repo +
+# workflow as a trusted publisher for the `terum-capture` project on PyPI
+# (the name is unclaimed as of 2026-09-01 — first publish claims it).
+# Until that's done, the publish step fails closed with a clear OIDC error;
+# it cannot accidentally publish anywhere.
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install build
+          python -m build
+      # Fail here, before publish, if the tag and __version__ disagree —
+      # hatch reads the version from src/terum_capture/__init__.py, so a
+      # mismatch means someone tagged without bumping (or vice versa).
+      - name: Check tag matches package version
+        run: |
+          pkg_version=$(python -c "import pathlib,re; print(re.search(r'__version__ = \"(.+?)\"', pathlib.Path('src/terum_capture/__init__.py').read_text()).group(1))")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$pkg_version" != "$tag" ]; then
+            echo "::error::tag v$tag != __version__ $pkg_version" && exit 1
+          fi
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

terum_capture-0.7.0/.github/workflows/tests.yml

@@ -0,0 +1,94 @@
+name: Tests
+
+# The pytest suite had never run anywhere except a developer's own machine: this repo had no
+# .github/workflows at all, so `gh pr checks` answered "no checks reported on the branch". Two
+# bugs fixed here both ended with the same follow-up — the convention needs a gate — and this is
+# that gate:
+#   - bug-560: running `pytest` rewrote the developer's real ~/.claude/settings.json, breaking
+#     every Claude Code prompt after the next branch switch. tests/conftest.py isolates all eight
+#     ~-rooted constants now; the HOME step below is what stops that fixture regressing silently
+#     (it would have caught the PR #11 widening at review time, which nothing did).
+#   - bug-561: `setup` printed `Error:` and exited 0, so no caller could detect failed onboarding.
+#     The exit codes are pinned by tests now — but nothing was running the tests.
+#
+# Hermetic: no secrets and no network. conftest.py points every ~-rooted path at tmp_path.
+on:
+  pull_request:
+    branches: [main]
+  # Also on direct pushes to main. Unlike Terum-MVP this repo has no .githooks/pre-push gate and
+  # is small enough that commits land on main directly, so PR-only coverage would miss exactly
+  # the commits nothing else checks.
+  push:
+    branches: [main]
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      # Report every interpreter separately. requires-python is >=3.10, but the only one
+      # installed on the dev machine is 3.14 — 3.10 through 3.13 had never executed this code
+      # before this workflow, so which of them breaks is the information we want; fail-fast
+      # would cancel the siblings and hide it.
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          # pyproject.toml is the only dependency manifest (there is no requirements.txt).
+          # Naming it keeps the cache key off setup-python's '**/' fallback glob.
+          cache-dependency-path: pyproject.toml
+
+      # Non-editable on purpose: pipx installs a built wheel, so this also proves the wheel
+      # carries everything the suite imports. pytest is not a runtime dependency — it lives in
+      # the `dev` extra so that CI (and a new contributor) has exactly one thing to install.
+      - run: pip install ".[dev]"
+
+      - name: Fingerprint HOME before the suite (bug-560)
+        id: home_before
+        run: bash scripts/home-fingerprint.sh > "$RUNNER_TEMP/home-before.txt"
+
+      - run: pytest -q
+
+      # always(): if the suite fails AND it escaped its tmp_path, the escape is the more
+      # important of the two facts and must not be hidden by the first failure. Gated on the
+      # before-snapshot succeeding, so a broken baseline reports itself instead of a bogus diff.
+      - name: Assert the suite touched nothing under HOME (bug-560)
+        if: always() && steps.home_before.outcome == 'success'
+        run: |
+          bash scripts/home-fingerprint.sh > "$RUNNER_TEMP/home-after.txt"
+          if ! diff -u "$RUNNER_TEMP/home-before.txt" "$RUNNER_TEMP/home-after.txt"; then
+            echo "::error::The suite modified files under HOME (bug-560): a ~-rooted path escaped tests/conftest.py's isolation. On a developer machine this rewrites the live ~/.claude/settings.json. Patch the new constant into conftest.py's isolate_home fixture."
+            exit 1
+          fi
+
+  # bug-561's follow-up gate. A fatal diagnostic must not go to stdout (a supervising hook
+  # surfaces stderr, so stdout is where a reason goes to die — bug-559), and a command that
+  # reports a failure must exit non-zero (`setup` printed Error: and exited 0, so
+  # `setup && next-step` ran next-step over a failed onboarding — bug-561).
+  #
+  # Its own job, not a step in the matrix: the check is interpreter-independent, so running it
+  # five times would only buy five copies of the same answer. stdlib `ast` only — no install,
+  # which is why this job has no pip step at all.
+  #
+  # The checker is also covered BY the suite above (tests/test_error_stream_lint.py), including a
+  # replay against the pre-fix source in git history. This job is what makes it block a merge.
+  output-discipline:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - run: python scripts/check_error_streams.py

terum_capture-0.7.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/

terum_capture-0.7.0/.python-version

@@ -0,0 +1 @@
+3.10.19

terum_capture-0.7.0/AGENTS.md

@@ -0,0 +1,200 @@
+# AGENTS.md — terum-capture
+
+Instructions for non-Claude coding agents (Codex CLI, etc.) working in this repo.
+
+**This file is a loader, not the source of truth.** Unlike Terum-MVP, this repo has no
+per-directory instruction files — the authoritative statements of each invariant are the module
+docstrings named below. Read the cited module before your first edit in it.
+
+**Your role here is implementer, not architect.** You are normally invoked against a spec in
+Terum-MVP's `.planning/specs/` that was written and locked upstream. Implement what the spec says.
+**If the spec is ambiguous, STOP and record the question — do not resolve the fork yourself.**
+
+**What this is:** a Python CLI that installs a Claude Code `Stop` hook, parses new turns out of
+Claude Code transcripts, and POSTs them to Terum's ingest pipeline. It is `pipx`-installed on real
+developer machines and **runs supervised, as a hook**. Both of those shape every rule below.
+The CLI is machine-wide; the hook it installs is **per-project by default** (invariant 7).
+
+---
+
+## Top invariants
+
+### 1. The sidecar offset advances ONLY after a confirmed 2xx
+
+This is the anti-data-loss invariant. Authoritative: the `_write_sidecar` and `_process_transcript`
+docstrings in `src/terum_capture/upload.py`.
+
+Each transcript has a sidecar at `~/.terum/sent_<session_id>` holding the byte offset already
+uploaded. Advance it before the POST succeeds and those turns are skipped **permanently** — there
+is no second chance, because the next run reads from the advanced offset. The return vocabulary
+encodes exactly this and must be preserved:
+
+| status | meaning | sidecar |
+| --- | --- | --- |
+| `uploaded` | every event POSTed with a 2xx | advanced |
+| `skipped` | nothing new (`file_size <= last offset`) | unchanged, no POST |
+| `no_turns` | new bytes, no qualifying turns | advanced |
+| `rate_limited` | a 429 | **NOT advanced** — caller backs off and retries |
+| `failed` | non-2xx / non-429 / transport error | **NOT advanced** |
+
+Corollaries, both already implemented — do not "simplify" either away:
+- The sidecar write goes through a temp file + `os.replace`, so a kill mid-write cannot leave a
+  torn file. A truncated or unparseable sidecar resets to offset 0 — a full, safe reprocess. The
+  server dedups, so re-sending is cheap; a false "already sent" is unrecoverable. **When the two
+  failure modes trade off, always choose re-send.**
+- Auxiliary fields (`repo`, `tokens`) may be written with an UNCHANGED offset. That is safe by
+  construction and is not a violation of this rule.
+
+### 2. stdout is the product; stderr is the diagnostic
+
+Authoritative: the module docstring of `src/terum_capture/output.py`. Gated by
+`scripts/check_error_streams.py` (AST, its own CI job).
+
+- **stdout** = what the user asked for. `status`'s report, `MCP connected`, a hook's JSON payload.
+  This includes reports whose content is bad news — `Status: invalid or revoked` is the *answer*.
+- **stderr** = why we could not do what was asked: usage errors, unknown commands, unmet
+  preconditions, failed reinstalls. Route every one through `output.die()` or `output.err()`.
+
+Why it matters more here than in a normal CLI — a hook is **supervised**:
+1. A supervisor reports a failed child by surfacing its **stderr**. Put the reason on stdout and
+   the user sees "Failed with non-blocking status code: No stderr output" — told it broke and
+   denied the one line saying why. That is bug-559.
+2. On `UserPromptSubmit`, Claude Code treats a hook's stdout as **context to inject**. A diagnostic
+   on stdout is not merely invisible — on any path exiting 0 it is a candidate for being fed to the
+   model as though it were retrieved team content.
+
+### 3. A command that reports a failure must EXIT non-zero
+
+bug-561: `cmd_setup` aborted on seven terminal failures with a bare `return`, printing `Error: …`
+to stdout and exiting **0** — so `setup && next-step` ran `next-step` over a failed onboarding, and
+two of those paths had already deleted the config.
+
+`print`-then-`return` is the same defect as `print`-then-wrong-stream, one notch worse: there is no
+failure signal at all. **When sweeping for this class, grep the `return` variant too** — the
+bug-559 sweep grepped only `sys.exit(1)` and structurally could not see these.
+
+### 4. The test suite must never touch the real `$HOME`
+
+bug-560: running `pytest` rewrote the developer's real `~/.claude/settings.json`, breaking every
+Claude Code prompt after the next branch switch. `tests/conftest.py` has an **autouse**
+`isolate_home` fixture that monkeypatches every `~`-rooted constant at its module to a `tmp_path`.
+
+**If you add a new `~`-rooted module constant, patch it into `isolate_home` in the same commit.**
+The fixture also `chdir`s each test into a throwaway project dir, because project-scoped capture
+resolves a second family of real paths from the **current directory** (`.claude/settings.local.json`,
+`CLAUDE.local.md`, `.gitignore`) and pytest's cwd is this checkout — so a developer who ran `setup`
+here would otherwise have the suite rewriting their own live hook. A test needing a different cwd
+must `monkeypatch.chdir` explicitly. Note that CI's `$HOME` fingerprint cannot see this second
+family at all; the tests are the only guard.
+CI fingerprints `$HOME` before and after the suite and fails on any diff. The watchlist
+(`scripts/home-watchlist.txt`) is the single source of truth for both that script and
+`tests/test_home_isolation_coverage.py`, which fails if a `Path.home()` constant in `src/` names an
+entry missing from it.
+
+**Do not reproduce that check locally and trust the result.** CI is hermetic; your machine is not.
+Running `scripts/home-fingerprint.sh` around a local `pytest` reports a diff from whatever else is
+writing under `~/.claude` at the time — Claude Code's own `.last-cleanup`, `.claude.json` backup
+rotation, plugin-cache markers, session transcripts. Verified 2026-07-31: a local run showed six
+changed paths and **none** were suite-owned. Before concluding the isolation regressed, check
+whether the changed paths are actually in the watchlist (`.claude/settings.json`, `.claude.json`,
+`.cursor`, `.terum`); if they are not, it is your environment, not the suite.
+
+### 5. Partial work must never report "complete"
+
+A run that skipped anything reports it, does not advance state past unfetched items, and surfaces
+the partial state. The status vocabulary in invariant 1 *is* this mechanism — a helper that returns
+an empty result on a non-OK status is silent data loss. Return an explicit stub or raise so retry
+engages.
+
+### 6. `delivery_hooks.py` is FAIL-OPEN BY CONSTRUCTION
+
+Any error — no config, unreachable backend, timeout, bad payload — must degrade to injecting
+nothing. It runs on `UserPromptSubmit`, so a raise or a slow path blocks the user's prompt. Its
+swallowed errors are **deliberate and load-bearing**; do not "fix" them into raises. Read the module
+docstring before touching it.
+
+### 7. Only `setup` may widen capture's scope
+
+Capture is **per-project by default**: `setup` writes the Stop hook to `<project>/.claude/settings.local.json`
+(git-ignored), and `--global` is an explicit opt-in to the machine-wide `~/.claude/settings.json`.
+Authoritative: the `_scope_targets` and `_refresh_installed_hooks` docstrings in `commands.py`.
+
+The consequence that is easy to undo by accident: every OTHER path that writes a hook is
+**refresh-only**. `setup-hook` (which `terum-capture update` runs on every upgrade) and the daily
+self-heal in `maintenance.py` both go through `_refresh_installed_hooks()`, which re-applies the
+canonical entry to the scopes that already have one and **creates none**. Calling `_configure_hook()`
+directly from either — the shape they had when global was the only scope — silently hands a
+machine-wide hook to a user who deliberately picked one project, re-arming capture for every repo
+on their box with no prompt. Pinned by `TestRefreshInstalledHooks` in `tests/test_project_scope.py`.
+
+Deliberately still global, and not a violation: the pipx CLI itself, the API key in
+`~/.terum/config.json`, MCP (`~/.claude.json`), and the delivery hook. The last two are read-only
+*pulls* of team knowledge, not capture.
+
+---
+
+## Gates — run these yourself before reporting done
+
+```bash
+pip install ".[dev]"                    # pytest is in the `dev` extra, not a runtime dependency
+pytest -q
+python scripts/check_error_streams.py   # AST gate for invariants 2 and 3, stdlib only
+```
+
+There is **no** ruff, mypy, or npm gate in this repo — do not invent one, and do not import the
+Terum-MVP `npm run lint / typecheck / test` battery. `requires-python` is `>=3.10` and CI runs the
+suite on 3.10–3.14; if your change is version-sensitive, say which interpreters you actually ran.
+
+**Report real counts, not impressions.** Record the pass/fail baseline BEFORE your change so "no
+regressions" is a recorded diff (`baseline 2 failing {a,b} → still 2 {a,b}`), not a feeling. If a
+gate fails for a reason you did not introduce, say so explicitly.
+
+---
+
+## Bug logs live in the OTHER repo
+
+This repo has no `.planning/`. Bug logs for terum-capture are filed in **Terum-MVP** at
+`.planning/debug/capture-cli/`, and bug numbers are global across both repos.
+
+You cannot allocate a number from here — `scripts/next-bug-number.sh` is in Terum-MVP. **Never
+grep or `ls` for the next number** (that is a known collision race). If you find a bug, describe it
+in your report and let the caller allocate the number.
+
+---
+
+## Git discipline
+
+- **Stage only the files your task touched.** Concurrent agent sessions and worktrees share this
+  `.git`. Never `git add -A`; flag unrelated changes as follow-ups.
+- Never commit or push unless explicitly asked. Never add `Co-Authored-By` lines.
+- If you are in a worktree, stay in it.
+- Unlike Terum-MVP, this repo has **no `.githooks/pre-push` gate** and commits land on `main`
+  directly — CI on `main` is the only thing standing behind a bad push. Do not treat a green local
+  run as equivalent.
+
+---
+
+## Hard stops — ask, do not proceed
+
+- Anything that writes outside the repo: `~/.terum/`, `~/.claude/`, `~/.claude.json`,
+  `~/.cursor/mcp.json`. These are the user's live config; the whole point of invariant 4 is that
+  even the *tests* must not touch them.
+- Changing the wire contract with Terum-MVP's ingest endpoint (event payload shape, auth header,
+  `api_url` semantics). That is a coordinated two-repo change.
+- Adding a runtime dependency. `httpx` is the only one, deliberately — this is `pipx`-installed on
+  developer machines and every addition is a new install failure mode.
+- Publishing, tagging, or bumping `__version__`. The release order is load-bearing and spans both
+  repos: bump `__version__` → merge → **tag** → *only then* bump `LATEST_CAPTURE_VERSION` in
+  Terum-MVP. That constant is the fleet's rollout trigger, so pointing it at an untagged version
+  tells every client to install something that does not exist. Drifting it the other way is
+  bug-576 — 0.3.0 and 0.4.0 both shipped while it still said `0.2.0`, so no user was ever nagged.
+  Terum-MVP's `npm run check:capture-version-sync` is the lockstep gate.
+- Anything the spec did not authorize.
+
+---
+
+## Reporting back
+
+Finish with: what you changed (file list), the real gate output including which interpreters ran,
+any place the spec was ambiguous and what you did about it, and the single claim you are least
+confident is correct.

terum_capture-0.7.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+Notable changes to terum-capture. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow the tags in this repo. Entries before this file existed were
+reconstructed from git history.
+
+## [Unreleased]
+
+## [0.7.0] — 2026-09-02
+
+First release published to [PyPI](https://pypi.org/project/terum-capture/).
+
+### Added
+- Project-scoped capture by default, with an interactive project picker in
+  `setup` — the hook is written into each selected repo's git-ignored
+  `.claude/settings.local.json` instead of globally (#6)
+
+### Changed
+- `install.sh` now announces install phases and reports failures as a one-line
+  reason instead of a raw pipx/uv error dump (#19, #20)
+- README leads with the `install.sh` one-liner; pipx is the alternative (#21)
+
+### Fixed
+- `install.sh` falls back to `uv` with a managed Python when pipx can't work
+  (broken Homebrew Pythons on macOS 26.1/26.2), and `terum-capture update` is
+  uv-aware afterwards (#19)
+
+## [0.6.1] — 2026-08-04
+
+### Added
+- The update nag is now user-visible: surfaced as a `systemMessage` from the
+  Stop hook instead of being silently swallowed (#18)
+
+## [0.6.0] — 2026-08-04
+
+### Added
+- Delivery gate: decision guidance and a hook-performed conflict check on
+  UserPromptSubmit (#16, #17)
+- `AGENTS.md` so Codex-style agents load the repo conventions (#16)
+
+### Changed
+- The delivery hook's two retrieval lanes run in parallel with a 15s timeout
+  (bug-592)
+
+### Fixed
+- The delivery hook's fail-open guarantee is structural — a gate failure can no
+  longer block the user's prompt (bugs 593, 594)
+
+## [0.5.0] — 2026-07-31
+
+### Added
+- Version signaling baseline: the CLI reports its version with events and the
+  backend can request an update nag, gated by a cross-repository sync check
+
+[Unreleased]: https://github.com/ryanliu-terum/terum-capture/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/ryanliu-terum/terum-capture/compare/v0.6.1...v0.7.0
+[0.6.1]: https://github.com/ryanliu-terum/terum-capture/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/ryanliu-terum/terum-capture/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/ryanliu-terum/terum-capture/releases/tag/v0.5.0

terum_capture-0.7.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to terum-capture
+
+Thanks for your interest in improving terum-capture. This is a small, test-heavy
+codebase with a few hard rules that exist because breaking them has bitten real
+users; read this page before opening a PR and the review will be quick.
+
+## Development setup
+
+Requires Python ≥ 3.10.
+
+```bash
+git clone https://github.com/ryanliu-terum/terum-capture
+cd terum-capture
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+`pip install -e ".[dev]"` is the one documented way to get a working test
+environment — it installs the pinned pytest the suite expects.
+
+## The rules CI enforces
+
+**Tests never touch your real home directory.** Every `~`-rooted path the CLI
+uses is redirected to `tmp_path` by `tests/conftest.py`. If you add a new
+`~`-rooted constant, wire it into that fixture and into
+`scripts/home-watchlist.txt`, or CI's home-isolation check will fail. This rule
+exists because a test run once rewrote a developer's real
+`~/.claude/settings.json` and broke every Claude Code prompt afterwards.
+
+**Fatal diagnostics go to stderr, and failure exits non-zero.** Claude Code runs
+several of these commands as hooks: a supervisor surfaces a failed child's
+*stderr*, and on some hook events *stdout is injected as model context*. So
+`print("Error: ...")` is a bug twice over. Route diagnostics through
+`output.err()` / `output.die()`, and make sure any command that reports a
+failure also exits non-zero. `scripts/check_error_streams.py` (an AST gate, run
+by the test suite) enforces both rules — don't work around it; if it flags your
+code, the code is wrong.
+
+**All of CI must be green.** The pytest matrix runs on every interpreter from
+3.10 through 3.14. PRs target `main`.
+
+## Making changes
+
+- Keep the repo's comment convention: comments state the constraint or the bug
+  that made the code this way, not what the next line does.
+- New behavior needs a test. Look at the existing `tests/test_*.py` for the
+  house style — they are hermetic (no network, no real `$HOME`).
+- The install path (`install.sh`) and the self-updater (`updater.py`) are the
+  highest-risk surfaces: they run unattended on user machines. Changes there
+  get extra scrutiny.
+
+## Releases (maintainers)
+
+Versioning is manual and single-sourced: bump `__version__` in
+`src/terum_capture/__init__.py` (hatch reads it from there), update
+`CHANGELOG.md`, then tag `vX.Y.Z` and publish a GitHub release.
+
+## Questions and discussion
+
+Open a GitHub issue. For security reports, see [SECURITY.md](SECURITY.md) —
+please don't open public issues for vulnerabilities.

terum_capture-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terum
+
+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.