@piagent/platform 1.6.1 → 1.8.0

package/docs/piagent-core-offline-implementation-2026-09-06.md

@@ -0,0 +1,219 @@
+<!-- language: en -->
+
+# PCL-A offline implementation and evaluation protocol
+
+Plan PCL-2026-09-06, PCL-A approved. This document describes the source freeze; the local qualification verdict, finite register and hash-bound checkpoint are in `.tmp/pcl-20260906/`. Implementation work and release qualification are separate states. No release or paid readiness is asserted by this document. Current continuation status: stage 5 completed 5,225 tests (5,150 PASS, 17 FAIL, 58 SKIP, zero cancelled), with browser/typecheck PASS and all 2,720 files unchanged. The default stable-dedup expectation closed in full; no new failure names appeared. Stage 6 repairs a separately reproduced API-evidence dispatch error; that changed candidate still requires full qualification.
+
+## Implemented scope
+
+C0 verified HEAD `c3a4427396984554eb1571e687caba0f831176ae`, branch `codex/piagent-35-recovery-20260831`, 157 initial status entries and zero staged paths. All 153 E14 recovery file hashes and all 188 sealed artifact hashes matched. The original PCL checkpoint is retained as parent. The preservation manifest and file preimages distinguish inherited recovery from PCL hunks. E14 is historical evidence, not the identity of this candidate.
+
+C1 writes numeric metadata to the existing bounded context telemetry stream. Each SDK turn receives a request identity bound to the task at turn start. Assistant message-end and turn-end share that identity; cumulative terminal replay is deduplicated. Late fields can fill unknown values, while contradictory known amounts, unsupported deltas, session totals, missing terminals, multiple observed dispatches and incomplete telemetry make totals unknown. Error/abort attempts with reported usage remain in accounting; synthetic zero usage on an error or abort is not evidence of zero billing. SDK estimated cost is separate from billed cost, which remains unavailable without a billing receipt. Existing benchmark exact accounting was not replaced or regraded.
+
+Tool counts come from SDK post-execution tool-result hooks, reconciled with attempt and terminal events. SDK start events alone also include blocked, invalid and truncated calls and are not counted as execution. The live task view and `/context efficiency` use the same task report. Solver projections now require the decision reference in the task's persisted trajectory, preventing a later task in the same session from changing an earlier task's reported route. Older unbound records remain readable with unknown solver attribution.
+
+Successful source mutations record the existing post-edit tree and workspace revision in tool-result metadata. First-correct-edit timing requires an observed mutation, the same tree and revision in all exact current verifiers after the edit, and an existing approved completion gate supplied by the live view. It measures the first observed edit that reached the accepted final source, not the independent correctness of one hunk. Pending, unsupported, stale, corrupt or unapproved tasks remain unknown. This metric cannot grant acceptance. The standalone efficiency command has no current completion gate and therefore keeps that timing unknown.
+
+C2 measures UTF-8 JSON bytes for instructions, tools, input and the remaining envelope at the existing provider payload hook. Components reconcile to the serialized payload. This observation is bounded, stores no payload text, and is distinct from HTTP transport bytes, tokenization and later extensions' transformations. The signed fingerprint contract is unchanged. Equivalent fingerprints do not prove a cache hit; SDK-reported cache read/write tokens remain separate evidence. No new context reduction was justified by the available observations, so prompt text, retrieval selection and governor thresholds were retained.
+
+C3–C5 reuse existing behavior. Freshness checks reject proven file drift and renamed old paths; bounded edit recovery carries the actual current file and preserves earlier successful edits. Path, ambiguous-anchor and stale-anchor failures remain distinct, while permission errors and failing code remain failures. Existing long-output capture/readback, exact exit-code handling, protected paths and tool-pair controls are exercised in the session tests. Tiny tasks use existing audited phase skips. Shadow/recommendation results stay distinct from enforcement. Recovery continues to use the single global continuation maximum of one and its progress signature, with no second counter or automatic external replay.
+
+Memory remains advisory. Existing expiry, protected-path selection and citation checks were retained. Historical hints can remain visible until expiry; they are not silently promoted to fresh source or acceptance evidence. Current reads, task requirements and user corrections take precedence. Rename/source-change controls reject stale source evidence. The existing lossless task ledger, authority snapshot, open obligations and uncertain-side-effect handoff survive the tested resume paths. Reduced rereading or real-work memory benefit remains unproven; no additional store was created.
+
+## Offline evidence and limits
+
+The evidence manifest records exact commands, logs, hashes and outcomes. Selected controls before freeze include:
+
+| Evidence | Observed scope |
+|---|---|
+| `11-c1-c2-tests.log` | 22 PASS, 0 FAIL/SKIP: accounting, task attribution, timing, payload and operator reports |
+| `09-c2-c5-controls.log` | 186 PASS, 0 FAIL/SKIP: governor, ledger, output handling, tools, phases, recovery, authority and resume |
+| `15-sdk-compaction-resume.log` | Historical SDK/compaction control; its native-read claim was invalidated by the execution-count audit described below |
+| `16-c3-c6-controls.log` | 31 PASS / 5 FAIL: exposed the added fingerprint field's incompatibility with signed receipts; failure retained |
+| `17-wire-contract-fix.log` | 30 PASS, 0 FAIL/SKIP after keeping measurements outside the signed fingerprint contract |
+| `12-typecheck.log`, `13-architecture.log` | Typecheck and architecture budgets passed at that revision; final checks bind the freeze |
+
+Earlier failing marker fixtures used invalid digest namespaces; their logs are retained. The corrected controls use the runtime's namespaced tree and revision identities. Initial line-budget failures were addressed by putting metadata in the existing helper and keeping the composition hook within its original budget. No gate was relaxed. Counts above overlap and must not be added into a single unique-test total.
+
+The installed-SDK test uses a local scripted model runtime, synthetic credentials and test-owned source/session directories. It makes no model/provider call. It proves SDK hook and compaction protocol behavior, not production billing completeness or model quality. It preserves corrections and tool pairing after durable compaction without a summarizer call. Directed model summaries, opaque provider state and every provider-specific late billing path have not been verified against a live provider.
+
+At freeze, run `bash scripts/verify-local.sh --offline` once. Preserve its first failure. If it stops before the full test runner or other qualification gates, execute those unreached commands once as diagnostic qualification evidence, with the canonical verdict still FAIL. Never relabel component passes as a canonical pass. Final results and the exact freeze are recorded in `20-candidate-freeze.json`, `31-pcl-checkpoint.json` and `32-offline-report.md` under the local evidence directory. Subsequent source changes require a new identity and justified checks.
+
+The inherited full result remains 4,820 PASS / 22 FAIL / 222 SKIP. Eighteen default correct-completion expectations remain required even when configured controls pass. Docs full configured SDK integration and the expiry/reference arity decision remain open. R5's 108 sessions/54 pairs are scripted evidence. Run-6 remains INVALID_MEASUREMENT: 13 started, 12 accepted exact, one unknown. No old evidence was resumed, reused as a new measurement, merged or regraded.
+
+## C6 version decision prepared for review
+
+Keep SDK 0.84.1 for this PCL candidate. Its local package version, peer pins, hook imports, dispatch order, tool execution, usage/cache fields and durable compaction/resume were checked. Existing steering/abort and model-policy tests form part of offline qualification. Exact user model and effort remain pinned; model capability metadata is not a quality ranking. No package, lockfile or global installation changed for PCL.
+
+The existing research identified 0.85.1 as a future candidate and an import correction relative to 0.85.0. Those release notes do not prove compatibility with this source. Proposed PCL-SDK decision: permit a separate, isolated version comparison only if a required unsupported contract or reproducible SDK defect justifies it; otherwise retain 0.84.1. The comparison must cover import closure, hook order, steering/abort, terminal usage, cache fields, complete tool pairing, compaction/resume and current phase/source identity. All causal arms would use the same chosen SDK. No upgrade is performed or requested as a prerequisite for finishing offline work.
+
+Support status: installed 0.84.1 with the local scripted runtime is offline-tested for the stated contracts; live provider billing/model quality remains unknown. Other installed or future SDK/model combinations are not newly certified by this work.
+
+## C7 evaluation protocol, not campaign authority
+
+[Twenty-four specifications](piagent-core-evaluation-specs-2026-09-06.json) propose 12 development and 12 holdout tasks, with two from each split in each of six work categories. Every row has a requirement, behavioral criterion, distinct proposed root-cause cluster and proposed verifier. No row has a selected repository, source hash or rights approval. Commands are proposals and are not certified valid until bound to an authorized source. Public task outlines are not sealed unseen holdout work. A custodian must choose actual authorized backlog tasks, inspect prior PRB/development exposure, reject related root causes crossing splits and seal the holdout before any evaluation. Missing source rights cannot be replaced by invented fixtures presented as real work.
+
+Keep three evidence layers distinct: offline protocol tests; same-model/same-SDK feature comparisons; product comparison and real-work retention. Baselines retain the same necessary safety guards, permissions and verifier authority. Hold task/source identity, provider/model snapshot, effort, SDK, tools, limits and cache condition constant. Record order and cold/warm state; reset test-owned memory between arms to prevent carryover. Outcome is correct completion of the whole contract, wrong blocked, or finite unsupported handoff. Handoff does not count as completion. Record regression, independent authorized behavioral results, accepted source identity, user corrections and rework after handoff.
+
+Only two follow-up hypotheses are retained:
+
+1. Existing exact recovery snapshots may reduce failed-edit rereads without changing source correctness. The current-file recovery and post-execution metadata establish a measurable path, not a benefit estimate. Falsifier: replayed successful hunks, wrong targets, additional failed attempts or higher total task cost. Compare the same existing recovery feature on/off only after treatment approval.
+2. Existing governor projection and deterministic compaction may reduce duplicate payload residency without losing corrections, pairing or source freshness. UTF-8 reconciliation and installed-SDK controls establish observability and protocol preservation. Falsifier: more retrieval/tool work, stale evidence, lost obligation, cache loss outweighing savings or worse completion. Do not remove more context before evidence supports a specific hunk.
+
+Evaluate total task input/output/cache tokens, known billed failed attempts, missing-usage rate, elapsed time and user rework jointly with correct completion. Keep billing receipts distinct from SDK rate estimates, and unknown distinct from zero. Report paired outcomes and uncertainty; 12 holdout tasks cannot establish a universal two-percentage-point noninferiority claim. After two development rounds without new evidence for one hypothesis, stop and reassess. Looking at holdout failure and fixing against it makes that task development evidence; obtain a separately sealed replacement rather than rerunning it as unseen.
+
+No provider sessions are allocated. PCL-EVAL must separately bind actual corpus, treatments, quality criteria, repetitions, count and total budget including failures, summaries and helpers before execution. D-026 stays bound to its old candidate: combined cap 184, used 76, fresh maximum 108, zero retry, 3,000,000 tokens/four hours, gates 12→18→54→108, stop on unknown and no extra canary. Choosing PCL for that campaign requires qualification and explicit candidate/treatment rebind; it does not move the 108 sessions onto this proposed corpus. No paid authority or independent verifier is created here.
+
+## Handoff and rollback
+
+Use `21-pcl-hunks.patch` and the per-file preimage/postimage hashes in `20-candidate-freeze.json`. Reverse only PCL hunks when current postimages still match; inspect conflicts and stop that rollback if later edits overlap. Never restore the whole file from HEAD. The original dirty recovery diff and all source preimages remain in local evidence. New PCL files are identified separately. Final preservation checks verify unchanged inherited files, PCL-only delta reconstruction, branch/HEAD/staging and sealed E14 integrity.
+
+Next action is to read the final finite register and qualification checkpoint, then resolve the specific remaining contract/quality gates before any release or paid candidate selection. The offline deliverables do not claim better model reasoning, lower billed tokens or completed real-world tasks.
+
+
+A subsequent installed-SDK negative control found that `tool_execution_start` also fires for blocked/invalid/truncated calls (`34-tool-start-reproducer.log`: two reads reported when only one executed). Freeze 1 was invalidated and its full test attempt interrupted; all logs are retained under `freeze-1/`. The correction uses the existing afterToolCall-backed `tool_result` hook and reconciles attempted, executed and not-executed calls. Incomplete execution evidence and incomplete failed-attempt totals remain unknown with observed subtotals separate. Final qualification is a justified new freeze after this concrete runtime compatibility correction, not a rerun to seek a green result. The installed-SDK regression now includes blocked, invalid and truncated calls alongside the real successful read.
+
+
+The execution audit also found an error in the new test fixture: SDK `tools` expects tool names, but the first fixture supplied a tool-definition object. Earlier logs 14/15 therefore do not prove native read execution. The corrected fixture uses the installed `read` name and requires a successful persisted tool result containing the test-owned file text, plus separate blocked, invalid and truncated negatives. `42-execution-and-sdk-readback.log` is the replacement evidence for that claim. Existing runtime and benchmark expected outcomes were not changed. The documentation language-marker check was also corrected by adding explicit language metadata to the three PCL Markdown documents; research content and source references remain intact.
+
+
+Freeze 2 completed 5,174 tests: 4,872 PASS / 22 FAIL / 280 SKIP / 0 cancelled. Eighteen failures retain default correct-completion expectations. The other four exposed maintenance required by the new PCL observation hooks/tests: the exact hook registration list lacked three new events, and three readiness checks rejected a stale public-test exposure digest. The registration assertion now includes exactly those events while retaining tool/command counts. Public exposure generation showed only `visibleTrees[tests].fileCount` and `.sha256` changed; those metadata fields were refreshed. No benchmark criterion, expected task outcome, private artifact, independent custody receipt or provider authority changed. Freeze-2 evidence is retained; final qualification binds a new freeze after these concrete test/inventory corrections.
+
+
+## Full continuation and scoped runtime integration
+
+The later stage-3 canonical run completed on an unchanged 2,719-file candidate: 5,179 tests, 5,103 PASS, 18 FAIL, zero cancelled and 58 SKIP. Browser and typecheck passed; the canonical verdict remains FAIL. All failures are the retained default correct-completion expectations. This supersedes neither E14 nor the earlier PCL freezes. Full receipts and all skip entries are in `.tmp/pcl-full-20260906/53-stage3-final-result.json` and `57-stage3-skip-inventory.json`.
+
+Stage 4 fixes two additional scoped runtime gaps: native completed operations now retire exact closed custody before the next operation, and unchanged permitted files no longer require artificial writes during review. Unknown unjournaled changes and out-of-scope mutations remain blocked. The actual SDK configured documentation path now covers scout, implement, no-change review and closed disk readback; wrong content remains blocked. These fixtures use explicit test-owned host contracts and no real model/provider. Default completion authority is unchanged.
+
+The initial 108-test regression passed. A subsequent 42-PASS/1-FAIL run was invalidated by a type-only source edit during execution; source-bound host approval correctly rejected the changed installed digest even though emitted runtime bytes were identical. The source-stable follow-up passed all 64 tests without failure, cancellation or skip. The final full qualification must bind the subsequent stage-4 manifest; these targets alone are not release qualification. No SDK upgrade, source rights, paid campaign or rebind was created.
+
+
+## Stage 5: default API completion and quantified input preservation
+
+The existing task-baseline API reader now supports a closed local-array result representation, alongside its existing primitive grammar. New collection support requires unshadowed bindings, supported local collection calls and consistent normal return paths. Captured task/session/source identity, all current verifiers, unchanged public signatures and unrelated public implementation closures remain mandatory. Exact callable repair directives are routed through the existing source-origin resolver with an exact owning path. Matching array representation does not establish behavioral equivalence or element semantics.
+
+A separate executed counterexample showed that “Do not mutate either argument” could accept a mutating second argument when only the first was compared with its snapshot. The quantifier check now selects the existing all-argument proof path for both/either/all/any. This strengthens the required evidence; it does not admit unsupported grouped snapshots or infer missing input behavior.
+
+The actual source passed 161 focused regression tests, typecheck and architecture checks. The unchanged default production data-journey test passed both selected cases through SDK 0.84.1 and loopback HTTP/WebSocket: the correct stable deduplication implementation completed scout, implement and verify, while the equal-sequence mutant failed actual project verification and remained pending. All 2,720 candidate files were unchanged during this two-case run. No independent host contract, oracle, prompt, test expectation or paid provider was added. This evidence covers the live session, not a new cold-readback claim.
+
+The stage-4 full result remains 5,106 PASS / 18 FAIL / 58 SKIP, with zero cancelled. Stage-5 targets establish progress on one of those default expectations; they do not establish a new full failure count or overall qualification. Preimages and source/test hunks are retained in `90-stage5-preservation.json` and `90-stage5-source-tests.patch`. The public exposure change is limited to the tests-tree digest; all other metadata and the 469-file count are unchanged.
+
+
+## Stage 6: explicit API intent retains baseline authority
+
+An executed counterexample found that an exact “Preserve the API…” criterion was inferred as a boundary case. The receipt then accepted passing boundary tests even when the exported function gained a parameter, and even without the baseline reader. The same exact API clause now dispatches to the existing task-baseline reader regardless of its inferred category. Its original text, hash and category remain intact. The recovery projection follows the same route. The runtime reader still requires the exact source-change task binding, task-start baseline, current tree and all configured verifiers; category inference no longer substitutes for API evidence.
+
+The wrong signature remains pending with an explicit API-change reason; the compatible API receives task-baseline evidence. A missing reader cannot inherit a previously satisfied receipt. Two executed reproductions changed from failure to pass, and 70 API/inference regression tests passed. No benchmark source, prompt, grader, oracle, threshold, expected outcome, SDK or provider authority changed. The expiry/reference arity conflict remains open; this dispatch repair does not make an incompatible reference correct.
+
+The completed stage-5 evidence is in `.tmp/pcl-full-20260906/107-stage5-final-result.json`; its 58 skips, current criteria, finite register and requirement audit are retained in 107–114. Stage-6 preimages are in `116-stage6-preservation.json`, the failing reproduction in `115-api-intent-reproducer.log`, the repaired reproduction in `117-api-intent-repair.log`, and the 70-test regression in `118-api-intent-regressions.log`. Further targeted and full qualification are recorded against the subsequent stable manifest, not inferred from these small checks.
+
+Broad regression initially exposed two correct temporal-helper journeys previously relying on the weaker dispatch. The existing API reader now recognizes closed boolean public return representations, including bounded Date helpers; it continues to reject changed signatures, mixed or unknown returns, escaping or rebound function bindings, computed intrinsics and unsupported calls. This is API shape evidence only. Invalid-input semantics and nonmutation retain their separate source requirements. Existing primitive uses of a parameter named Date remain supported when no Date intrinsic is used.
+
+The registered guard also exposed a task-start manifest whose only unavailable bytes belonged to a protected configuration file. The reader can now use unrelated source from a complete inventory whose unavailable status is exclusively protected entries. Protected target bytes, truncated inventories, failed reads and oversized entries still provide no evidence; neither the manifest nor the protected file is rewritten or opened. All four existing composed-helper guard cases then had their expected outcomes: two correct implementations completed and two incorrect implementations remained pending. A new negative fixture initially failed to create its intended dirty entry; that setup was corrected by an actual byte change, with its failing log retained. Evidence 123–127 distinguishes these intermediate outcomes from subsequent qualification. The earlier 122 target freeze was superseded before any SDK or full run.
+
+The subsequent 62-file acceptance regression completed 829 tests: 826 PASS, zero FAIL, three SKIP, zero cancelled (`129-stage6-acceptance-regressions-receipt.json`). Typecheck and all 634 architecture checks passed (130). This regression result is separate from installed-SDK and full qualification; the three skips are not counted as verified.
+
+Installed SDK 0.84.1 qualification ran four unchanged native HTTP/WebSocket journeys: three PASS and one FAIL, zero skips or cancellations (132–133), with all 2,720 files unchanged. Both stable-dedup controls retained their expected outcomes, as did the expiry mutant. The expiry reference still failed its existing completed expectation; its exact API criterion now correctly remains pending instead of borrowing a boundary test. This is a retained failure, not a target waiver or a new full verdict. Full qualification uses the subsequent stage-6 freeze; only these two documentation files changed after the SDK run.
+
+
+## Stage 7: preserve optional API metadata and bind compound input rejection
+
+Stage6 full qualification completed on all2,720 unchanged files: 5,253 tests, 5,177 PASS,18 FAIL,58 SKIP,zero cancelled; browser/typecheck PASS. Evidence137 records all18 leaf failures and all skips. The17 prior default failures remain, plus the owned-Date guard whose baseline parameter timestamp differs from expiresAt in its implementation. The API reader treats that name difference as a contract change; the fixture and completed expectation remain intact pending resolution.
+
+Ten current preimages were preserved before applying the reviewed143/155 hunks (156–158). The existing API reader now retains supported default values and their positions plus observable function.length. Closed numeric public returns admit bounded local reduce callbacks without treating arithmetic as equivalent. Exact Repair directives share the existing Fix source-origin rule; foreign paths, ambiguous examples and unrelated public implementation changes remain rejected.
+
+An actual executed counterexample showed a passing verifier covering tax rejection could satisfy a money/quantity criterion even while bad line data returned1. The existing integer-parameter route now binds each explicitly declared scalar input to immediate source guards and isolated negative/fractional witnesses. Incidental invalid arguments cannot create the requested domain. Unsupported property labels, extra constraints and unbound inputs remain pending. This does not yet prove the original invoice property contract. Existing continuation maximum1 and progress-signature behavior are unchanged.
+
+Seventy-five new controls were added to three existing test files:47 API/default/target controls,24 input-domain controls,two actual receipt controls and two registered guard journeys. Draft qualification included129 API tests,424 acceptance regressions and six guard cases, but applied-source qualification is still required. The151 regression copy was invalid because regex import rewriting altered embedded fixture strings;152 used AST-only substitution. A new153 guard test wrongly expected immediate handoff;154 checked exactly one existing continuation followed by unchanged handoff. Neither invalid result is a runtime qualification claim. The public tests inventory retains469 files and changes only its digest. No benchmark prompt,grader,oracle,threshold,expected outcome,reference source,SDK or provider authority changed.
+
+
+The applied stage7 regression completed 904 tests:901 PASS,zero FAIL,three SKIP; typecheck and architecture passed, and all2,720 files retained their hashes (159–166). An executed API reproduction isolated the new stage6 full failure to internal parameter spelling. The comparator now permits fresh local names while conservatively rejecting retained names moved to another position. Defaults,arity,export names and return representation stay exact. Existing target/source binding and unrelated-public-body comparison remain mandatory. API shape still does not prove behavior.
+
+This follow-up draft passed148 API tests,three source-authority receipt controls and the original owned-Date registered guard test, including both its correct completion and wrong-offset rejection. No fixture or expected outcome was modified. Five preimages were captured in167 before application;168 retains the exact hunk and20 additional controls. Applied-source and installed-SDK qualification remain separate from these draft results. The18 failures from full stage6 are not replaced by a target-only verdict.
+
+The final applied regression ran 370 tests: 370 PASS,0 FAIL,0 SKIP,0 cancelled, including the entire original guard integration file(171). Typecheck/architecture passed. The installed-SDK run completed four unchanged invoice/expiry cases:two PASS,two FAIL,zero skipped/cancelled,with all2,720 file hashes unchanged. Invoice API preservation now receives baseline evidence; its money/quantity rejection obligation remains pending. Expiry retains malformed-date and default/signature gaps. Both mutant expectations remain satisfied. Records174–176 retain criterion-level evidence,the finite register and target qualification. A new canonical full is justified by the concrete stage6 guard regression and changed runtime behavior; these targets do not establish its verdict.
+
+## Stage7 full and stage8 parser implementation
+
+Stage7 canonical qualification completed with 5348 TESTS, 5270 PASS, 20 FAIL, 58 SKIPPED, 0 CANCELLED; browser=PASS, typecheck=PASS. Record `.tmp/pcl-resume-20260907/03-stage7-final-result.json` verifies all2,720 frozen files unchanged. Its leaf failure set remains authoritative; draft or targeted results do not replace it.
+
+Stage8 reuses the existing terminal state-machine proof and bounded module statement inventory. It supports owned local output arrays only within a closed module, requires escaped-quote progress and mutually exclusive closure, and verifies all counter writes. An exact implicit terminal rejection clause can bind only to one stable export/import. Original criterion text and receipt identity remain unchanged. Record197 preserves seven current preimages;198 contains four source/test hunks. Fifty-eight parser controls and two registered guard journeys are appended to existing tests. The new guard uses a real passing verifier for both candidates: the correct parser completes and omitted escape progress stays pending with a finite handoff. No benchmark artifact, authority, counter, provider or installed SDK changed.
+
+Draft report196 records78 parser PASS,319 direct semantic regressions PASS and2 registered guard PASS, including prototype mutation and actual executable malformed-escape counterexamples. Applied-source regression, installed SDK default journeys and subsequent frozen full remain required. CSV helper-reference's focused-error discrepancy104 remains unwaived.
+
+## Stage9 applied; integrated qualification pending
+
+Stage8 installed-SDK CSV public-contract completion and escaped-quote rejection passed. The helper expectation discrepancy remains a recorded FAIL. Its acceptance run was980 PASS/1 FAIL/3 SKIP; the failed execution could not confirm container creation. Exact test-owned cleanup40 and whole worker test recheck41 are separate evidence, not a rewritten broad result. Typecheck and architecture42 passed.
+
+Stage9 preserves ten preimages and applies seven source/test files from numeric12, snapshot22 qualified by28, and resume-clock38. Numeric proof requires the declared JavaScript Number division formula, complete domains and live focused witnesses. Snapshot evidence requires stable own-data capture and comparison, an unmodified assertion/clone environment, and no intervening input restoration or snapshot mutation. The resume fixture now controls Date at its historical capture time and tests attribution just before versus at expiration; runtime retention is unchanged. Existing source behavior, benchmark contracts and completion obligations remain required. Applied regression, actual SDK pagination and stable-dedup controls, remaining finite issues and final frozen qualification are still pending.
+
+## Stage10 Git probes applied; configured docs qualification pending
+
+Stage9 applied regression finished1,069 PASS/0 FAIL/4 SKIP and four original pagination/stable-dedup SDK controls passed. Static checks passed; final canonical qualification remains outstanding.
+
+Profile43/47b traces configured-docs settlement cost to repeated workspace observations and Git subprocesses. Stage10 passes an already observed HEAD-presence value to the private enumerator within the same synchronous snapshot call. It removes two redundant Git probes per root without caching across captures or removing content/material/revision checks. Seven fixture snapshots remain equal with fewer real Git calls. Three permanent fault tests preserve unavailable evidence on diff/enumeration failure and on a repository disappearing after the probe; the original implementation fails the disappearance control. Five current preimages are preserved60, including the public test inventory and docs. Applied source tests and original configured docs correct/wrong SDK journeys are still required. No benchmark contract, deadline, SDK, authority or retry budget changed.
+
+## Stage11 applied; outer callback binding
+
+Stage10 actual configured-docs correct and missing-restart controls pass2/2 with original deadlines. Related source/verifier/resume checks including the pinned native Pi bash module pass165/165; typecheck and architecture pass. This does not close default docs.
+
+The rejection reader previously used the first arrow anywhere in an operation, so a direct call receiving an arrow callback lost its actual target. Stage11 unwraps only an outer arrow prefix. Five preimages preserve the two source/test changes, inventory digest and these documents. The19 added tests retain dead/skipped/unawaited, unrelated-target, altered-error, import-shadow and sync/async exclusions; anonymous function expressions keep their existing lexical exclusion. The exact retry fixture now has source/test evidence in draft, but unchanged SDK completion and mutant rejection, applied regressions and final full remain required. CSV/expiry decisions and remaining P2–P8 work are open.
+
+## Stage12 applied; declared record integer fields
+
+Stage11 actual retry SDK controls pass3/3: both correct variants complete and the unchanged backoff mutant stays pending. Applied acceptance checks are1.046 PASS/0 FAIL/3 SKIP; typecheck and architecture pass.
+
+Stage12 extends the existing parameter-contract reader rather than introducing another verifier. Related task prose supplies the monetary field and positive quantity/default; a bounded synchronous reducer must guard every declared field through stable local integer helpers. Literal witnesses must isolate each invalid field while all other guarded record and scalar inputs are valid. The reader preserves source/import/error-class/verifier/tree gates and rejects missing or ambiguous context. Six source/test files, inventory digest and these documents have nine preserved preimages.
+
+Draft v1 broad checks passed1.073 with3 explicit skips. A separate falsifier showed a test could borrow Array and replace native reduce; the final witness reader rejects that escape, with88 targeted checks including real passing-verifier receipt controls. The v1 broad receipt remains bound to its original preserved inputs. Actual applied SDK invoice, source regressions, static checks and final frozen full remain required. Benchmark prompts, reference, expectations, SDK and approval authority are unchanged.
+
+## Stage13 applied; finite interval fields, fallback and grouped snapshots
+
+Stage12 invoice qualification remains recorded separately: actual SDK2/2, applied regression1,101PASS/0FAIL/3SKIP, typecheck and architecture PASS.
+
+Stage13 preserves15 preimages for eight existing source modules, four additive test files, the public test digest and these documents. The existing temporal reader binds every finite field and skew/order relation to task context and isolated source/test evidence. Its fallback proof binds the complete declared earlier branch order, boundary operators and literal results before accepting a live native assertion for the otherwise domain. Grouped non-mutation proof requires a closed source selector, fresh flat data, native structuredClone before invocation, both input identities after invocation, and literal loop coverage of every result and the error path. Aliases, reflection, mutable intrinsics, missing source guards and snapshots captured/altered after invocation grant no proof.
+
+The combined draft passed1,244 checks with3 explicit opt-in skips. Unchanged retained public source/tests pass5/5; all three previously pending billing criteria are satisfied through a disposable executed-verifier receipt with a compiled scoped graph. Draft controls include actually passing weak verifiers with incorrect source, so verifier success alone cannot supply missing obligations. The initial fallback-only test fixture lacked that graph and was corrected; no runtime authority was opened.
+
+Applied actual SDK billing correct/mutant controls, source regressions/static checks and final canonical full remain required. Source application is not full qualification, paid readiness or evidence of model quality/token savings. Other P2-P8 issues and CSV/expiry decisions remain open.
+
+## Stage14 applied; cached record validation and separate snapshots
+
+Stage13 billing qualification remains recorded separately: actual SDK2/2, applied regression1,244PASS/0FAIL/3SKIP, typecheck and architecture PASS.
+
+Stage14 preserves nine preimages: three existing source modules, three additive test files, test inventory digest and these documents. The existing record reader requires typed guards for every task-derived identifier/time/revision role and nullable field, including non-array object shape. Empty/non-string and non-finite/fractional/non-number test witnesses must isolate each field while other inputs remain valid. Closed literal loop conditions preserve nullable exclusions. Separate pre-call native clones must retain both argument identities across true, false and throwing outcomes.
+
+The baseline admitted a missing-field source after a real passing null-only verifier; the exact source/test hashes are rejected by the draft. Another executed control shows why empty-array rejection tests alone are insufficient: a source lacking the array guard can admit an array carrying all valid-looking fields. The draft rejects that source structurally even when its public-shaped tests pass. Mutation/restore, snapshot aliases and replaced intrinsics remain unproved.
+
+Combined draft checks:1,365PASS/0FAIL/3SKIP. Unchanged retained source/tests:7/7; both remaining cache criteria satisfied through an executed-verifier receipt. Applied actual SDK correct/cross-tenant-mutant, source regressions, static checks and final canonical full remain required. No new independent authority, benchmark change, provider call or SDK upgrade.
+
+## Stage15 applied: byte view and backing-buffer ownership
+
+The stage14 cache qualification remains2/2SDK and1,365PASS/0FAIL/3SKIP with static checks. Stage15 preserves six preimages: two existing source modules, one additive test file, test inventory digest and these documents. Native encoded allocations and subarray bounds identify the complete backing buffers. Pre-call Array.from projections capture bytes, spread captures array identities, and post-call comparisons cover every backing root, array length and individual view identity. Source references are scoped and limited to input shape checks, iteration and native decoding; unknown calls, writes and native escapes cannot establish non-mutation. The existing dependency-neutral gate is still required.
+
+Draft:1,387PASS/0FAIL/3SKIP; retained four public tests unchanged. A wrong variant reverses/restores the input array: all four tests pass while a Proxy records four writes; source-effect checks keep its non-mutation criterion pending.22new real-verifier controls cover partial backing coverage, aliases, assertion/projection tampering, array identity, source mutation/restore and dependency changes. Applied SDK/regression/static qualification and final full remain required.
+
+Checkpoint shape draft162 is preserved separately. Counterexample164 exposes the unchanged reference mutating inputs when the exact thrown error aliases an input. Proposal167 requests one explicit error-annotation exception and remains unapproved/unapplied, alongside CSV/expiry decisions. No benchmark prompt/reference/expected change, SDK upgrade, provider call or new authority is included in stage15.
+
+## Stage16 applied: pure record reducer non-mutation evidence
+
+Stage15 byte qualification is sealed with SDK 2/2, regression 1,387 PASS / 0 FAIL / 3 SKIP and static checks PASS. Stage16 preserves six preimages and extends two existing acceptance modules. The source reader permits only a closed synchronous reducer over scoped record fields, native numeric predicates and fresh record/array expressions. Every branch is checked, including paths absent from public tests. Unknown effects, input writes or restore sequences, input freezing and effectful defaults cannot establish non-mutation. The test reader requires actual source-bound record/array invocations in live literal test bodies; frozen witnesses alone are insufficient.
+
+Draft regression: 1,408 PASS / 0 FAIL / 3 SKIP. Twenty-one additive real-verifier controls retain the original test prefix and cover ordinary mutable inputs, renamed APIs/fields, conditional input/array writes, freeze effects, restoration, unknown helpers/defaults, missing arrays and unreachable/tampered witnesses. Counterexample190 inserts a conditional write into the original reference; all four public tests pass while an ordinary state object changes. Its non-mutation criterion remains pending. Original benchmark source, prompts, tests and expected outcomes are unchanged.
+
+Applied SDK/regression/static qualification and final full remain required. Checkpoint shape draft162 and the three unapproved contract proposals are preserved separately. No SDK upgrade, provider call or new authority is included.
+
+## Stage17 applied: origin of local computed record stores
+
+Stage16 abort qualification is sealed with SDK 2/2, regression 1,408 PASS / 0 FAIL / 3 SKIP and static checks PASS. Stage17 preserves five preimages: one existing source module, one additive test file, test inventory digest and these documents. A computed store of a plain record into a locally declared const empty object or unshadowed native clone of a parameter cannot itself introduce a callable at that dynamic key. The inventory still visits every child member; competing methods/function references remain ambiguous. Unknown receivers, native/helper aliases, block/catch/function/class binding collisions, computed receiver chains, prototype paths and unsupported values remain unresolved. Analysis is bounded to32local stores and existing AST budgets.
+
+Thirty-eight additive origin controls retain the existing test prefix. Draft broad regression: 1,446 PASS / 0 FAIL / 3 SKIP. Original replay export routing is restored, but the exact whole criterion remains pending: source/test evidence for contextual identifier fields is still required. Counterexample213 changes the ID predicate to accept undefined; all four unchanged public tests pass, yet events missing either declared ID are wrongly accepted. No replay completion or acceptance authority follows from origin classification. Applied regression/static/SDK and final candidate full remain required. All three contract proposals and checkpoint shape draft162 remain unapplied.
+
+## Stage18 applied: field rejection and order in record transitions
+
+Stage17 callable origin is validated by 1,446 PASS / 0 FAIL / 3 SKIP and static checks; its original replay SDK still fails the combined field/order acceptance clause. Stage18 adds bounded optional nested literal facts to the existing reader and a contract/source/test path in the existing parameter reader. It derives names from declared fields and signatures, checks all statements of the supported transition, validates native clone/set and guard bindings, and requires direct real rejection calls for isolated malformed fields plus a fresh ordered multi-event result assertion. Unsupported shapes, extra clauses, unknown calls, native aliases and unstable bindings stay pending. No new verifier authority, benchmark-name routing or retry counter is added.
+
+Seven preserved paths contain three existing source modules, one additive test, the public-test inventory digest and these two documents. Sixty-nine controls retain the original 174-test prefix. Draft qualification234 is 1,515 PASS / 0 FAIL / 3 SKIP. Diagnostic232 retains all ten original SDK clauses and four public tests; executed counterexamples233 show missing-ID acceptance and output sorting both pass those public tests yet violate required behavior and remain pending. These are offline disposable development controls, not changed campaign mutants. Applied-source SDK, regression/static and final full qualification remain required.
+
+Checkpoint shape draft162 and the three contract proposals remain separate. Workspace SDK235 on stage17 records cycle and non-mutation proof pending; its 1 PASS / 1 FAIL is not a new-candidate full result. Chat/workflow, default docs, mapping108, final qualification and D026 rebind remain open.

package/docs/piagent-core-plan-checkpoint-2026-09-06.json

@@ -0,0 +1,69 @@
+{
+  "schemaVersion": 1,
+  "planId": "PCL-2026-09-06",
+  "version": "1.0",
+  "recordedAt": "2026-09-06T15:00:32.362336+00:00",
+  "status": "RESEARCH_COMPLETE_IMPLEMENTATION_PAUSED",
+  "repository": "/Users/vtamm/Documents/piagent-35-recovery-20260831T090020Z/implementation",
+  "head": "c3a4427396984554eb1571e687caba0f831176ae",
+  "branch": "codex/piagent-35-recovery-20260831",
+  "parentBenchmarkPlanId": "PRB-108-2026-09-06",
+  "parentEvidence": {
+    "name": "benchmark-validity-recovery-20260906T135741Z",
+    "manifestSha256": "995bcc902f89e40e7ea0828b6e6d9fdcc9098bfb5f35ee7418624aa6ba4ab5fa",
+    "sealedEvidenceModified": false
+  },
+  "research": {
+    "primarySources": 34,
+    "publicRepositoriesPinned": 8,
+    "selectedCodeFiles": 13,
+    "changelogs": 1,
+    "papersReadAtAbstractScopeOnly": 4
+  },
+  "preservation": {
+    "preexistingGitStatusEntries": 153,
+    "e14ChangedFileHashesMatchedBeforeWrite": 153,
+    "scopedSourceAndDocFilesCheckedBeforeWrite": 2456,
+    "sourceChangesInThisResearchTurn": 0,
+    "stagedPaths": [],
+    "onlyNewDocumentationFiles": [
+      "piagent-core-improvement-plan.md",
+      "piagent-core-reasoning-research-2026-09-06.md",
+      "piagent-core-research-sources-2026-09-06.json",
+      "piagent-core-plan-checkpoint-2026-09-06.json"
+    ],
+    "candidateIdentityNote": "New nonignored docs change whole-candidate selection. E14 source/test evidence remains historical and is not rebound by this checkpoint."
+  },
+  "boundaries": {
+    "implementationPaused": true,
+    "sdkUpgraded": false,
+    "testsRunThisResearchTurn": false,
+    "providerInferenceCallsThisResearchTurn": 0,
+    "campaignReserved": false,
+    "paidAuthorityCreated": false,
+    "subagentsSpawned": false,
+    "worktreeCreated": false,
+    "pushedOrPublished": false,
+    "benchmarkTreatmentChanged": false,
+    "d026Rebound": false,
+    "run6Verdict": "INVALID_MEASUREMENT"
+  },
+  "artifacts": [
+    {
+      "path": "docs/piagent-core-improvement-plan.md",
+      "sha256": "b8bc53d19e753e40e9f7371248b49049933d0a9227585f6f182d8a32dc37a049",
+      "bytes": 38504
+    },
+    {
+      "path": "docs/piagent-core-reasoning-research-2026-09-06.md",
+      "sha256": "bb1ce6a8544a8b72c7574226621515d257ec0e1bbd7f311d949edfe5039895d1",
+      "bytes": 26595
+    },
+    {
+      "path": "docs/piagent-core-research-sources-2026-09-06.json",
+      "sha256": "939bf4e91e916417bf9ee626a10caad39c4be8a42758436089afee3cd82a4654",
+      "bytes": 17191
+    }
+  ],
+  "nextActionAfterOfflineResume": "C0 preservation and hunk manifest, then C1 exact usage to task report wiring; no provider launch or full suite first."
+}

package/docs/piagent-core-reasoning-research-2026-09-06.md

@@ -0,0 +1,225 @@
+<!-- language: vi; english-index: docs/en/README.md -->
+
+# Nghiên cứu lõi coding agent và đối chiếu Piagent
+
+**Ngày:** 2026-09-06 · **Thuộc plan:** PCL-2026-09-06 · **Trạng thái:** nghiên cứu hoàn tất, triển khai pause.
+
+Tài liệu phục vụ [kế hoạch cải thiện lõi Piagent](piagent-core-improvement-plan.md). Kết luận ưu tiên là **nối đúng những cơ chế đã có, giữ đủ thông tin cho model và giảm thao tác vô ích**, sau đó đo lợi ích trên công việc thực tế. Chưa có bằng chứng candidate Piagent mới làm tăng chất lượng hay giảm token của model thật.
+
+## 1. Phạm vi và cách đọc nguồn
+
+- 34 nguồn chính trong ledger dưới đây: bài kỹ thuật/docs của tác giả, file nguồn/changelog và bốn abstract nghiên cứu.
+- 10 hệ agent: Pi, Codex, Claude Code, Cursor, Aider, mini-SWE-agent, OpenHands SDK, Gemini CLI, OpenCode, Cline. SWE-agent được bổ sung qua paper về giao diện agent–máy tính.
+- Tám repo công khai ghim commit; tải **13 file source và một changelog** vào vùng tạm để đọc tĩnh các đoạn liên quan. Không clone, cài package, chạy agent hay thực thi code bên ngoài.
+- Đọc có mục tiêu vòng xử lý, context, công cụ, event/state và failure behavior. Không tuyên bố audit toàn repo, tái lập leaderboard hay đọc toàn văn bốn paper.
+- Claude Code/Cursor: nguồn là bài kỹ thuật do đội sản phẩm công bố. Không coi repo CLI/public docs là mã nguồn mở đầy đủ của lõi hai sản phẩm này.
+- Các trang docs và blog có thể thay đổi; mốc truy cập 2026-09-06. Code links ghim commit, không dùng `main` làm identity tái lập. Metadata và SHA-256 từng file nằm trong [source manifest](piagent-core-research-sources-2026-09-06.json).
+- Chỉ dùng nguồn sơ cấp để rút khuyến nghị. Search snippets, Reddit, trang tổng hợp và tài liệu do AI dựng không được dùng làm bằng chứng thiết kế.
+
+## 2. Những kết luận có tác động tới plan
+
+### 2.1 Năng lực hiệu dụng phụ thuộc đường chạy
+
+Model tốt vẫn có thể làm việc kém khi thiếu source đúng, công cụ báo lỗi mơ hồ, trạng thái bị mất hoặc bị ép theo một chuỗi pha không phù hợp. SWE-agent nghiên cứu tác động của giao diện hành động; mini-SWE-agent hiện lại cung cấp một lõi rất gọn. Hai nguồn này cho lý do **thử đúng interface theo model/task**, không cho công thức “càng nhiều tool càng tốt” hay “bash-only luôn tốt nhất”. [S31][S31], [S22][S22]
+
+Áp dụng cho Piagent: giữ control plane đang có, nhưng kiểm xem mỗi instruction, context pack, tool group và pha có giúp hoàn tất việc hay chỉ tăng chi phí. Không thay Pi bằng một framework khác để theo xu hướng.
+
+### 2.2 Cắt token có thể làm tốn token hơn
+
+Postmortem Claude Code ghi nhận việc xóa reasoning lặp sau idle làm mất tính liên tục và gây cache misses; một thay đổi giảm verbosity cũng làm chất lượng coding giảm. Đây là evidence của hệ đó tại thời điểm đó, không phải bug đã chứng minh trong Piagent. [S11][S11]
+
+Áp dụng: đo usage, cache, đọc lại, effort và chất lượng cùng nhau. Không đặt giảm reasoning hay giảm độ dài output thành mục tiêu độc lập. Context ngắn hơn chỉ đáng giữ nếu tổng chi phí để làm đúng giảm.
+
+### 2.3 Retrieval nên đưa đúng phần cần thiết và cho phép quay lại nguồn
+
+Aider dùng graph/symbol ranking; Cursor đưa các output dài ra tài nguyên có thể đọc theo nhu cầu. Anthropic mô tả cách kết hợp dữ kiện ban đầu với truy xuất đúng lúc. [S16][S16], [S14][S14], [S08][S08]
+
+Piagent đã có lexical/symbol/RRF retrieval và delivery confirmation. Bước kế tiếp là kiểm freshness, dependency coverage, lặp context và giá trị thật của pack. Không cần mở dự án embedding service trước khi chứng minh retrieval hiện tại không đủ.
+
+### 2.4 Phải tách lịch sử nguồn khỏi bản context chiếu cho model
+
+OpenHands có event history và view; condenser không được sửa trực tiếp cached view. OpenCode chỉ prune tool results theo điều kiện và vùng được giữ. [S24][S24], [S25][S25], [S28][S28]
+
+Piagent đã có governor/ledger và task truth. Nên kiểm sự nhất quán của projection/resume thay vì thêm store trạng thái thứ hai. Một bản tóm tắt không được thay thế authority, exact verifier hoặc source identity.
+
+### 2.5 Kiểm chứng cần giúp chọn bước sửa, không sinh vòng chứng minh vô hạn
+
+Nghiên cứu intrinsic self-correction có kết quả và điều kiện khác nhau; abstract của một công trình cho kết quả tiêu cực khi thiếu external feedback, công trình khác nhấn mạnh điều kiện prompt/temperature. Không thể suy thành định luật cho mọi model hiện nay. [S33][S33], [S34][S34]
+
+Lựa chọn thực dụng cho Piagent: dùng lỗi quan sát được, source hiện tại và kiểm tra có thể bác bỏ giả thuyết; không thêm reviewer model hoặc lời nhắc “nghĩ lại” sau mọi lượt. Tái sử dụng continuation maximum 1/progress signature; không sao chép loop detector có thêm model calls của Gemini. [S27][S27]
+
+### 2.6 Chất lượng sản phẩm cần một nguồn phản hồi ngoài điểm test
+
+Cursor mô tả kết hợp eval với dữ liệu sử dụng như code bị sửa lại và phản hồi người dùng. Anthropic phân biệt outcome thực tế với lời agent tự báo và nhấn mạnh độ tin cậy của phép chấm. [S15][S15], [S12][S12]
+
+Áp dụng: theo dõi first-handoff correctness, việc mở lại, công sửa tay và cost của cả những attempt thất bại. Không dùng “code còn được giữ” hay một câu hài lòng thay cho kiểm chứng correctness; chúng là tín hiệu bổ sung.
+
+## 3. Ma trận tiếp nhận theo từng hệ
+
+| Hệ / mức đọc | Cơ chế đáng học | Áp dụng ở Piagent | Điều không sao chép mặc định |
+|---|---|---|---|
+| Pi — release + 2 source slices | Agent loop, steering, compaction, protocol failure | Giữ SDK làm nền; kiểm adapter/hook compatibility | Theo `main` hoặc nâng SDK ngay vì có version mới |
+| Codex — blog + 2 source slices + model docs | Prefix/cache, context metadata, compaction boundary | Dùng wire telemetry đã có, kiểm replay/phase/opaque state | Biến cơ chế riêng Responses thành giả định cho mọi provider |
+| Claude Code — engineering articles | Context rõ, long-task artifacts, postmortem chất lượng | Giữ task truth, hành trình đúng, feedback cụ thể | Hạ effort/cắt reasoning hoặc thêm initializer/subagent trái phạm vi |
+| Cursor — 2 blog kỹ thuật | Dynamic context, theo dõi rework thực tế | Output references và real-work follow-up có quyền | Chép tỷ lệ tiết kiệm của Cursor thành cam kết Piagent |
+| Aider — 3 docs/blog + 2 source slices | Repo map, edit format, failed-hunk feedback | Dùng index/edit freshness hiện tại, báo lỗi sửa được | Fallback tự chuyển patch sang file khác; hai model cho mọi edit |
+| mini-SWE-agent — docs + default agent | Lõi nhỏ, tách model/environment, tính cả lỗi đã billed | Đối chứng đơn giản và accounting thất bại | Mang cost/step defaults hay quyền bash không giới hạn vào Piagent |
+| OpenHands SDK — docs + 2 source slices | Event history và context projection tách biệt | Giữ ledger/view không làm biến dạng source evidence | Framework mới, remote server hoặc nhiều condenser chồng nhau |
+| Gemini CLI — 2 source slices | Giữ recent outputs, phát hiện summary rỗng/phình, failure taxonomy | Controls cho compaction/progress hiện có | Hai lượt model để summary+probe; LLM loop-check thêm phí |
+| OpenCode — 2 source slices | Prune có vùng bảo vệ, rõ loại stop/continue/compact | Kiểm hiệu quả và tính đầy đủ của governor | Copy doom-loop threshold/retry policy thành counter thứ hai |
+| Cline — changelog ở commit ghim | Ca lỗi compaction quá mạnh, edit retries và model compatibility | Thêm đúng controls thiếu nếu Piagent có đường tương tự | Coi changelog là chứng minh code Cline hay Piagent đã an toàn |
+
+## 4. Đối chiếu cụ thể với code Piagent
+
+Đường dẫn dưới đây thuộc repo implementation đã chỉ định. Đây là đọc tĩnh có phạm vi; “cần kiểm” không có nghĩa “đã xác nhận bug”.
+
+| ID local | Bằng chứng | Kết luận được phép | Gói plan |
+|---|---|---|---|
+| P01 | `runtime/product/efficiency-metrics.ts`: exactUsage default unavailable; invocation count/first-correct-edit còn null | Báo cáo task có wiring gap đã xác nhận | C1 |
+| P02 | `runtime/registration/context-commands.ts:221`, `runtime/product/operator-projections.ts:82` | Call sites đã đọc không truyền exactUsage; cần nối nguồn usage phù hợp | C1 |
+| P03 | `extensions/context-engine.js`: index v2, lexical/symbol/RRF, budgets, dedup, protected excludes | Retrieval tồn tại; token estimate không phải token billed | C2 |
+| P04 | `runtime/context/context-delivery.ts` | Đã phân biệt offered/staged với delivered/confirmed theo task identity | C2 |
+| P05 | `runtime/session/adaptive-context-governor.ts`, `adaptive-context-ledger.ts` | Có governor, bảo toàn task truth/protocol và passthrough; không thêm engine trùng | C2/C5 |
+| P06 | `runtime/context/prefix-telemetry.ts`, `runtime/model/provider-wire-fingerprint.ts`, `extensions/piagent-guard.ts:3858` | Có cả canonical và ordered wire fingerprints. Chưa đủ để suy cache hit nếu không nối provider usage | C1/C2 |
+| P07 | `runtime/solver/solver-shadow.ts`, `solver-policy.ts` | Solver mặc định shadow; suggestion không đồng nghĩa thực thi | C4 |
+| P08 | `runtime/model/model-route-policy.ts`, `extensions/piagent-guard.ts:3900` | Có bảng model cụ thể, explicit pin preservation, mặc định off; host đã đọc báo boundary unavailable | C6 |
+| P09 | `runtime/recovery/continuation-budget.ts` | Global continuation/progress signature đã có; giữ maximum 1 | C4 |
+| P10 | `runtime/quality/edit-freshness-guard.ts`, `runtime/tools/phase-tool-runtime.ts` được đăng ký trong guard | Đã có cơ chế; cần đọc đúng consumer/tests trước thay đổi | C3 |
+| P11 | `extensions/repository-memory.js`, `runtime/context/repository-memory-hints.ts` | Có citations/expiry/protected filtering/advisory; chưa chứng minh freshness và lợi ích trên mọi hành trình | C5 |
+
+Các đường dẫn bắt đầu bằng `runtime/` hoặc `extensions/` trong bảng nằm dưới `packages/piagent-core/`.
+
+Một phát hiện tránh được việc xây thừa: chỉ nhìn `prefix-telemetry.ts` sẽ thấy tool list được sort, nhưng code khác đã có `orderedToolSurfaceHash` và `provider_request_wire_surface`. Vì vậy plan không ghi “thiếu wire fingerprint”; gap là **đối soát wire/context với usage và outcome của task**.
+
+## 5. Ledger 34 nguồn chính
+
+### Pi và Codex
+
+| ID / nguồn | Phần đã đọc và bằng chứng | Giới hạn / quyết định |
+|---|---|---|
+| S01 — [Pi releases][S01] | Release notes 0.85.0/0.85.1; 0.85.1 sửa lỗi import SDK và một số tương thích provider | Chọn ứng viên nâng cấp có qualification, không khẳng định SDK cũ gây mọi failure |
+| S02 — [Pi agent-loop.ts][S02] | `runLoop`, steering/prepareNextTurn, error/abort và tool call khi output bị cắt | Code upstream snapshot, không tự coi đã có trong SDK 0.84.1 cài local |
+| S03 — [Pi compaction.ts][S03] | `calculateContextTokens`, usage selection và estimate trailing messages | Context estimate phục vụ quản lý cửa sổ; không thay cost accounting |
+| S04 — [Unrolling the Codex agent loop][S04] | Performance/cache prefix, tool order, config changes và compaction | Bài 23/01/2026; một số hiện thực có thể tiến hóa, không đồng nhất snapshot tháng 9 |
+| S05 — [Codex compact_remote.rs][S05] | Request/step boundary, metadata trigger/reason/phase và hook khi compaction | Học cách quan sát lifecycle; không copy remote endpoint vào mọi provider |
+| S06 — [Codex history.rs][S06] | History envelopes, normalized prompt views và metadata preservation | Đọc phần liên quan, không audit toàn bộ bộ quản lý history |
+| S07 — [OpenAI model guidance, GPT-5.5][S07] | Outcome/success/stopping rules; giữ phase khi replay assistant items | Guidance theo model, không phải lệnh đổi model hoặc bỏ invariant Piagent |
+
+### Claude Code / Anthropic và Cursor
+
+| ID / nguồn | Phần đã đọc và bằng chứng | Giới hạn / quyết định |
+|---|---|---|
+| S08 — [Effective context engineering][S08] | Context nhỏ nhưng đủ tín hiệu, retrieval đúng lúc, compaction/note-taking | Không gán mọi hiện tượng long context của model cũ cho mọi model mới |
+| S09 — [Writing effective tools][S09] | Tool purpose rõ, giảm overlap, output hữu ích với chế độ concise/detailed | Không loại ID/field cần cho hành động sau chỉ vì muốn ít token |
+| S10 — [Effective harnesses for long-running agents][S10] | Tiến độ tăng dần, feature state, artifact tiếp nối và premature completion | Dùng task state có sẵn; không thêm initializer/subagent hay auto commit |
+| S11 — [Claude Code quality postmortem][S11] | Ba thay đổi effort/context/verbosity và cách chúng gây giảm chất lượng | Case study, không kết luận model weights kém hoặc Piagent có cùng bug |
+| S12 — [Demystifying evals for AI agents][S12] | Outcome vs transcript, model+harness, capability/regression eval và grader reliability | Giữ eval như phép đo; không thêm cả chương trình benchmark mới vào core |
+| S13 — [Infrastructure noise][S13] | Resource enforcement và timeout làm thay đổi ý nghĩa kết quả | Khóa tài nguyên; không sao chép mức headroom hay tăng cap hiện tại |
+| S14 — [Cursor dynamic context discovery][S14] | Output file references, history retrieval, skills/tool discovery | Số tiết kiệm tác giả báo là riêng cohort của Cursor, không đưa vào target Piagent |
+| S15 — [Cursor harness improvement][S15] | Context thay đổi theo model; online/offline signals, keep rate/rework và error taxonomy | Keep rate chỉ là proxy; không dùng model đọc phản hồi user nếu chưa có quyền |
+
+### Aider và mini-SWE-agent
+
+| ID / nguồn | Phần đã đọc và bằng chứng | Giới hạn / quyết định |
+|---|---|---|
+| S16 — [Aider repository map][S16] | Symbol/signature map, dependency graph ranking và budget | Không copy token default; Piagent đã có index/ranking |
+| S17 — [Aider repomap.py][S17] | `get_repo_map`, ranked tags/cache và PageRank implementation slices | Có implementation support cho docs; chưa kiểm định ranking trên repo Piagent |
+| S18 — [Aider edit formats][S18] | Whole vs diff/search-replace; khả năng theo format khác nhau giữa model | Chọn theo evidence; không bắt whole-file cho mọi thay đổi |
+| S19 — [Aider editblock_coder.py][S19] | Dry-run/apply, feedback failed hunk, partial success và fallback sang file khác | Chỉ học feedback; không chấp nhận chuyển target file tự động vào Piagent |
+| S20 — [Separating code reasoning and editing][S20] | Hai bước architect/editor, có thể cùng hoặc khác model; tradeoff latency | Thí nghiệm 2024, không áp mặc định hai calls hoặc hai agents hiện nay |
+| S21 — [mini-SWE-agent overview][S21] | Thiết kế tối giản, tách agent/environment/model | Documentation/claims của tác giả; không nhập điểm benchmark vào báo cáo Piagent |
+| S22 — [mini-SWE-agent default.py][S22] | Đọc default agent: step/query/execute, limits, format-error billed cost, save state | Học phân loại failure/accounting; không copy default limits hoặc raw trajectory logging |
+
+### OpenHands, Gemini CLI, OpenCode, Cline
+
+| ID / nguồn | Phần đã đọc và bằng chứng | Giới hạn / quyết định |
+|---|---|---|
+| S23 — [OpenHands condenser architecture][S23] | Condenser/View/Condensation và no-op/LLM/pipeline distinction | Context management có giá; không mặc định thêm summarizer model |
+| S24 — [OpenHands condenser/base.py][S24] | Read-only cached views, soft/hard condensation và fallback | Giữ lịch sử nguồn và projection riêng; không sửa cached state tại chỗ |
+| S25 — [OpenHands conversation/state.py][S25] | Event log, active-branch derived view/cache và incremental tail | Bài học state ownership; không thêm branching/worktree vào phạm vi single-agent |
+| S26 — [Gemini chatCompressionService.ts][S26] | Recent-output budget, summary+probe và reject summary rỗng/phình | Học negative controls; hai model turns cho compression không phải tối ưu miễn phí |
+| S27 — [Gemini loopDetectionService.ts][S27] | Lặp phải không có tiến bộ; có model-based check với lịch riêng | Giữ progress guard sẵn có; không thêm model-loop reviewer/counter |
+| S28 — [OpenCode compaction.ts][S28] | Prune completed tool outputs, recent/protected vùng và minimum saving | Không bỏ tool state đang pending hoặc evidence còn cần |
+| S29 — [OpenCode processor.ts][S29] | So recent tool name+arguments, loại lỗi, stop/continue/compact và retry policy | Không copy doom-loop threshold hay tăng retry quyền Piagent |
+| S30 — [Cline CHANGELOG][S30] | Lỗi compaction quá mạnh, retry edit lặp, native tool/model compatibility | Chỉ là changelog: dùng chọn failure scenarios, không coi là source-level proof |
+
+### Nghiên cứu để kiểm tra giả định
+
+| ID / nguồn | Phần đã đọc và bằng chứng | Giới hạn / quyết định |
+|---|---|---|
+| S31 — [SWE-agent ACI paper][S31] | Abstract: giao diện hành động ảnh hưởng khả năng tìm/sửa/test code | Không tái lập paper; model/task 2024 khác hệ hiện tại |
+| S32 — [Lost in the Middle][S32] | Abstract: vị trí thông tin ảnh hưởng QA/key-value retrieval ở model nghiên cứu | Không chứng minh mọi model 2026 cùng mức suy giảm, cần controls của Piagent |
+| S33 — [Cannot Self-Correct Reasoning Yet][S33] | Abstract: intrinsic self-correction thiếu external feedback có thể không giúp | Không suy thành “model không thể tự sửa” vô điều kiện |
+| S34 — [Intrinsic Self-Correction Ability][S34] | Abstract: kết quả khác dưới điều kiện prompt/temperature được nghiên cứu | Không tự đổi temperature trên provider/model không hỗ trợ; kiểm chứng khách quan vẫn cần |
+
+## 6. Quyết định ưu tiên / thử có điều kiện / hoãn
+
+| Hướng | Quyết định | Lý do và ranh giới |
+|---|---|---|
+| Usage → task/outcome; tính cả thất bại | Ưu tiên đầu | Gap code xác nhận, cần cho mọi quyết định tiết kiệm |
+| Context đúng nguồn, output có thể đọc lại, cache-aware | Ưu tiên sau instrumentation | Tận dụng retrieval/governor/wire có sẵn, giữ correctness |
+| Feedback sửa lỗi rõ và edit freshness | Ưu tiên khi có đường lỗi cụ thể | Tránh token lãng phí ở thao tác, không nới guard |
+| Task state ngắn, bước tiếp theo theo evidence | Ưu tiên | Giúp model giải quyết thay vì lặp diễn giải plan |
+| SDK 0.85.1 | Thử tương thích riêng | Phiên bản mới có ích tiềm năng nhưng ảnh hưởng identity/protocol |
+| Repo map / tool grouping / edit format | Thử theo task/model | Không có một cấu hình tốt nhất cho mọi model |
+| Cross-task memory | Cải thiện phần hiện có có điều kiện | Phải advisory, có nguồn, đúng quyền và có lợi ích |
+| Model routing tự động / giảm effort | Hoãn | Chưa có causal evidence; giữ pin và quality floor |
+| Hai model architect/editor, critic sau mỗi bước | Hoãn | Thêm phí/latency, chưa chứng minh thắng single-agent |
+| LLM verifier cho mọi summary/loop | Không đưa vào đợt đầu | Tăng vòng gọi; đã có deterministic safeguards |
+| Vector DB, framework rewrite, swarm | Không đưa vào đợt này | Chưa có gap chứng minh cần; trái phạm vi single-agent nếu swarm |
+| Universal semantic prover / benchmark-specific branches | Không theo đuổi | Quay lại vòng nghiên cứu khó kết thúc và nguy cơ overfit |
+| Bỏ guard để “model thông minh hơn” | Không chấp nhận | Autonomy phải ở trong quyền và contract đã cấp |
+
+## 7. Những gì chưa biết và cách giải hữu hạn
+
+1. **Piagent đang lãng phí ở đâu nhiều nhất?** C1 trả lời theo chi phí task; không đoán bằng số dòng source hay số tests.
+2. **Governor và SDK compaction có tương tác làm mất nghĩa?** C2/C6 kiểm đúng transitions, không blanket audit mọi provider.
+3. **Context pack/routing hiện tại giúp hay làm model phân tâm?** Chọn tối đa hai giả thuyết sau telemetry; đối chứng cùng model/SDK ở C7 khi được phép.
+4. **Task thật của người dùng phân bố thế nào?** Lập corpus từ backlog được quyền sử dụng; chưa có thì ghi thiếu dữ liệu, không gọi fixture là real use.
+5. **SDK mới có đáng nâng?** Dùng contract matrix; nếu không có lợi hoặc không tương thích thì giữ version cũ với giới hạn rõ.
+
+Mỗi unknown có owner là người triển khai single-agent, evidence cần lấy và giới hạn nghiên cứu trong C0. Không mở thêm lượt đọc blog chỉ để tăng số nguồn sau khi câu hỏi thiết kế đã được trả lời.
+
+## 8. Checkpoint và bảo toàn
+
+Nghiên cứu được thực hiện trên HEAD `c3a4427396984554eb1571e687caba0f831176ae`, branch `codex/piagent-35-recovery-20260831`, với 153 đường dẫn recovery thay đổi trước tài liệu mới. Không có source edits, tests, SDK upgrade, provider/model calls, campaign reservation, paid authority, worktree, subagent, push hay publish trong đợt nghiên cứu này. Các yêu cầu HTTP đọc tài liệu/repo công khai là hoạt động nghiên cứu, không phải phiên model benchmark.
+
+Không khẳng định E14 full qualification đã xanh. Kết quả full lịch sử và 18 default correct-completion đỏ được giữ nguyên. Run-6 tiếp tục `INVALID_MEASUREMENT`. Mọi thay đổi source/treatment đề xuất trong PCL cần thuộc đúng phạm vi resume/identity; D-026 không tự áp cho chúng.
+
+Chi tiết hash tài liệu và kiểm tra bảo toàn xem [checkpoint PCL](piagent-core-plan-checkpoint-2026-09-06.json). Nội dung này là nghiên cứu và kế hoạch, không phải evidence cải thiện model đã đạt.
+
+
+[S01]: https://github.com/earendil-works/pi/releases
+[S02]: https://github.com/earendil-works/pi/blob/9767ba275f3e9a5ee0f5c5342249b629ab1b2282/packages/agent/src/agent-loop.ts
+[S03]: https://github.com/earendil-works/pi/blob/9767ba275f3e9a5ee0f5c5342249b629ab1b2282/packages/coding-agent/src/core/compaction/compaction.ts
+[S04]: https://openai.com/index/unrolling-the-codex-agent-loop/
+[S05]: https://github.com/openai/codex/blob/ac192cd7937b0d73edc6dffe009940ae53782dd4/codex-rs/core/src/compact_remote.rs
+[S06]: https://github.com/openai/codex/blob/ac192cd7937b0d73edc6dffe009940ae53782dd4/codex-rs/core/src/context_manager/history.rs
+[S07]: https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.5
+[S08]: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+[S09]: https://www.anthropic.com/engineering/writing-tools-for-agents
+[S10]: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
+[S11]: https://www.anthropic.com/engineering/april-23-postmortem
+[S12]: https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents
+[S13]: https://www.anthropic.com/engineering/infrastructure-noise
+[S14]: https://cursor.com/blog/dynamic-context-discovery
+[S15]: https://cursor.com/blog/continually-improving-agent-harness
+[S16]: https://aider.chat/docs/repomap.html
+[S17]: https://github.com/Aider-AI/aider/blob/5dc9490bb35f9729ef2c95d00a19ccd30c26339c/aider/repomap.py
+[S18]: https://aider.chat/docs/more/edit-formats.html
+[S19]: https://github.com/Aider-AI/aider/blob/5dc9490bb35f9729ef2c95d00a19ccd30c26339c/aider/coders/editblock_coder.py
+[S20]: https://aider.chat/2024/09/26/architect.html
+[S21]: https://mini-swe-agent.com/latest/
+[S22]: https://github.com/SWE-agent/mini-swe-agent/blob/04d809ceab9df28f9adaed044884180159172930/src/minisweagent/agents/default.py
+[S23]: https://docs.openhands.dev/sdk/arch/condenser
+[S24]: https://github.com/OpenHands/software-agent-sdk/blob/8ea8e3bc1d5e84542f7702b8813734ef600c9fce/openhands-sdk/openhands/sdk/context/condenser/base.py
+[S25]: https://github.com/OpenHands/software-agent-sdk/blob/8ea8e3bc1d5e84542f7702b8813734ef600c9fce/openhands-sdk/openhands/sdk/conversation/state.py
+[S26]: https://github.com/google-gemini/gemini-cli/blob/85aca163f6c73ac6ce380b5447359146b8adcae4/packages/core/src/context/chatCompressionService.ts
+[S27]: https://github.com/google-gemini/gemini-cli/blob/85aca163f6c73ac6ce380b5447359146b8adcae4/packages/core/src/services/loopDetectionService.ts
+[S28]: https://github.com/anomalyco/opencode/blob/337fd144d2ba144743368f78d9579a99cce175bd/packages/opencode/src/session/compaction.ts
+[S29]: https://github.com/anomalyco/opencode/blob/337fd144d2ba144743368f78d9579a99cce175bd/packages/opencode/src/session/processor.ts
+[S30]: https://github.com/cline/cline/blob/dac3b35ba485dbab3b5a73aca239b0d07ce071cf/CHANGELOG.md
+[S31]: https://arxiv.org/abs/2405.15793
+[S32]: https://arxiv.org/abs/2307.03172
+[S33]: https://arxiv.org/abs/2310.01798
+[S34]: https://arxiv.org/abs/2406.15673