pontonier 0.5.0__tar.gz

pontonier-0.5.0/.github/scripts/changelog-section.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Print the CHANGELOG.md body for a given version section: lines after the
+# "## [X.Y.Z]" heading up to (not including) the next "## " heading, with
+# surrounding blank lines trimmed. Prints nothing if the section is absent.
+set -euo pipefail
+
+version="${1:?usage: changelog-section.sh <version>}"
+file="${2:-CHANGELOG.md}"
+
+awk -v ver="$version" '
+  index($0, "## [" ver "]") == 1 { capture = 1; next }
+  capture && /^## / { exit }
+  capture { print }
+' "$file" |
+  # trim leading blank lines, then trailing blank lines
+  awk 'NF { started = 1 } started { print }' |
+  awk '{ lines[NR] = $0 } END { last = NR; while (last > 0 && lines[last] ~ /^[[:space:]]*$/) last--; for (i = 1; i <= last; i++) print lines[i] }'

pontonier-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least-privilege default token; this workflow only reads the repo.
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml

pontonier-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,223 @@
+name: Publish
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to release, with or without leading v
+        required: true
+        type: string
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-${{ github.ref_name }}-${{ inputs.version }}
+  cancel-in-progress: false
+
+jobs:
+  release-metadata:
+    name: Validate release metadata
+    runs-on: ubuntu-latest
+    outputs:
+      tag: ${{ steps.metadata.outputs.tag }}
+      version: ${{ steps.metadata.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Validate version references
+        id: metadata
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_VERSION: ${{ inputs.version }}
+          REF_NAME: ${{ github.ref_name }}
+          GITHUB_REF: ${{ github.ref }}
+        run: |
+          set -euo pipefail
+
+          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
+            if [[ "$GITHUB_REF" != "refs/heads/main" ]]; then
+              echo "Manual releases must run from main; got $GITHUB_REF" >&2
+              exit 1
+            fi
+            version="${INPUT_VERSION#v}"
+            tag="v${version}"
+            if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
+              echo "Tag ${tag} already exists" >&2
+              exit 1
+            fi
+          else
+            tag="$REF_NAME"
+            version="${tag#v}"
+          fi
+
+          if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Version must be X.Y.Z; got ${version}" >&2
+            exit 1
+          fi
+
+          # pyproject.toml is the single source for the version; pontonier.__version__
+          # derives from the built metadata, so there is no second literal to check.
+          # What the test suite cannot see is the tag, so pin the tag to it here.
+          grep -Fq "version = \"${version}\"" pyproject.toml
+          grep -Fq "## [${version}]" CHANGELOG.md
+
+          {
+            echo "tag=${tag}"
+            echo "version=${version}"
+          } >> "$GITHUB_OUTPUT"
+
+  test:
+    needs: release-metadata
+    uses: ./.github/workflows/test.yml
+
+  build:
+    name: Build distributions
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: uv build --no-sources
+
+      - name: Check distributions
+        run: uvx twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: python-package-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  # Create the tag BEFORE publishing so a PyPI release (irreversible) never
+  # exists without its git tag. Only workflow_dispatch reaches here: on a
+  # tag-push the tag already exists, so this job is skipped and no contents:write
+  # token is minted on that path. A tag pushed with GITHUB_TOKEN does not
+  # retrigger this workflow.
+  create-tag:
+    name: Create tag
+    needs: [release-metadata, build]
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Create tag if needed
+        env:
+          TAG: ${{ needs.release-metadata.outputs.tag }}
+        run: |
+          set -euo pipefail
+
+          # release-metadata already verified this tag is absent for the dispatch.
+          # If it exists now, a concurrent or foreign release created it. Tolerate
+          # ONLY our own tag (already pointing at GITHUB_SHA, e.g. a job re-run);
+          # fail loudly on a mismatched tag so we never publish a release under a
+          # tag that points somewhere else. For an annotated tag the peeled ref
+          # (^{}) is the commit; for a lightweight tag the plain ref is.
+          peeled="$(git ls-remote --tags origin "refs/tags/${TAG}^{}" | awk '{print $1}')"
+          direct="$(git ls-remote --tags origin "refs/tags/${TAG}" | awk '{print $1}')"
+          target="${peeled:-$direct}"
+          if [ -n "$target" ]; then
+            if [ "$target" = "$GITHUB_SHA" ]; then
+              echo "Tag ${TAG} already points at ${GITHUB_SHA}; nothing to do."
+              exit 0
+            fi
+            echo "Tag ${TAG} already exists at ${target}, not ${GITHUB_SHA}; refusing to publish a mismatched release." >&2
+            exit 1
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "pontonier ${TAG}" "$GITHUB_SHA"
+          git push origin "$TAG"
+
+  publish:
+    name: Publish to PyPI
+    # create-tag is skipped on tag-push (the tag already exists) and required on
+    # workflow_dispatch. Proceed when the build succeeded and create-tag did not
+    # fail (success or skipped); !cancelled() lets this override the default
+    # skip-on-skipped-dependency behavior without running on a cancelled run.
+    needs: [build, create-tag]
+    if: ${{ !cancelled() && needs.build.result == 'success' && needs.create-tag.result != 'failure' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: [release-metadata, publish]
+    # `publish` transitively depends on `create-tag`, which is skipped on a tag-push
+    # (it only runs for workflow_dispatch). Without an explicit condition the default
+    # success() would propagate that skip and skip this job too, so a tag-push would
+    # publish to PyPI but never create the GitHub Release. Mirror `publish`'s guard:
+    # run whenever the publish succeeded and the run was not cancelled.
+    if: ${{ !cancelled() && needs.publish.result == 'success' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Build release notes
+        env:
+          VERSION: ${{ needs.release-metadata.outputs.version }}
+        run: |
+          set -euo pipefail
+          .github/scripts/changelog-section.sh "$VERSION" > release-notes.md
+          if [[ ! -s release-notes.md ]]; then
+            echo "See CHANGELOG.md for release notes." > release-notes.md
+          fi
+
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.release-metadata.outputs.tag }}
+        run: |
+          set -euo pipefail
+
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "GitHub Release ${TAG} already exists."
+            exit 0
+          fi
+
+          gh release create "$TAG" dist/* \
+            --title "pontonier ${TAG}" \
+            --notes-file release-notes.md

pontonier-0.5.0/.github/workflows/test.yml

@@ -0,0 +1,49 @@
+name: Test
+
+on:
+  workflow_call:
+
+# Least-privilege: the gate only reads the repo. Keep OIDC/environment OUT of here.
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    name: lint + types + tests (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        include:
+          # The orphan-sweep tests exercise `ps` portability (GNU vs BSD, -ww
+          # truncation), so at least one macOS runner is load-bearing, not a nicety.
+          - os: macos-latest
+            python-version: "3.14"
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Check GitHub Actions are SHA-pinned
+        run: uv run python scripts/check_github_actions_pinning.py
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format
+        run: uv run ruff format --check .
+      - name: Type check
+        run: uv run ty check
+      - name: One-way core dependency rule
+        run: uv run lint-imports
+      - name: Test (95% coverage floor)
+        run: uv run pytest
+      - name: Wheel builds and imports without test deps
+        run: |
+          set -euo pipefail
+          uv build --wheel
+          uv run --isolated --no-project --with dist/*.whl \
+            python -c "import pontonier.core.jobs, pontonier.core.worktree; import pontonier; print(pontonier.__version__)"

pontonier-0.5.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[co]
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+*.egg-info/

pontonier-0.5.0/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+All notable changes to this project will be documented in this file. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.5.0] — 2026-08-16
+
+### Release engineering
+
+- The project is renamed **pontifex → pontonier**. The old name collided with
+  the unrelated `pontifex-mcp` on PyPI, which is also MCP-adjacent. A pontonier
+  is the engineer who builds pontoon bridges, which keeps the "not a bridge —
+  what bridges are built from" framing. Nothing was ever published under the old
+  name, so there is no compatibility shim and no deprecation period. Two
+  runtime-visible strings moved with it: throwaway worktrees are now
+  `pontonier-worktree-*`, and the default worktree git identity is
+  `pontonier <pontonier@local>`. All three bridges override both, so neither
+  string reaches a consumer.
+- `pyproject.toml` is now the single source for the version. `__version__` reads
+  the installed distribution metadata instead of repeating a literal, so the two
+  can no longer disagree — the drift this replaces was real (`__version__` stuck
+  at 0.3.0.dev0 across two bumps). `tests/test_version.py` now pins the
+  installed metadata to the `pyproject.toml` declaration, which also catches an
+  editable install left stale by a bump without a re-sync.
+- Releases publish from CI. `.github/workflows/publish.yml` runs the full test
+  gate, builds with `--no-sources`, creates the tag before publishing so a PyPI
+  release can never exist without its git tag, uploads to PyPI through trusted
+  publishing (OIDC, no long-lived token), and opens a GitHub Release with the
+  changelog section as its notes. Adapted from the codex-in-claude workflow.
+
+### Hardening
+
+- `JobStore` now confines job ids to the shape it mints (`uuid4().hex`, 32
+  lowercase hex). A job id is used verbatim as a path component under the
+  workspace directory; previously a caller-supplied traversal-shaped id
+  (`../…`) reached the filesystem join, and `status`/`discard`/`cancel` could
+  read — or delete — a record-shaped directory outside the store root.
+  Defense in depth: two of the three bridges pass `job_id: str` to the store
+  unvalidated. Malformed ids now read as not-found in every public lookup
+  (`status`, `result_payload`, `discard`, `cancel` — no wire-behavior change
+  for consumers), and the `_job_dir` join itself raises as a backstop.
+  Perturbation-verified: with the guards disabled, the new traversal test
+  reaches a planted decoy record outside the store root.
+
+### 0.5.0 (THE PROTOCOL FREEZE — `contract_api_version = 1`)
+
+- `pontonier.backend` is FROZEN. The plan's freeze criterion — all three real
+  adapters compile, type-check, and pass conformance and differential fixtures
+  — was met and then exceeded: each bridge's production orchestration now
+  stages every model-bearing run through its adapter's `prepare()`
+  (codex-in-claude's `run_codex_exec`, moonbridge's `run_kimi_exec`, and
+  claude-in-codex's sync tools + async job launch), so the adapters cannot
+  drift from production behavior — they are production behavior.
+- Freeze discipline, now binding: required Protocol members and required
+  `BackendContract` fields are stable within a minor line; "additive" changes
+  to a Protocol or frozen dataclass are breaking, so new behavior lands as
+  defaulted fields or optional capability protocols (the pattern
+  `effort_validation`, `dropped_flags`, and `artifact_paths` already
+  followed).
+- Deferred-findings ledger closed: the 0.3.0 note's schema-instruction seam
+  resolved consumer-side (the Kimi re-plumb dissolved the duplication — one
+  source, in the bridge that owns the strategy); classification's ambient
+  extra-args context is recorded on the Codex adapter as acceptable while
+  extra args are operator-owned process state.
+
+### 0.4.0 (redaction strengthening — key-block handling flows into core)
+
+- `PreparedRun.artifact_paths` (defaulted, non-breaking): NAMED staged paths,
+  keyed like `RunOutcome.artifact_texts`. Freeze-window finding from the Kimi
+  adapter: the flat `artifacts` tuple cannot tell the consumer which staged
+  file is the answer channel, and it must be read back inside the `prepare()`
+  context (staging is torn down on exit). `artifacts` stays as the
+  cleanup/enumeration view; when both are set they must agree.
+- `PreparedRun.dropped_flags` (defaulted, non-breaking): the channel for
+  help-gated flags the preparation dropped because the installed CLI does not
+  advertise them. Freeze-window finding from re-plumbing the Codex bridge's
+  orchestration through its adapter: production surfaces dropped flags as
+  compat warnings and reconciles reported model provenance from them, so a
+  `prepare()` that discarded them could not carry the real hot path.
+
+- `core.redaction` now redacts multi-line private-key blocks (PEM/PKCS8/OpenSSH/
+  PGP) STATEFULLY — ported from the claude-in-codex bridge's local redactor,
+  closing the pre-unification gap recorded under 0.3.0. The BEGIN/END markers
+  stay visible so a reviewer sees what was dropped; every body line between them
+  is replaced 1:1 with `[redacted: secret value]` (hunk line counts survive, so
+  a redacted patch still applies); an UNTERMINATED block fails closed, redacted
+  to end of input; a block never bleeds across `diff --git` headers or
+  hunk/metadata boundaries; and the inline patterns scan the key pass's output,
+  so a token sharing the END marker's physical line is still caught. Applies to
+  `redact`/`DiffRedactor` (key masks flow through the same staged
+  `masked_paths`/`inline_masks` accounting, including withhold dominance) and to
+  `redact_text`/`redact_tree`/`exc_summary`.
+- Five vendor patterns ported from the claude-in-codex bridge's local set:
+  GitHub fine-grained PAT (`github_pat_`), GitLab PAT (`glpat-`), Anthropic
+  key (`sk-ant-` — its hyphens put it out of the plain `sk-` run's reach, so
+  it is not a redundant specialization), npm automation token (`npm_`), and
+  PyPI upload token (`pypi-`). Unifying that bridge onto this engine without
+  them would have weakened its coverage; codex-in-claude and moonbridge gain
+  them outright.
+- `StreamRedactor` — a stateful line-stream redactor for callers that sanitize
+  output as it is produced (a worker scrubbing a child's stderr) and cannot
+  buffer the full sensitive stream: key-block state spans calls, and the
+  public writable `in_key_block` lets a caller that lost line fidelity
+  (overlong-line truncation) fail closed until an END marker arrives.
+- REMOVED the `-----BEGIN [A-Z ]*PRIVATE KEY-----` entry from
+  `SECRET_VALUE_PATTERNS`. It masked the BEGIN marker itself while shipping the
+  entire base64 body — a disclosure marker claiming coverage it did not have —
+  and its missing trailing alternation never matched PGP's "PRIVATE KEY BLOCK"
+  suffix at all. The stateful pass owns key material now; output for
+  key-bearing input changes accordingly (markers visible, body dropped).
+
+### 0.3.0 (protocol feedback from the three real adapters — still PROVISIONAL)
+
+- `RunOutcome.events` is now an OPAQUE raw payload string instead of parsed
+  event dicts. The Codex adapter showed that typed dicts forced eager parsing
+  upstream of the tolerance boundary — real normalize layers must parse
+  tolerantly so a malformed line degrades instead of raising. Its docs also now
+  state that a backend may use neither the events nor the artifacts channel
+  (the Claude adapter reads everything from the stdout envelope).
+- `BackendContract.effort_validation` (defaulted, non-breaking) declares how
+  pre-spend effort validation works: `enumerated` (Claude),
+  `token_floor_plus_catalog` (Kimi — universal token floor, catalog-relative
+  refinement, failing OPEN when the catalog cannot answer), or `shape_only`
+  (Codex — upstream rejects bad values loudly; only argv-hostile shapes are
+  refused locally).
+- Deferred to the freeze window, recorded from adapter findings: a shared seam
+  for the prompt-append schema-instruction text (currently duplicated in the
+  Kimi bridge under a byte-parity test), and classification's ambient
+  extra-args context.
+- `JobStore.start` (and `start_idempotent` via passthrough) accepts
+  `stdin_text`: streamed to the worker over a pipe by a daemon thread, never
+  persisted — the transport for bridges whose prompts must stay off disk and
+  off argv (the claude bridge's design). Default `None` keeps the prior
+  DEVNULL behavior byte-identical.
+- Known gap, discovered during the claude-in-codex context comparison:
+  `core.redaction` has NO multi-line PEM/OpenSSH/PGP key-block handling — a
+  private key pasted into a tracked file's diff (or returned in prose) is
+  scrubbed only if the inline value patterns happen to match. claude-in-codex's
+  local redactor handles these blocks statefully (failing closed on an
+  unterminated block); that handling must flow into `core.redaction` BEFORE any
+  bridge unifies onto the shared engine, or unification would weaken redaction.
+
+### 0.2.0 (milestone M1 — conventions + provisional protocol)
+
+- `pontonier.conventions.envelope`: shared error taxonomy — universal codes
+  (the verified intersection across the three bridges), backend-prefixed code
+  minting, feature-gated codes (`transfer`, `model_validation`,
+  `empty_response_detection`), and per-code `RepairRule` tables parameterized
+  by a `BackendErrorVocabulary`. Wire serialization deliberately stays
+  consumer-side.
+- `pontonier.conventions.prompts`: the shared framing/builders, with the host
+  harness name as a parameter; `framings("Claude Code")` reproduces the
+  source bridges' prose byte-for-byte (pinned by tests).
+- `pontonier.conventions.annotations`: tool-annotation builders parameterized
+  by declared effects (`AnnotationEffects`) instead of universal constants —
+  the bridges' differing values are deliberate positions, now explicit.
+- `pontonier.conventions.preflight`: `HelpProbe` (instance-cached `--help`
+  feature detection, fail-open) generalizing the per-repo module.
+- `pontonier.conventions.fingerprint`: the surface-digest / fingerprint-bump
+  invariant as reusable, framework-agnostic mechanics.
+- `pontonier.backend` (**PROVISIONAL**, `CONTRACT_API_VERSION = 0`):
+  `BackendContract` (static facts: flag classes, failure-signature tables,
+  field-scoped model-catalog authority, typed extra-args policy, isolation
+  policy, limits), the `AgentBackend` protocol as a staged lifecycle
+  (`validate_request` → `prepare` → `finalize`/`classify_failure`), shared
+  `RunRequest`/`PreparedRun`/`RunOutcome`/`ExecResult` types, and a shared
+  failure classifier with fixed precedence and a backend hook.
+- `pontonier.testing`: importable, framework-agnostic test kit —
+  surface-honesty phrase scanning, adapter/contract conformance checks
+  (including the mandatory pre-spend effort-validation invariant), and
+  sync/async pair parity. No pytest dependency.
+- Three fake adapters (Codex-like, Kimi-like, Claude-like) validate that the
+  provisional protocol expresses all three real invocation shapes.
+- Deviation from plan, documented: no `pydantic` dependency was added — the
+  backend/conventions layers are plain dataclasses, so the wheel still
+  depends only on `anyio`. The planned `testing` extra is unnecessary for the
+  same reason (the kit imports no test framework).
+
+### 0.1.0 (milestone M0 — core extraction)
+
+- `pontonier.core`: the CLI-agnostic machinery extracted from moonbridge's
+  `_core` (jobs, worktree, gitdiff, redaction, runtime, gitproc, streamcap,
+  idempotency, workspace, jsoncache), carrying the redaction
+  trailing-newline fix and the orphan-process sweep.
+- `WorktreeConfig`: worktree prefix, baseline-commit identity, and extra
+  exclude pathspecs are per-consumer fields with behavioral tests.
+- One-way dependency rule (`core` imports nothing from the rest) enforced by
+  import-linter in CI.

pontonier-0.5.0/LICENSE

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

pontonier-0.5.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: pontonier
+Version: 0.5.0
+Summary: Shared core library for agent-bridge MCP servers (codex-in-claude, moonbridge, claude-in-codex)
+Project-URL: Homepage, https://github.com/briandconnelly/pontonier
+Project-URL: Repository, https://github.com/briandconnelly/pontonier
+Project-URL: Issues, https://github.com/briandconnelly/pontonier/issues
+Author: Brian Connelly
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-bridge,claude-code,codex,jobs,kimi,mcp,worktree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4
+Description-Content-Type: text/markdown
+
+# pontonier
+
+Pontonier is the shared core library for agent-bridge MCP servers. An
+agent bridge lets one agent harness call an agent that runs on a
+different model. Three bridges use this library:
+
+- [codex-in-claude](https://github.com/briandconnelly/codex-in-claude) — Claude Code → Codex CLI
+- [moonbridge](https://github.com/briandconnelly/moonbridge) — Claude Code or Codex → Kimi CLI
+- [claude-in-codex](https://github.com/briandconnelly/claude-in-codex) — Codex → Claude Code CLI
+
+A pontonier is the engineer who builds pontoon bridges: pontonier is
+not itself a bridge — it is what the bridges are built from.
+
+## What is in the box
+
+`pontonier.core` — backend-agnostic machinery, extracted from the
+bridges' `_core` packages:
+
+| Module | Purpose |
+| --- | --- |
+| `jobs` | Disk-backed, daemonless async job store |
+| `worktree` | Throwaway git worktrees for delegated work |
+| `gitdiff` | Bounded, redacted git diff gathering |
+| `redaction` | Best-effort secret redaction for diffs and prose |
+| `runtime` | Subprocess execution with bounded streams and cleanup |
+| `gitproc` | Hardened git subprocess helpers |
+| `streamcap` | Bounded stream capture |
+| `idempotency` | On-disk idempotency-key index |
+| `workspace` | MCP-root workspace resolution |
+| `jsoncache` | Small JSON file cache |
+
+**Rule:** `pontonier.core` never imports from the rest of the package.
+CI enforces this with import-linter.
+
+`pontonier.conventions` — the shared vocabulary bridges are built from:
+error taxonomy + repair rules (`envelope`), host-parameterized prompt
+framing (`prompts`), effect-parameterized tool annotations
+(`annotations`), CLI `--help` feature detection (`preflight`), and the
+surface-fingerprint invariant (`fingerprint`). Wire serialization stays
+in each bridge.
+
+`pontonier.backend` — **FROZEN** (`CONTRACT_API_VERSION = 1`): the
+`BackendContract` static-facts dataclass, the `AgentBackend` staged run
+lifecycle (`validate_request` → `prepare` → `finalize`/`classify_failure`),
+and a shared failure classifier with fixed precedence. Required Protocol
+members and required `BackendContract` fields are stable within a minor
+line; because additive changes to a Protocol or a frozen dataclass are
+breaking, new behavior lands as optional capability protocols or
+defaulted fields.
+
+`pontonier.testing` — importable, framework-agnostic test kit: surface
+honesty (forbidden-phrase scanning against the built wire), adapter and
+contract conformance, and sync/async tool-pair parity. Checks return
+violation lists; wire them into any harness.
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync
+uv run pytest
+uv run ruff check
+uv run lint-imports
+```