plan-auditor 2.1.0__tar.gz → 2.2.0__tar.gz

{plan_auditor-2.1.0 → plan_auditor-2.2.0}/.gitignore

@@ -1,11 +1,21 @@
 __pycache__/
 *.pyc
 .pytest_cache/
+build/
+dist/
+*.egg-info/
 .plan-auditor/evidence.jsonl
+.plan-auditor/evidence.head.json
+.plan-auditor/evidence.write.lock
+.plan-auditor/audit.freeze.lock
+.plan-auditor/request.json
+.plan-auditor/activation.json
+.plan-auditor/integrity.json
 .plan-auditor/*.tmp
 .plan-auditor/archive/
 .plan-auditor/snapshots/
 .plan-auditor/seal.json
+.plan-auditor/seals/
 .plan-auditor/supervisor-runtime.json
 .plan-auditor/supervisor-assessment.json
 .plan-auditor/supervisor.stop

{plan_auditor-2.1.0 → plan_auditor-2.2.0}/CHANGELOG.md

@@ -1,15 +1,34 @@
+## Unreleased
+
+- None yet.
+
 # Changelog
 
+## v2.2.0 — 2026-09-05
+
+- **Physical control-plane confinement:** existing `.plan-auditor`, plan, seal, request/activation and policy path components are inspected with `lstat`; symlinked parents/leaves cannot redefine the workspace trust root.
+- **Policy read confinement:** `load_config` authorizes only symlink-free workspace policy directories before policy loading; a resolved external symlink target is rejected before its files are read.
+- **Sealed scope freeze:** automatic monotonic strengthening remains available for extra deterministic checks/prerequisites, but new steps, requirements, tools, coverage assignments or declared outputs now require a new host-approved request generation.
+- **Safe v3→v4 migration:** `plan-auditor-migrate-seal` provides a representation-only migration path for exact full-contract v3 seals. It requires authoritative request alignment and refuses any plan-scope change.
+- **Seal self-consistency:** v3/v4 seals validate their contract hash and criteria count on load/save before being trusted or authenticated.
+- **Streaming evidence verification:** JSONL verification, hashing and HMAC migration retain one record/chunk at a time instead of reading complete evidence/archive files into RAM.
+- **PID-aware registry locking:** registry transaction locks carry PID + random token; live owners are never evicted because of age alone, and stale cleanup requires a provably dead PID plus unchanged lock identity.
+- **Activation semantics:** a lone `.plan-auditor/supervisor.json`, log or cache no longer makes a plans-free workspace look like an activated failed task; request/seal/evidence/plan/integrity/registry state still prevents deletion from degrading to `NO_PLAN`.
+- **Single audit freeze implementation:** the unused `workspace.audit.lock` implementation was removed; `audit.freeze.lock`/`final_audit_session` remains the sole workspace final-audit freeze path.
+- **Version identity:** source/package version advances to `2.2.0`, preventing post-v2.1.0 hardening from producing a different wheel under the already-published `2.1.0` version.
+- **Trust-boundary documentation:** deliberate same-OS-user interference is explicitly treated as an OS isolation problem; separate account/container/VM deployment is required when that attacker is in scope.
+- **Regression coverage:** new tests cover plan/policy symlink escapes, scope expansion, config-only activation, PID-aware registry locks, streaming evidence verification and exact legacy-seal migration.
+
 ## v2.1.0 — 2026-09-05
 
 - **Aggregate multi-plan completion:** the integrated supervisor now enumerates the default plan and every safe `.plan-auditor/plans/<name>.json` plan. Global PASS requires every active plan to PASS; a passing default plan cannot hide an unfinished named plan, and a named-only workspace is no longer misclassified as `NO_PLAN`.
 - **Explicit requirement coverage:** Supervisor Mode requires explicit requirements and deterministic `covers` links from steps. Every `must`/`should` requirement must be covered; omitted user requirements, unknown coverage IDs and duplicate requirement contracts block plan approval/PASS.
-- **Full-contract format-v3 seals:** seals now bind task, requirements, required tools, step identity/order/title, requirement coverage, dependencies, required outputs, output contracts/checks, step checks, and the supervisor profile/mode/tier/policy fingerprint. Existing criteria may only be strengthened.
-- **Authenticated seals:** external-key HMAC integrity now authenticates plan seals in addition to evidence, checkpoints, registry state and the integrity marker. Seal tampering or missing/wrong key material fails closed after integrity initialization.
+- **Full-contract format-v3 seals:** seals bind task, requirements, required tools, step identity/order/title, requirement coverage, dependencies, required outputs, output contracts/checks, step checks, and the supervisor profile/mode/tier/policy fingerprint. Existing criteria may only be strengthened.
+- **Authenticated seals:** external-key HMAC integrity authenticates plan seals in addition to evidence, checkpoints, registry state and the integrity marker. Seal tampering or missing/wrong key material fails closed after integrity initialization.
 - **Configuration/policy downgrade prevention:** malformed supervisor configuration and configured policy files are explicit blocking errors. Profile/mode/tier and policy-file fingerprint are part of the sealed environment contract, so a post-seal downgrade is detected.
 - **Evidence concurrency and rotation continuity:** evidence append/rotation uses a cross-process exclusive lock, active evidence links the latest archive tail, and failed-attempt limits are counted across archived plus active evidence instead of resetting after rotation.
-- **Complete evidence verification:** `plan-auditor evidence verify` now checks both active evidence and anchored archives.
-- **Safe plan addressing:** named plan IDs are validated as safe basenames and cannot traverse outside `.plan-auditor/plans`.
+- **Complete evidence verification:** `plan-auditor evidence verify` checks both active evidence and anchored archives.
+- **Safe plan addressing:** named plan IDs are validated as safe basenames and cannot use lexical `..` traversal outside `.plan-auditor/plans`.
 - **Canonical multi-agent ownership:** agent IDs are safe basenames and ownership paths are canonical workspace-relative paths before conflict comparison, preventing alternate spellings from evading `parallel-strict` overlap detection.
 - **Transactional full-scope rollback:** default snapshots carry a manifest with file type, mode and hash; rollback restores that state and removes files introduced after the snapshot. Explicit snapshot lists remain intentionally scoped.
 - **Stronger fresh-audit fingerprint:** workspace fingerprints include directories, file type and mode/executable bits in addition to contents and symlink targets.
@@ -20,7 +39,7 @@
 - **Three-platform packaging and release gates:** real wheels are built and installed in clean virtual environments on Ubuntu, Windows and macOS. Smoke tests exercise multi-plan discovery, DAG/output dependencies, requirement coverage, full-contract seals, external-key HMAC, integrated audit, doctor, and evidence/integrity CLI paths. PyPI publishing waits for the same three-platform wheel preflight.
 - **Versioning:** development version advanced to `2.1.0` so the hardened source cannot be confused with the already-published `2.0.2` artifact.
 - **Regression hardening:** dedicated failure-injection tests cover named-plan bypasses, seal-contract weakening, environment downgrade, HMAC seal tampering, invalid config/policies, path traversal, evidence races/rotation/retry history, active-log tampering, rollback cleanup, executable-bit fingerprint changes, canonical agent conflicts, missing tools and bounded verifier output.
-- **Observational final audit:** a full audit now fails if a verifier mutates product workspace content, type, or mode. Verification must prove pre-existing implementation state rather than creating the claimed result during the audit itself.
+- **Observational final audit:** a full audit fails if a verifier mutates product workspace content, type, or mode. Verification must prove pre-existing implementation state rather than creating the claimed result during the audit itself.
 
 ## v2.0.2 — 2026-09-05
 

{plan_auditor-2.1.0 → plan_auditor-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plan-auditor
-Version: 2.1.0
+Version: 2.2.0
 Summary: Independent multi-layer verification supervisor for AI coding agents
 Project-URL: Homepage, https://github.com/Furox-Art/plan-auditor
 Project-URL: Repository, https://github.com/Furox-Art/plan-auditor

plan_auditor-2.2.0/docs/deployment-isolation.md

@@ -0,0 +1,59 @@
+# Deployment isolation for a deliberately malicious agent
+
+Plan Auditor's normal mode assumes the AI agent may be wrong or overconfident but
+does not have an OS security boundary from the deterministic supervisor. If the
+agent process itself is deliberately malicious, a same-user Python lock/HMAC
+setup is not a sufficient root of trust: the process can ignore cooperative lock
+files and may be able to read same-user key material.
+
+## Required boundary
+
+For that threat model, run the verifier under a different OS/container identity:
+
+1. **Supervisor identity** owns the external HMAC key and Plan Auditor control
+   state. The agent identity must not be able to read the key.
+2. **Agent identity** gets only the repository/product write permissions needed
+   for implementation. It must not be able to modify the supervisor executable,
+   key file, service configuration or host approval source.
+3. The supervisor receives read access to product state plus the narrowly scoped
+   writes required for `.plan-auditor` evidence/seals/registry.
+4. Host request activation is performed by the trusted/user side, not by the
+   untrusted agent identity.
+5. The final audit runs after cooperating agent processes are quiescent. For a
+   hostile agent, the OS/container boundary—not `audit.freeze.lock`—prevents
+   concurrent mutation of trusted control state.
+
+## Linux example boundary
+
+A typical layout uses two users, for example `pa-agent` and `pa-supervisor`.
+Keep the HMAC key in a file readable only by `pa-supervisor` and start the
+supervisor service with:
+
+```text
+PLAN_AUDITOR_HMAC_KEY_FILE=/var/lib/plan-auditor/keys/project.key
+```
+
+The key file should not be inside the workspace. Use normal filesystem ACLs,
+service sandboxing or a container mount policy so `pa-agent` cannot read it.
+
+## Container/VM boundary
+
+For stronger isolation, place the deterministic supervisor in a separate
+container/VM. Mount product state read-only for the final audit when practical,
+and mount only the Plan Auditor control-state directory writable by the
+supervisor. Do not share the HMAC secret with the agent container.
+
+## Windows boundary
+
+Use a distinct Windows account/service identity for the supervisor and ACL the
+key file so the agent account cannot read it. The same principle applies: a
+process running under the same account is not considered isolated merely because
+it is a different PID.
+
+## What this changes
+
+This deployment boundary upgrades the external-HMAC/freeze controls from
+workspace tamper detection to a meaningful adversarial boundary. Without it, the
+project intentionally makes the narrower claim documented in `threat-model.md`:
+it detects buggy/overconfident agent behavior and workspace tampering within the
+stated same-user trust assumptions; it is not a kernel sandbox.

{plan_auditor-2.1.0 → plan_auditor-2.2.0}/docs/threat-model.md

@@ -13,8 +13,9 @@ normal installation both processes may run as the same OS user. Plan Auditor is
 
 For the normal “buggy/overconfident agent” threat model, deterministic evidence,
 full-contract sealing, requirement coverage and fail-closed aggregation are the
-main controls. Separate OS users/containers are optional defense-in-depth for a
-deliberately malicious process with the same credentials.
+main controls. A deliberately malicious process with the same OS credentials is a
+different trust boundary: use a separate OS account/container/VM and keep the HMAC
+key inaccessible to the untrusted account when that adversary is in scope.
 
 ## Trust model
 
@@ -25,7 +26,7 @@ deliberately malicious process with the same credentials.
 | Repository/product files | untrusted until checked |
 | Plan requirements and verification contract | trusted only after full-contract seal |
 | Verification commands/build scripts | executable code; results are evidence, not inherently trustworthy semantics |
-| User configuration/policies | trusted intent, but syntax is validated fail-closed |
+| User configuration/policies | trusted intent, but syntax and physical path confinement are validated fail-closed |
 | External HMAC key | trusted only while inaccessible to an untrusted forger |
 
 ## Main failure/attack classes
@@ -35,13 +36,14 @@ deliberately malicious process with the same credentials.
 3. AI skips a prerequisite or consumes an unverified intermediate result.
 4. AI marks a step `verified` without real evidence.
 5. AI weakens checks/dependencies/coverage after approval.
-6. A named plan is left unfinished while a default plan passes.
-7. Evidence is edited, truncated, reordered, or races under concurrent writers.
-8. A verification command is unsafe or produces pathological output.
-9. Configuration/policies are malformed or downgraded after sealing.
-10. Multi-agent file ownership uses alternate path spellings to evade conflicts.
-11. Package behavior differs across Linux/Windows/macOS.
-12. A malicious same-user process directly interferes with supervisor state/key material.
+6. AI expands approved scope by adding steps/requirements/tools/outputs after sealing.
+7. A named plan is left unfinished while a default plan passes.
+8. Evidence is edited, truncated, reordered, raced under concurrent writers, or made pathologically large.
+9. A verification command is unsafe or produces pathological output.
+10. Configuration/policies are malformed, symlinked outside workspace, or downgraded after sealing.
+11. Multi-agent file ownership uses alternate path spellings or stale-lock eviction to evade coordination.
+12. Package behavior differs across Linux/Windows/macOS.
+13. A malicious same-user process directly interferes with supervisor state/key material.
 
 ## Controls
 
@@ -51,14 +53,19 @@ deliberately malicious process with the same credentials.
 | Hidden named plan | Integrated gate enumerates default + every safe named plan; global PASS requires ALL active plans PASS |
 | Skipped prerequisite | DAG validation, topological full audit, `depends_on`, concrete `outputs` and `requires_outputs` rechecks |
 | Fake `status=verified` | Status alone is never fresh-audit proof; final gate matches current checks/graph/output evidence and workspace fingerprint |
-| Criteria weakening | Format-v3 seal binds task, requirements, tools, step order/title, coverage, DAG, outputs and all verification checks |
-| Config/policy downgrade | Seal binds profile/mode/tier/policy fingerprint; malformed config/policy files are blocking errors |
+| Criteria weakening | Format-v4 seal binds task, requirements, tools, step identity/order/title, coverage, effective DAG, outputs, verification checks and supervisor/request environment |
+| Scope expansion | Existing sealed step/requirement/tool/coverage/output scope is frozen; only proof-strengthening checks/prerequisites may be added automatically |
+| Legacy seal migration | `plan-auditor-migrate-seal` migrates only an exact v3 contract after authoritative-request alignment; migration cannot reseal changed scope |
+| Config/policy downgrade | Seal binds profile/mode/tier/runtime limits/policy/request fingerprints; malformed config/policy files are blocking errors |
+| Control-plane symlink escape | Existing `.plan-auditor`, plan, seal, request and policy path components are checked with `lstat`; symlinked control-plane roots/leaves are rejected before read/write |
 | Command injection | Structured `argv` preferred; shell disabled by default; `shell:true` is explicit opt-in and cannot combine with `argv` |
-| Path traversal | Workspace paths are realpath-confined; named plan IDs and agent IDs are safe basenames |
+| Path traversal | Workspace paths are physically confined; named plan IDs and agent IDs are safe basenames |
 | Agent path aliases | Ownership paths are canonical workspace-relative paths before conflict comparison |
+| Registry lock theft | Registry write locks carry PID + random token; live writers are never evicted by age alone and stale removal requires a provably dead PID plus unchanged lock identity |
 | Evidence concurrent writes | Cross-process evidence write lock serializes append/rotation |
+| Evidence memory exhaustion | Evidence chain verification, hashing and HMAC migration stream records/files rather than loading whole JSONL files into RAM |
 | Evidence history rewrite | SHA-256 `prev` chain spans rotations; active log links latest archive tail |
-| Tail truncation / forged state | Optional external-key HMAC signs records, heads/checkpoints, registry state, integrity marker and plan seals |
+| Tail truncation / forged state | Optional external-key HMAC signs records, heads/checkpoints, registry state, integrity marker, request activation and plan seals |
 | Retry-cap reset by rotation | Failed attempts are counted across archived and active evidence |
 | Rollback leftovers | Full-workspace snapshots contain a manifest; rollback restores state and prunes introduced files within full scope |
 | File-mode drift | Workspace fingerprint includes type and POSIX mode as well as content/symlink target |
@@ -93,9 +100,18 @@ plan-auditor integrity init .
 plan-auditor audit .
 ```
 
+For an old full-contract v3 workspace, perform the representation-only migration
+before the final v4 audit:
+
+```bash
+plan-auditor-migrate-seal .
+plan-auditor audit .
+```
+
 Initialization validates existing hash chains before authenticating them, signs
-all active plan seals, evidence/archive records and checkpoints, and agent-registry
-records/head. The signed integrity marker is written last.
+all active plan seals, evidence/archive records and checkpoints, request/activation
+metadata, and agent-registry records/head. The signed integrity marker is written
+last.
 
 Once initialized, missing/wrong key material, HMAC mismatch, seal tampering, tail
 truncation or marker loss fails closed.
@@ -104,9 +120,13 @@ truncation or marker loss fails closed.
 
 HMAC protects against workspace-only rewriting **only while the attacker cannot
 obtain the key**. A same-user process that can read the environment/key file can
-compute valid HMACs. That limitation is explicit; use OS-level credential/process
-separation only when the deployment threat model requires protection against a
-deliberately malicious same-user process.
+compute valid HMACs and can ignore cooperative freeze files. No Python lock can
+create a security boundary against a process with the same OS credentials.
+
+When deliberate same-user interference is in scope, the root control is deployment
+isolation: run the deterministic supervisor under a distinct OS identity or in a
+separate container/VM, give the untrusted agent write access only to the intended
+workspace/product surface, and expose the HMAC key only to the supervisor identity.
 
 ## Fail-closed terminology
 
@@ -114,9 +134,7 @@ The project does not claim “unbreakable”, “immutable”, or “perfectly s
 uses these narrower guarantees:
 
 - **deterministic evidence** — real reproducible checks rather than agent prose,
-- **full-contract seal** — approved criteria cannot be weakened without detection,
-- **tamper-evident/authenticated state** — modifications are detected within the
-  stated key/trust boundary,
+- **full-contract seal** — approved criteria and scope cannot be weakened/expanded without detection/host approval,
+- **tamper-evident/authenticated state** — modifications are detected within the stated key/trust boundary,
 - **aggregate multi-plan gate** — all active plans participate in completion,
-- **fail-closed** — invalid/unknown critical state resolves to FAIL/UNKNOWN rather
-  than PASS.
+- **fail-closed** — invalid/unknown critical state resolves to FAIL/UNKNOWN rather than PASS.

{plan_auditor-2.1.0 → plan_auditor-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plan-auditor"
-version = "2.1.0"
+version = "2.2.0"
 description = "Independent multi-layer verification supervisor for AI coding agents"
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,7 @@ dependencies = []
 
 [project.scripts]
 plan-auditor = "supervisor.cli:entrypoint"
+plan-auditor-migrate-seal = "supervisor.seal_migration:main"
 
 [project.urls]
 Homepage = "https://github.com/Furox-Art/plan-auditor"