ithrl 0.1.0__tar.gz → 0.3.0__tar.gz

{ithrl-0.1.0 → ithrl-0.3.0}/.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 *.py[cod]
 .pytest_cache/
 .ruff_cache/
+.rumdl_cache/
 .hypothesis/
 .pyrefly/
 .coverage

ithrl-0.3.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# CHANGELOG
+
+## v0.3.0 (2026-11-10)
+
+### Features
+
+- Add finer final-response reduction ([#52](https://github.com/eberkut/ithrl/pull/52), [`562124a`](https://github.com/eberkut/ithrl/commit/562124ab071788a52e0d50dd538048ee67de464b))
+- Define source-bound text-section removal ([#51](https://github.com/eberkut/ithrl/pull/51), [`56c9e6c`](https://github.com/eberkut/ithrl/commit/56c9e6cfb24a83dc32573232b447e574cb0f616f))
+- Inspect retained context without provider calls ([#49](https://github.com/eberkut/ithrl/pull/49), [`5604688`](https://github.com/eberkut/ithrl/commit/5604688e269543305fe4b7b253a703dc404c1139))
+- **reduce**: Qualify paragraph removal on ordinary sessions ([#58](https://github.com/eberkut/ithrl/pull/58), [`5c6ae26`](https://github.com/eberkut/ithrl/commit/5c6ae26760ea7bd94b406ebf9ba3214e5c4ce64c))
+
+### Refactoring
+
+- Simplify experiment workflows and test fixtures ([#50](https://github.com/eberkut/ithrl/pull/50), [`782bfa2`](https://github.com/eberkut/ithrl/commit/782bfa2692a49a5bb2a4f555801abda23cde6fda))
+
+## v0.2.0 (2026-11-02)
+
+### Bug Fixes
+
+- **codex**: Bound and account for physical provider requests ([#33](https://github.com/eberkut/ithrl/pull/33), [`88529d6`](https://github.com/eberkut/ithrl/commit/88529d6f8b930dbcc546a0011f085c67d0bef1ac))
+- **copilot**: Recover catalogue connections and qualify fuzzing ([#37](https://github.com/eberkut/ithrl/pull/37), [`ff6cf63`](https://github.com/eberkut/ithrl/commit/ff6cf6324325f7f6dad8f8c9c80ea58bfe4e249a))
+- **copilot**: Restore native session prefixes through the CLI ([#34](https://github.com/eberkut/ithrl/pull/34), [`36845dd`](https://github.com/eberkut/ithrl/commit/36845ddb8239c0a488552297aaa70e6211979e59))
+- **fuzz**: Preserve accounting and validate campaign recovery ([#25](https://github.com/eberkut/ithrl/pull/25), [`f1f4793`](https://github.com/eberkut/ithrl/commit/f1f479318fe914f3033667b65381f7101bd3aaea))
+- **sampling**: Enforce calibration budgets and report durable progress ([#32](https://github.com/eberkut/ithrl/pull/32), [`bd40577`](https://github.com/eberkut/ithrl/commit/bd40577c734d70b36e59a9e6d3babafa1502bfd3))
+
+### Features
+
+- **extract**: Support literal predicates for native decisions ([#31](https://github.com/eberkut/ithrl/pull/31), [`3b18c2b`](https://github.com/eberkut/ithrl/commit/3b18c2bdd814c4e4c3bf79825a8cab77eb433661))
+- **fuzz**: Add mutation and sampled comparison services ([`56ee8b8`](https://github.com/eberkut/ithrl/commit/56ee8b8c5e1370b91db6c9c952eb8ceec19c95ae))
+- **fuzz**: Expose inspectable campaigns and saved results ([#24](https://github.com/eberkut/ithrl/pull/24), [`e60e472`](https://github.com/eberkut/ithrl/commit/e60e47230b99e50ff42de7cd8fb89b3769e6d6e2))
+- **fuzz**: Persist campaigns and recover interrupted execution ([#22](https://github.com/eberkut/ithrl/pull/22), [`806667f`](https://github.com/eberkut/ithrl/commit/806667f47e8bae1ccbf9b32fadc511ca559675d0))
+- **fuzz**: Qualify native Codex text appends ([#28](https://github.com/eberkut/ithrl/pull/28), [`a5b880b`](https://github.com/eberkut/ithrl/commit/a5b880b60ef9834bb57b2c4950e18cd17ff0b275))
+
+### Performance Improvements
+
+- Streamline local workflows and harden result publication ([#36](https://github.com/eberkut/ithrl/pull/36), [`43b9d81`](https://github.com/eberkut/ithrl/commit/43b9d81d0dcff85708da5c914986a68bbe8141db))
+
+## v0.1.0 (2026-10-23)
+
+### Bug Fixes
+
+- **adapters**: Detect saved session formats structurally ([`c8256b9`](https://github.com/eberkut/ithrl/commit/c8256b93ce79fb9c3f025e2b92a970f336497218))
+- **reduce**: Validate native candidates before sampled dispatch ([`90d4c0d`](https://github.com/eberkut/ithrl/commit/90d4c0d11a206389d44c6a59991df53c19802514))
+- **runner**: Clarify Codex isolation prerequisites ([`4a409c1`](https://github.com/eberkut/ithrl/commit/4a409c1f37caf301a00cfbd20d3a95cf15844eb9))
+
+### Features
+
+- Establish credential-free context reduction core ([`c517409`](https://github.com/eberkut/ithrl/commit/c517409c06e40c92b24a8b990685abd4acc9a9ba))
+- **adapters**: Parse Codex and Copilot session evidence ([`3b81c26`](https://github.com/eberkut/ithrl/commit/3b81c2607397d884bcfb1b19dbf995f66ccb0107))
+- **calibration**: Add bounded sampled runner calibration ([`f9db180`](https://github.com/eberkut/ithrl/commit/f9db18012565badc2cf2a3a4a6158487d4c5fb70))
+- **case**: Preserve immutable native source evidence ([`d108b96`](https://github.com/eberkut/ithrl/commit/d108b96487ccb69f6b36642ae331d36272038722))
+- **cli**: Add an installed example and focused public guides ([`1efc2ff`](https://github.com/eberkut/ithrl/commit/1efc2ffb03c734b666b1d1da9b5610ad62970267))
+- **cli**: Add guarded native calibration ([`06d2bfb`](https://github.com/eberkut/ithrl/commit/06d2bfb3f4d34f4dc845d9d6877257e4e79f9120))
+- **cli**: Integrate sampled reduction and exact resume ([`40be766`](https://github.com/eberkut/ithrl/commit/40be7664ba90ac5341d93fb5a725dbfa0efd48d3))
+- **extract**: Support ordinary Codex and Copilot sessions ([`3cd0c10`](https://github.com/eberkut/ithrl/commit/3cd0c1092aeb3669b86fdae07e887d28ba9d685f))
+- **reduce**: Add sampled contracts and durable progress ([`650252d`](https://github.com/eberkut/ithrl/commit/650252d76e8d7d72f3f5715ecaf488e752dc18b1))
+- **reduce**: Integrate sampled candidate search ([`72958d8`](https://github.com/eberkut/ithrl/commit/72958d8d6ae0307ca2d090a2a10d02606bafdea6))
+- **runner**: Add Codex final-response execution ([`ad30a9a`](https://github.com/eberkut/ithrl/commit/ad30a9a17b0e665056eca9b415cbf4e2770a7bf7))
+- **runner**: Add controlled Copilot execution ([`c9d1bb2`](https://github.com/eberkut/ithrl/commit/c9d1bb23bfdd98bb022fd0b62ca9b8a81021fe4b))
+- **runner**: Add isolated execution runtime ([`17d2224`](https://github.com/eberkut/ithrl/commit/17d22240414cdb32d4464f16e7b2621d99729ca0))
+- **runner**: Add shared execution foundation ([`89536e9`](https://github.com/eberkut/ithrl/commit/89536e919730fc0abf680a2928a89761c78339f5))
+- **runner**: Validate isolated native calibration ([`b0cd438`](https://github.com/eberkut/ithrl/commit/b0cd438d1fa280f0ddafa39d23653a7ac926da1b))
+- **sampling**: Collect bounded fresh-baseline blocks ([`16abf30`](https://github.com/eberkut/ithrl/commit/16abf30b964eae299177d1e1dade6f545ffbda31))
+- **sampling**: Support paced execution and safe overload replacement ([`5d70fbd`](https://github.com/eberkut/ithrl/commit/5d70fbd26901a0574883e07fd4055644c8515e80))
+- **statistics**: Add fixed-sample candidate classification ([`fb26fca`](https://github.com/eberkut/ithrl/commit/fb26fcaf7c064f49ac7d63b4e2ceb1ab3d6dcdb5))
+- **workflow**: Confirm sampled reductions with fresh evidence ([`ee291e4`](https://github.com/eberkut/ithrl/commit/ee291e4d906394452da61640989cef594f62caf7))
+
+### Refactoring
+
+- Simplify execution paths and avoid redundant context copies ([`34ab361`](https://github.com/eberkut/ithrl/commit/34ab36165fed08678a80679b3f1753e6f26f63f8))

{ithrl-0.1.0 → ithrl-0.3.0}/CONTRIBUTING.md

@@ -1,19 +1,37 @@
 # Contributing
 
-Start with an [issue](https://github.com/eberkut/ithrl/issues) describing the problem or proposed
-change. Pull requests are limited to collaborators; discuss the work before preparing one.
+Open an [issue](https://github.com/eberkut/ithrl/issues) for a bug report, question or proposed
+change. Pull requests are limited to collaborators. If you are not a collaborator and want to
+implement a change, agree on scope and ask the maintainer about access in the issue before preparing
+a PR.
 
 For bug reports, include the ithrl version, platform, sanitized error code and steps to reproduce.
 Keep full sessions, cases, proprietary source and credentials out of public reports. Report
-suspected vulnerabilities through [private vulnerability reporting](https://github.com/eberkut/ithrl/security/advisories/new).
+suspected vulnerabilities through
+[private vulnerability reporting](https://github.com/eberkut/ithrl/security/advisories/new).
+
+## First contribution
+
+1. Find an existing issue or open one, and agree on scope with the maintainer.
+2. Follow [development setup](#development-setup) to prepare the locked environment.
+3. Make a focused change using [Preparing a change](#preparing-a-change), and run the relevant
+   [checks](#checks).
+4. Open a PR linking the issue and explaining the change and its validation. Follow the
+   [review requirements](#pull-request-review).
+
+For task-specific instructions, see [documentation](#documentation),
+[workflows and dependencies](#workflow-and-dependency-checks),
+[integration tests](#credential-free-integration-tests) or
+[native smoke tests](#opt-in-native-smoke-tests).
 
 ## Development setup
 
-Use [uv](https://docs.astral.sh/uv/) and Python 3.12, 3.13 or 3.14. Python 3.14 is the primary
-development version. From the repository root:
+Use [uv](https://docs.astral.sh/uv/) at the version required by `tool.uv.required-version` in
+`pyproject.toml`, and Python 3.12, 3.13 or 3.14. CI reads the same uv pin through `setup-uv`'s
+`version-file` input. Python 3.14 is the primary development version. From the repository root:
 
 ```bash
-uv sync --locked --all-groups
+uv sync --locked --all-groups --all-extras
 uv run ithrl --help
 ```
 
@@ -28,6 +46,8 @@ Run the same entry points used by CI:
 uv lock --check
 uv run ruff check .
 uv run ruff format --check .
+uv run rumdl fmt --check .
+uv run rumdl check .
 uv run pyrefly check
 uv run pytest --ignore=tests/packaging
 uv run radon cc src/ithrl --min B --show-complexity --total-average
@@ -36,7 +56,8 @@ uv build --sdist --wheel --no-sources
 ITHRL_DIST_DIR=dist uv run pytest -o addopts= tests/packaging
 ```
 
-Non-packaging tests and the synthetic example need no provider credentials or network requests.
+Non-packaging tests and the synthetic example need no provider credentials or external network
+access. Native-runner tests need Linux, Bubblewrap and OpenSSL; their HTTPS fixture runs locally.
 Packaging checks may download build and runtime dependencies. Radon reports are review signals.
 
 CI runs tests, dependency audits and installed-package checks on Python 3.12–3.14. It builds one
@@ -47,6 +68,23 @@ an isolated tool, pass its path to `uv tool install` or `pipx install`.
 For local matrix runs, set `UV_PYTHON` on every command. Use separate environments, test caches and
 coverage files for parallel runs; otherwise run versions sequentially.
 
+Install the local hooks with `uv run pre-commit install`; run them on the whole repository with
+`uv run pre-commit run --all-files`. Ruff and rumdl format files in place. CI checks formatting
+without modifying files.
+
+Recognized Markdown-only PRs skip Python linting, typing, unit-test matrices and dependency audits.
+They retain Markdown formatting/linting, documentation tests, the strict site build, workflow and
+dependency review, and all package build/install checks. Mixed changes, unknown paths, configuration
+changes and PRs with 3,000 or more changed files run full validation. Rename detection considers
+both paths; deletions participate. Failed path detection fails the required Workflows check.
+Main-branch, scheduled, manual and release runs always perform full validation.
+
+The required `Python tests` check summarizes the test matrix. It accepts a skipped matrix only
+after successful Markdown-only classification. Failed classification, missing decisions, test
+failures and unexpected skips fail this check.
+
+The logo sources, usage rules and regeneration commands are in [branding](docs/branding/README.md).
+
 ## Workflow and dependency checks
 
 For GitHub Actions or Dependabot changes, use the jactionlint release pinned in
@@ -58,12 +96,13 @@ jactionlint --no-online --strict-exit
 
 CI uses its default correctness/security profile, with online lookups and automatic fixes disabled.
 
-Audit the resolved runtime dependencies and every dependency group, including development, docs
-and audit tooling, from `uv.lock`. Run this in Bash with the locked environment synchronized:
+Audit the resolved runtime dependencies, optional extras and every dependency group, including
+development, docs and audit tooling, from `uv.lock`. Run this in Bash with the locked environment
+synchronized:
 
 ```bash
 set -o pipefail
-uv export --locked --all-groups --no-emit-project --format requirements.txt |
+uv export --locked --all-groups --all-extras --no-emit-project --format requirements.txt |
   uv run --locked --group audit pip-audit --strict --disable-pip --require-hashes -r /dev/stdin
 ```
 
@@ -72,25 +111,56 @@ package names and versions without installing those packages, resolving alternat
 fixes. CI evaluates markers on each supported Python version. This covers locked versions rather
 than every version permitted by package dependency ranges.
 
-GitHub's dependency graph and Dependency Review use the inventory GitHub has for each commit.
-Before relying on them for `uv.lock` coverage, compare the hosted package/version inventory with
-the locked export on each supported Python version. The PR dependency-review job rejects newly
-introduced known vulnerabilities at any severity across runtime, development and unknown scopes.
-It uses a read-only token and does not check out or execute PR code. If it reports incomplete
-dependency snapshots, wait for GitHub's graph update and rerun the job. No license allowlist is
-enforced by this check. Keep the lockfile audit above as the full-inventory CI gate; Dependabot
-version updates alone do not establish dependency-graph coverage.
+For dependency changes, run the lockfile audit above on each supported Python version. GitHub's
+dependency graph may omit packages from `uv.lock`, so Dependabot and Dependency Review cannot
+replace that audit.
+
+The PR dependency-review job rejects newly introduced known vulnerabilities at any severity across
+runtime, development and unknown scopes. It uses a read-only token and does not check out or execute
+PR code. If it reports incomplete dependency snapshots, wait for GitHub's graph update and rerun
+the job. License checks are disabled.
 
 CI runs weekly on Monday at 06:17 UTC to detect new advisories. Dependabot checks Python, Actions
 and pre-commit dependencies weekly, groups minor/patch updates and leaves majors individually
 reviewable. Ordinary updates have a seven-day cooldown; security updates have none. Updates are
-never automatically merged. Hosted dependency-graph coverage is a separate verification gate.
+never automatically merged.
 
 ## Documentation
 
-README owns the quick start; `docs/` owns user guides and reference. Support, security and conduct
-policies live at the repository root. Keep private sessions, cases and credentials out of
-documentation and generated output.
+Use `uv run rumdl fmt .` to format Markdown, then `uv run rumdl check .` to lint it. The same
+version and `pyproject.toml` configuration apply to pre-commit and CI. Prose wraps at 100
+characters; commands and tables retain their layout. MkDocs syntax is recognized within `docs/`. The
+generated CLI reference has narrow exceptions for Typer's prompts, option alignment and wrapping;
+its byte-for-byte generation check remains enforced. The generated changelog keeps each entry on
+one source line, with a line-length exception.
+
+Keep installation and first-use instructions in README, and detailed user guides and reference in
+`docs/`. Support, security and conduct policies live at the repository root. Keep private sessions,
+cases and credentials out of documentation and generated output.
+
+Use [Diátaxis](https://diataxis.fr/) to match a section to the reader's need. A tutorial guides
+learning through a reproducible example with expected results. A how-to gives prerequisites,
+actions and a success check for a specific task. Reference describes commands and contracts;
+explanation covers rationale, evidence and limits. Link between these when the reader needs more
+detail. Apply the distinction within existing pages; add a page when it has a separate purpose.
+Use concrete instructions and claims supported by evidence. Remove filler, promotional language
+and repeated explanations.
+
+[ROADMAP.md](ROADMAP.md) describes future direction. GitHub issues own actionable scope,
+dependencies, acceptance criteria and status; release milestones group scope and the public
+[Project](https://github.com/users/eberkut/projects/1/views/4) provides views of those same issues.
+Link implementation pull requests to their owning issues and record relevant validation before
+closing them. Keep future plans separate from current support claims.
+
+Use [architecture](docs/architecture.md) to locate current contracts,
+[decision records](docs/decisions/index.md) for significant choices and alternatives, and
+[research](docs/research/index.md) for methods, measurements and reproducibility. Amend the owning
+document instead of maintaining a second plan. A new decision record should explain context,
+decision, alternatives and consequences; supersede an old decision explicitly when needed.
+
+Before evaluating a new study, declare its tested domain, criteria, seeds, budget and intended
+claims. Report costs across complete workflows, including failed and incomplete work, and document
+the alternatives and limitations needed to interpret the results.
 
 The optional `docs` dependency group pins MkDocs and the shadcn theme. Search runs in the browser;
 fonts and scripts are served with the site. GitHub star-count requests and raw Markdown copying
@@ -100,13 +170,16 @@ When changing the theme or enabled extensions, check that asset list and the
 To preview the site locally:
 
 ```bash
-uv sync --locked --all-groups
+uv sync --locked --all-groups --all-extras
 uv run --group docs mkdocs serve
 ```
 
-`mkdocs.yml` admits only the named public files under `docs/`. When adding a page, update its
-navigation and file allowlist, the sdist include list in `pyproject.toml`, and the documentation
-manifests in the documentation and packaging tests. Never set `docs_dir` to the repository root.
+`mkdocs.yml` admits public pages and Markdown files in the dedicated `docs/decisions/` and
+`docs/research/` directories. These directories contain publication-ready material only. Add new
+pages to navigation; a page within an admitted directory needs no per-file package/test entry.
+When adding a public directory or asset type, update the site/sdist publication boundaries and
+their tests together. Never set `docs_dir` to the repository root. Keep raw evidence and generated
+research outputs outside the documentation sources.
 
 After changing CLI options or help, regenerate the committed reference with Typer:
 
@@ -132,7 +205,7 @@ runs in a separate `github-pages` environment job without checking out or execut
 Pull requests receive read-only documentation checks through CI and cannot deploy.
 
 Repository administrators must select **Settings → Pages → Source: GitHub Actions** and restrict
-the `github-pages` environment to `main` before the first deployment. No custom domain, separate
+the `github-pages` environment to `main`. No custom domain, separate
 site repository, `gh-pages` branch or personal access token is needed. After a successful
 deployment, check the published pages, navigation and static assets at the URL above.
 
@@ -153,8 +226,15 @@ accounting and budget refusal:
 uv run pytest -o addopts= tests/integration/test_native_calibration.py -q
 ```
 
+Fuzz CLI tests cover harness-free inspection, consent, bounded collection, unsuccessful outcomes,
+interruption and exact resume without provider requests:
+
+```bash
+uv run pytest -o addopts= tests/integration/test_fuzz_cli.py -q
+```
+
 These tests establish local contracts. Native qualification is recorded in the
-[measurement notes](docs/native-runs.md#compatibility-and-measurements).
+[measurements](docs/measurements.md).
 
 ## Opt-in native smoke tests
 
@@ -188,13 +268,13 @@ uv run pytest -o addopts= tests/live -m native_smoke -s \
 ```
 
 Every invocation creates fresh private state, harmless session content and an empty original
-workspace. Calibration requires two matching attempts and permits at most two, each bounded at
-120 seconds plus cancellation grace. Final-response profiles allow up to two provider calls;
-Copilot shell allows up to four, with `pwd` visible but denied.
+workspace. Calibration requires two matching attempts and permits at most two, each bounded at 120
+seconds plus cancellation grace. Codex allows up to 32 provider calls across the two attempts;
+either Copilot profile allows up to two. In the shell profile, `pwd` is visible but denied.
 
-Returned actions never execute. Hosted tools, MCP and tool-side network effects remain forbidden.
-An input-token cap cannot be enforced. Private evidence records known counts and unknown
-acceptance explicitly. Unsupported or unsuccessful profiles fail the test without skipping or retrying.
+Returned actions never execute. Hosted tools, MCP and tool-side network effects remain forbidden. An
+input-token cap cannot be enforced. Private evidence records known counts and unknown acceptance
+explicitly. Unsupported or unsuccessful profiles fail the test without skipping or retrying.
 
 ## Preparing a change
 
@@ -206,13 +286,38 @@ Changes to native protocols, reconstruction, permissions or provider accounting
 the affected safety boundary. Mock tests establish local contracts; claims of native support also
 need capability, isolation, calibration and live-use evidence for the target profile.
 
+### Pull request review
+
+Pull requests are squash-merged, with the PR title becoming the commit subject. Use a Conventional
+Commit title, such as `fix(codex): handle overload responses` or
+`docs: explain confirmation results`. The title check reruns on title edits and new pushes; it reads
+metadata without checking out PR code. Make sure the required CI and CodeQL checks pass and resolve
+review conversations before merging.
+
+CodeRabbit reviews PRs when they are ready for review and posts feedback in a walkthrough and
+inline comments. Address relevant findings or explain why a suggestion does not apply. The
+maintainer makes the final review and merge decisions.
+
+CodeRabbit's optional planning and code-generation features are configured in
+[`.coderabbit.yaml`](.coderabbit.yaml). A paid CodeRabbit account is not required to contribute.
+
 ## Preparing a release
 
+The release procedures below are for maintainers with repository and package-publishing access.
+
+For every feature, aim for parity across supported harnesses. Any exception must be clearly
+justified and documented before release.
+
 Python Semantic Release, pinned in the `release` dependency group, calculates versions from
 Conventional Commits. `pyproject.toml` is the version source; installed CLI and Codex client
 metadata read that distribution version. The tool generates `CHANGELOG.md` from the full release
-history, omitting routine build, CI, documentation, style and test commits. Do not edit the
-generated changelog by hand; review its contents before approving a release.
+history, omitting routine build, CI, documentation, style and test commits. Its
+[template](.github/changelog/CHANGELOG.md.j2) keeps lists compact, with one entry per source line.
+Change the template to adjust formatting; do not edit generated entries by hand.
+
+A maintainer starts preparation; Semantic Release chooses the version and writes the notes.
+Review and merge the generated files through a PR so CI tests the prepared version before the
+publication workflow builds it. The publication workflow uses that committed version.
 
 Use `main` with complete history and all existing release tags available. Preview the next version
 without changing files, the index, commits, tags or remote state:
@@ -250,24 +355,26 @@ ownership and the following repository/index settings:
 
 - PyPI and TestPyPI Trusted Publishers bind `eberkut/ithrl`, `release.yml` and their respective
   `pypi` / `testpypi` environments. Publishing uses OIDC, without a stored PyPI API token.
-- Both environments admit only `main`. `pypi` requires the maintainer's approval, permits
-  self-review and disallows administrative approval bypass. Environment declarations in YAML
-  do not configure these protections; verify the actual settings before dispatch.
+- Both environments admit only `main`, require the maintainer's approval, permit self-review and
+  disallow administrative approval bypass. Environment declarations in YAML do not configure these
+  protections; verify the actual settings before dispatch.
 - Release-tag rules permit the maintainer's signed-tag creation and prevent unapproved tag
   replacement or deletion. The workflow never creates a tag.
 
-The dispatch gate admits the repository's current maintainer identity and requires the full source
-SHA and exact final `X.Y.Z` version. Replace the placeholders with the reviewed values:
+The release workflow accepts dispatches only from the repository maintainer. Supply the full source
+commit SHA and exact final `X.Y.Z` version. Replace the placeholders with the reviewed values:
 
 ```bash
 gh workflow run release.yml --repo eberkut/ithrl --ref main \
   -f version=X.Y.Z -f source-sha=FULL_APPROVED_COMMIT_SHA
 ```
 
-1. Inspect that run's checks and successful **Publish TestPyPI rehearsal** job. Its summary records
+1. After source verification and validation pass, approve the `testpypi` deployment on the run's
+   GitHub page. This authorizes the public TestPyPI upload.
+2. Inspect the successful **Publish TestPyPI rehearsal** job. Its summary records
    the source, version, immutable artifact ID and checksum-manifest digest. The production job
    waits at the `pypi` environment. TestPyPI files, logs and artifacts are public.
-2. Download that run's `release-distributions` artifact into a new review directory. For example:
+3. Download that run's `release-distributions` artifact into a new review directory. For example:
 
    ```bash
    gh run download RUN_ID --repo eberkut/ithrl \
@@ -278,7 +385,7 @@ gh workflow run release.yml --repo eberkut/ithrl --ref main \
    from the review directory. Inspect the release notes and confirm TestPyPI serves the same
    distribution hashes. Complete a clean TestPyPI installation/example rehearsal before approval;
    resolve dependencies only from the normal PyPI index, without mixing indexes.
-3. After the rehearsal passes and tag creation is approved, create and verify the signed tag at
+4. After the rehearsal passes and tag creation is approved, create and verify the signed tag at
    the frozen source commit, then push only that tag through the permitted tag-rules path:
 
    ```bash
@@ -287,12 +394,12 @@ gh workflow run release.yml --repo eberkut/ithrl --ref main \
    git push origin refs/tags/vX.Y.Z
    ```
 
-4. Review and approve the `pypi` deployment on the run's GitHub page. The job verifies the existing
+5. Review and approve the `pypi` deployment on the run's GitHub page. The job verifies the existing
    annotated tag targets the frozen source, rechecks the files, and uploads to PyPI. The final job
    rechecks the tag/files and creates the GitHub Release with those distributions, notes and
    checksums. Signature verification belongs to the preceding maintainer tag check; the workflow
    checks the tag object and target commit.
-5. Verify the published versions, hashes, attestations and installed example. A successful upload
+6. Verify the published versions, hashes, attestations and installed example. A successful upload
    alone does not complete release acceptance.
 
 Complete review within 30 days: release artifacts are retained for 30 days, and GitHub limits the

ithrl-0.3.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.5
+Name: ithrl
+Version: 0.3.0
+Summary: Find smaller agent contexts that preserve a selected model behavior
+Project-URL: Source, https://github.com/eberkut/ithrl
+Project-URL: Issues, https://github.com/eberkut/ithrl/issues
+Project-URL: Documentation, https://eberkut.github.io/ithrl/
+Project-URL: Changelog, https://github.com/eberkut/ithrl/releases
+Author: Vincent Morel
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.12
+Requires-Dist: filelock>=3.32.4
+Requires-Dist: github-copilot-sdk==1.0.28
+Requires-Dist: jsonschema>=4.25
+Requires-Dist: packaging>=24.2
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: pydantic>=2.12
+Requires-Dist: rich>=14
+Requires-Dist: typer>=0.16
+Provides-Extra: fuzz
+Requires-Dist: scipy>=1.18; extra == 'fuzz'
+Description-Content-Type: text/markdown
+
+<!-- rumdl-disable MD033 -->
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/eberkut/ithrl/main/docs/branding/ithrl-logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/eberkut/ithrl/main/docs/branding/ithrl-logo-light.svg">
+    <img src="https://raw.githubusercontent.com/eberkut/ithrl/main/docs/branding/ithrl-logo.png" alt="ithrl" width="320" height="158">
+  </picture>
+</h1>
+<!-- rumdl-enable MD033 -->
+
+[![PyPI](https://img.shields.io/pypi/v/ithrl.svg)](https://pypi.org/project/ithrl/)
+[![CI](https://github.com/eberkut/ithrl/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/eberkut/ithrl/actions/workflows/ci.yml)
+
+`ithrl` turns saved Codex and GitHub Copilot sessions into debugging experiments. Search for a
+smaller context that preserves a chosen response or tool request, or a small text change that alters
+it.
+
+[Documentation](https://eberkut.github.io/ithrl/) · [Try it](#try-it) ·
+[Supported inputs](#supported-inputs)
+
+## Install
+
+With [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv tool install ithrl
+```
+
+You can also install with `pipx install ithrl` or, in an existing virtual environment,
+`python -m pip install ithrl`. For context fuzzing, use `'ithrl[fuzz]'` in place of `ithrl` in
+the installation command.
+
+Tested on Python 3.12–3.14. Native runners require Linux. APIs and saved formats may change before
+1.0; keep your source sessions and record the version used for each case.
+
+## Try it
+
+The bundled deterministic example needs no account, agent installation or model access:
+
+```bash
+mkdir -m 700 ithrl-demo
+ithrl extract --example --output ithrl-demo/case
+ithrl shrink ithrl-demo/case --observation-store ithrl-demo/observations.sqlite
+```
+
+The result removes half the context items and confirms that the target is preserved. Output excerpt:
+
+```text
+Reduced and confirmed
+  context items   10 -> 5
+  original test   target observed
+  search          1-minimal; all valid single removals tested
+  confirmation    target preserved
+  observations    15
+  No network requests or provider calls. No actions executed.
+```
+
+Inspect the saved result in `ithrl-demo/case/results/`; the
+[results guide](https://github.com/eberkut/ithrl/blob/main/docs/results.md) explains its files.
+Use a new directory to repeat the example; extraction refuses to overwrite an existing case.
+
+## Commands
+
+- `ithrl extract` browses saved sessions and creates a case from a selected decision.
+- `ithrl shrink CASE` searches for context removals that preserve the selected behavior.
+- `ithrl inspect retained CASE --result RESULT` explains retained units and recorded removal trials
+  from a saved reduction without model access. See
+  [results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md#inspect-retained-context).
+- `ithrl fuzz CASE --config PRIVATE_TOML` searches for and simplifies text appends that decrease how
+  often the selected behavior occurs, with independent confirmation.
+
+For example, extract a saved session file:
+
+```bash
+ithrl extract path/to/session.jsonl --output .ithrl/case
+```
+
+Extraction makes no provider calls. Native experiments require Linux, usable Bubblewrap, an
+installed harness and model access. Review the provider, safety controls and call/time budget in the
+[native-run guide](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md) before execution.
+Returned actions are observed and denied. Cases contain copied session content; keep them private.
+
+## Supported inputs
+
+| Input | Extracted decisions | Reduction | Fuzzing |
+| --- | --- | --- | --- |
+| Bundled synthetic example | Synthetic tool request | Deterministic local runner | Local fake runner |
+| Codex CLI rollouts | Final responses | Experimental native runner; [paragraph-removal measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#ordinary-session-paragraph-removal) | Experimental prior-user text appends |
+| Copilot CLI session events | Final responses and shell requests | Experimental final-response paragraph removal and denied `bash` runner | Experimental prior-user text appends for final-response targets |
+
+Native Codex and Copilot final-response fuzzing supports appending text to eligible prior user
+input while preserving the fixed triggering input. The
+[fuzzing walkthrough](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#context-fuzzing)
+starts with a local example and covers native execution.
+
+[Saved-session measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#saved-session-experiments)
+include ordinary Codex and Copilot final-response experiments that removed paragraphs from retained
+prior-user text and passed fresh confirmation at a 20-percentage-point preservation margin. The
+[worked investigation](https://github.com/eberkut/ithrl/blob/main/docs/research/ordinary-session-investigation.md)
+explains what the smaller Codex context helped a developer inspect and what remains unresolved.
+The measurements distinguish private runtime qualification from integrated support and report
+resource usage and unsuccessful outcomes alongside completed runs. Check
+[native compatibility](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#compatibility-and-measurements)
+for the installed harness's requirements.
+
+## Documentation
+
+Read the [documentation site](https://eberkut.github.io/ithrl/) or browse the guides below.
+
+- [Native runs](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md): session selection,
+  experiment configuration, preflight, model execution and measured resource usage.
+- [Results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md): saved files,
+  result interpretation, budgets, resume and sensitive data.
+- [Contributing](https://github.com/eberkut/ithrl/blob/main/CONTRIBUTING.md): issue-first
+  collaboration, checkout setup, checks and smoke tests.
+- [Roadmap](https://github.com/eberkut/ithrl/blob/main/ROADMAP.md): current priorities and planned
+  capabilities.
+- [Architecture](https://github.com/eberkut/ithrl/blob/main/docs/architecture.md): implementation
+  boundaries and decisions.
+- [Research](https://github.com/eberkut/ithrl/blob/main/docs/research/index.md): feasibility
+  studies, statistical methods and measurements.
+
+For help, bugs or proposals, see [Support](https://github.com/eberkut/ithrl/blob/main/SUPPORT.md).
+Report vulnerabilities through
+[private reporting](https://github.com/eberkut/ithrl/security/advisories/new).
+
+## Name
+
+Pronounce `ithrl` as **Ithuriel**, the angel whose spear reveals Satan in disguise in Milton's
+[*Paradise Lost*](https://rpo.library.utoronto.ca/content/paradise-lost-book-iv-1674).
+
+## License
+
+Licensed under the [Apache License 2.0](https://github.com/eberkut/ithrl/blob/main/LICENSE).