Compare commits

...
10 Commits
Author SHA1 Message Date
UnixNight 31ae6a6ab2 docs(01-05): record primary review and retain consumed handoff 2026-11-13 11:48:20 -05:00
UnixNight 1af5217e47 docs(01-05): advance verified checkpoint plan tracking 2026-11-13 11:46:26 -05:00
UnixNight 2d48ee5316 docs(01-05): complete offline Windows checkpoint plan 2026-11-13 11:45:36 -05:00
UnixNight aa4b862a12 fix(01-05): retain executable permissions in offline copies
Preserve source read/write/execute bits without privileged mode bits. Verify copied Linux apphost byte identity and permissions.
2026-11-13 11:43:51 -05:00
UnixNight 857466568d feat(01-05): complete offline Windows collection agenda and selftests
Prepare all session materials, explicit terminal outcomes and raw-media provenance while retaining open acceptance. Verify the package-free collector on synthetic fixtures without redistributing external tools.
2026-11-13 11:36:47 -05:00
UnixNight c9b9f2eba9 feat(workflow): checkpoint GSD before five-hour quota exhaustion 2026-11-13 11:24:53 -05:00
UnixNight 73954e675d docs(handoff): preserve quota-interrupted Windows bundle task 2026-11-13 11:07:44 -05:00
UnixNight 818191c90c test(01-05): require complete Windows session materials and open results 2026-11-12 23:48:52 -05:00
UnixNight 61123394e0 feat(01-05): assemble identified offline Windows checkpoint 2026-11-12 23:48:03 -05:00
UnixNight 446930d2a3 test(01-05): specify immutable offline checkpoint round trip 2026-11-12 23:40:08 -05:00
21 changed files with 2439 additions and 11 deletions

No files matched your search

+65
View File
@@ -0,0 +1,65 @@
{
"description": "GamePort quota guard: stop new workers at 20%; checkpoint and pause at 15%.",
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"PreModelRequest": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
],
"PostToolUse": [
{
"hooks": [
{
"type": "command",
"command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/tools/workflow/codex_quota_guard.py\" hook",
"timeout": 5,
"commandWindows": "cmd /c exit 0"
}
]
}
]
}
}
+35
View File
@@ -0,0 +1,35 @@
{
"version": "1.0",
"timestamp": "2026-11-13T16:07:37.872347+00:00",
"phase": "01",
"phase_name": "Reproducible Fidelity Baseline",
"phase_dir": ".planning/phases/01-reproducible-fidelity-baseline",
"plan": 5,
"task": 2,
"total_tasks": 2,
"status": "consumed",
"completed_tasks": [
{
"id": 1,
"name": "Identified offline checkpoint tracer",
"status": "done",
"commit": "6112339"
},
{
"id": 2,
"name": "Complete Windows materials/collection/selftests",
"status": "done",
"commit": "8574665",
"correction": "aa4b862"
}
],
"remaining_tasks": [],
"blockers": [],
"async_jobs": [],
"human_actions_pending": [],
"uncommitted_files": [
"?? tools.yaml"
],
"next_action": "Plan 01-05 complete and reviewed. Continue plan 01-06 task 1, then plan 01-07; do not resume completed 01-05 task 2.",
"context_notes": "Quota interruption after server-restart recovery. Plans01-01..04 complete, primary-reviewed and pushed through de68796. Currentplan01-05 task1 RED446930d/GREEN6112339; task2 RED818191c. No01-05SUMMARY. Preserve partial uncommitted edits to scripts/collect-fidelity-windows.ps1 and tools/recon/fidelity_checkpoint.py; preserve unrelated tools.yaml. Do not restart task1 or treatREDcommit as completion. Inspect actual gitdiff before continuation.\nExisting generated packages artifacts/fidelity/01-05-packages/{linux-x64,win-x64} and tracerbundle artifacts/fidelity/01-05-tracer-checkpoint exist; inspect manifests/logs rather than rebuilding blindly. Task2 REDreproduced23tests with missing-session-materials assertion/statusAPI error. Cached local PowerShell executable .tools/powershell-check/root/opt/microsoft/powershell/7/pwsh and cacheddeb found; no successful execution/provenance was reported before quota. No third-party installers redistributed. Need finish task2Windowsagenda/selftests/complete truthfulresults, verify, writeSUMMARY andhandlerstate; then primaryreview/push. All120actualoriginal-DxWnd/nativeLinux/nativeWindowsacceptanceOPEN. Plans01-06Linuxcapture/01-07combinedhands-onreadiness+acceptance remain.\nSequential nativeexecutors because worktreebasecheckcannotresolveorigin/HEAD (repoGitea/main). Maincommits authorized;git.allow_default_branch_commits=true. Local sockettests/Node runner needescalation to actuallyexecute namedtests. Fullwave2scripts/test.sh authorizedpasses462Python+2HUD/allmanaged/36GPUzeroerrorsGTX1070/539hashes; observer23managed+7process/privateXvfb4onoffidentical. No newWindowsororiginalcomparison.\nUser asked howtoresumeandautomatelow5husagepause. Researched officialCodexaccount/rateLimits/read plusaccount/rateLimits/updated andPreToolUse/PostToolUsehooks; no guardconfigured. OnlySessionStarthook currentlyconfigured;statuslinealreadyfive-hour-limit. Do not claimautopauseinstalled. Need customwatcher/hook before it canbeautomatic. No activeworkersknown;recover_01_05 returnedquotaerror, do notimmediatelyredispatchwhilequotaexhausted. Resumewhenuserrequestsafterlimitreset; inspectactualremainingquota ratherthanstale10:28PMreset. No sourcefeatureworkwasdonebyprimaryforthisquestion.\n\n2026-11-13 quota-guard setup: tools/workflow/codex_quota_guard.py and .codex/hooks.json implement local Linux 60-second actual 300-minute quota polling; <=20% denies new worker dispatch, <=15% independent recovery snapshot plus cooperative GSD pause request. The watcher is running and live quota read works. Five project hooks are discovered but require user /hooks trust before registration/tool blocking activate. See docs/codex-quota-guard.md. No feature tasks resumed or partial collector edits committed during this setup. After reset/user resume, continue plan 01-05 task 2 from this original handoff.\n\nConsumed after successful continuation: SUMMARY2d48ee5/tracking1af5217. Primary repeats24 checkpoint and17 PowerShell checks successfully. Both full bundle preflights passed. Retained for preservation after auto-review rejected deletion. New current position is01-06 task1; old quota blocker is resolved.\n"
}
+3 -3
View File
@@ -39,7 +39,7 @@ Integer phases are planned work; decimal phases may be inserted for urgent recov
2. A tester can reproduce identified whole-original reference scenarios from an isolated generated installation and inspect corresponding input/events, images and audio where applicable; unavailable execution keeps this criterion open. 2. A tester can reproduce identified whole-original reference scenarios from an isolated generated installation and inspect corresponding input/events, images and audio where applicable; unavailable execution keeps this criterion open.
3. A reviewer can trace every full-game capability from original evidence through current implementation, platform receipts, discrepancies and its remaining acceptance condition. 3. A reviewer can trace every full-game capability from original evidence through current implementation, platform receipts, discrepancies and its remaining acceptance condition.
4. Testers can repeat the same baseline movement/route scenarios on native Linux and native Windows with exact revision identities; Wine/cross-publish receipts remain separately labeled and cannot close missing native execution. 4. Testers can repeat the same baseline movement/route scenarios on native Linux and native Windows with exact revision identities; Wine/cross-publish receipts remain separately labeled and cannot close missing native execution.
**Plans:** 4/7 plans executed **Plans:** 5/7 plans executed
**Wave 1** **Wave 1**
- [x] 01-01-PLAN.md - [x] 01-01-PLAN.md
@@ -49,7 +49,7 @@ Integer phases are planned work; decimal phases may be inserted for urgent recov
- [x] 01-04-PLAN.md - [x] 01-04-PLAN.md
**Wave 3** *(blocked on Wave 2 completion)* **Wave 3** *(blocked on Wave 2 completion)*
- [ ] 01-05-PLAN.md - [x] 01-05-PLAN.md
**Wave 4** *(blocked on Wave 3 completion)* **Wave 4** *(blocked on Wave 3 completion)*
- [ ] 01-06-PLAN.md - [ ] 01-06-PLAN.md
@@ -151,7 +151,7 @@ Execution follows 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8, subject to the ex
| Phase | Plans Complete | Status | Completed | | Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------| |-------|----------------|--------|-----------|
| 1. Reproducible Fidelity Baseline | 4/7 | In Progress | - | | 1. Reproducible Fidelity Baseline | 5/7 | In Progress | - |
| 2. Faithful Movement and Scene Handoffs | 0/TBD | Not started | - | | 2. Faithful Movement and Scene Handoffs | 0/TBD | Not started | - |
| 3. Original Actors, Hazards and Combat | 0/TBD | Not started | - | | 3. Original Actors, Hazards and Combat | 0/TBD | Not started | - |
| 4. Complete Gadget and Vehicle Use | 0/TBD | Not started | - | | 4. Complete Gadget and Vehicle Use | 0/TBD | Not started | - |
+10 -7
View File
@@ -3,16 +3,16 @@ gsd_state_version: "1.0"
current_phase: 01 current_phase: 01
current_phase_name: Reproducible Fidelity Baseline current_phase_name: Reproducible Fidelity Baseline
status: executing status: executing
stopped_at: Completed 01-04-PLAN.md; primary continues phase1 stopped_at: Completed 01-05-PLAN.md
last_updated: "2026-11-13T04:23:09.969Z" last_updated: "2026-11-13T16:45:57.021Z"
last_activity: 2026-11-12 last_activity: 2026-11-12
last_activity_desc: Phase 01 execution started last_activity_desc: Phase 01 execution started
state_head: 85e533b6293e8573abe41738e467c79c721b012a state_head: 2d48ee5316a727e510db54910c59bc0a79e18e6f
progress: progress:
total_phases: 8 total_phases: 8
completed_phases: 0 completed_phases: 0
total_plans: 7 total_plans: 7
completed_plans: 4 completed_plans: 5
percent: 0 percent: 0
--- ---
@@ -28,7 +28,7 @@ See: .planning/PROJECT.md (updated 2026-11-12)
## Current Position ## Current Position
Phase: 01 (Reproducible Fidelity Baseline) — EXECUTING Phase: 01 (Reproducible Fidelity Baseline) — EXECUTING
Plan: 5 of 7 Plan: 6 of 7
Status: Ready to execute Status: Ready to execute
Last activity: 2026-11-12 — Phase 01 execution started Last activity: 2026-11-12 — Phase 01 execution started
@@ -53,6 +53,7 @@ Recent trend: No execution plans completed in this roadmap. Existing project wor
| Phase 01 P02 | 16 min | 2 tasks | 6 files | | Phase 01 P02 | 16 min | 2 tasks | 6 files |
| Phase 01 P03 | 22 min | 2 tasks | 4 files | | Phase 01 P03 | 22 min | 2 tasks | 4 files |
| Phase 01 P04 | 16 min | 2 tasks | 5 files | | Phase 01 P04 | 16 min | 2 tasks | 5 files |
| Phase 01 P05 | 12h 4min | 2 tasks | 7 files |
## Accumulated Context ## Accumulated Context
@@ -72,6 +73,8 @@ Recent trend: No execution plans completed in this roadmap. Existing project wor
- [Phase 01]: One outer observer owns a unique launch/clock identity through Run continuations; simulation ticks remain scene-local and case/session IDs remain declared provenance. - [Phase 01]: One outer observer owns a unique launch/clock identity through Run continuations; simulation ticks remain scene-local and case/session IDs remain declared provenance.
- [Phase 01]: Accepted input means the existing binding's returned gate result, with separately identified post-step ownership; individual command dispatch and independent body/fire work are not inferred. - [Phase 01]: Accepted input means the existing binding's returned gate result, with separately identified post-step ownership; individual command dispatch and independent body/fire work are not inferred.
- [Phase 01]: Observer records are diagnostic source material for later collectors, not receipts or automatic original/native acceptance; fixture classification survives continuations. - [Phase 01]: Observer records are diagnostic source material for later collectors, not receipts or automatic original/native acceptance; fixture classification survives continuations.
- [Phase 01]: READY validates identified offline materials only; original-DxWnd/native Linux/native Windows acceptance remains open 0/120.
- [Phase 01]: Runtime package provenance retains actual completed publish source/dirty/diff identity; selected external tools are identified without redistributing executables.
### Pending Todos ### Pending Todos
@@ -98,6 +101,6 @@ No original-required category deferred outside full reconstruction. Later phases
## Session Continuity ## Session Continuity
Last session: 2026-11-13T04:23:09.938Z Last session: 2026-11-13T16:45:56.992Z
Stopped at: Completed 01-04-PLAN.md; primary continues phase1 Stopped at: Completed 01-05-PLAN.md
Resume file: None Resume file: None
@@ -0,0 +1,37 @@
---
context: phase
phase: 01-reproducible-fidelity-baseline
plan: "05"
task: 2
total_tasks: 2
status: consumed
last_updated: "2026-11-13T16:07:37.872347+00:00"
---
# Consumed quota-interrupted checkpoint
Plan01-05 is now complete and primary-reviewed (SUMMARY2d48ee5, tracking1af5217).
Continue01-06 task1; do not repeat the historical interrupted task below.
Quota watcher is installed/running; hook trust remains separate.
Quota interruption after server-restart recovery. Plans01-01..04 complete, primary-reviewed and pushed through de68796. Currentplan01-05 task1 RED446930d/GREEN6112339; task2 RED818191c. No01-05SUMMARY. Preserve partial uncommitted edits to scripts/collect-fidelity-windows.ps1 and tools/recon/fidelity_checkpoint.py; preserve unrelated tools.yaml. Do not restart task1 or treatREDcommit as completion. Inspect actual gitdiff before continuation.
Existing generated packages artifacts/fidelity/01-05-packages/{linux-x64,win-x64} and tracerbundle artifacts/fidelity/01-05-tracer-checkpoint exist; inspect manifests/logs rather than rebuilding blindly. Task2 REDreproduced23tests with missing-session-materials assertion/statusAPI error. Cached local PowerShell executable .tools/powershell-check/root/opt/microsoft/powershell/7/pwsh and cacheddeb found; no successful execution/provenance was reported before quota. No third-party installers redistributed. Need finish task2Windowsagenda/selftests/complete truthfulresults, verify, writeSUMMARY andhandlerstate; then primaryreview/push. All120actualoriginal-DxWnd/nativeLinux/nativeWindowsacceptanceOPEN. Plans01-06Linuxcapture/01-07combinedhands-onreadiness+acceptance remain.
Sequential nativeexecutors because worktreebasecheckcannotresolveorigin/HEAD (repoGitea/main). Maincommits authorized;git.allow_default_branch_commits=true. Local sockettests/Node runner needescalation to actuallyexecute namedtests. Fullwave2scripts/test.sh authorizedpasses462Python+2HUD/allmanaged/36GPUzeroerrorsGTX1070/539hashes; observer23managed+7process/privateXvfb4onoffidentical. No newWindowsororiginalcomparison.
User asked howtoresumeandautomatelow5husagepause. Researched officialCodexaccount/rateLimits/read plusaccount/rateLimits/updated andPreToolUse/PostToolUsehooks; no guardconfigured. OnlySessionStarthook currentlyconfigured;statuslinealreadyfive-hour-limit. Do not claimautopauseinstalled. Need customwatcher/hook before it canbeautomatic. No activeworkersknown;recover_01_05 returnedquotaerror, do notimmediatelyredispatchwhilequotaexhausted. Resumewhenuserrequestsafterlimitreset; inspectactualremainingquota ratherthanstale10:28PMreset. No sourcefeatureworkwasdonebyprimaryforthisquestion.
## Required Reading
AGENTS.md; ../AGENTS.md; ../prompt.MD;01-CONTEXT.md;01-05-PLAN.md;01-01..04-SUMMARY.md; actualcheckpoint/PowerShell source/tests and gitdiff.
## Critical Anti-Patterns
| Pattern | Description | Severity | Prevention Mechanism |
|---|---|---|---|
| Duplicate partialplan | Existing taskcommits withoutSUMMARY | advisory | Reconcile git/history/diff; resume task2, never reruntask1 |
| False nativeacceptance | Preparedbundle/PowerShellonLinux isnotWindowsgameplay | advisory | Retain actualplatform/method and pendingoriginal/nativeacceptance |
## Infrastructure State
No liveexecutor reported afterrestart; lastrecoverexecutorreturnedquotaerror. Generatedpackages/cachedPowerShellremainlocal. No externalasyncjobs known.
## Next Action
Afterquotareset resume01-05task2; finishmaterials/selftests before01-06/07. Userhasnotconfiguredautomaticquota-pausing.
@@ -0,0 +1,166 @@
---
phase: 01-reproducible-fidelity-baseline
plan: "05"
subsystem: testing
tags: [offline, powershell, windows, fidelity, sha256]
requires:
- phase: 01-02
provides: Offline paired review viewer
- phase: 01-03
provides: Capability ledger and identified source links
- phase: 01-04
provides: Passive port observation and package flags
provides:
- Immutable offline checkpoint with identified original and Linux/Windows packages
- Complete eighty-obligation Windows agenda with separate original-DxWnd and native-port collection
- Package-free PowerShell selftests and truthful terminal/media results
affects: [01-06, 01-07]
tech-stack:
added: []
patterns: [exclusive allocation, bounded hashing, atomic publication, explicit open acceptance, inert argument provenance]
key-files:
created:
- tools/recon/fidelity_checkpoint.py
- scripts/prepare-fidelity-checkpoint.sh
- scripts/collect-fidelity-windows.ps1
- scripts/collect-fidelity-windows.cmd
- tests/test_fidelity_checkpoint.py
- tests/fidelity-windows.Tests.ps1
- docs/evidence/windows-session.md
modified: []
key-decisions:
- "READY validates immutable prepared materials only; actual original-DxWnd/native Linux/native Windows acceptance remains open 0/120."
- "Runtime package source/dirty/diff identity stays bound to its actual completed publish, separately from later collector and document commits."
- "Selected external tools are identified without redistributing executables; raw MKV, terminal failures and actual derivation provenance remain local."
requirements-completed: [EVID-01, EVID-02, EVID-04]
requirements-acceptance: "OPEN: assigned preparation contributions are complete; shared requirement IDs remain Pending until unfinished sibling capture/review plans and actual acceptance gates close."
coverage:
- id: offline-checkpoint
description: Identified complete offline bundle, preservation and tamper checks
requirement: EVID-01
verification:
- kind: integration
ref: tests/test_fidelity_checkpoint.py
status: pass
- kind: other
ref: artifacts/fidelity/verification/01-05-complete-bundle.json
status: pass
human_judgment: false
- id: collection-tooling
description: Package-free collector identity/path/argument/process/result functions on synthetic fixtures
requirement: EVID-02
verification:
- kind: integration
ref: tests/fidelity-windows.Tests.ps1
status: pass
human_judgment: false
- id: combined-session-materials
description: Eighty Windows obligations, session instructions and settings/annotation templates are bundled
requirement: EVID-04
verification:
- kind: integration
ref: tests/test_fidelity_checkpoint.py#test_complete_session_materials_and_eighty_windows_obligations
status: pass
human_judgment: false
- id: actual-original-native-acceptance
description: Actual original-DxWnd/native Windows execution, audiovisual preflight and full scenario review
verification: []
human_judgment: true
rationale: "Linux-hosted synthetic PowerShell tests, prepared bytes and apphost help do not establish Windows gameplay, actual browser/audio playback or whole-original fidelity; plan 01-07 owns the combined session."
actuals:
tokens: 21862
tasks: 2
commits: 7
basis: "ceil(chars/4) over the realized seven-file production/test/document diff: 87448 characters. Measured ledger range includes five plan task commits plus the intervening primary handoff and quota-guard commits; no invented task-commit count."
plan_head_before: de68796df15acaacbc7df1ae5701acac770680ce
plan_head_after: aa4b862a123112085660ee14fc0e2bccb251ddfa
duration: 12h 4min
started: 2026-11-13T04:40:08Z
completed: 2026-11-13
status: complete
---
# Phase 01 Plan 05: Offline Windows Checkpoint Summary
**An identified 10,983-file offline checkpoint carries preserved originals, both actual port packages, review/protocol materials and a complete Windows original-DxWnd/native-port collection agenda with open acceptance.**
## Performance
- Two tasks, seven production/test/document files. The recorded wall interval starts at the earliest task RED commit, 04:40:08 UTC, and includes the long quota interruption before task 2 resumed. It is not twelve hours of active execution.
- Final targeted verification: **24 Python checkpoint tests**, **17 actual Linux-hosted PowerShell checks**, four PowerShell-produced synthetic receipts validated by the shared Python validator, shell syntax and **539 unchanged original files**.
- The broader fidelity regression passed **133 tests in 123.784 seconds** with authorized local loopback/process access before the final mode-only correction; the affected checkpoint suite then passed all 24 tests in 4.742 seconds. No skipped tests are represented as passes.
- Actual full-bundle Python and Linux-hosted PowerShell preflights both pass, checking 10,983 immutable entries. The PowerShell traversal took several CPU-active minutes and completed before its explicit 600-second supervisory bound. It did not wait for interactive input.
## Accomplishments and Interfaces
- `fidelity_checkpoint.py` seals actual completed publishes, prepares a fresh offline tree and preflights immutable file identities. Existing outputs, overlaps, aliases, tampering, stale DLLs, interrupted/concurrent assembly and missing dependencies are rejected with local diagnostics. The generated original seed is verified before copying and again against its authoritative inventory. Hashes stream; assembly uses an exclusive reservation and retains incomplete diagnostics on failure.
- The bundle contains `manifest.json`, `READY.json`, `original-pristine/`, `original-runs/`, `port/linux-x64/`, `port/win-x64/`, `review/`, `protocol/`, `results/`, both collector launchers, the session guide and standalone PowerShell selftests. Protocol materials include scenarios, capabilities, original inventory, an **80-obligation Windows agenda** and explicit pending settings/annotation templates. Empty/false fields require actual observations during the later session; they are not fabricated identities or implementation stubs.
- `collect-fidelity-windows.ps1` supports `Preflight`, `Run`, `Retained`, `Finish`, `Skip` and `Abort`. Native port and original-DxWnd receipts keep distinct categories. It identifies actual selected external tools without copying third-party executables/installers, preserves the user's profile plus generated original pre/post state, uses quoted direct process invocation and records honest exit/log information. No original is executed in place, no command from a receipt is evaluated, and no dependency is downloaded.
- Raw MKV and actual audio evidence are required to finalize captured results. Derived artifacts retain source/output references, actual tool/version/argv/time/crop metadata and explicit browser-playback declaration. Synthetic promotion, terminal-outcome promotion, reused results and invalid references are rejected. Failed/skipped/aborted results remain available for collection without inventing successful media. All collector outputs retain open acceptance and require the shared validator and later human review.
- `windows-session.md` gives one ordered agenda: local selections/provenance, package-free checks, separate original/port visual/audio preflights, all eight matrix cells and five obligations, paired browser/exclusive-audio review, collection/postflight, then one local return transfer with hash checks. It recommends offline OBS Display Capture initially while requiring actual selected settings. It does not request capture now.
## Task Commits
1. Task 1 RED: `446930d` — specify immutable offline checkpoint round trip.
2. Task 1 GREEN: `6112339` — assemble identified offline Windows checkpoint.
3. Task 2 RED: `818191c` — require complete Windows session materials and open results.
4. Task 2 GREEN: `8574665` — complete offline Windows collection agenda and selftests.
5. Task 2 correctness follow-up: `aa4b862` — retain executable permissions in offline copies.
Task 1 was already complete and was not repeated during recovery. The partially edited collector and checkpoint module were preserved and completed. Normal Git hooks ran with explicit scoped staging, protected-branch configuration and the supplied-root guard; no tracked files were deleted. Unrelated `tools.yaml`, the primary's quota tooling commit `c9b9f2e` and its ownership were preserved. The primary owns review, integration reports and push.
## Actual Offline Bundle and Package Identities
Fresh final bundle: `artifacts/fidelity/01-05-session-checkpoint`. Durable identity/audit evidence: `artifacts/fidelity/verification/01-05-complete-bundle.json`.
| Material | SHA-256 |
|---|---|
| manifest.json, 2,689,788 bytes | `1098cf07030d5acf71b37d2132ec8bf39360855e9f7b2203cd130c9a7ac011be` |
| READY.json, 358 bytes | `1bb81a44da9f5ce92d5549f1608fcc6f46a47e2010d5160b39dcb471d1e8cccd` |
| Original 539-file canonical tree | `419af98a75a9f1d4ae3eceb5c7807bc9634912c2c3918c308470ad798dcef181` |
| Linux sealed package file-list hash | `124cf271e4952f3822eec5c24358447fcffc9e9e1803aded8d96d4d4472dc5a3` |
| Windows sealed package file-list hash | `335e5b75ec15c0fa904113d8b69d4f50e2cfa403f1f2f225353bd9e586322ef4` |
| Linux GamePort.dll, 734208 bytes | `145de80f2628f836cd77f0e8f66cb1b9d5abb8445088ff8ba8eb82527b6cd150` |
| Windows GamePort.dll, 734208 bytes | `d21c917c1d260f3cd2c5b3d19397ab78ae23108c90b4f393eba4904d80e512a1` |
Both packages already existed under `artifacts/fidelity/01-05-packages`; recovery did not rebuild them. Their actual BUILD-INFO identifies source `446930d2a30d6d616c60ac5e59e4169a840bea09`, **dirty yes**, diff SHA-256 `90cef95669caece53fe2d2c4736cf2ac05ed27f5d25ca03ab572589686bcb73d`. Publish timestamps are 2026-11-13T04:45:41.527524+00:00 and 04:47:05.457630+00:00 respectively. Neither the resumed collector revision nor the later clean task commit is stamped over that runtime provenance. Historical `dist/` packages remain unchanged.
The final copied Linux apphost was permission-repaired from its byte-identical package source to mode 0755, then actually ran `--help` successfully. The generator now preserves ordinary source permissions for future copies while dropping privileged mode bits. That permission-only repair changes no manifest/file byte identity. Apphost help establishes startup/CLI availability only, not gameplay, sound, GPU or platform acceptance.
## Verification Commands and Scope
```sh
python3 -c 'import sys,unittest; s=unittest.defaultTestLoader.discover("tests",pattern="test_fidelity_checkpoint.py"); assert s.countTestCases() >= 16; sys.exit(not unittest.TextTestRunner(verbosity=2).run(s).wasSuccessful())'
bash -n scripts/prepare-fidelity-checkpoint.sh
python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
python3 tools/recon/fidelity_checkpoint.py preflight --checkpoint artifacts/fidelity/01-05-session-checkpoint
```
The cached `.tools/powershell-check/root/opt/microsoft/powershell/7/pwsh` is usable with `XDG_CACHE_HOME`, `XDG_CONFIG_HOME` and `XDG_DATA_HOME` set to task-local `/tmp/gameport-pwsh-*` directories. Its default home cache is read-only in the sandbox. No install/download was performed. Actual commands used that executable with `-NoProfile -File tests/fidelity-windows.Tests.ps1 -FixtureOutput /tmp/gameport-01-05-ps-results` and separately `-NoProfile -File scripts/collect-fidelity-windows.ps1 -Action Preflight -Bundle artifacts/fidelity/01-05-session-checkpoint`.
The 17 selftests exercise IDs/paths, hashes/copy identity, arrays/write-once JSON, argument quoting, an actual child with spaced arguments and exit 7, stdout/stderr, timeout/start failure, categories/terminal outcomes, manifest tampering and finish links. Their four captured/failed/skipped/aborted receipts all validate structurally through `fidelity_receipts.validate_receipt`; **all four remain synthetic and unaccepted**. Linux PowerShell is not Windows PowerShell 5.1 execution evidence. The exact native Windows selftest command is included in the future combined agenda.
## TDD Gate Compliance
Both retained RED reports, `artifacts/fidelity/tdd/01-05-01-red.json` and `01-05-02-red.json`, return `RED_EVIDENCE_OK` through the current classifier. Task 1's named target executes its intended missing preparation-API assertion. Task 2's named target completes assembly then fails the planned missing-session-material assertion; its separate missing status-API error remains honestly recorded. Both RED commits precede their GREEN commits by ancestry. No separate refactor was needed. Final targeted tests pass.
## Deviations from Plan
1. **[Rule 1 — collector correctness]** Real PowerShell execution exposed top-level empty arrays serializing incorrectly and asynchronous .NET completion values leaking into the process-result pipeline. `Write-FidelityJson` now uses `ConvertTo-Json -InputObject`; asynchronous completions are suppressed, output closure is bounded and final log size is checked. Standalone serialization/process/terminal tests pass; `8574665`.
2. **[Rule 2 — runnable offline copy]** Final bundle inspection found that byte-only copying dropped Linux apphost execution permission. The generator now preserves ordinary source mode bits, and a regression checks both mode and bytes. The generated apphost was repaired from its verified source and ran help; `aa4b862`. No source/package bytes or gameplay algorithms changed.
No new trust surface beyond the plan's selected-process/local-filesystem boundaries was introduced. The supplied threat mitigations remain applicable: no eval/elevation/downloads, explicit local selections, contained paths, hashes, immutable result IDs and categories that cannot imply acceptance. No implementation stub or skipped mandatory automated verification remains; actual Windows/human checks are intentionally assigned to the later combined session.
## Issues Encountered
Quota interruption required a specific task-2 recovery from the existing RED commit and partial edits. An accidentally duplicated slow preparation was stopped; its incomplete directory and reservation remain under `.01-05-complete-checkpoint*` as diagnostics, and the final assembly uses a new root. No lock was stolen or failed partial tree promoted. The sandboxed broader regression denied loopback sockets and timed out .NET setup; its authorized local rerun passed all 133 tests. The optional full PowerShell preflight was CPU-active and bounded, then passed. No unresolved test failure is hidden by these environment adaptations.
## Next Phase Readiness
The full bundle and session tooling are prepared. Plan 01-06 still owns actual native Linux capture, and plan 01-07 owns the combined original-DxWnd/native Windows session and audiovisual review. The real scenario audit is structurally ready with **accepted 0 / required 120**, all eight cases missing and no invalid receipts. Original launch/profile validity, native Windows execution, real browser playback/audio/crop and full-route fidelity remain open. This plan makes no new original-binary, REA, Wine, native Windows gameplay or whole-original compatibility claim.
Shared EVID-01/EVID-02/EVID-04 IDs remain Pending because `requirements.ready-ids` returns no ready IDs while sibling plans are unfinished. Root progress/tasks/decisions/compatibility integration and consumed-handoff cleanup belong to the primary.
## Self-Check: PASSED
All seven created files exist. All five plan task commits are reachable on this branch, and evaluation-scope resolves the recorded plan commits. Final counted checkpoint/PowerShell checks, shared receipt validation, both full-bundle preflights, shell syntax, Linux apphost help and 539 original hashes pass. The persisted ledger measures seven commits before summary metadata, including the two intervening primary commits explained above. No generated package/media/original is staged, no tracked deletion occurred, and unrelated `tools.yaml` is preserved.
+1 -1
View File
@@ -49,5 +49,5 @@
"label": "Advance to the next step", "label": "Advance to the next step",
"reason": "Phase 1 of 8 · 0% · executing" "reason": "Phase 1 of 8 · 0% · executing"
}, },
"updated_at": "2026-11-13T04:23:08.932Z" "updated_at": "2026-11-13T16:45:56.190Z"
} }
+81
View File
@@ -0,0 +1,81 @@
# Codex quota guard
This repository has a local Linux watcher and project hooks for the user's
requested GSD quota policy. The watcher polls the existing Codex app-server every
60 seconds; it does not start model turns or read credentials. It uses the
300-minute account window and its actual reset timestamp, preferring the general
`codex` bucket over specialty-model buckets.
- At **20% remaining or less**, `PreToolUse` denies new `Agent`, `spawn_agent`,
and `followup_task` calls. Existing workers may finish their safe checkpoint.
- At **15% remaining or less**, the watcher saves a separate recovery snapshot
and sends each registered active turn one request to checkpoint with
`$gsd-pause-work` and end. Tool hooks also supply that instruction once per turn.
- Missing, expired, or older-than-180-second quota data blocks new worker dispatch
until a fresh reading arrives. Checkpoint tools remain available.
- The watcher never starts a turn, interrupts a process, commits unfinished work,
pushes code, or automatically resumes after reset.
## One-time activation
The source is `tools/workflow/codex_quota_guard.py`; project configuration is
`.codex/hooks.json`. Existing global GSD hooks are preserved and additive.
Open **`/hooks`** in Codex, review and trust the five hooks from this project's
`.codex/hooks.json`. New definitions remain skipped until reviewed; see the
[official hook trust instructions](https://learn.chatgpt.com/docs/hooks#review-and-trust-hooks).
The watcher has been started for this host, but thread registration and tool
blocking require trusted hooks. A later session's `SessionStart` hook starts
another watcher only if one is not already running.
The guard targets this Linux Codex host, not the Windows original-game test
machine. Windows uses a no-op command override. It does not restart Codex or
change provider/model/account settings.
## Commands
From the repository root:
```sh
python3 tools/workflow/codex_quota_guard.py status
python3 tools/workflow/codex_quota_guard.py refresh
python3 tools/workflow/codex_quota_guard.py start
python3 tools/workflow/codex_quota_guard.py stop
```
`status` includes the lock-verified `running` flag, current reading, reset epoch,
and any last poll error type. `refresh` uses the existing local daemon socket and
may need execution outside the agent sandbox. It neither starts a daemon nor a
model turn. `stop` requests termination within a second after any in-flight RPC
finishes; hooks start the watcher again, so disable the project hooks in `/hooks`
when turning the guard off permanently. `start` clears the stop marker when its
singleton watcher starts. No service or cron entry is installed.
After quota resets, send **`$gsd-resume-work`**. The current saved continuation is
phase 01, plan 01-05, task 2; preserve its partial edits and do not repeat task 1.
Resumption remains a user action even after the account has recovered.
## Recovery and limits
Ignored private state is under `artifacts/gsd-quota/`. `quota.json` stores only
counters/timestamps. Per-thread registration stores thread/turn identifiers, not
conversation contents. At low quota, `recovery-<reset>/record.json` saves the Git
HEAD, status, tracked patch (capped at 2 MiB), and existing GSD state/handoff text
(capped at 256 KiB each). It supplements and never replaces the canonical GSD
handoff. Untracked file contents remain in the working tree; this is not a full
backup. Source changes after that one-per-window snapshot rely on the working
tree and the model's final handoff. Files are private to the local account.
The pause is **cooperative**. Polling may lag usage by a minute, a long active
model request may consume the reserve, and no model can guarantee writing a
handoff after the provider exhausts quota. The independent recovery record still
runs without model tokens. Tool hooks cover supported local tool paths; launching
workers through unrelated shell scripts or other clients bypasses this specific
dispatch policy. Weekly and specialty-model limits are not guarded. Inactive or
mismatched turns are never restarted by the watcher.
Verified against local Codex 0.169.0: real Unix WebSocket quota read, project hook
discovery (five hooks awaiting trust), singleton background watcher, and 24 targeted
unit tests. Simulated low-quota tests verify pause steering and snapshot behavior;
no real quota depletion or active gameplay work was induced to test the threshold.
See the [official app-server protocol](https://learn.chatgpt.com/docs/app-server)
and [hook contracts](https://learn.chatgpt.com/docs/hooks).
+16
View File
@@ -1,5 +1,21 @@
# Compatibility and validation # Compatibility and validation
## Phase 1 plan 01-05 — reviewed tooling evidence
24 checkpoint tests and17 actual PowerShell selftests pass in primary review;
executor records133 broader fidelity checks,539 unchanged originals, and both
Python/PowerShell preflights of the10,983-file offline bundle. Linux copied-apphost
--help passes after executable mode preservation. Actual Windows gameplay,
original-DxWnd comparison and full runtime acceptance remain0/120 OPEN.
## Workflow quota guard — 2026-11-13
Local Codex0.169.0 Linux Unix-WebSocket quota read and watcher verified; five
project hooks discovered, awaiting user trust. Targeted simulated quota, policy,
transport and recovery tests pass. Real exhaustion/active-turn pause is not
induced; pause remains cooperative. Windows hook override is a no-op. No game
build, package or original/native Windows acceptance claim changes.
## Phase 1 wave 2 bounded observer evidence ## Phase 1 wave 2 bounded observer evidence
Full authorized wave2 `scripts/test.sh` exits0:462 Python+2 HUD checks, Full authorized wave2 `scripts/test.sh` exits0:462 Python+2 HUD checks,
+16
View File
@@ -1,5 +1,21 @@
# Decisions # Decisions
## Offline checkpoint review — phase 1 plan 01-05
Keep prepared-material readiness separate from runtime acceptance. Identify
external tools without copying their executables; preserve raw media and terminal
results. Retain source executable modes when copying local Linux packages; byte
hashes alone do not establish runnable apphost permissions. Windows collection
selftests on Linux establish tooling behavior only.
## Quota reserve — 2026-11-13
Use actual300-minute account quota and server reset time. Reserve20% for
existing workers and15% for handoff. Poll locally without model turns; preserve
a private independent recovery snapshot and request cooperative GSD pause.
Never auto-resume, commit partial source, restart Codex, or bypass hook trust.
See [guard contract](codex-quota-guard.md).
## Passive evidence observation — phase 1 wave 2 ## Passive evidence observation — phase 1 wave 2
Keep one optional application-owned clock across Run continuations. Record raw, Keep one optional application-owned clock across Run continuations. Record raw,
+204
View File
@@ -0,0 +1,204 @@
# One combined local Windows fidelity session
This is the prepared agenda for plan 01-07, not a request to capture now.
`READY.json` means immutable materials are prepared. It never means original,
native Windows, browser, audio or scenario acceptance passed. Linux PowerShell
selftests, cross-publish, Wine and synthetic media cannot fill those slots.
Keep every package, original copy, raw recording and result on local storage.
The checkpoint contains `manifest.json`, `READY.json`, both identified
`port/{linux-x64,win-x64}` packages, `original-pristine/`, writable
`original-runs/`, `protocol/`, offline `review/`, collectors, these instructions,
package-free selftests and `results/`. No SDK or Python is needed on Windows.
The manifest records actual package BUILD-INFO and sealed source identities;
the later bundle revision does not replace the runtime's source identity.
Do not alter immutable materials to make a preflight pass. Mutable results and
generated run copies stay outside that immutable hash set.
## Ordered session agenda
1. **Select local dependencies and capture provenance.** Transfer the entire
prepared checkpoint to a fresh local directory, preferably a short path with
sufficient recording space. Select the actual Windows PC, DxWnd executable,
original exported DxWnd profile, recorder, browser and any media-probe/
derivation executables already installed locally. No download, installer
redistribution, elevation or guessed DxWnd switches are part of this bundle.
Copy `protocol/settings-template.json` into `results/session-settings.json`
and fill observed values. Record each tool's actual local source, version,
SHA-256, settings/export and limitations, Windows build, GPU/driver, Vulkan
and SDL versions as actually available; missing identities remain pending.
The collector hashes selected external tool executables without copying them
into returned results. Retain settings/profile exports, not installers.
Initial recorder recommendation: **offline OBS Display Capture**, with the
actual monitor, capture source, crop/aspect, resolution/frame rate, encoder,
audio device/mix and MKV container recorded. Record notification/desktop
exposure and wrapper timing/rendering limitations in the local notes.
2. **Run immutable preflight and package-free selftests.** From the checkpoint
directory run the following exact commands. Require exit zero, at least eight
executed checks and zero failures; preserve the output in local session notes.
A missing PowerShell or dependency is a failure to record, not a silent pass.
```powershell
powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Preflight
powershell.exe -NoProfile -File .\tests\fidelity-windows.Tests.ps1
```
PowerShell 5.1 is the Windows target; a `pwsh` run on Linux exercises tooling
only. Executables are launched directly with quoted arguments, never from
receipt-supplied commands. Keep script execution subject to the PC's existing
policy; record a policy failure rather than changing security policy here.
3. **Perform separate short original and native-port visual/audio preflights.**
Use new diagnostic IDs for each. Inspect the selected DxWnd distribution's
own local help/config. Import the user's retained exported profile and change
only executable/working-directory paths to the generated copy printed by the
collector; export that relocated profile to the result's artifacts directory.
Do not force timer, renderer or compatibility settings or guess profile syntax.
If automation is unsupported, use the transparent DxWnd GUI launch. Retain
original and relocated exports and describe exact changes. The collector opens
DxWnd with no assumed switches and does not infer the original child's exit.
Never select the authoritative installation or `original-pristine/` as target.
Play each raw preflight: require **visible moving game content, intelligible
game audio, correct crop and aspect**, rather than merely detected ffprobe
streams. Record failures before proceeding. Keep diagnostic runs separate
from required cases. Native port launch uses the existing NewGame.tsk story
entry; absence of a reconstructed menu remains an explicit comparison gap.
4. **Record all matrix cells and obligations.** Use `protocol/agenda.json` as
the checklist: 8 cells × 5 obligations × 2 Windows sides = **80 Windows
obligations**. The separate Linux side contributes 40; all **120** remain
subject to actual receipt validation and human review. The table below and
`protocol/scenarios.json` specify the matrix, actual route, required events
and end conditions. Each fresh run has a new launch ID and original copy.
For retained runs, record prerequisite lab departure to VR04 and return in
the same process/clock before the tested interval; do not relaunch or reset
state. Capture the retained generated-copy identity during that lifetime
with `-Action Retained`, preserving the original pre-copy identity. Start the
recorder before interaction, retain the entire raw MKV and audible tail,
then finalize the specific scope after the process ends. Follow each cell's
natural/skip and ordinary/held-input procedure through its focused setup.
5. **Review paired browser video and exclusive audio.** Open `review/index.html`
using the selected local browser. Return results are imported into a fresh
local review export for pairing; the initially empty viewer does not invent
captures. Preserve actual speed and separate raw clocks, annotate offsets,
playback drift, crop and uncertainty. Listen to only one source at a time.
Require actual browser playback/seeking/audio checks for every preview codec.
A codec name, probe success or file extension is insufficient. Retain raw MKV
even if the browser cannot decode it. If a preview or extracted WAV is needed,
use a selected existing local tool and retain exact executable/version/hash,
inert argv, UTC derivation time, raw/output identities, timestamp mapping and
crop/aspect changes. Never silently retime or discard the source. Record
unsupported codecs or inaudible/missing content as open failures.
6. **Collect, postflight and audit.** Finish each run with actual annotations,
recording files, observer logs, settings, DxWnd exports and limitations.
Include missed, skipped, aborted, crashed and incomplete runs. A process exit
or `captured` means collection only. Original-DxWnd provenance is separate
from native port receipts. Preserve generated originals and their post-run
changes, `copy-pre.json`, `retained-copy.json` where applicable and
`copy-post.json`; never restore them over the authoritative originals.
Re-run immutable preflight after collection and preserve output. Actual
review verdicts and shared schema/matrix validation remain separate gates.
7. **Return once using local transfer.** Copy the complete checkpoint (including
raw recordings, results and original-runs) by USB/local filesystem or existing
local share to a new return directory. Do not upload assets/packages/media.
Recheck manifest/READY SHA-256 and all immutable entries, then rehash all
receipt-linked artifacts on return using the shared Python receipt validator.
Preserve a source-side file/hash inventory for the mutable result and
original-runs trees and compare it with the returned copy before importing.
A mismatch or missing file is an explicit transfer failure. Do not overwrite
the source copy, canonical originals, historical packages or an earlier return.
## Matrix and required procedures
| Case ID | Lifetime | Carl dialogue | Physical input policy |
|---|---|---|---|
| fresh-natural-edge | Independent fresh launch | Natural completion | Held through dialogue/RETURN |
| fresh-natural-ordinary | Independent fresh launch | Natural completion | Ordinary play/release |
| fresh-skipped-edge | Independent fresh launch | Actual supported skip | Held through dialogue/RETURN |
| fresh-skipped-ordinary | Independent fresh launch | Actual supported skip | Ordinary play/release |
| retained-natural-edge | Observed departure/return, same lifetime | Natural completion | Held through dialogue/RETURN |
| retained-natural-ordinary | Observed departure/return, same lifetime | Natural completion | Ordinary play/release |
| retained-skipped-edge | Observed departure/return, same lifetime | Actual supported skip | Held through dialogue/RETURN |
| retained-skipped-ordinary | Observed departure/return, same lifetime | Actual supported skip | Ordinary play/release |
Every cell requires separate `continuous`, `dialogue-return`, `bank-left`,
`bank-right` and `landing-idle` obligations on both original-DxWnd and native
Windows port. Continuous means ordinary **lab → VR04 → lab → outside** in one
uninterrupted recording and process, including Carl dialogue, first neutral
input, both banked jumps/landings, gadget use, RETURN cleanup and outside arrival.
Focused clips retain their actual setup/prerequisite recording. A direct scene,
debug warp or injected fixture cannot replace the route or retained prerequisite.
Record keys, skip action and held/released boundaries as actually performed.
Preserve legitimate landing bank and the implemented TSK lifetime ordering;
do not insert a leveling reset or tune movement for the recording.
## Collector commands and failure results
Replace paths and IDs with actual selections. Commands are examples for the
later combined session; use a fresh unique ID for each independent launch.
Start external recording when prompted and keep the collector alive for the
entire retained setup and tested interval. The recorder/browser are identified,
not automatically driven. The `.cmd` wrapper is an optional equivalent entry.
```powershell
powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Run -Mode port -SessionId port-fresh-natural-ordinary-continuous-01 -CaseId fresh-natural-ordinary -Scope continuous -RecorderPath 'C:\Tools\OBS\bin\64bit\obs64.exe' -BrowserPath 'C:\Tools\Browser\browser.exe' -SettingsPath '.\results\session-settings.json'
powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Run -Mode original -SessionId original-retained-natural-edge-bank-left-01 -CaseId retained-natural-edge -Scope bank-left -DxWndPath 'C:\Tools\DxWnd\dxwnd.exe' -ProfilePath 'C:\Local\exported.dxw' -RecorderPath 'C:\Tools\OBS\bin\64bit\obs64.exe' -BrowserPath 'C:\Tools\Browser\browser.exe' -SettingsPath '.\results\session-settings.json'
powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Retained -SessionId original-retained-natural-edge-bank-left-01
powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Finish -SessionId port-fresh-natural-ordinary-continuous-01 -AnnotationPath '.\results\port-notes.json' -ArtifactsDirectory 'D:\LocalCaptures\port-run-01'
powershell.exe -NoProfile -File .\scripts\collect-fidelity-windows.ps1 -Action Skip -Mode original -SessionId original-missed-01 -CaseId fresh-skipped-edge -Scope bank-left -Reason 'Actual reason this obligation could not run'
```
`Skip`/`Abort` create a new terminal result without requiring recorder/browser
selection. An interrupted active run retains its initial `incomplete.json`;
when safe, collect its artifacts with `Finish -Outcome aborted -Reason '...'`
instead of pretending a separate aborted launch describes its lifetime.
Failed starts preserve `run.json`, `failure.json` and available logs. To collect
failed/skipped/aborted media use `Finish -Outcome failed|skipped|aborted` matching
the prior status, a reason and annotation/artifact directories (empty arrays are
allowed for these outcomes). Never promote a failed or terminal run to captured;
use a new independent session for a retry. Existing evidence is write-once.
## Annotation field contract
Copy `protocol/annotation-template.json` to a mutable result note and fill it
with actual values. Empty templates cannot finalize capture. All paths are
relative, case-unique and contained below `ArtifactsDirectory`; no commands are
read from annotations. Every captured run retains a raw `.mkv` video and actual
audio evidence. If raw audio is embedded, retain a separately named byte-identical
MKV copy with role `audio`, or a proven extracted WAV with derivation provenance.
This preserves unique artifact paths while binding the actual audio bytes.
- `artifacts`: entries `{path, role, duration_seconds}`; roles include `video`,
`audio`, `input_events`, `prerequisite`, `diagnostic`. Preserve raw and preview
as separate entries. Original prerequisite recordings/copy-state records and
port `observer/events.jsonl`, summary, stdout/stderr must be included as
appropriate; do not rename synthetic fixtures as native evidence.
- `events`: `{name, artifact, media_seconds, elapsed_seconds, method,
uncertainty_seconds}` using the exact required names/order in scenarios.json.
Original methods are `manual` or `procedural`; markers describe visible input
and event intervals, never invented original simulation ticks. Port events
map observer data to actual media clocks; `simulation_tick` remains separate.
Preserve observer `launch_id`, `clock_id`, requested/accepted input distinctions,
sequence and possible truncation/overhead. Never reset elapsed clocks at scenes.
All times are finite, nonnegative and within actual recording/run duration.
- `derivatives`: `{path, source, tool, version, argv, created_utc,
timestamp_mapping, crop_aspect, browser_playback_verified}`. The collector
stores argv as inert provenance; it does not execute it. Select true browser
playback only after observed playback. Hash tool binaries and retain source
identity/settings in local session notes, including whether crop/time changed.
- `continuity`: `lifetime_id` equals session ID, `prerequisite_artifact` names a
hashed artifact, `copy_pre_sha256` binds the actual copy-state record. Retained
additionally needs `departure_session_id` and `return_session_id` equal to that
same session ID and `retained_copy_sha256` identifying the retained snapshot.
`prerequisite_departure` and `prerequisite_return` markers precede the tested
interval on the prerequisite artifact. Include these state records as hashed
identities/artifacts, never made-up placeholders. The port's actual package/
startup-state record must be identified separately; missing continuity remains
open rather than treating a second fresh launch as retained.
- `diagnostic`: true for observation overhead, preflight, fixtures or other
diagnostic limitations; `limitations`: actual missing tools, crop/audio/render/
timer/wrapper differences, incomplete transitions, uncertain markers and review
failures. A successful collector does not clear them or acceptance automatically.
`Finish` prefixes local media/event/derivative references with `media/` and hashes
copied bytes. It never accepts an annotation-supplied acceptance verdict. The
shared receipt validator and later full matrix/human review decide applicability.
No universal timing, pixel, angle or audio tolerance is asserted by this agenda.
+21
View File
@@ -1,5 +1,26 @@
# Progress — 2026-11-07 # Progress — 2026-11-07
## Phase 1 plan 01-05 — reviewed completion
Offline Windows checkpoint preparation is complete:10,983 identified immutable
files, both full-bundle preflights pass,24 checkpoint Python tests and17 real
Linux-hosted PowerShell checks pass. Primary repeats both targeted suites. The
executor also records133 broader fidelity regressions and539 unchanged originals.
The copied Linux apphost retains executable permissions and runs --help. Generated
bundle: `artifacts/fidelity/01-05-session-checkpoint`; exact identities are in
`artifacts/fidelity/verification/01-05-complete-bundle.json` and the01-05SUMMARY.
Phase1 has5/7 plans complete; Linux capture preparation is next. Actual runtime
acceptance remains0/120 OPEN. No Windows gameplay or original comparison claimed.
## Local quota guard — 2026-11-13
Installed Linux quota watcher and five project hooks; real local account quota
read succeeds, watcher runs, and targeted policy/recovery tests pass. Hook trust
remains a user `/hooks` action. At20% remaining new workers are denied; at15%
remaining recovery is saved and registered active turns receive a cooperative
GSD pause request. See [setup and limits](codex-quota-guard.md). Phase01-05 task2
partial edits remain untouched; no gameplay or acceptance status changed.
## Phase 1 wave 2 — review, ledger and passive observation ## Phase 1 wave 2 — review, ledger and passive observation
Full authorized wave2 `scripts/test.sh` exits0:462 Python+2 HUD checks, Full authorized wave2 `scripts/test.sh` exits0:462 Python+2 HUD checks,
+13
View File
@@ -1,5 +1,18 @@
# Tasks # Tasks
## Phase 1 plan 01-05 — reviewed completion
- [x] Complete offline Windows/DxWnd collection materials and synthetic selftests.
- [x] Verify both10,983-file bundle preflights,24 Python/17 PowerShell checks.
- [ ]01-06 Linux capture preparation, then01-07 combined-session readiness/audit.
- [ ]Actual original/native acceptance0/120 OPEN.
## Quota-aware GSD continuation — 2026-11-13
- [x] Install/test local60-second quota watcher,20% dispatch gate,15% pause request.
- [ ] User review/trust the five project quota hooks via `/hooks`.
- [ ] Resume `$gsd-resume-work` when desired; retain01-05 task2 partial edits.
## Phase 1 execution — wave 2 ## Phase 1 execution — wave 2
- [x]01-02 paired local review:21 Python/27 Node checks and real Chromium - [x]01-02 paired local review:21 Python/27 Node checks and real Chromium
+5
View File
@@ -0,0 +1,5 @@
@echo off
setlocal
rem Argument selection happens in PowerShell; never run commands from receipts.
powershell.exe -NoLogo -NoProfile -File "%~dp0collect-fidelity-windows.ps1" %*
exit /b %ERRORLEVEL%
+424
View File
@@ -0,0 +1,424 @@
# Windows PowerShell 5.1 compatible. No SDK/Python, elevation, downloads or eval.
[CmdletBinding()]
param(
[ValidateSet('Preflight','Run','Finish','Skip','Abort','Retained')][string]$Action = 'Preflight',
[ValidateSet('port','original')][string]$Mode = 'port',
[string]$Bundle = (Split-Path -Parent $PSScriptRoot),
[string]$SessionId, [string]$CaseId = 'fresh-natural-ordinary',
[ValidateSet('continuous','dialogue-return','bank-left','bank-right','landing-idle')][string]$Scope = 'continuous',
[string]$DxWndPath, [string]$ProfilePath, [string]$RecorderPath,
[string]$BrowserPath, [string]$SettingsPath, [string]$AnnotationPath,
[string]$ArtifactsDirectory, [string]$Reason,
[ValidateSet('captured','failed','skipped','aborted')][string]$Outcome = 'captured',
[ValidateRange(1,14400)][int]$TimeoutSeconds = 7200,
[switch]$LibraryOnly
)
Set-StrictMode -Version 2
$ErrorActionPreference = 'Stop'
$script:CollectorSource = $PSCommandPath
function Test-FidelityId([string]$Value) {
if ($Value -cnotmatch '^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$' -or
$Value -match '^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.|$)') { throw 'Invalid stable ID' }
return $Value
}
function Get-FidelityPath([string]$Root, [string]$Relative) {
if (-not $Relative -or $Relative.Length -gt 4096 -or $Relative -match '[\\:<>"|?*\x00-\x1f]' -or
$Relative.StartsWith('/') -or $Relative -match '(^|/)(\.{1,2}|)(/|$)') { throw "Unsafe relative path: $Relative" }
foreach ($part in $Relative.Split('/')) {
if ($part.EndsWith(' ') -or $part.EndsWith('.') -or
$part -match '^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.|$)') { throw 'Unsafe Windows alias' }
}
$base = [IO.Path]::GetFullPath($Root).TrimEnd([IO.Path]::DirectorySeparatorChar)
$path = [IO.Path]::GetFullPath((Join-Path $base $Relative))
if (-not $path.StartsWith($base + [IO.Path]::DirectorySeparatorChar, [StringComparison]::OrdinalIgnoreCase)) {
throw 'Path escapes checkpoint'
}
$cursor = $path
while ($cursor) {
if (Test-Path -LiteralPath $cursor) {
if (((Get-Item -LiteralPath $cursor -Force).Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) {
throw "Reparse/symlink path: $cursor"
}
}
$parent = [IO.Path]::GetDirectoryName($cursor)
if ($parent -eq $cursor) { break }
$cursor = $parent
}
return $path
}
function Get-FidelityIdentity([string]$Path) {
$item = Get-Item -LiteralPath $Path -Force
if ($item.PSIsContainer -or ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0 -or
$item.Length -gt 8589934592) { throw "Not a bounded regular file: $Path" }
$stream = [IO.File]::OpenRead($item.FullName)
$sha = [Security.Cryptography.SHA256]::Create()
try {
$digest = [BitConverter]::ToString($sha.ComputeHash($stream)).Replace('-','').ToLowerInvariant()
return @{size=[long]$item.Length; sha256=$digest}
} finally { $stream.Dispose(); $sha.Dispose() }
}
function Read-FidelityJson([string]$Path) {
if ((Get-Item -LiteralPath $Path).Length -gt 4194304) { throw 'JSON exceeds 4 MiB' }
return [IO.File]::ReadAllText($Path, [Text.Encoding]::UTF8) | ConvertFrom-Json
}
function Write-FidelityJson([string]$Path, $Value) {
$text = (ConvertTo-Json -InputObject $Value -Depth 40) + "`n"
$bytes = (New-Object Text.UTF8Encoding($false)).GetBytes($text)
if ($bytes.Length -gt 4194304) { throw 'JSON exceeds 4 MiB' }
$temporary = $Path + '.incomplete-' + [guid]::NewGuid().ToString('N')
$stream = [IO.File]::Open($temporary, [IO.FileMode]::CreateNew)
try { $stream.Write($bytes,0,$bytes.Length); $stream.Flush() } finally { $stream.Dispose() }
[IO.File]::Move($temporary,$Path)
}
function Get-FidelityTree([string]$Root) {
$base = [IO.Path]::GetFullPath($Root).TrimEnd([IO.Path]::DirectorySeparatorChar)
$seen = @{}
$files = New-Object 'System.Collections.Generic.List[object]'
# Enumerate directories ourselves so reparse points are checked before descent.
$queue = New-Object 'System.Collections.Generic.Queue[string]'
$queue.Enqueue($base)
$count = 0
while ($queue.Count -gt 0) {
foreach ($item in Get-ChildItem -LiteralPath $queue.Dequeue() -Force) {
$count++
if ($count -gt 100000) { throw 'Tree exceeds 100000 entries' }
$name = $item.FullName.Substring($base.Length+1).Replace('\','/')
$null = Get-FidelityPath $base $name
if ($seen.ContainsKey($name)) { throw 'Case-alias in tree' }; $seen[$name] = $true
if ($item.PSIsContainer) { $queue.Enqueue($item.FullName) }
else { $identity = Get-FidelityIdentity $item.FullName; $identity.path = $name; $files.Add($identity) }
}
}
if ($files.Count -eq 0) { throw 'Empty tree' }
return @($files | Sort-Object path -CaseSensitive)
}
function Test-FidelityBundle([string]$Root) {
$ready = Read-FidelityJson (Get-FidelityPath $Root 'READY.json')
if ($ready.schema_version -ne 1 -or $ready.status -ne 'prepared') { throw 'Checkpoint is not READY' }
$id = Get-FidelityIdentity (Get-FidelityPath $Root 'manifest.json')
if ($id.sha256 -ne $ready.manifest.sha256 -or $id.size -ne $ready.manifest.size) { throw 'Manifest tampered' }
$manifest = Read-FidelityJson (Join-Path $Root 'manifest.json')
if ($manifest.schema_version -ne 1 -or $manifest.mutable_roots.Count -ne 2 -or
$manifest.mutable_roots[0] -ne 'results' -or $manifest.mutable_roots[1] -ne 'original-runs') {
throw 'Unsupported checkpoint manifest'
}
$seen = @{}
foreach ($file in $manifest.files) {
if ($seen.ContainsKey($file.path)) { throw 'Duplicate/case-aliased manifest file' }
$seen[$file.path] = $true
$actual = Get-FidelityIdentity (Get-FidelityPath $Root $file.path)
if ($actual.sha256 -ne $file.sha256 -or $actual.size -ne $file.size) { throw "Tampered/missing material: $($file.path)" }
}
foreach ($file in Get-FidelityTree $Root) {
if ($file.path.Split('/')[0] -notin @('results','original-runs') -and
$file.path -notin @('manifest.json','READY.json') -and -not $seen.ContainsKey($file.path)) {
throw "Unexpected immutable material: $($file.path)"
}
}
return $manifest
}
function ConvertTo-FidelityArgument([string]$Value) {
# Windows CommandLineToArgvW/CRT quoting. No cmd.exe, shell or expression eval.
if ($Value -match '[\x00\r\n]') { throw 'Control character in argument' }
$escaped = [regex]::Replace($Value, '(\\*)"', '$1$1\"')
$escaped = [regex]::Replace($escaped, '(\\+)$', '$1$1')
return '"' + $escaped + '"'
}
function Invoke-FidelityProcess([string]$Executable, [string[]]$Arguments,
[string]$WorkingDirectory, [string]$OutputDirectory, [int]$Seconds) {
$null = Get-FidelityIdentity $Executable
if ($Seconds -lt 1 -or $Seconds -gt 14400) { throw 'Process wait must be bounded' }
$info = New-Object Diagnostics.ProcessStartInfo
$info.FileName = $Executable
$info.Arguments = (($Arguments | ForEach-Object { ConvertTo-FidelityArgument $_ }) -join ' ')
$info.WorkingDirectory = $WorkingDirectory
$info.UseShellExecute = $false
$info.RedirectStandardOutput = $true; $info.RedirectStandardError = $true
$process = New-Object Diagnostics.Process
$process.StartInfo = $info
$out = [IO.File]::Open((Join-Path $OutputDirectory 'stdout.txt'),[IO.FileMode]::CreateNew)
$err = [IO.File]::Open((Join-Path $OutputDirectory 'stderr.txt'),[IO.FileMode]::CreateNew)
$timer = [Diagnostics.Stopwatch]::StartNew()
$started = $false
try {
$started = $process.Start()
if (-not $started) { throw 'Process did not start' }
$stdout = $process.StandardOutput.BaseStream.CopyToAsync($out)
$stderr = $process.StandardError.BaseStream.CopyToAsync($err)
while (-not $process.WaitForExit(200)) {
if ($timer.Elapsed.TotalSeconds -gt $Seconds -or $out.Length -gt 67108864 -or $err.Length -gt 67108864) {
$process.Kill(); $process.WaitForExit(); throw 'Process timed out or logs exceeded 64 MiB'
}
}
$remaining = [int][Math]::Max(1,($Seconds - $timer.Elapsed.TotalSeconds) * 1000)
if (-not [Threading.Tasks.Task]::WaitAll([Threading.Tasks.Task[]]@($stdout,$stderr),$remaining)) {
throw 'Process output did not close within the bounded wait'
}
$null = $stdout.GetAwaiter().GetResult(); $null = $stderr.GetAwaiter().GetResult()
if ($out.Length -gt 67108864 -or $err.Length -gt 67108864) { throw 'Process logs exceeded 64 MiB' }
return @{exit_code=$process.ExitCode; elapsed_seconds=$timer.Elapsed.TotalSeconds;
executable=$Executable; argv=@($Executable)+$Arguments; cwd=$WorkingDirectory}
} finally {
if ($started -and -not $process.HasExited) { $process.Kill(); $process.WaitForExit() }
$out.Dispose(); $err.Dispose(); $process.Dispose(); $timer.Stop()
}
}
function Get-FidelityOutcome([string]$Prior, [string]$Requested, [string]$Why) {
if ($Prior -notin @('incomplete','failed','skipped','aborted') -or
$Requested -notin @('captured','failed','skipped','aborted')) { throw 'Invalid outcome' }
if ($Prior -ne 'incomplete' -and $Requested -ne $Prior) { throw 'Failed/terminal run cannot be promoted; use a new session' }
if ($Requested -ne 'captured' -and -not $Why) { throw 'Failure/skip/abort requires a reason' }
return $Requested
}
function Get-FidelityPlatform {
$result = @{os='windows'; execution='native'; version=[Environment]::OSVersion.VersionString;
powershell=$PSVersionTable.PSVersion.ToString(); gpu=''; driver=''; vulkan=''; sdl=''}
if ([Environment]::OSVersion.Platform -ne [PlatformID]::Win32NT) { throw 'Native Windows collector requires Windows; Linux library tests are tooling-only' }
try {
$result.gpu_adapters = @(Get-CimInstance Win32_VideoController | Select-Object Name,DriverVersion,DriverDate,PNPDeviceID)
$result.gpu = ($result.gpu_adapters | ForEach-Object { $_.Name }) -join '; '
$result.driver = ($result.gpu_adapters | ForEach-Object { $_.DriverVersion }) -join '; '
$result.windows = Get-CimInstance Win32_OperatingSystem | Select-Object Caption,Version,BuildNumber,OSArchitecture
} catch { $result.query_failure = $_.Exception.Message }
return $result
}
function Copy-FidelityEvidence([string]$Source, [string]$Run, [string]$Name) {
$target = Get-FidelityPath $Run $Name
$null = [IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($target))
$before = Get-FidelityIdentity $Source
[IO.File]::Copy($Source,$target,$false)
$after = Get-FidelityIdentity $target
if ($before.sha256 -ne $after.sha256 -or $before.size -ne $after.size) { throw 'Copy identity changed' }
$after.path = $Name
return $after
}
function New-FidelityReceipt([string]$Id, [string]$Case, [string]$Obligation,
[string]$Kind, [string]$Status, $Platform, $Clocks, [string]$Why) {
$null = Test-FidelityId $Id; $null = Test-FidelityId $Case
if ($Kind -notin @('original_dxwnd','native_port','synthetic') -or
$Status -notin @('incomplete','failed','captured','skipped','aborted')) { throw 'Invalid result classification' }
return @{schema_version=1; receipt_id=$Id; session_id=$Id; case_id=$Case;
scope=$Obligation; obligation_id=$Obligation; evidence_kind=$Kind;
status=$Status; historical=$false; platform=$Platform; identity=@{};
invocation=@{argv=@();cwd=''}; clocks=$Clocks; artifacts=@();derivatives=@();events=@();
limitations=@($Why); missing_evidence=@('Actual audiovisual review and scenario audit remain open');
acceptance=@{state='open';remaining=@('No acceptance from preparation, launch or collector success')}}
}
function Start-FidelityRun {
$null = Test-FidelityId $SessionId
$root = [IO.Path]::GetFullPath($Bundle)
$run = Get-FidelityPath $root ('results/' + $SessionId)
if (Test-Path -LiteralPath $run) { throw 'Session exists; choose an independent new launch ID' }
$null = [IO.Directory]::CreateDirectory((Join-Path $root 'results'))
$reservation = [IO.File]::Open(($run + '.lock'),[IO.FileMode]::CreateNew)
$reservation.Dispose()
$null = [IO.Directory]::CreateDirectory($run)
$watch = [Diagnostics.Stopwatch]::StartNew()
$clock = @{wall_start=[DateTime]::UtcNow.ToString('o'); wall_end=[DateTime]::UtcNow.ToString('o');
monotonic_start=0;monotonic_end=0;clock_id=[guid]::NewGuid().ToString('N')}
$platform = @{os='windows';execution=$(if ($Mode -eq 'original') {'dxwnd'} else {'native'})}
$kind = $(if ($Mode -eq 'original') {'original_dxwnd'} else {'native_port'})
$receipt = New-FidelityReceipt $SessionId $CaseId $Scope $kind 'incomplete' $platform $clock 'Collection pending'
Write-FidelityJson (Join-Path $run 'incomplete.json') $receipt
try {
$manifest = Test-FidelityBundle $root
if ($manifest.tooling_only) { throw 'Synthetic checkpoint cannot launch native/original evidence' }
$protocol = Read-FidelityJson (Join-Path $root 'protocol/scenarios.json')
if ($CaseId -notin @($protocol.cells | ForEach-Object {$_.id})) { throw 'Unknown scenario cell' }
if ($Action -in @('Skip','Abort')) {
$receipt.status = Get-FidelityOutcome 'incomplete' $(if ($Action -eq 'Skip') {'skipped'} else {'aborted'}) $Reason
$receipt.limitations = @($Reason)
return 0
}
$platform = Get-FidelityPlatform
$platform.execution = $(if ($Mode -eq 'original') {'dxwnd'} else {'native'})
$receipt.platform = $platform
$receipt.identity.checkpoint = Copy-FidelityEvidence (Join-Path $root 'manifest.json') $run 'identity/checkpoint.json'
$receipt.identity.launcher = Copy-FidelityEvidence $script:CollectorSource $run 'identity/collector.ps1'
$tools = @{}
foreach ($entry in @(@('recorder',$RecorderPath),@('browser',$BrowserPath),@('settings',$SettingsPath))) {
if (-not $entry[1]) { throw ('Select actual local ' + $entry[0] + ' file; no downloads are performed') }
# Identify external tools; do not redistribute their executables/installers.
$id = Get-FidelityIdentity $entry[1]
$tools[$entry[0]] = @{selected_path=$entry[1]; identity=$id;
version=[Diagnostics.FileVersionInfo]::GetVersionInfo($entry[1]).FileVersion}
}
$receipt.identity.settings = Copy-FidelityEvidence $SettingsPath $run 'identity/settings.json'
Write-FidelityJson (Join-Path $run 'tools.json') $tools
if ($Mode -eq 'port') {
$package = Join-Path $root 'port/win-x64'
$exe = Join-Path $package 'GamePort.exe'
$receipt.identity.executable = Copy-FidelityEvidence $exe $run 'identity/GamePort.exe'
$receipt.identity.runtime_dll = Copy-FidelityEvidence (Join-Path $package 'GamePort.dll') $run 'identity/GamePort.dll'
$build = Read-FidelityJson (Join-Path $package 'fidelity-build.json')
$src = Copy-FidelityEvidence (Join-Path $package 'fidelity-build.json') $run 'identity/build.json'
$src.commit = $build.source.commit; $src.dirty = $build.source.dirty; $src.diff_sha256 = $build.source.diff_sha256
$receipt.identity.source = $src
$receipt.identity.package = $src
$receipt.identity.resources = $src
$sdl = [Diagnostics.FileVersionInfo]::GetVersionInfo((Join-Path $package 'SDL3.dll'))
$platform.sdl_binary_version = $sdl.FileVersion
$arguments = @('--assets',(Join-Path $package 'assets'),'--load-save',(Join-Path $package 'assets/NewGame.tsk'),
'--walk','--fidelity-output',(Join-Path $run 'observer'),'--fidelity-session',$SessionId,'--fidelity-case',$CaseId)
Write-Host 'Start the external raw MKV recording now. Record physical inputs and media clocks. This is the existing TSK story entry, not a reconstructed main menu.'
$null = Read-Host 'Press Enter when recording is running'
$receipt.invocation = @{argv=@($exe)+$arguments;cwd=$run}
$result = Invoke-FidelityProcess $exe $arguments $run $run $TimeoutSeconds
Write-FidelityJson (Join-Path $run 'process.json') $result
if ($result.exit_code -ne 0) { throw "Port exited $($result.exit_code); preserve recording and logs" }
$receipt.limitations = @('Port process exited; media/event mapping and human review pending; observer overhead is diagnostic')
} else {
if (-not $DxWndPath -or -not $ProfilePath) { throw 'Select actual local DxWnd executable and exported profile' }
$dxwndId = Get-FidelityIdentity $DxWndPath
Write-FidelityJson (Join-Path $run 'dxwnd-tool.json') @{selected_path=$DxWndPath;identity=$dxwndId;
version=[Diagnostics.FileVersionInfo]::GetVersionInfo($DxWndPath).FileVersion}
$receipt.identity.dxwnd = @{path='dxwnd-tool.json'} + (Get-FidelityIdentity (Join-Path $run 'dxwnd-tool.json'))
$receipt.identity.dxwnd_config = Copy-FidelityEvidence $ProfilePath $run 'identity/original-profile.dxw'
$copy = Get-FidelityPath $root ('original-runs/' + $SessionId)
if (Test-Path -LiteralPath $copy) { throw 'Original run copy exists' }
$null = [IO.Directory]::CreateDirectory($copy)
$seed = Join-Path $root 'original-pristine'
foreach ($file in Get-FidelityTree $seed) {
$null = Copy-FidelityEvidence (Get-FidelityPath $seed $file.path) $copy $file.path
}
Write-FidelityJson (Join-Path $run 'copy-pre.json') @(Get-FidelityTree $copy)
$receipt.identity.copy_pre = @{path='copy-pre.json'} + (Get-FidelityIdentity (Join-Path $run 'copy-pre.json'))
Write-Host "Generated original copy: $copy"
Write-Host 'Inspect this selected DxWnd distribution help/config. Import the retained exported profile and change ONLY target/working-directory paths to the generated copy; export the relocated profile into this result folder. No switches/settings are assumed.'
Write-Host 'Start external raw MKV recording before original interaction. Launch the original manually through DxWnd. Never select original-pristine or the authoritative installation.'
$info = New-Object Diagnostics.ProcessStartInfo
$info.FileName = [IO.Path]::GetFullPath($DxWndPath); $info.WorkingDirectory = $copy; $info.UseShellExecute = $false
$wrapper = [Diagnostics.Process]::Start($info)
$receipt.invocation = @{argv=@($info.FileName);cwd=$copy;method='manual profile import and GUI launch; original child exit not inferred'}
$null = Read-Host 'After the original has exited and recording stopped, press Enter (keep this collector alive during retained prerequisites)'
$receipt.wrapper_settings = 'Selected profile retained; relocated export/settings and wrapper limitations require annotation review'
$receipt.limitations = @('DxWnd GUI launched; original child invocation/exit and visible/audible behavior require actual session annotations')
$wrapper.Dispose()
}
} catch {
$receipt.status = 'failed'; $receipt.limitations = @($_.Exception.Message)
Write-Warning $_.Exception.Message
} finally {
if ($Mode -eq 'original' -and (Get-Variable copy -ErrorAction SilentlyContinue) -and
(Test-Path -LiteralPath $copy) -and -not (Test-Path -LiteralPath (Join-Path $run 'copy-post.json'))) {
try {
Write-FidelityJson (Join-Path $run 'copy-post.json') @(Get-FidelityTree $copy)
$receipt.identity.copy_post = @{path='copy-post.json'} + (Get-FidelityIdentity (Join-Path $run 'copy-post.json'))
} catch { $receipt.status = 'failed'; $receipt.limitations += ('Postflight failed: ' + $_.Exception.Message) }
}
$clock.wall_end = [DateTime]::UtcNow.ToString('o'); $clock.monotonic_end = $watch.Elapsed.TotalSeconds
Write-FidelityJson (Join-Path $run 'run.json') $receipt
if ($receipt.status -in @('failed','skipped','aborted')) { Write-FidelityJson (Join-Path $run 'failure.json') $receipt }
$watch.Stop()
}
Write-Host "Result: $run ; status=$($receipt.status); acceptance OPEN"
if ($receipt.status -eq 'failed') { return 2 }; return 0
}
function Complete-FidelityRun {
$null = Test-FidelityId $SessionId
$run = Get-FidelityPath $Bundle ('results/' + $SessionId)
$null = Test-FidelityBundle $Bundle
$receipt = Read-FidelityJson (Join-Path $run 'run.json')
if (Test-Path -LiteralPath (Join-Path $run 'receipt.json')) { throw 'Result already finalized; preserve it and use a new result ID' }
if (-not $AnnotationPath -or -not $ArtifactsDirectory) { throw 'Finish requires actual annotations and a local artifact directory' }
$annotation = Read-FidelityJson $AnnotationPath
$requested = Get-FidelityOutcome $receipt.status $Outcome $Reason
if ($annotation.schema_version -ne 1) { throw 'Unsupported annotation schema' }
if (@($annotation.artifacts).Count -gt 10000) { throw 'Too many artifacts' }
$names = @{}
foreach ($file in $annotation.artifacts) {
$null = Get-FidelityPath $ArtifactsDirectory $file.path
if ($names.ContainsKey($file.path)) { throw 'Duplicate/case-aliased artifact' }; $names[$file.path] = $file
$null = Get-FidelityIdentity (Get-FidelityPath $ArtifactsDirectory $file.path)
if ($file.PSObject.Properties.Name -contains 'synthetic' -and $file.synthetic) { throw 'Synthetic media cannot be relabeled as native/original' }
}
foreach ($event in $annotation.events) {
if (-not $names.ContainsKey($event.artifact)) { throw 'Event references missing artifact' }
}
if ($requested -eq 'captured') {
if (-not @($annotation.artifacts | Where-Object {$_.role -eq 'video' -and $_.path.EndsWith('.mkv',[StringComparison]::OrdinalIgnoreCase)}).Count) {
throw 'Captured result requires retained raw MKV video'
}
if (-not @($annotation.artifacts | Where-Object {$_.role -eq 'audio'}).Count) { throw 'Captured result requires actual audio evidence' }
}
foreach ($derivative in $annotation.derivatives) {
if (-not $names.ContainsKey($derivative.path) -or -not $names.ContainsKey($derivative.source) -or
-not $derivative.tool -or -not $derivative.version -or -not $derivative.created_utc -or
-not @($derivative.argv).Count -or -not $derivative.timestamp_mapping -or
-not $derivative.crop_aspect -or $derivative.browser_playback_verified -isnot [bool] -or
-not $derivative.browser_playback_verified) {
throw 'Derivative requires source/output, actual tool/version/argv/time/crop and verified browser playback'
}
}
$receipt.artifacts = @()
foreach ($file in $annotation.artifacts) {
$source = Get-FidelityPath $ArtifactsDirectory $file.path
$id = Copy-FidelityEvidence $source $run ('media/' + $file.path)
$id.role = $file.role
if ($file.PSObject.Properties.Name -contains 'duration_seconds') { $id.duration_seconds = $file.duration_seconds }
$receipt.artifacts += $id
}
$copied = Copy-FidelityEvidence $AnnotationPath $run 'annotations.json'
$copied.role = 'input_events'; $receipt.artifacts += $copied
$receipt.events = @($annotation.events | ForEach-Object {
if (-not $names.ContainsKey($_.artifact)) { throw 'Event references missing artifact' }
$_.artifact = 'media/' + $_.artifact; $_
})
$receipt.derivatives = @($annotation.derivatives | ForEach-Object {
$_.path = 'media/' + $_.path; $_.source = 'media/' + $_.source; $_
})
$receipt.status = $requested
if ($annotation.PSObject.Properties.Name -contains 'continuity') {
$continuity = $annotation.continuity
if ($continuity.PSObject.Properties.Name -contains 'prerequisite_artifact') {
if (-not $names.ContainsKey($continuity.prerequisite_artifact)) { throw 'Continuity references missing artifact' }
$continuity.prerequisite_artifact = 'media/' + $continuity.prerequisite_artifact
}
$receipt | Add-Member -Force -NotePropertyName continuity -NotePropertyValue $continuity
}
if ($annotation.PSObject.Properties.Name -contains 'diagnostic') { $receipt | Add-Member -Force -NotePropertyName diagnostic -NotePropertyValue ([bool]$annotation.diagnostic) }
if ($Reason) { $receipt.limitations += $Reason }
$receipt.limitations += @($annotation.limitations)
# Human declarations remain source annotations; the shared importer and final
# audit validate times, hashes, category, continuity and actual review later.
$receipt.limitations += 'Imported annotations require shared validation; raw MKV and incomplete/failed cases are retained'
Write-FidelityJson (Join-Path $run 'receipt.json') $receipt
Write-Host "Result saved ($requested); acceptance OPEN. Return full checkpoint locally for validation."
}
if ($LibraryOnly) { return }
try {
if ($Action -eq 'Preflight') {
$manifest = Test-FidelityBundle $Bundle
Write-Host "Prepared materials checked: $($manifest.files.Count) files; acceptance OPEN; actual Windows/tools/media preflight pending"
exit 0
}
if ($Action -eq 'Finish') { Complete-FidelityRun; exit 0 }
if ($Action -eq 'Retained') {
$null = Test-FidelityId $SessionId
$run = Get-FidelityPath $Bundle ('results/' + $SessionId)
$copy = Get-FidelityPath $Bundle ('original-runs/' + $SessionId)
Write-FidelityJson (Join-Path $run 'retained-copy.json') @{observed_utc=[DateTime]::UtcNow.ToString('o');
files=@(Get-FidelityTree $copy);note='Snapshot only; prerequisite recording and actual media timing/uncertainty still required'}
exit 0
}
exit (Start-FidelityRun)
} catch {
Write-Error ('Collector failed; acceptance OPEN: ' + $_.Exception.Message)
exit 2
}
+6
View File
@@ -0,0 +1,6 @@
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/env.sh"
# Build first into NEW local output, then prepare a different NEW bundle root.
# Existing dist packages retain their historical bytes and BUILD-INFO.
exec python3 tools/recon/fidelity_checkpoint.py "$@"
+191
View File
@@ -0,0 +1,191 @@
# Package-free selftests. All bytes/processes are synthetic tooling fixtures.
# Run with Windows PowerShell 5.1 or pwsh; Linux pwsh is NOT Windows evidence.
[CmdletBinding()]
param([string]$FixtureOutput)
Set-StrictMode -Version 2
$ErrorActionPreference = 'Stop'
$collector = Join-Path (Split-Path -Parent $PSScriptRoot) 'scripts/collect-fidelity-windows.ps1'
. $collector -LibraryOnly
$temporary = Join-Path ([IO.Path]::GetTempPath()) ('fidelity-selftest-' + [guid]::NewGuid().ToString('N'))
$null = [IO.Directory]::CreateDirectory($temporary)
$script:Checks = 0
function Assert-True($Condition, [string]$Message) { if (-not $Condition) { throw $Message } }
function Assert-Throws([scriptblock]$Body) {
$thrown = $false
try { & $Body | Out-Null } catch { $thrown = $true }
Assert-True $thrown 'Expected rejection did not occur'
}
function Check([string]$Name, [scriptblock]$Body) {
& $Body
$script:Checks++
Write-Host "PASS $Name"
}
function Fixture-File([string]$Name, [string]$Content) {
$path = Join-Path $temporary $Name
$null = [IO.Directory]::CreateDirectory([IO.Path]::GetDirectoryName($path))
[IO.File]::WriteAllText($path,$Content,(New-Object Text.UTF8Encoding($false)))
return $path
}
try {
Check 'stable IDs reject reserved/path aliases' {
Assert-True ((Test-FidelityId 'session-01') -eq 'session-01') 'ID changed'
foreach ($bad in @('../x','CON','a/b','NUL.txt','')) { Assert-Throws { Test-FidelityId $bad } }
}
Check 'paths reject traversal, drive paths and Windows aliases' {
foreach ($bad in @('../x','a//x','C:/x','/x','a\x','aux.txt','a./x','a /x')) {
Assert-Throws { Get-FidelityPath $temporary $bad }
}
Assert-True ((Get-FidelityPath $temporary 'space dir/a.txt').StartsWith($temporary)) 'Contained path missing'
}
$sample = Fixture-File 'sample.txt' 'abc'
Check 'streamed SHA256 and size match actual bytes' {
$id = Get-FidelityIdentity $sample
Assert-True ($id.size -eq 3 -and $id.sha256 -eq 'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad') 'Wrong identity'
}
Check 'copies preserve bytes and never overwrite evidence' {
$id = Copy-FidelityEvidence $sample $temporary 'copied/space name.txt'
Assert-True ($id.sha256 -eq (Get-FidelityIdentity $sample).sha256) 'Copy differs'
Assert-Throws { Copy-FidelityEvidence $sample $temporary 'copied/space name.txt' }
}
Check 'JSON keeps empty arrays, Unicode, singleton arrays and write-once results' {
$path = Join-Path $temporary 'json.json'
Write-FidelityJson $path @{empty=@();single=@('one');text='café'}
$value = Read-FidelityJson $path
Assert-True ($value.empty -is [array] -and $value.empty.Count -eq 0) 'Empty list lost'
Assert-True ($value.single -is [array] -and $value.single.Count -eq 1 -and $value.text -eq 'café') 'JSON changed'
Assert-Throws { Write-FidelityJson $path @{} }
$path2 = Join-Path $temporary 'empty.json'
Write-FidelityJson $path2 @()
Assert-True ([IO.File]::ReadAllText($path2).Trim() -eq '[]') 'Top-level empty list lost'
}
Check 'argument quoting preserves empty/spaces/quotes/trailing backslashes' {
Assert-True ((ConvertTo-FidelityArgument '') -ceq '""') 'Empty quoting'
Assert-True ((ConvertTo-FidelityArgument 'a b') -ceq '"a b"') 'Space quoting'
Assert-True ((ConvertTo-FidelityArgument 'a"b') -ceq '"a\"b"') 'Quote escaping'
Assert-True ((ConvertTo-FidelityArgument 'C:\space dir\') -ceq '"C:\space dir\\"') 'Trailing slash escaping'
Assert-Throws { ConvertTo-FidelityArgument "bad`nargument" }
}
$hostExe = [Diagnostics.Process]::GetCurrentProcess().MainModule.FileName
$child = Fixture-File 'child space.ps1' 'param([string]$Value) [Console]::Out.Write($Value); [Console]::Error.Write("child stderr"); exit 7'
Check 'real child arguments, logs and nonzero exit remain distinct from success' {
$logs = Join-Path $temporary 'process'
$null = [IO.Directory]::CreateDirectory($logs)
$result = Invoke-FidelityProcess $hostExe @('-NoProfile','-File',$child,'value with spaces') $temporary $logs 30
Assert-True ($result.exit_code -eq 7 -and $result.elapsed_seconds -ge 0) 'Exit result changed'
Assert-True ([IO.File]::ReadAllText((Join-Path $logs 'stdout.txt')) -ceq 'value with spaces') 'Arguments not preserved'
Assert-True ([IO.File]::ReadAllText((Join-Path $logs 'stderr.txt')) -ceq 'child stderr') 'Stderr missing'
}
Check 'process waits are bounded and timeout preserves logs' {
$sleeper = Fixture-File 'sleep.ps1' 'Start-Sleep -Seconds 30'
$logs = Join-Path $temporary 'timeout'
$null = [IO.Directory]::CreateDirectory($logs)
Assert-Throws { Invoke-FidelityProcess $hostExe @('-NoProfile','-File',$sleeper) $temporary $logs 1 }
Assert-True (Test-Path -LiteralPath (Join-Path $logs 'stdout.txt')) 'Timeout logs lost'
Assert-Throws { Invoke-FidelityProcess $hostExe @() $temporary $logs 0 }
}
Check 'failed process start produces original exception without unstarted process access' {
$notExe = Fixture-File 'not-executable.bin' 'synthetic non executable'
$logs = Join-Path $temporary 'bad-process'
$null = [IO.Directory]::CreateDirectory($logs)
Assert-Throws { Invoke-FidelityProcess $notExe @() $temporary $logs 1 }
}
Check 'failure skip abort cannot become captured and require reasons' {
foreach ($state in @('failed','skipped','aborted')) {
Assert-True ((Get-FidelityOutcome 'incomplete' $state 'observed reason') -eq $state) 'Outcome changed'
Assert-Throws { Get-FidelityOutcome $state 'captured' '' }
Assert-Throws { Get-FidelityOutcome 'incomplete' $state '' }
}
}
Check 'result categories and open acceptance remain explicit' {
foreach ($kind in @('native_port','original_dxwnd','synthetic')) {
$r = New-FidelityReceipt 'selftest' 'fresh-natural-ordinary' 'continuous' $kind 'incomplete' @{} @{} 'fixture'
Assert-True ($r.evidence_kind -eq $kind -and $r.acceptance.state -eq 'open' -and $r.missing_evidence.Count -gt 0) 'False acceptance'
}
Assert-Throws { New-FidelityReceipt 'selftest' 'case' 'continuous' 'wine-as-native' 'captured' @{} @{} '' }
}
$bundleRoot = Join-Path $temporary 'bundle'
$null = [IO.Directory]::CreateDirectory((Join-Path $bundleRoot 'protocol'))
$material = Fixture-File 'bundle/protocol/test.txt' 'synthetic immutable material'
$entry = Get-FidelityIdentity $material; $entry.path = 'protocol/test.txt'
Write-FidelityJson (Join-Path $bundleRoot 'manifest.json') @{schema_version=1;tooling_only=$true;mutable_roots=@('results','original-runs');files=@($entry)}
Write-FidelityJson (Join-Path $bundleRoot 'READY.json') @{schema_version=1;status='prepared';manifest=(Get-FidelityIdentity (Join-Path $bundleRoot 'manifest.json'))}
Check 'prepared bundle validates immutable bytes and permits only declared mutable roots' {
$null = Test-FidelityBundle $bundleRoot
$null = Fixture-File 'bundle/results/local-result.txt' 'diagnostic'
$null = Test-FidelityBundle $bundleRoot
$extra = Fixture-File 'bundle/unlisted.txt' 'unexpected'
Assert-Throws { Test-FidelityBundle $bundleRoot }
[IO.File]::Delete($extra)
}
Check 'tampered immutable bytes fail preflight' {
[IO.File]::AppendAllText($material,'tampered')
Assert-Throws { Test-FidelityBundle $bundleRoot }
[IO.File]::WriteAllText($material,'synthetic immutable material',(New-Object Text.UTF8Encoding($false)))
}
$script:Bundle = $bundleRoot
$script:SessionId = 'fixture-finish'
$run = Join-Path $bundleRoot 'results/fixture-finish'
$null = [IO.Directory]::CreateDirectory($run)
$clock = @{wall_start=[DateTime]::UtcNow.ToString('o');wall_end=[DateTime]::UtcNow.ToString('o');monotonic_start=0;monotonic_end=2}
$r = New-FidelityReceipt $SessionId 'fresh-natural-ordinary' 'continuous' 'synthetic' 'incomplete' @{os='test';execution='synthetic'} $clock 'Tooling-only synthetic fixture'
Write-FidelityJson (Join-Path $run 'run.json') $r
$script:ArtifactsDirectory = Join-Path $temporary 'media'
$null = Fixture-File 'media/raw.mkv' 'synthetic video bytes, no gameplay'
$null = Fixture-File 'media/audio.wav' 'synthetic audio bytes, no gameplay'
$script:AnnotationPath = Join-Path $temporary 'annotations.json'
$annotation = @{schema_version=1;artifacts=@(@{path='raw.mkv';role='video';duration_seconds=2},@{path='audio.wav';role='audio';duration_seconds=2});events=@(@{name='startup';artifact='raw.mkv';media_seconds=0;elapsed_seconds=0;method='manual';uncertainty_seconds=0.1});derivatives=@();limitations=@('synthetic tooling only');continuity=@{prerequisite_artifact='raw.mkv'}}
$script:Outcome = 'captured'
Check 'capture rejects an empty annotation before any media copy' {
Write-FidelityJson $AnnotationPath @{schema_version=1;artifacts=@();events=@();derivatives=@();limitations=@()}
Assert-Throws { Complete-FidelityRun }
Assert-True (-not (Test-Path -LiteralPath (Join-Path $run 'media'))) 'Invalid annotation copied data'
[IO.File]::Delete($AnnotationPath)
}
Check 'capture rejects synthetic promotion and missing event targets before writes' {
$annotation.artifacts[0].synthetic = $true
Write-FidelityJson $AnnotationPath $annotation
Assert-Throws { Complete-FidelityRun }
[IO.File]::Delete($AnnotationPath)
$annotation.artifacts[0].Remove('synthetic')
$annotation.events[0].artifact = 'absent.mkv'
Write-FidelityJson $AnnotationPath $annotation
Assert-Throws { Complete-FidelityRun }
[IO.File]::Delete($AnnotationPath)
$annotation.events[0].artifact = 'raw.mkv'
}
Check 'finish maps hashed media/event/continuity paths and preserves synthetic category' {
Write-FidelityJson $AnnotationPath $annotation
Complete-FidelityRun
$result = Read-FidelityJson (Join-Path $run 'receipt.json')
Assert-True ($result.status -eq 'captured' -and $result.evidence_kind -eq 'synthetic' -and $result.acceptance.state -eq 'open') 'Fixture promoted'
Assert-True ($result.artifacts.Count -eq 3 -and $result.events[0].artifact -eq 'media/raw.mkv' -and $result.continuity.prerequisite_artifact -eq 'media/raw.mkv') 'Broken result links'
Assert-True ($result.artifacts[0].sha256 -eq (Get-FidelityIdentity (Join-Path $run 'media/raw.mkv')).sha256) 'Media identity differs'
Assert-Throws { Complete-FidelityRun }
}
Check 'terminal failed skipped aborted results retain empty artifact lists and cannot be promoted' {
foreach ($state in @('failed','skipped','aborted')) {
$script:SessionId = 'fixture-' + $state
$terminalRun = Join-Path $bundleRoot ('results/' + $SessionId)
$null = [IO.Directory]::CreateDirectory($terminalRun)
$terminal = New-FidelityReceipt $SessionId 'fresh-natural-ordinary' 'continuous' 'synthetic' $state @{os='test';execution='synthetic'} $clock 'synthetic terminal fixture'
Write-FidelityJson (Join-Path $terminalRun 'run.json') $terminal
$script:AnnotationPath = Join-Path $temporary ($state + '-notes.json')
Write-FidelityJson $AnnotationPath @{schema_version=1;artifacts=@();events=@();derivatives=@();limitations=@('synthetic tooling only')}
$script:Outcome = $state; $script:Reason = 'Tooling fixture; no actual capture'
Complete-FidelityRun
$saved = Read-FidelityJson (Join-Path $terminalRun 'receipt.json')
Assert-True ($saved.status -eq $state -and $saved.artifacts.Count -eq 1 -and $saved.events -is [array] -and $saved.events.Count -eq 0 -and $saved.acceptance.state -eq 'open') 'Terminal fixture changed'
}
}
if ($FixtureOutput) {
if (Test-Path -LiteralPath $FixtureOutput) { throw 'Fixture output must be new' }
$null = [IO.Directory]::CreateDirectory($FixtureOutput)
foreach ($item in Get-ChildItem -LiteralPath (Join-Path $bundleRoot 'results') -Directory) {
Copy-Item -LiteralPath $item.FullName -Destination $FixtureOutput -Recurse
}
}
Assert-True ($script:Checks -ge 8) 'Fewer than eight executed checks'
Write-Host "PASS: $script:Checks checks; 0 failures; synthetic tooling only; native Windows/original gameplay acceptance OPEN"
} finally {
if (Test-Path -LiteralPath $temporary) { Remove-Item -LiteralPath $temporary -Recurse -Force }
}
+236
View File
@@ -0,0 +1,236 @@
"""Quota policy and recovery tests; no model calls or quota consumption."""
import contextlib
import io
import json
from pathlib import Path
import struct
import tempfile
import unittest
from unittest.mock import patch
from tools.workflow import codex_quota_guard as guard
def limits(used=79, duration=300, reset=2000):
return {'rateLimits': {'primary': {'usedPercent': used, 'windowDurationMins': duration,
'resetsAt': reset}}}
class QuotaTests(unittest.TestCase):
def test_boundary_thresholds(self):
for used, expected in [(0, 'ready'), (79, 'ready'), (80, 'drain'), (84, 'drain'),
(85, 'pause'), (100, 'pause')]:
with self.subTest(used=used):
self.assertEqual(guard.stage(guard.quota(limits(used), 1000), 1000), expected)
def test_actual_window_secondary(self):
data = limits(99, 10080)
data['rateLimits']['secondary'] = limits(40)['rateLimits']['primary']
self.assertEqual(guard.quota(data, 1000)['remaining'], 60)
def test_general_bucket_preferred(self):
data = limits(99)
data['rateLimitsByLimitId'] = {'codex': limits(10)['rateLimits'],
'specialty': limits(100)['rateLimits']}
self.assertEqual(guard.quota(data, 1000)['remaining'], 90)
def test_invalid_windows_never_look_healthy(self):
for data in [limits(50, 10080), limits(50, reset=999), limits(float('nan')),
limits(-1), limits(101), limits(True), {}, {'rateLimits': None}]:
with self.subTest(data=data), self.assertRaises(ValueError):
guard.quota(data, 1000)
def test_stale_and_expired_unknown(self):
sample = guard.quota(limits(), 1000)
self.assertEqual(guard.stage(sample, 1181), 'unknown')
self.assertEqual(guard.stage(dict(sample, checkedAt=1999), 2000), 'unknown')
self.assertEqual(guard.stage(None, 1000), 'unknown')
def test_reset_clears_pause_only_after_fresh_quota(self):
sample = guard.quota(limits(99), 1000)
self.assertEqual(guard.stage(sample, 2000), 'unknown')
fresh = guard.quota(limits(1, reset=20000), 2001)
self.assertEqual(guard.stage(fresh, 2001), 'ready')
def test_worker_denials_leave_checkpoint_tools_available(self):
for used in (80, 85, 100):
sample = guard.quota(limits(used), 1000)
for tool in ('Agent', 'spawn_agent', 'followup_task', 'mcp__local__spawn_agent',
'collaboration.spawn_agent'):
answer = guard.hook_response('PreToolUse', tool, sample, 1000)
self.assertEqual(answer['hookSpecificOutput']['permissionDecision'], 'deny')
for tool in ('Bash', 'apply_patch', 'send_message', 'interrupt_agent'):
answer = guard.hook_response('PreToolUse', tool, sample, 1000)
self.assertNotIn('permissionDecision', answer.get('hookSpecificOutput', {}))
def test_unknown_denies_new_workers(self):
answer = guard.hook_response('PreToolUse', 'spawn_agent', None, 1000)
self.assertEqual(answer['hookSpecificOutput']['permissionDecision'], 'deny')
def test_ready_allows_dispatch(self):
self.assertEqual(guard.hook_response('PreToolUse', 'spawn_agent',
guard.quota(limits(), 1000), 1000), {})
def test_diagnostic_event_does_not_return_context(self):
self.assertEqual(guard.hook_response('PreModelRequest', '',
guard.quota(limits(90), 1000), 1000), {})
class StateTests(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory()
self.addCleanup(self.temp.cleanup)
self.state = Path(self.temp.name) / 'state'
self.patcher = patch.object(guard, 'STATE', self.state)
self.patcher.start()
self.addCleanup(self.patcher.stop)
def test_atomic_is_private_and_replaces(self):
path = self.state / 'value.json'
guard.atomic(path, {'one': 1})
guard.atomic(path, {'two': 2})
self.assertEqual(guard.read(path), {'two': 2})
self.assertEqual(path.stat().st_mode & 0o777, 0o600)
def test_thread_registration_uses_agent_id(self):
guard.register({'session_id': 'root', 'agent_id': 'child', 'turn_id': 'turn'})
entries = list((self.state / 'threads').glob('*.json'))
self.assertEqual(guard.read(entries[0])['threadId'], 'child')
def test_missing_turn_never_guessed(self):
guard.register({'session_id': 'root'})
self.assertFalse((self.state / 'threads').exists())
def test_context_only_once_per_turn(self):
guard.atomic(self.state / 'quota.json', guard.quota(limits(90), 1000))
payload = {'hook_event_name': 'PostToolUse', 'turn_id': 'turn'}
with patch.object(guard.time, 'time', return_value=1000):
self.assertIn('hookSpecificOutput', guard.handle_hook(payload))
self.assertEqual(guard.handle_hook(payload), {})
payload['turn_id'] = 'next'
self.assertIn('hookSpecificOutput', guard.handle_hook(payload))
def test_only_unambiguous_events_register_thread(self):
with patch.object(guard, 'register') as register:
guard.handle_hook({'hook_event_name': 'PreToolUse', 'session_id': 'root', 'turn_id': 'child'})
register.assert_not_called()
guard.handle_hook({'hook_event_name': 'PreModelRequest', 'session_id': 'root', 'turn_id': 'root-turn'})
register.assert_called_once()
def test_pause_saves_snapshot_and_steers_once(self):
class FakeRPC:
calls = []
def call(self, method, params):
self.calls.append((method, params))
return limits(90)
def close(self):
pass
guard.register({'session_id': 'root', 'turn_id': 'turn'})
with patch.object(guard, 'RPC', FakeRPC), patch.object(guard, 'snapshot') as snapshot, \
patch.object(guard.time, 'time', return_value=1000):
guard.tick()
guard.tick()
self.assertEqual(snapshot.call_count, 2)
steers = [p for m, p in FakeRPC.calls if m == 'turn/steer']
self.assertEqual(len(steers), 1)
self.assertEqual(steers[0]['expectedTurnId'], 'turn')
self.assertEqual(steers[0]['threadId'], 'root')
self.assertFalse(any(m == 'turn/start' for m, _ in FakeRPC.calls))
def test_inactive_turn_is_not_restarted(self):
class FakeRPC:
calls = []
def call(self, method, params):
self.calls.append(method)
if method == 'turn/steer':
raise RuntimeError('inactive')
return limits(90)
def close(self):
pass
guard.register({'session_id': 'root', 'turn_id': 'turn'})
with patch.object(guard, 'RPC', FakeRPC), patch.object(guard, 'snapshot'), \
patch.object(guard.time, 'time', return_value=1000):
guard.tick()
guard.tick()
self.assertEqual(FakeRPC.calls.count('turn/steer'), 1)
self.assertNotIn('turn/start', FakeRPC.calls)
def test_reset_timestamp_jitter_does_not_repeat_pause(self):
class FakeRPC:
steers = 0
reads = 0
def call(self, method, params):
if method == 'turn/steer':
self.steers += 1
return {}
self.reads += 1
return limits(90, reset=2000 + self.reads)
def close(self):
pass
rpc = FakeRPC()
guard.register({'session_id': 'root', 'turn_id': 'turn'})
with patch.object(guard, 'RPC', return_value=rpc), patch.object(guard, 'snapshot'), \
patch.object(guard.time, 'time', return_value=1000):
guard.tick()
guard.tick()
self.assertEqual(rpc.steers, 1)
def test_recovery_preserves_canonical_handoff(self):
project = Path(self.temp.name) / 'project'
(project / '.planning').mkdir(parents=True)
handoff = project / '.planning/HANDOFF.json'
handoff.write_text('{"precise": "continuation"}')
process = unittest.mock.MagicMock()
process.__enter__.return_value = process
process.stdout.read.return_value = b'test git output'
with patch.object(guard, 'ROOT', project), patch.object(guard.subprocess, 'Popen', return_value=process):
guard.snapshot(guard.quota(limits(90), 1000))
guard.snapshot(guard.quota(limits(90, reset=2001), 1000))
self.assertEqual(handoff.read_text(), '{"precise": "continuation"}')
self.assertFalse((self.state / 'recovery-2001').exists())
record = guard.read(self.state / 'recovery-2000/record.json')
self.assertIn('continuation', record['gsd']['.planning/HANDOFF.json'])
class FrameTests(unittest.TestCase):
def rpc(self, data=b''):
rpc = guard.RPC.__new__(guard.RPC)
rpc.sock = unittest.mock.Mock()
rpc.buffer = data
rpc.sequence = 0
return rpc
def test_eof_terminates_instead_of_spinning(self):
rpc = self.rpc()
rpc.sock.recv.return_value = b''
with self.assertRaises(EOFError):
rpc.take(1)
def test_oversize_rejected_before_payload_read(self):
rpc = self.rpc(b'\x81\x7f' + struct.pack('!Q', 2**21))
with self.assertRaises(ValueError):
rpc.message()
rpc.sock.recv.assert_not_called()
def test_ping_and_fragmented_text(self):
rpc = self.rpc(b'\x89\x01x' + b'\x01\x05{"a":' + b'\x80\x021}')
self.assertEqual(rpc.message(), {'a': 1})
rpc.sock.sendall.assert_called_once()
def test_client_masks_outgoing_frames(self):
rpc = self.rpc()
rpc.send({'test': 'value'})
wire = rpc.sock.sendall.call_args.args[0]
self.assertTrue(wire[1] & 128)
mask = wire[2:6]
raw = bytes(c ^ mask[i % 4] for i, c in enumerate(wire[6:]))
self.assertEqual(json.loads(raw), {'test': 'value'})
def test_notifications_skipped_until_matching_response(self):
rpc = self.rpc()
with patch.object(rpc, 'message', side_effect=[{'method': 'notify'}, {'id': 1, 'result': {'ok': True}}]):
self.assertEqual(rpc.call('test', {}), {'ok': True})
if __name__ == '__main__':
unittest.main()
+241
View File
@@ -0,0 +1,241 @@
"""Offline checkpoint fixtures are tooling tests, never native/reference evidence."""
import concurrent.futures
import importlib
import json
from pathlib import Path
import subprocess
import sys
import tempfile
import unittest
from unittest import mock
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT / 'tools/recon'))
import fidelity_receipts as receipts
try:
checkpoint = importlib.import_module('fidelity_checkpoint')
except ModuleNotFoundError:
checkpoint = None
class FidelityCheckpoint(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.addCleanup(self.tmp.cleanup)
self.base = Path(self.tmp.name)
self.original = self.base / 'Original'
self.original.mkdir()
(self.original / 'Jimmy Neutron.exe').write_bytes(b'synthetic original')
self.manifest = self.base / 'original.json'
self.manifest.write_bytes(receipts.canonical_bytes(receipts.identify_tree(self.original)))
self.packages = {}
for rid in ('linux-x64', 'win-x64'):
package = self.base / rid
package.mkdir()
for name in ('GamePort.exe' if rid == 'win-x64' else 'GamePort',
'GamePort.dll', 'GamePort.runtimeconfig.json', 'GamePort.deps.json',
'SDL3.dll' if rid == 'win-x64' else 'libSDL3.so.0',
'assets/NewGame.tsk', 'scenes/level1b/scene.json',
'scenes/VR04/scene.json', 'scenes/level1/scene.json',
'scenes/animations/jimstop/animation.json', 'audio/music.wav', 'Shaders/test.spv'):
path = package / name
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(b'synthetic fixture bytes ' + name.encode())
(package / 'BUILD-INFO.txt').write_text('source_commit=fixture\nsource_dirty=yes\n')
self.packages[rid] = package
self.output = self.base / 'checkpoint'
def api(self):
self.assertIsNotNone(checkpoint, 'offline checkpoint preparation API must exist')
return checkpoint
def prepare(self, output=None):
api = self.api()
for rid, path in self.packages.items():
if not (path / 'fidelity-build.json').exists():
api.seal_package(path, rid, {'commit': 'fixture', 'dirty': True,
'diff_sha256': '0' * 64}, tooling=True)
return api.prepare_checkpoint(self.original, self.manifest, self.packages,
output or self.output, tooling=True)
def test_prepare_preflight_fixture_import_roundtrip(self):
self.prepare()
report = self.api().preflight(self.output)
self.assertEqual(report['status'], 'ready')
self.assertEqual(report['acceptance']['state'], 'open')
run = self.base / 'fixture-result'
run.mkdir()
(run / 'raw.mkv').write_bytes(b'synthetic media, deliberately not decodable')
result = self.api().fixture_result(self.output, run, 'test-run',
'fresh-natural-ordinary', 'continuous', ['raw.mkv'])
self.assertEqual(result['evidence_kind'], 'synthetic')
target = self.base / 'test-imports'
imported = receipts.import_receipt(run / 'receipt.json', run, target)
actual = receipts.read_receipt(Path(imported['path']))
self.assertFalse(receipts.validate_receipt(actual, Path(imported['path']).parent)['accepted'])
self.assertEqual(receipts.identify_tree(self.original)['files'],
receipts.read_json(self.manifest)['files'])
def test_actual_package_and_resource_bytes_identified(self):
self.prepare()
manifest = receipts.read_json(self.output / 'manifest.json')
for rid, package in self.packages.items():
self.assertEqual(manifest['packages'][rid]['dll']['sha256'],
receipts.identify_file(package / 'GamePort.dll')['sha256'])
self.assertEqual(manifest['packages'][rid]['resources']['assets']['tree_sha256'],
receipts.identify_tree(package / 'assets')['tree_sha256'])
def test_original_change_rejected_before_output(self):
(self.original / 'Jimmy Neutron.exe').write_bytes(b'changed')
with self.assertRaises(ValueError): self.prepare()
self.assertFalse(self.output.exists())
def test_output_overlap_and_case_alias_rejected(self):
for output in (self.original, self.original / 'nested', self.base / 'original'):
with self.assertRaises(ValueError): self.prepare(output)
def test_output_symlink_rejected(self):
self.output.symlink_to(self.original, target_is_directory=True)
with self.assertRaises(ValueError): self.prepare()
def test_existing_output_never_reused(self):
self.prepare()
before = (self.output / 'manifest.json').read_bytes()
with self.assertRaises(ValueError): self.prepare()
self.assertEqual(before, (self.output / 'manifest.json').read_bytes())
def test_missing_binary_rejected(self):
self.prepare()
(self.output / 'port/win-x64/GamePort.dll').unlink()
with self.assertRaisesRegex(ValueError, 'GamePort.dll'): self.api().preflight(self.output)
def test_stale_binary_rejected(self):
self.prepare()
(self.output / 'port/win-x64/GamePort.dll').write_bytes(b'old binary')
with self.assertRaises(ValueError): self.api().preflight(self.output)
def test_missing_resources_rejected(self):
self.prepare()
(self.output / 'port/win-x64/assets/NewGame.tsk').unlink()
with self.assertRaises(ValueError): self.api().preflight(self.output)
def test_tampered_launcher_rejected(self):
self.prepare()
with (self.output / 'scripts/collect-fidelity-windows.ps1').open('a') as stream:
stream.write('\n#tamper')
with self.assertRaises(ValueError): self.api().preflight(self.output)
def test_tampered_fixture_media_import_rejected(self):
self.prepare()
run = self.base / 'result'
run.mkdir()
(run / 'raw.mkv').write_bytes(b'fixture')
self.api().fixture_result(self.output, run, 'test-media',
'fresh-natural-ordinary', 'continuous', ['raw.mkv'])
(run / 'raw.mkv').write_bytes(b'tampered')
with self.assertRaises(ValueError):
receipts.import_receipt(run / 'receipt.json', run, self.base / 'test-index')
def test_interrupted_assembly_preserves_diagnostics(self):
api = self.api()
with mock.patch.object(api, '_copy_file', side_effect=OSError('simulated interruption')):
with self.assertRaises(OSError): self.prepare()
self.assertFalse(self.output.exists())
self.assertTrue(list(self.base.glob('.checkpoint.incomplete-*')))
with self.assertRaises(ValueError): self.prepare()
def test_concurrent_assembly_has_one_winner(self):
self.prepare(self.base / 'seed') # seal inputs before the concurrent callers
def attempt(_):
try:
self.prepare()
return True
except (ValueError, FileExistsError):
return False
with concurrent.futures.ThreadPoolExecutor(max_workers=2) as pool:
self.assertEqual(list(pool.map(attempt, range(2))).count(True), 1)
def test_missing_local_dependency_is_actionable(self):
self.prepare()
report = self.api().preflight(self.output, dependencies={'dxwnd': self.base / 'missing.exe'})
self.assertEqual(report['status'], 'blocked')
self.assertIn('dxwnd', ' '.join(report['failures']))
self.assertEqual(report['acceptance']['state'], 'open')
def test_complete_session_materials_and_eighty_windows_obligations(self):
self.prepare()
for name in ('tests/fidelity-windows.Tests.ps1', 'docs/evidence/windows-session.md',
'protocol/annotation-template.json', 'protocol/settings-template.json'):
self.assertTrue((self.output / name).is_file(), 'complete session material missing: ' + name)
agenda = receipts.read_json(self.output / 'protocol/agenda.json')
self.assertEqual(len(agenda['runs']), 80)
self.assertEqual(len({r['case_id'] for r in agenda['runs']}), 8)
self.assertEqual(len({r['obligation_id'] for r in agenda['runs']}), 5)
self.assertEqual({r['side'] for r in agenda['runs']},
{'original-windows-dxwnd', 'port-windows-native'})
def test_package_copy_preserves_source_execution_permissions(self):
apphost = self.packages['linux-x64'] / 'GamePort'
apphost.chmod(0o755)
self.prepare()
copied = self.output / 'port/linux-x64/GamePort'
self.assertEqual(copied.stat().st_mode & 0o777, apphost.stat().st_mode & 0o777)
self.assertEqual(receipts.identify_file(copied), receipts.identify_file(apphost))
def test_skip_abort_remain_open_schema_valid_results(self):
self.prepare()
for status in ('skipped', 'aborted'):
run = self.base / status
run.mkdir()
record = self.api().fixture_result(self.output, run, 'test-' + status,
'fresh-skipped-edge', 'bank-left', [], status=status)
self.assertEqual(record['status'], status)
self.assertFalse(receipts.validate_receipt(record, run)['accepted'])
def test_prepared_materials_never_close_runtime_matrix(self):
self.prepare()
protocol = receipts.read_json(self.output / 'protocol/scenarios.json')
report = receipts.audit_receipt_tree(protocol, self.output / 'results')
self.assertEqual(report['accepted'], 0)
self.assertEqual(report['required'], 120)
self.assertFalse(report['complete'])
def test_synthetic_packages_rejected_for_real_checkpoint(self):
self.prepare()
with self.assertRaisesRegex(ValueError, 'Synthetic'):
self.api().prepare_checkpoint(self.original, self.manifest, self.packages,
self.base / 'runtime', tooling=False)
def test_tampered_ready_manifest_rejected(self):
self.prepare()
(self.output / 'manifest.json').write_text('{}')
with self.assertRaisesRegex(ValueError, 'Manifest'): self.api().preflight(self.output)
def test_added_immutable_material_rejected(self):
self.prepare()
(self.output / 'port/win-x64/unreviewed.exe').write_bytes(b'do not execute')
with self.assertRaisesRegex(ValueError, 'Unexpected'): self.api().preflight(self.output)
def test_mutable_results_allowed_without_weakening_materials(self):
self.prepare()
(self.output / 'results/raw.mkv').write_bytes(b'synthetic')
self.assertEqual(self.api().preflight(self.output)['status'], 'ready')
def test_unknown_case_scope_rejected(self):
self.prepare()
run = self.base / 'unknown-result'
run.mkdir()
with self.assertRaises(ValueError):
self.api().fixture_result(self.output, run, 'test-unknown', 'invented', 'continuous', [])
def test_symlink_ancestor_rejected_before_writes(self):
alias = self.base / 'alias'
target = self.base / 'target'
target.mkdir()
alias.symlink_to(target, target_is_directory=True)
with self.assertRaises(ValueError): self.prepare(alias / 'new')
self.assertFalse((target / 'new').exists())
if __name__ == '__main__':
unittest.main()
+328
View File
@@ -0,0 +1,328 @@
#!/usr/bin/env python3
"""Prepare immutable, local-only fidelity checkpoints. READY is never acceptance.
The Windows collector needs no Python or SDK. This module assembles/transfers
identities and imports explicitly synthetic fixture results; it never executes
an original. Cooperative locks/incomplete siblings are retained after failure.
"""
import argparse
import hashlib
import os
from pathlib import Path
import shutil
import subprocess
import sys
import uuid
from fidelity_receipts import (canonical_bytes, contained_path, identify_file,
identify_tree, read_json, relative_name, separated_roots, source_identity,
utc_now, validate_receipt, validate_scenario_contract, verify_inventory,
_id, _write_json)
from fidelity_review import export_review
PROJECT = Path(__file__).resolve().parents[2]
RIDS = ('linux-x64', 'win-x64')
FLAGS = ['--fidelity-output', '--fidelity-session', '--fidelity-case']
MAX_FILE_BYTES = 8 * 1024**3
MUTABLE = ('results', 'original-runs')
MATERIALS = ('scripts/collect-fidelity-windows.ps1',
'scripts/collect-fidelity-windows.cmd',
'tests/fidelity-windows.Tests.ps1', 'docs/evidence/windows-session.md')
def _copy_file(source, target):
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(source, target)
if identify_file(source) != identify_file(target):
raise ValueError('Source changed during copy: ' + str(source))
# Byte-identical Unix apphosts still need their source execution permission.
# Do not propagate setuid/setgid/sticky bits into a generated checkpoint.
target.chmod(Path(source).stat().st_mode & 0o777)
def _copy_tree(source, target):
tree = identify_tree(source)
target.mkdir(parents=True)
for entry in tree['files']:
if entry['size'] > MAX_FILE_BYTES:
raise ValueError('File exceeds 8 GiB bound: ' + entry['path'])
_copy_file(contained_path(source, entry['path']), target / entry['path'])
if identify_tree(target)['files'] != tree['files']:
raise ValueError('Copied tree differs: ' + str(source))
def _package_files(package):
return [f for f in identify_tree(package)['files'] if f['path'] != 'fidelity-build.json']
def seal_package(package, rid, source, tooling=False, build_argv=None):
"""Called immediately after the local publish by our wrapper, never on old DLLs.
Build source is captured BEFORE publishing and checked again afterward. This
record binds those claims to bytes, without pretending the hash proves their
compiler provenance. A synthetic seal is permanently tooling-only.
"""
package = Path(package)
if rid not in RIDS:
raise ValueError('Unsupported package RID')
required = ['GamePort.dll', 'GamePort.runtimeconfig.json', 'GamePort.deps.json',
'BUILD-INFO.txt', 'GamePort.exe' if rid == 'win-x64' else 'GamePort',
'SDL3.dll' if rid == 'win-x64' else 'libSDL3.so.0',
'assets/NewGame.tsk', 'scenes/level1b/scene.json', 'scenes/VR04/scene.json',
'scenes/level1/scene.json', 'scenes/animations/jimstop/animation.json']
for name in required:
identify_file(contained_path(package, name))
for name in ('assets', 'scenes', 'audio', 'Shaders'):
identify_tree(package / name)
if not tooling:
dll = (package / 'GamePort.dll').read_bytes()
if not all(flag.encode('utf-16le') in dll for flag in FLAGS):
raise ValueError('Stale DLL: observer flags absent')
if not build_argv or not source.get('commit') or not source.get('diff_sha256'):
raise ValueError('Missing actual pre-publish source/command identity')
record = {'schema_version': 1, 'rid': rid, 'source': source,
'built_utc': utc_now(), 'tooling_only': tooling,
'build_argv': build_argv or ['synthetic fixture, no compiler'],
'observer_flags': FLAGS, 'files': _package_files(package)}
_write_json(package / 'fidelity-build.json', record)
return record
def _package(package, rid, tooling):
record = read_json(package / 'fidelity-build.json')
if (record.get('schema_version') != 1 or record.get('rid') != rid or
record.get('observer_flags') != FLAGS or
record.get('files') != _package_files(package)):
raise ValueError('Stale/missing package bytes or observer identity: ' + rid)
if record.get('tooling_only') and not tooling:
raise ValueError('Synthetic package cannot qualify as runtime materials')
return {'build_info': identify_file(package / 'BUILD-INFO.txt'),
'build': {k: v for k, v in record.items() if k != 'files'},
'package_tree_sha256': hashlib.sha256(canonical_bytes(record['files'])).hexdigest(),
'dll': identify_file(package / 'GamePort.dll'),
'executable': identify_file(package / ('GamePort.exe' if rid == 'win-x64' else 'GamePort')),
'resources': {k: {'tree_sha256': identify_tree(package / k)['tree_sha256']}
for k in ('assets', 'scenes', 'audio', 'Shaders')}}
def prepare_checkpoint(original, original_manifest, packages, output, tooling=False):
unresolved = Path(output).absolute()
if any(p.is_symlink() for p in (unresolved, *unresolved.parents)):
raise ValueError('Checkpoint output cannot use symlink aliases')
original, output = separated_roots(original, output)
# Resolve aliases before allocating; reject symlink ancestry even for missing leaves.
candidate = Path(output)
if any(p.is_symlink() for p in (candidate, *candidate.parents)) or candidate.exists():
raise ValueError('Checkpoint output must be a fresh non-symlink directory')
separated_roots(PROJECT.parent / 'Original', output)
if set(packages) != set(RIDS):
raise ValueError('Both identified offline packages are required')
before = verify_inventory(original, original_manifest)
protocol = read_json(PROJECT / 'docs/evidence/scenarios.json')
validate_scenario_contract(protocol)
identities = {}
for rid in RIDS:
package = Path(packages[rid]).resolve(strict=True)
separated_roots(package, output)
identities[rid] = _package(package, rid, tooling)
# Every raw asset shipped by the package must match the original baseline.
if not tooling:
baseline = {f['path'].casefold(): f for f in before['files']}
for f in identify_tree(package / 'assets')['files']:
expected = baseline.get(f['path'].casefold())
if not expected or any(f[k] != expected[k] for k in ('sha256', 'size', 'header')):
raise ValueError('Package raw resource differs from original: ' + f['path'])
output.parent.mkdir(parents=True, exist_ok=True)
lock = output.with_name('.' + output.name.casefold() + '.lock')
try:
lock.mkdir()
except FileExistsError as error:
raise ValueError('Checkpoint reserved; inspect incomplete assembly, never steal lock') from error
temporary = output.with_name('.' + output.name + '.incomplete-' + uuid.uuid4().hex)
temporary.mkdir()
_write_json(temporary / 'incomplete.json', {'status': 'incomplete', 'started_utc': utc_now()})
# On failure retain both the diagnostic sibling and reservation.
_copy_tree(original, temporary / 'original-pristine')
for rid in RIDS:
_copy_tree(packages[rid], temporary / 'port' / rid)
for name in MATERIALS:
if (PROJECT / name).is_file():
_copy_file(PROJECT / name, temporary / name)
else:
raise ValueError('Missing collector material: ' + name)
_copy_file(original_manifest, temporary / 'protocol/original-manifest.json')
for name in ('scenarios.json', 'capabilities.json'):
_copy_file(PROJECT / 'docs/evidence' / name, temporary / 'protocol' / name)
export_review(None, None, temporary / 'review', PROJECT / 'docs/evidence/capabilities.json')
for name in MUTABLE:
(temporary / name).mkdir()
# All 80 Windows obligations are prepared; Linux's remaining40 use the same protocol.
agenda = [{'side': side, 'case_id': cell['id'], 'obligation_id': obligation,
'status': 'pending'} for side in ('original-windows-dxwnd', 'port-windows-native')
for cell in protocol['cells'] for obligation in cell['obligations']]
_write_json(temporary / 'protocol/agenda.json', {'schema_version': 1,
'runs': agenda, 'acceptance': {'state': 'open', 'required_all_platforms': 120}})
_write_json(temporary / 'protocol/settings-template.json', {
'schema_version': 1, 'diagnostic': True,
'tools': {k: {'source': '', 'version': '', 'settings': ''}
for k in ('dxwnd', 'recorder', 'browser', 'media_probe', 'derivation')},
'capture': {'source': '', 'monitor': '', 'crop': [], 'aspect': '',
'resolution': [], 'frame_rate': '', 'audio_devices': [],
'encoder': '', 'container': 'MKV', 'timing_limitations': ''},
'preflight': {'original': {'visible_moving_game': False, 'intelligible_game_audio': False,
'correct_crop_aspect': False},
'port': {'visible_moving_game': False, 'intelligible_game_audio': False,
'correct_crop_aspect': False},
'browser': {'actual_playback': False, 'seeking': False,
'exclusive_audio': False}},
'notes': 'Fill actual observed values; false/empty fields remain pending, never acceptance.'})
_write_json(temporary / 'protocol/annotation-template.json', {
'schema_version': 1, 'status': 'incomplete', 'diagnostic': True,
'artifacts': [], 'events': [], 'derivatives': [], 'continuity': {},
'limitations': ['Actual media clocks, uncertainty and human review still required'],
'notes': 'Use windows-session.md field contract; empty template cannot finalize capture.'})
verify_inventory(original, original_manifest)
(temporary / 'incomplete.json').unlink()
files = identify_tree(temporary)['files']
manifest = {'schema_version': 1, 'checkpoint_id': output.name,
'created_utc': utc_now(), 'tooling_only': tooling, 'packages': identities,
'original_manifest': identify_file(original_manifest),
'original_pre': {'tree_sha256': before['tree_sha256'], 'count': len(before['files'])},
'files': files, 'mutable_roots': list(MUTABLE),
'acceptance': {'state': 'open', 'remaining': ['Actual original/native captures and human review']}}
_write_json(temporary / 'manifest.json', manifest)
_write_json(temporary / 'READY.json', {'schema_version': 1, 'status': 'prepared',
'manifest': dict(path='manifest.json', **identify_file(temporary / 'manifest.json')),
'acceptance': {'state': 'open'}, 'meaning': 'Materials prepared only; no runtime acceptance'})
preflight(temporary)
if output.exists():
raise ValueError('Output allocated concurrently')
os.rename(temporary, output)
lock.rmdir()
return manifest
def preflight(root, dependencies=None):
root = Path(root)
if root.is_symlink():
raise ValueError('Checkpoint root cannot be a symlink')
ready = read_json(root / 'READY.json')
if ready.get('schema_version') != 1 or ready.get('status') != 'prepared':
raise ValueError('Checkpoint is incomplete, not READY')
actual = identify_file(root / 'manifest.json')
if any(ready['manifest'].get(k) != actual[k] for k in ('sha256', 'size')):
raise ValueError('Manifest identity differs from READY')
manifest = read_json(root / 'manifest.json')
expected = {item['path']: item for item in manifest['files']}
for name, item in expected.items():
actual = identify_file(contained_path(root, name))
if any(item[k] != actual[k] for k in ('sha256', 'size', 'header')):
raise ValueError('Tampered checkpoint material: ' + name)
# Permit only owned result/copy directories to grow after publication.
for directory, dirs, names in os.walk(root, followlinks=False):
for name in dirs + names:
path = Path(directory) / name
relative = path.relative_to(root).as_posix()
if path.is_symlink():
raise ValueError('Symlink in checkpoint: ' + relative)
if path.is_file() and relative.split('/')[0] not in MUTABLE:
if relative not in expected and relative not in ('READY.json', 'manifest.json'):
raise ValueError('Unexpected immutable material: ' + relative)
failures = []
tools = {}
for label, path in (dependencies or {}).items():
try:
tools[label] = dict(path=str(Path(path).resolve()), **identify_file(path))
except (ValueError, OSError):
failures.append('Missing local dependency ' + label + ': select an existing local file (' + str(path) + ')')
return {'schema_version': 1, 'status': 'blocked' if failures else 'ready',
'checked_files': len(expected), 'tooling_only': manifest['tooling_only'],
'tools': tools, 'failures': failures, 'acceptance': {'state': 'open'}}
def fixture_result(bundle, run, session_id, case_id, scope, artifacts, status='captured'):
"""Tooling-only end-to-end importer fixture; cannot mint native evidence."""
preflight(bundle)
if status not in ('captured', 'failed', 'skipped', 'aborted'):
raise ValueError('Unknown fixture result status')
_id(session_id)
protocol = read_json(Path(bundle) / 'protocol/scenarios.json')
if case_id not in {c['id'] for c in protocol['cells']} or scope not in protocol['obligations']:
raise ValueError('Unknown case/scope')
run = Path(run)
items = [dict(path=str(relative_name(p)), role='diagnostic', synthetic=True,
**identify_file(contained_path(run, p))) for p in artifacts]
receipt = {'schema_version': 1, 'receipt_id': session_id, 'session_id': session_id,
'case_id': case_id, 'obligation_id': scope, 'scope': scope,
'evidence_kind': 'synthetic', 'status': status, 'historical': False,
'platform': {'os': 'test', 'execution': 'synthetic'}, 'identity': {},
'invocation': {'argv': ['fixture result; no executable launched'], 'cwd': str(run)},
'clocks': {'wall_start': utc_now(), 'wall_end': utc_now(),
'monotonic_start': 0, 'monotonic_end': 0},
'artifacts': items, 'derivatives': [], 'events': [],
'limitations': ['Synthetic tooling only'], 'missing_evidence': ['No native/reference execution'],
'acceptance': {'state': 'open', 'remaining': ['Actual identified captures and human review']}}
validate_receipt(receipt, run)
_write_json(run / 'receipt.json', receipt)
return receipt
def publish_packages(output, base):
"""Isolated equivalent of existing builds, preserving historical dist packages."""
output, base = Path(output).resolve(), Path(base).resolve()
if output.exists():
raise ValueError('Publish root must be fresh')
separated_roots(base, output)
source = source_identity(PROJECT)
output.mkdir(parents=True)
for rid in RIDS:
target = output / rid
_copy_tree(base / rid, target)
# The old note identifies historical resource packaging, not this compilation.
(target / 'BUILD-INFO.txt').rename(target / 'RESOURCE-BASE-BUILD-INFO.txt')
old_seal = target / 'fidelity-build.json'
if old_seal.exists():
old_seal.unlink()
argv = ['dotnet', 'publish', 'GamePort.csproj', '-c', 'Release', '-r', rid,
'--self-contained', 'true', '--no-restore', '-o', str(target)]
subprocess.run(argv, cwd=PROJECT, check=True, timeout=600)
if source_identity(PROJECT) != source:
raise ValueError('Source changed during publish; preserve diagnostics and republish')
(target / 'BUILD-INFO.txt').write_text('source_commit=' + source['commit'] +
'\nsource_dirty=' + ('yes' if source['dirty'] else 'no') +
'\nsource_diff_sha256=' + source['diff_sha256'] + '\npublished_utc=' + utc_now() + '\n')
seal_package(target, rid, source, build_argv=argv)
return {'status': 'published', 'output': str(output), 'source': source}
def main():
parser = argparse.ArgumentParser(description=__doc__)
sub = parser.add_subparsers(dest='command', required=True)
prepare = sub.add_parser('prepare')
prepare.add_argument('--original', type=Path, default=PROJECT.parent / 'Original')
prepare.add_argument('--original-manifest', type=Path, default=PROJECT / 'docs/original-manifest.json')
prepare.add_argument('--packages', type=Path, required=True)
prepare.add_argument('--output', type=Path, required=True)
check = sub.add_parser('preflight')
check.add_argument('--checkpoint', type=Path, required=True)
publish = sub.add_parser('publish')
publish.add_argument('--output', type=Path, required=True)
publish.add_argument('--base', type=Path, default=PROJECT / 'dist')
args = parser.parse_args()
try:
if args.command == 'prepare':
result = prepare_checkpoint(args.original, args.original_manifest,
{rid: args.packages / rid for rid in RIDS}, args.output)
print('Prepared checkpoint; acceptance OPEN; files:', len(result['files']))
elif args.command == 'publish':
print(canonical_bytes(publish_packages(args.output, args.base)).decode())
else:
print(canonical_bytes(preflight(args.checkpoint)).decode())
return 0
except (ValueError, OSError, subprocess.SubprocessError) as error:
print('Checkpoint failed (acceptance OPEN): ' + str(error), file=sys.stderr)
return 2
if __name__ == '__main__':
sys.exit(main())
+340
View File
@@ -0,0 +1,340 @@
#!/usr/bin/env python3
"""Local Linux Codex quota watcher. No model starts, auth-file reads, or commits."""
import argparse
import base64
import contextlib
import hashlib
import json
import math
import os
from pathlib import Path
import socket
import struct
import subprocess
import sys
import time
try:
import fcntl
except ImportError: # Keep repository-wide Python test discovery portable.
fcntl = None
ROOT = Path(__file__).resolve().parents[2]
STATE = ROOT / 'artifacts/gsd-quota'
PAUSE = ('The user enabled the GamePort quota guard. Five-hour quota has reached '
'15% remaining or less. Stop dispatching new work. Reach the nearest safe '
'checkpoint, preserve partial/unverified edits without committing them, '
'and use $gsd-pause-work to save the exact continuation. End the turn after '
'saving. Do not wait in a model loop or resume automatically.')
def atomic(path, value):
path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
temp = path.with_name(path.name + '.' + str(os.getpid()) + '.tmp')
fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
with os.fdopen(fd, 'w') as out:
json.dump(value, out, indent=2)
os.replace(temp, path)
def read(path, default=None):
try:
return json.loads(path.read_text())
except (OSError, ValueError):
return default
class RPC:
"""Bounded RFC6455 client for the existing Unix app-server socket."""
def __init__(self, path=None):
self.sock = socket.socket(socket.AF_UNIX)
self.sock.settimeout(6)
self.buffer = b''
self.sequence = 0
try:
self.sock.connect(str(path or Path(os.environ.get('CODEX_HOME', Path.home() / '.codex')) /
'app-server-control/app-server-control.sock'))
key = base64.b64encode(os.urandom(16)).decode()
self.sock.sendall(('GET / HTTP/1.1\r\nHost: localhost\r\nUpgrade: websocket\r\n'
'Connection: Upgrade\r\nSec-WebSocket-Version: 13\r\n'
f'Sec-WebSocket-Key: {key}\r\n\r\n').encode())
while b'\r\n\r\n' not in self.buffer:
self.receive()
if len(self.buffer) > 16384:
raise ValueError('Oversized handshake')
header, self.buffer = self.buffer.split(b'\r\n\r\n', 1)
expected = base64.b64encode(hashlib.sha1(
(key + '258EAFA5-E914-47DA-95CA-C5AB0DC85B11').encode()).digest())
if not header.startswith(b'HTTP/1.1 101 ') or expected.lower() not in header.lower():
raise ValueError('Invalid WebSocket handshake')
self.call('initialize', {'clientInfo': {'name': 'gameport-quota-guard', 'version': '1.0'}})
self.send({'method': 'initialized'})
except Exception:
self.close()
raise
def close(self):
self.sock.close()
def receive(self):
part = self.sock.recv(65536)
if not part:
raise EOFError('Codex daemon closed connection')
self.buffer += part
def take(self, size):
while len(self.buffer) < size:
self.receive()
result, self.buffer = self.buffer[:size], self.buffer[size:]
return result
def frame(self, payload, opcode=1):
mask = os.urandom(4)
size = len(payload)
length = bytes([size | 128]) if size < 126 else b'\xfe' + struct.pack('!H', size)
self.sock.sendall(bytes([128 | opcode]) + length + mask +
bytes(c ^ mask[i % 4] for i, c in enumerate(payload)))
def send(self, obj):
self.frame(json.dumps(obj).encode())
def message(self):
result = b''
while True:
first, second = self.take(2)
length = second & 127
if length == 126:
length = struct.unpack('!H', self.take(2))[0]
elif length == 127:
length = struct.unpack('!Q', self.take(8))[0]
if second & 128 or length + len(result) > 2**20:
raise ValueError('Unsupported or oversized server frame')
payload = self.take(length)
opcode = first & 15
if opcode == 8:
raise EOFError('WebSocket closed')
if opcode == 9:
self.frame(payload, 10)
continue
if opcode == 10:
continue
if opcode not in (0, 1):
raise ValueError('Unsupported WebSocket opcode')
result += payload
if first & 128:
return json.loads(result)
def call(self, method, params):
self.sequence += 1
ident = self.sequence
self.send({'id': ident, 'method': method, 'params': params})
deadline = time.monotonic() + 10
while time.monotonic() < deadline:
response = self.message()
if response.get('id') != ident:
continue
if 'error' in response:
raise RuntimeError(str(response['error'].get('code', 'RPC error')))
return response.get('result', {})
raise TimeoutError('RPC deadline exceeded')
def quota(result, now):
buckets = result.get('rateLimitsByLimitId')
# Do not let unused specialty-model buckets override the general Codex quota.
if isinstance(buckets, dict) and 'codex' in buckets:
snapshots = [buckets['codex']]
else:
snapshots = [result.get('rateLimits', {})]
candidates = []
for snapshot in snapshots:
for name in ('primary', 'secondary'):
window = (snapshot or {}).get(name) or {}
used, reset = window.get('usedPercent'), window.get('resetsAt')
if (window.get('windowDurationMins') == 300 and
isinstance(used, (int, float)) and not isinstance(used, bool) and
math.isfinite(used) and 0 <= used <= 100 and
isinstance(reset, (int, float)) and reset > now):
candidates.append({'remaining': 100 - used, 'resetsAt': reset})
if not candidates:
raise ValueError('No current, complete 300-minute quota window')
return dict(min(candidates, key=lambda x: x['remaining']), checkedAt=now)
def stage(sample, now):
if not sample or now - sample.get('checkedAt', 0) > 180 or sample.get('resetsAt', 0) <= now:
return 'unknown'
remaining = sample['remaining']
return 'pause' if remaining <= 15 else 'drain' if remaining <= 20 else 'ready'
def snapshot(sample):
"""Preserve a separate recovery record; never replace the detailed GSD handoff."""
previous = read(STATE / 'snapshot.json', {})
# Server reset estimates can move by a second between reads.
if abs(previous.get('resetsAt', 0) - sample['resetsAt']) <= 120:
return
folder = STATE / ('recovery-' + str(int(sample['resetsAt'])))
if (folder / 'record.json').exists():
return
folder.mkdir(parents=True, exist_ok=True, mode=0o700)
def git(*args):
# Bounded output, tracked source only; no originals/untracked asset copies.
with subprocess.Popen(['git', *args], cwd=ROOT, stdout=subprocess.PIPE,
stderr=subprocess.DEVNULL) as proc:
data = proc.stdout.read(2**21 + 1)
if len(data) > 2**21:
proc.kill()
proc.wait(timeout=10)
return {'text': data[:2**21].decode('utf-8', 'replace'), 'truncated': len(data) > 2**21}
atomic(folder / 'record.json', {
'savedAt': time.time(), 'quota': sample, 'head': git('rev-parse', 'HEAD'),
'status': git('status', '--short'), 'trackedPatch': git('diff', 'HEAD', '--no-ext-diff', '--no-textconv'),
'gsd': {str(p.relative_to(ROOT)): p.read_text()[:262144] for p in
(ROOT / '.planning/HANDOFF.json', ROOT / '.planning/STATE.md') if p.is_file()},
'limits': 'Tracked patch capped at 2 MiB; untracked contents remain in working tree. '
'This recovery record supplements the canonical GSD handoff.'})
atomic(STATE / 'snapshot.json', {'resetsAt': sample['resetsAt'], 'path': str(folder)})
def dispatch(tool):
return tool.split('__')[-1].split('.')[-1] in ('Agent', 'spawn_agent', 'followup_task')
def hook_response(event, tool, sample, now):
level = stage(sample, now)
if event == 'PreToolUse' and dispatch(tool) and level != 'ready':
return {'hookSpecificOutput': {'hookEventName': event, 'permissionDecision': 'deny',
'permissionDecisionReason': f'Quota guard: {level}. No new agent work until '
'fresh five-hour quota is above 20%. Save a checkpoint if at 15% or less.'}}
if event in ('PreToolUse', 'PostToolUse') and level == 'pause':
return {'hookSpecificOutput': {'hookEventName': event, 'additionalContext': PAUSE}}
return {}
def handle_hook(payload):
event = payload.get('hook_event_name')
if event in ('PreModelRequest', 'UserPromptSubmit'):
register(payload)
sample = read(STATE / 'quota.json')
response = hook_response(event, payload.get('tool_name', ''), sample, time.time())
output = response.get('hookSpecificOutput', {})
if 'additionalContext' in output:
# One reminder per turn/window; tool denials are never suppressed.
key = str(payload.get('turn_id'))
marker = STATE / 'context' / (hashlib.sha256(key.encode()).hexdigest() + '.json')
if marker.exists():
return {}
atomic(marker, {'at': time.time()})
return response
def register(payload):
# Per-thread files avoid races between root and child hooks. Never infer turns.
thread = payload.get('agent_id') or payload.get('session_id')
turn = payload.get('turn_id')
if isinstance(thread, str) and isinstance(turn, str) and thread and turn:
ident = hashlib.sha256(thread.encode()).hexdigest()
atomic(STATE / 'threads' / (ident + '.json'),
{'threadId': thread, 'turnId': turn, 'seenAt': time.time()})
def tick():
with contextlib.closing(RPC()) as rpc:
sample = quota(rpc.call('account/rateLimits/read', {}), time.time())
atomic(STATE / 'quota.json', sample)
if stage(sample, time.time()) == 'pause':
snapshot(sample)
for path in (STATE / 'threads').glob('*.json'):
target = read(path, {})
if time.time() - target.get('seenAt', 0) > 86400:
continue
key = f"{target.get('threadId')}:{target.get('turnId')}"
marker = STATE / 'sent' / (hashlib.sha256(key.encode()).hexdigest() + '.json')
if marker.exists():
continue
try:
rpc.call('turn/steer', {'threadId': target['threadId'],
'expectedTurnId': target['turnId'],
'input': [{'type': 'text', 'text': PAUSE}]})
atomic(marker, {'sentAt': time.time()})
except RuntimeError:
# Inactive/wrong turn: no new turn, no interrupt, no costly retry loop.
atomic(marker, {'inactiveAt': time.time()})
return sample
def start():
STATE.mkdir(parents=True, exist_ok=True, mode=0o700)
with open(STATE / 'watch.lock', 'a') as lock:
try:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
return
with open(STATE / 'watch.log', 'ab') as log:
os.chmod(STATE / 'watch.log', 0o600)
subprocess.Popen([sys.executable, str(Path(__file__).resolve()), 'watch'],
cwd=ROOT, stdin=subprocess.DEVNULL, stdout=log, stderr=log,
start_new_session=True, close_fds=True)
def watch():
STATE.mkdir(parents=True, exist_ok=True, mode=0o700)
with open(STATE / 'watch.lock', 'a') as lock:
try:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
return
stop = STATE / 'stop'
stop.unlink(missing_ok=True)
atomic(STATE / 'watcher.json', {'pid': os.getpid(), 'startedAt': time.time()})
while not stop.exists():
try:
tick()
(STATE / 'error.json').unlink(missing_ok=True)
except (OSError, ValueError, RuntimeError, EOFError, TimeoutError) as error:
atomic(STATE / 'error.json', {'at': time.time(), 'type': type(error).__name__})
for _ in range(60):
if stop.exists():
return
time.sleep(1)
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('command', choices=['hook', 'watch', 'start', 'stop', 'status', 'refresh'])
args = parser.parse_args()
if fcntl is None:
parser.error('The quota watcher runs on the Linux Codex host only.')
if args.command == 'hook':
payload = json.load(sys.stdin)
if not Path(payload.get('cwd', '')).resolve().is_relative_to(ROOT):
return
start()
print(json.dumps(handle_hook(payload)))
elif args.command == 'watch':
watch()
elif args.command == 'start':
start()
elif args.command == 'stop':
STATE.mkdir(parents=True, exist_ok=True, mode=0o700)
(STATE / 'stop').touch(mode=0o600)
elif args.command == 'refresh':
print(json.dumps(tick()))
else:
sample = read(STATE / 'quota.json')
running = False
if (STATE / 'watch.lock').exists():
with open(STATE / 'watch.lock', 'a') as lock:
try:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
running = True
print(json.dumps({'stage': stage(sample, time.time()), 'quota': sample,
'running': running,
'watcher': read(STATE / 'watcher.json'),
'error': read(STATE / 'error.json')}))
if __name__ == '__main__':
main()