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.
Available now: T17 and the standalone, live-validated T18.2A CPU Activity
Check are implemented. Fixed tagged prereleases are authoritative through
GitHub Releases,
while main is moving development/latest source. Version v0.2.0-beta.7
contains the consolidated FIRST_RUN_RECOVERY_BATCH; the Releases page
remains the authority for whether that tag has been published. Published beta.1
through beta.4 remain immutable historical prereleases with their documented
scope. The existing v0.2.0-beta.5 tag was not published as a GitHub prerelease
and remains unchanged. A prerelease is not production readiness.
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.
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: Incident Observation with the cra-incident Skill. |
| Manually inspect candidates or use advanced workflows | Manual Guided: Finder, Session and Observation remain available where eligible. |
| 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.
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.
When the Releases page provides v0.2.0-beta.7, use its matching fixed checkout.
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-auditFor moving development/latest source, use --branch main instead and report the
actual commit when possible. 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.
-
Open/work in the CRA checkout in local Codex, or explicitly provide its absolute repository root.
-
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.
-
On the next Codex turn, confirm
cra-incidentappears 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.
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 $OutputDirectoryThe 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.
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.
- 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.
- 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 chooseO/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, enterQto cancel instead of guessing. - CRA checks the target at O0. O0 is the starting identity check and baseline capture. Only
MATCHEDallows the observation to continue. - Start or continue the activity, then enter
O1while it is running. This requests the during-activity capture. After O1 returns and the activity finishes, personally enterACTIVITY_END. - 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.
- 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.
| 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.
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.
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.
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:
- Independently select one current benign process and supply its PID.
- Review
GATE_A_BINDand type exactCONFIRM. - CRA binds one retained Windows process object without PID/name retargeting.
- Review
GATE_A_REVIEWand type exactCONFIRM. - Review the bounded plan at
GATE_B_START. - Type exact
START. - CRA samples cumulative process CPU time on a monotonic schedule for 5–60 seconds.
- CRA returns a privacy-allowlisted,
IN_MEMORY_ONLYresult.
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_ASSOCIATIONRequirements, 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.
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.
From your checkout in your own PowerShell 7 console:
.\codex-resource-audit.ps1 -Mode GuidedManual Guided retains F/Finder, S/Session and O/Observe where eligible. 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. Manual Finder.
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. See the Session operator guide and sanitized demo. Choosing Session alone does not establish a verified root.
$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.
- First-run setup and troubleshooting
- CPU Activity Check operator and validation guide
- Incident Observation and timing
- Canonical Codex Skill
- T17.1 semantic contract, T17.2 result API, T17.3 bridge and artifacts
- Session Task Delta and Process Branch Origin
- Pipeline design, validation record, synthetic examples
- Historical v0.1.0 release notes, v0.1.1 release notes, v0.2.0-beta.2 release notes, v0.2.0-beta.3 release notes and v0.2.0-beta.4 release notes; unpublished-tag v0.2.0-beta.5 notes; v0.2.0-beta.6 release notes.
- v0.2.0-beta.7 release notes: consolidated first-run recovery milestone and acceptance provenance.
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
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 -OfflineThe 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.
T17.1, T17.2, T17.3 and standalone T18.2A are complete within their documented public-main scopes. 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.
MIT License. Copyright (c) 2026 RobinLee.