Skip to content

About

Read-only Windows diagnostic tool for observing Codex-related process activity and collecting bounded evidence before conclusions.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Codex Resource Audit

Product maturity: EXPERIMENTAL. Public and usable within the documented scope; behavior and contracts may evolve. CRA is not production-ready and carries no stable support guarantee. External testing is welcome within that scope; organized Community Beta promotion remains subject to the beta gate. CRA is an independent project, not officially supported or endorsed by OpenAI.

Maintenance: ACTIVE - BEST EFFORT. Issues and reviews are handled as maintainer time permits, with no SLA or guaranteed response/fix time. Maturity and maintenance status are separate from test/CI results. Public availability is not stable status, a CI pass is not production readiness, and T17 availability is not a support guarantee.

Support | Security reporting | Contributing | Compatibility | Version policy

Codex Resource Audit (CRA) is a Windows-first, read-only evidence tool for observing Codex-related process activity, with safe local AI-assisted interpretation.

When Codex feels stuck or process behavior looks unusual, CRA captures bounded process evidence around an activity. It gives you evidence before conclusions: what was observed, what remains unknown, and what to investigate next. You retain control of target selection and every timing confirmation.

Choose a version before starting

For general use, choose the published v0.2.0-beta.7 prerelease. GitHub's release record and remote annotated tag were checked on 2026-10-13: published 2026-09-23, draft=false, prerelease=true, both resolving to commit 8beed2d0824a7bfcd464dc810359f5e9ac73f1a7. This is a fixed experimental version, not a production-readiness claim.

Capability Fixed beta.7 Moving main at reviewed commit 9633113e74756661d8a9d98ba0676716e0dbdaf6
T17 Incident Observation / AI-assisted bridge Historical Incident v1 workflow, with O0/O1/O2/O3 and first-run recovery. New Incident v2 is RELEASE_GATED; ordinary new Incident observation is unavailable.
Standalone T18.2A CPU Activity Check Implemented; historical Windows live-validation evidence is recorded below. Same CPU runtime as beta.7; independent of the Incident gate.
Manual candidates, Finder and Session Available within their separate eligibility and verification rules. Available within their separate rules; the Incident gate is not a product-wide shutdown.
T18.2B Memory Trend, T18.3 AI interpretation and T18.1 runtime ingestion Not implemented. Not implemented.

Do not start the main Incident flow or select candidates expecting to Observe. Its production collection profile is unset, so it stops with INCIDENT_POLICY_RELEASE_GATED before O0. Benchmark B1/B2/B3 are not production profiles or a user workaround. Main does not silently fall back to Incident v1; historical v1 reader compatibility does not enable new v1 runs. Use a separate, matching beta.7 checkout if you want its historical Incident workflow. These statements apply to the reviewed main commit, not all future main revisions. See compatibility and evidence limits.

Beta.7 first-run recovery: one milestone combines safe Skill replacement, same-request STEP 2 typo correction, copy-safe launch, OutputDirectory recovery guidance, direct AI safe-reader operation and safe request-context reuse. Human choices and the read-only safety model remain intact. Use matching Skill and runtime from the same checkout. See the beta.7 release notes.

When to use CRA

Use CRA when you can reproduce a process-behavior question or already have safe CRA evidence to interpret. A new observation cannot reconstruct a finished task without retained evidence. CRA does not automatically diagnose a hang, prove a Codex bug, or fix the problem.

Codex looks stuck or process activity looks unusual? Start with Incident Observation / Use with Codex. CRA can present bounded candidates and evidence, but it does not decide which process is "bad." You retain target selection; that is a safety boundary, not a missing automatic-diagnosis feature. The CPU Activity Check is a separate bounded diagnostic for one process you already selected independently. Finder, Session and T17/T18 contract details remain available below as advanced references.

Your goal Start here
Ask Codex to help inspect a stuck/slow workflow or unusual process activity Use with Codex from fixed beta.7: Incident Observation with the matching cra-incident Skill.
Manually inspect candidates or use advanced workflows Manual Guided: Finder and Session where eligible; Observe requires a version with an available Incident runtime.
Work with stronger verified-root / Session evidence requirements Advanced Session: a separate manual workflow, with its own verification requirements.
Receive a PowerShell object for an operator-run Incident observation PowerShell structured-result API.
Measure bounded CPU-time changes for one process you independently select CPU Activity Check: a separate Windows operator workflow, not AI-assisted Incident continuation.

The AI-assisted path supports Incident Observation only. Finder and Session are not AI-callable.

Quick Start

Requirements: Windows, Git for the clone example, PowerShell 7 (pwsh), and local Codex on the same machine for AI-assisted use. Run live observation or the CPU Activity Check in your own interactive PowerShell 7 ConsoleHost, outside Codex's execution environment.

Get the fixed beta or moving source

Use the verified fixed v0.2.0-beta.7 checkout for the Incident instructions below. Choose a parent directory in your own terminal and run:

git clone --branch v0.2.0-beta.7 `
  https://github.com/Robinlee0929/codex-resource-audit.git
cd codex-resource-audit
git rev-parse HEAD

Expected HEAD: 8beed2d0824a7bfcd464dc810359f5e9ac73f1a7.

For moving development/latest source, use --branch main instead and report the actual commit when possible. At the reviewed main commit, Incident v2 remains release-gated; choose main for development or its independent available workflows, not a new Incident observation. Use the Skill, bridge and runtime from the same checkout; do not mix files from main or another fixed/archive version. Every published beta should be used with its matching checkout, while main continues to move. See the version policy.

Product implementation acceptance: FIRST_RUN_RECOVERY_BATCH at 996996e58056245e8784e4db3dc7abd248f407e9 passed 1900/1900 local offline tests and exact-SHA Hosted Windows CI. Robin reported clean-clone acceptance PASS. These results belong to that product commit; they do not certify later documentation-only release-preparation bytes or a different release-target SHA. See the validation record.

Historical CPU validation baseline: the T18.2A implementation baseline ef450c2679e38eb380278861adc66e4c9ab0c50e passed local and Hosted Windows CI, 1859/1859 tests. Sanitized Windows live validation also passed its normal 5-second, maximum 60-second and process-exit runs. This records a verified baseline; it is not a release tag, benchmark, production-readiness claim or guarantee about future commits on main.

Prepare Codex

  1. Open/work in the CRA checkout in local Codex, or explicitly provide its absolute repository root.

  2. Setup request — ask Codex to deploy the repository Skill (this does not start an observation):

    Set up this checkout's skills/cra-incident/SKILL.md in your configured local user-Skill root. If absent, install and verify SHA-256; if identical, do not replace. If different, stop ordinary installation and show the source/destination paths and hashes plus a proposed backup outside Skill discovery locations. Explain possible custom changes and ask for explicit replacement authorization. Follow FIRST_RUN's backup, recheck, replacement and recognition steps. Do not modify global configuration or start observation.

  3. On the next Codex turn, confirm cra-incident appears in its available Skill list and that the matching deployed instructions are in use. Reload or start a new conversation when needed. A listed name alone does not prove the replacement loaded. Use the first-run guide before starting observation; a Skill mismatch invalidates version-specific UX acceptance.

The repository Skill is canonical; the installed copy is deployment only. The installed directory is never used to infer the CRA repository root. Codex validates the current Git workspace or an explicit root against CRA's required files.

Use with Codex

Version check first: these new-observation instructions apply to fixed beta.7's Incident v1 workflow. Do not launch the bridge from reviewed main for an Incident; its v2 release gate remains closed. Use the Skill, bridge and runtime from the same selected checkout; changing checkouts is an explicit version choice, not a fallback within an existing request.

Observation request — after Skill recognition succeeds, ask separately:

Use cra-incident to help me inspect Codex-related process activity while I reproduce my task.

Codex explains the workflow and gives you a complete copy/paste PowerShell command with your actual paths. You do not need to compose the long bridge command. You run it manually in your own PowerShell 7 console.

For a genuinely new invocation, first preserve any previous request's complete safe tuple (OutputDirectory, request_id, candidate_set_id) if still needed. Codex then supplies single-quoted literal assignments for $RepoRoot and $OutputDirectory using your validated real checkout and agreed fresh destination; embedded apostrophes are doubled, and path text is never evaluated. Set these variables in your own PowerShell window, clear stale $receipt, then launch:

This starts read-only evidence collection; it does not kill, suspend, restart, clean up or modify processes.

$receipt = $null
$receipt = & (Join-Path $RepoRoot 'scripts/Invoke-CraAiBridge.ps1') `
  -OutputDirectory $OutputDirectory

The output directory's parent must already exist, and the per-request directory must not exist. The bridge creates it and generates the IDs; OutputDirectory is its only feature parameter. The directory permanently belongs to that request, even after cancellation/failure: do not delete or reuse it. A new observation requires a new directory, fresh IDs/discovery and new human choices.

Share the CRA AI request_id=... candidate_set_id=... line and agreed directory with Codex once. Codex reuses that complete context for validated artifact reads. Never clear $receipt or replace the active $OutputDirectory during STEP 2 correction, same-request troubleshooting, artifact reading or active recovery. If you miss the safe line, no rerun is required: use the context recovery instructions.

How the observation works

Before STEP 2, decide which real application/process instance you intend to inspect. Review once, compare once, then choose: STEP 2 puts all still-plausible same-name candidates into one review set; STEP 3 compares them side by side locally; STEP 4 is the human target choice. Do not run repeated observations to test candidates one by one. Review membership does not mean a candidate is correct and does not authorize Observe.

  1. You choose candidates for review in PowerShell. STEP 3 then shows additional local comparison evidence, including PID and Creation Time UTC. Compare both with independent current information about the instance you intend to inspect. Do not choose by name, READY, ordering, group or PID alone; creation time does not establish ownership.
  2. At STEP 4, the human chooses exactly one candidate from the STEP 2 review set. This is the target-selection point, but it is not VERIFIED_ROOT. You then choose O/OBSERVE. Codex can explain the safe candidate/review artifact fields and their limits, but it cannot see the local PID/Creation Time comparison or make or recommend these choices. If you still cannot distinguish the intended instance at STEP 4, enter Q to cancel instead of guessing.
  3. CRA checks the target at O0. O0 is the starting identity check and baseline capture. Only MATCHED allows the observation to continue.
  4. Start or continue the activity, then enter O1 while it is running. This requests the during-activity capture. After O1 returns and the activity finishes, personally enter ACTIVITY_END.
  5. CRA captures O2, waits 30 seconds, then captures O3. These are the immediate and later follow-up observations; the wait is not a total-runtime guarantee.
  6. Codex reads and explains the safe final result. It describes recorded observations and unknowns, without turning them into ownership or leak claims.

STEP 2 typo recovery in the bridge/PassThru path: an invalid string accepts nothing. Re-enter the COMPLETE review set at the same prompt, or Q/QUIT to cancel. The request, directory, IDs and discovery stay the same; no partial set is retained and no review artifact is published before acceptance. After valid acceptance, STEP 2 is not re-entered. Reader failures and later target/action failures retain their existing stop behavior. Manual Guided/Session/Finder behavior is unchanged.

Codex can guide you, explain readiness and summarize safe evidence. It cannot drive interactive PowerShell, launch the wrapper, select a target, confirm on your behalf, enter O1/ACTIVITY_END, write back control commands, or kill/clean up processes. It cannot establish Incident ownership or decide that an observed process is residue or a leak.

What Codex reads

Safe artifact Purpose
candidate.json Available candidates and readiness for your review.
review.json The candidates you chose to review; it does not imply target selection or consent to Observe.
final_result.json The retained observation result, including incomplete or stopped outcomes.

Artifacts are one-way data, not AI control messages. Candidate/review artifacts do not expose PID, Creation Time UTC, executable path, parent information, command line or user/session context. Codex uses the existing safe reader with your explicit request context and validates versions and correlation. Missing or invalid evidence stops interpretation; a delivered file alone is not observation success. Do not paste private process tables or terminal transcripts. Reader and failure details.

When local execution/file access permits, Codex runs the existing safe reader itself. You normally do not invoke Read-CraAiArtifact, parse JSON, format observed_context, or paste raw artifacts. If the client lacks that capability, Codex explains the limitation without claiming validation or using raw JSON as a fallback. It asks for context again only when missing, ambiguous, stale or mismatched; the IDs are correlation, not authentication or authorization.

What the evidence means — and does not prove

Snapshots describe captures, not everything between them. An empty transition list does not prove no activity or no process creation/exit.

Evidence Safe interpretation and limit
NEWLY_OBSERVED First observed in this Incident history at that stage; not proof it was created by Codex/task.
NO_LONGER_OBSERVED Previously observed identity absent from a later capture; not proven process exit or cleanup success.
PRESENT at O3 Observed at that follow-up capture; not residue, orphan, leak or continuous presence between captures.
OBSERVED_PARENT_CHILD Reported stage-specific relationship; not ownership or causation.
Role hint Name-based hint only; not actual purpose or ownership.
Working set Point-in-time measurement; not task cost or proof of a memory leak. Unknown/unavailable is not zero.
Same PID Insufficient by itself to establish the same exact identity.
COMPLETED CRA's execution outcome; not proof that your problem is solved or a bug is confirmed.
Incident-derived ownership = UNKNOWN
Incident lifecycle = NOT_APPLICABLE
Observation != VERIFIED_ROOT
UNKNOWN != CODEX

These are Incident semantic boundaries. Candidate C labels belong only to one discovery, and P labels only to one result; do not join them across runs. The T17.1 contract defines the full semantics.

After CRA — what next?

Use the result to choose a possible next read-only diagnostic direction, not an automatic diagnosis. Start with the beginner decision table for symptom-to-next-step guidance:

  • No meaningful transition recorded: process lifecycle may not be the most useful first hypothesis, but short-lived activity could have been missed. Depending on the symptom, inspect CPU activity, I/O, application logs, network behavior or handles with separate tools.
  • An identity first appears late: consider a separate repeat or later observation before drawing persistence conclusions; do not extend or alter the current run's schedule.
  • An identity is PRESENT at O3: report that observation. If persistence matters, use a separate follow-up observation and other telemetry, without treating C/P labels as cross-run identities.
  • Many helpers are already present at O0: this weakens a simple creation-by-this-reproduction hypothesis only if that reproduction began after O0. It proves neither who created them nor what they do.
  • Working-set concern: gather repeated or continuous memory measurements using separate tools. One captured change cannot establish task cost or a leak.
  • O0 continuity fails: stop this attempt; any retry requires fresh discovery and new human choices. Do not silently retarget.

CRA now provides a separate bounded CPU Activity Check for one independently selected process. I/O, handle, network and continuous memory monitoring remain external/future directions. The CPU check cannot reconstruct the earlier Incident or turn its measurement into ownership or root-cause evidence.

CPU Activity Check

The standalone T18.2A check is a live-validated, read-only Windows capability. Task Manager helps show what exists now; CRA records what changed in bounded CPU intervals for one process the human independently selected. Neither is an automatic diagnosis.

The v0.2.0-beta.7 version contains the same CPU Activity Check runtime as beta.2. Every published beta should be used with its matching fixed checkout; main remains moving development/latest source. Published beta.3, beta.4 and earlier prereleases remain immutable with their recorded scopes. The unpublished beta.5 tag remains unchanged, and the historical fixed v0.2.0-beta.1 checkout does not contain the CPU runtime.

The operator flow is deliberately explicit:

  1. Independently select one current benign process and supply its PID.
  2. Review GATE_A_BIND and type exact CONFIRM.
  3. CRA binds one retained Windows process object without PID/name retargeting.
  4. Review GATE_A_REVIEW and type exact CONFIRM.
  5. Review the bounded plan at GATE_B_START.
  6. Type exact START.
  7. CRA samples cumulative process CPU time on a monotonic schedule for 5–60 seconds.
  8. CRA returns a privacy-allowlisted, IN_MEMORY_ONLY result.

From the repository root in an operator-owned PowerShell 7 ConsoleHost:

pwsh -NoProfile -File .\src\Invoke-CraCpuActivityCheckLive.ps1 `
  -ProcessId <SELECTED_PID> `
  -DurationSeconds 5 `
  -ActivityRelation NO_ACTIVITY_ASSOCIATION

Requirements, both exact activity-relation values, gate behavior, metric meaning, safe reporting and sanitized L1/L2/L3 evidence are in the CPU Activity Check guide. Anything other than the exact gate token cancels at that gate. Normal running cancellation is NOT_EXPOSED; do not document or use Ctrl+C as CPU_CANCELLED.

cpu_percent_one_core_relative = 100 is approximately one processor-second per elapsed second; values above 100 are possible. It is not whole-host CPU %, Task Manager process %, or logical-core-normalized utilization. CRA does not label it HIGH/LOW/CPU-bound or infer root cause, Codex ownership, a memory leak, child/app coverage, residue, or problem resolution.

For a CRA issue, share only the version/commit, environment versions (or unknown), workflow/stage, fixed reason/error code if available, sanitized reproduction steps and expected versus actual behavior. Follow Support and minimum disclosure; logs, screenshots and artifacts are not required. Suspected vulnerabilities use GitHub Private Vulnerability Reporting via Security reporting, not public Issues or PRs. CRA does not confirm a Codex bug or imply OpenAI endorsement.

First-run troubleshooting

If the Skill is unrecognized, no correct candidate is available, O0 fails, you cancel, or no final artifact appears, use the first-run troubleshooting table. It explains safe next steps and when a fresh attempt is required. No missing result should be described as zero activity or success.

Advanced and manual workflows

Manual Guided

From your checkout in your own PowerShell 7 console:

.\codex-resource-audit.ps1 -Mode Guided

Manual Guided retains F/Finder and S/Session where eligible. O/Observe is available in fixed beta.7; at reviewed main it reaches the Incident v2 release gate, even if candidate readiness permits the action. You inspect local terminal evidence, choose candidates for review, select one target and explicitly choose an action. Readiness and ordering never choose or trust a target automatically.

Follow the current manual Guided/Finder walkthrough:

  1. Inspect the captured C candidate list and each action's readiness. READY is captured eligibility, not ownership, identity continuity or release availability.
  2. At SELECT FOR REVIEW, enter literal F for Finder when you can reproduce activity that may expose newly observed identities. Finder is the feature name, not an accepted input token. Reproduce activity, then enter CAPTURE_ACTIVITY while it is running. Finder reuses discovery and takes exactly one additional snapshot; it can be invoked only once per Guided run.
  3. Read related, empty or unavailable results without inferring ownership or a clean system. If Finder returns to review, use the original C IDs, never its A evidence references. Cancellation or a terminal failure stops Guided.
  4. Enter a comma-separated review set, such as C3,C9, using IDs actually shown. This selects candidates for comparison, not a final target. Compare local PID and Creation Time UTC with independent current information about your intended instance; name, READY, ordering or PID alone is insufficient.
  5. Choose exactly one eligible C ID from that review set and an available action. For S/SESSION, inspect the captured identity before answering Y/YES, N/NO or Q/QUIT. Yes records confirmation; exact current identity revalidation is still required before Session starts. Cancel rather than guess.

Finder can miss short-lived processes between snapshots and does not diagnose CPU or hangs when an existing process simply stays active. Related rows are evidence for manual review, not recommendations. On development main, Incident v2 remains RELEASE_GATED before O0; Finder and eligible manual Session have separate rules. The bridge/PassThru STEP 2 correction loop does not apply to manual Guided: invalid manual review input stops the attempt. See the walkthrough for result limits, exact input behavior and safe cancellation.

Guided separates candidate eligibility (Session/Observation READY or BLOCKED) from Incident availability (development main remains RELEASE_GATED before O0). Neither READY nor Finder relationship counts establish ownership or a problem process. Finder explains Parent Hops, FROM and Supporting Identities; Partial Trace describes limited ancestry evidence, not a diagnosis. Stopped outcomes show their reasons before NEXT. See the walkthrough for the full definitions; input tokens, explicit human choices and identity revalidation remain unchanged.

Advanced Session

Session is a separate manual workflow with recognition/confirmation and exact revalidation. It retains S0–S4, TASK_END, Task Delta and Process Branch Origin; its verification and classifications do not transfer to Incident Observation. Start with the current manual walkthrough. Choosing Session alone does not establish a verified root.

PowerShell structured-result API

Use fixed beta.7 for a new Incident with this API. -PassThru does not bypass reviewed main's Incident v2 release gate.

$result = .\codex-resource-audit.ps1 -Mode Guided -PassThru
$result.result_type
$result.outcome

-PassThru returns a PSCustomObject through PowerShell's in-process success stream, with contract_version=1. It supports Incident Observation only; Finder and Session are unavailable. All human gates remain, including explicit O/OBSERVE. It does not automatically publish artifacts and is not a native stdout JSON contract.

Read result_type first: GUIDED_INCIDENT_REQUEST means no Incident run was produced; INCIDENT_OBSERVATION retains the observation result. Preserve blocked, stopped, cancelled, partial and unknown states. An interruption may prevent any result. Human terminal text is not machine evidence. See the T17.2 result API.

Technical references

Privacy and limitations

Windows collection can retain private metadata in memory, and local human recognition displays can contain identity details. AI-assisted use exposes only safe projections. Plain Guided/PassThru does not automatically persist artifacts; the bridge writes to the explicit request directory. CRA does not automatically upload them. Shell redirection and external logging are separate. Never publish command lines, credentials/tokens/cookies, usernames/hostnames, private paths, real PIDs/creation times, full process tables, raw process dumps, terminal transcripts, private source code, sensitive screenshots, sensitive diagnostic artifacts or entire artifact directories. Do not attach logs, screenshots or artifacts by default. Additional data requires prior explicit agreement on the minimum specific field, purpose and appropriate channel; see minimum-disclosure reporting. CRA not automatically uploading artifacts does not establish offline Codex processing or that all data stays on the machine.

Live collection is Windows-only. Missing or denied metadata stays unavailable; CRA never elevates privileges or changes host configuration. There is no autonomous AI selection/confirmation, automatic terminal launch, native stdout JSON, AI-callable Finder/Session, cleanup/kill/remediation, MCP server, public/remote endpoint or ChatGPT cloud direct control of a local PC. The CPU check does not persist its result, send it to AI automatically, control a process, aggregate children/the whole app, or expose normal running cancellation. CRA is not a definitive ownership, residue or leak detector, full-host accounting tool or continuous profiler.

Browser names or attached tools do not prove ownership. A confirmed Gate 2 false positive is NO-GO. Existing browser lifecycle limits remain:

REAL_BROWSER_MCP_LIFECYCLE_POLICY: EVIDENCE_BLOCKED
REAL_BROWSER_MCP_RESIDUE_CLAIM: NOT_SUPPORTED

Development and validation status

The pipeline separates collection, attribution, lifecycle analysis and reporting. Offline tests use synthetic/mocked evidence and Pester 6.2.0; the runner installs nothing:

pwsh -NoProfile -File .\scripts\Test-Stage0.ps1 -Offline

The historical CPU baseline recorded in Quick Start passed 1859/1859 locally and on Hosted Windows CI, with zero failed, skipped, inconclusive or NotRun tests. The beta.3, beta.4 and beta.5 preparation checkpoints reran the same full offline suite. For beta.6, one focused STEP 2 display regression was added and 1860/1860 offline tests passed before Owner review. These local reruns remain separate from the earlier exact-SHA baseline. Beta.7 product implementation acceptance at 996996e58056245e8784e4db3dc7abd248f407e9 passed 1900/1900 locally and on exact-SHA Hosted Windows CI, with zero failed, skipped, inconclusive or not-run tests; Robin reported clean-clone acceptance PASS. Later documentation changes and release-target commits require their own applicable review and validation.

Historical T17.1/T17.2/T17.3 acceptance applies to the Incident v1 workflow; it does not release main's Incident v2. Standalone T18.2A live validation passed L1/L2/L3; L4 is NOT_EXPOSED by design. Executable vectors remain 22/22 positive and 37/38 negative: N30 is intentionally PARTIAL because T18.1 has no executable parent external-state runtime seam. This does not implement T18.1 or T18.2B Memory Trend. Windows operator integration acceptance is not a universal host/client-version guarantee. Historical phase statements retain their own checkpoint scope.

License

MIT License. Copyright (c) 2026 RobinLee.

About

Read-only Windows diagnostic tool for observing Codex-related process activity and collecting bounded evidence before conclusions.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages