feat: native agent orientation with oracle conformance
Agents need orientation at session start. This adds native brief context, append-only history, and read-only tree/graph deps, with byte comparisons against the locked pm 2026.10.14 oracle. Release automation remains disabled.
Fixes #93.
The orientation contract lists every claimed flag, refusal, data boundary, concurrency limit and latency receipt. Context supports brief focus, high/low-level groups, blocked fallback, limits and token budgets. History supports compact/full rows, limits and opt-in seal/replay verification; --verify --strict-exit returns the oracle's broken-chain report with exit 1. Dependencies expose missing targets, cycles and bounded tree/graph traversal. All three retain default TOON and JSON bytes. Rich projections, canonical output controls, custom scorers and dependency writes are deferred with explicit problem envelopes.
Context captures one authoritative corpus. Reads acquire no writer lock and execute no recovery journal; they do not claim a transactional cross-file snapshot during same-item mutation. Concurrent unrelated-write acceptance preserves target item/history bytes. Existing writers retain locks and recovery; Windows publication replaces with rename directly so readers do not observe an unlink gap.
Review findings and regression evidence:
- Context captures the global extension root once and supplies it to both scorer refusal and extension health. SDK unit fixtures pass explicit synthetic roots.
cargo test --locked --lib context_explicit_global_rootfails with exit 101 when only the boundary's ambient lookup is restored under a synthetic global scorer; restored code passes. All 238 library tests pass under that same scorer. Service overrides still refuse with health enabled or omitted. - Collection selection, path receipts and prefix binary search are shared by list/search and orientation. Both command-specific finalizers keep their existing numeric semantics. This extraction preserves behavior: reverting it restores duplication rather than changing output.
npm exec --yes --package=jscpd@4.0.5 -- jscpd src/read_output.rs --format rust --min-lines 5 --min-tokens 50 --threshold 0 --reporters jsonpasses with zero clones. The previous implementation fails at unchanged settings with two clones, 26 duplicated lines (2.92%). Existing unit/oracle budget tests validate both callers. - The suggested normalized dependency graph keys are declined because they change the pinned oracle's output.
cargo test --locked --test orientation_differential deps_mixed_case_dangling_matches_oracleperforms 32 real-CLI comparisons: tree/graph, summary/full, JSON/TOON and depth/node/edge limits. Two dangling display spellings produce five full nodes/two missing rows but four normalized summary nodes/one missing identity. Applying only the suggested graph change fails (101); oracle-compatible code passes (0), preserving tracker bytes. - Reviewer issue #93 is fixed: dangling scalar parents produce parent edges in tree, graph and summary. Ten controls cover terminal/open holders, missing/existing parents, equivalent structured edges, mixed case/whitespace and scalar order: 120 real-CLI comparisons. Existing parents add no synthetic edge. Twelve additional controls retain the oracle's no-active-blocker traversal receipt.
- Earlier regression controls remain: rejected-token diagnostics use Clap's actual argument; history validates filenames before corpus/path checks; context handles non-Unicode environment strings and custom lifecycle progress classifications; dependency indexing constructs one normalized identity set. Finding-specific single-fix reverts fail after rebuilding, with exact commands recorded in PM. The closed-pipe test preflights valid history, then requires exit 2/stderr; malformed-history and injected exit-3 fault controls prove both assertions.
Current-head validation at ef276adb0316de850d89605ea295e9e997bf4ac8:
- Isolated
RUST_TEST_THREADS=8 just release-check: 464 normal + 464 instrumented tests, 20 suites each, zero failures or ignored tests. Mandatory published-oracle comparisons ran in both passes. Fmt, pedantic deny-warnings Clippy, private-item rustdoc, identity, audit and changelog pass. Coverage: 11,701/11,701 lines / 19,167/19,167 regions / 1,180/1,180 functions / 2,826/2,826 branches, all four dimensions 100% at unchanged thresholds. Source/test digests match the gate inputs. This Rust repository has no root package.json; its documented aggregate replaces the TypeScript npm/Bun gates. - PM-linked runner: orientation 18, CLI dispatch 14, library 238, workflow contracts 18, binary units 24: 312 passed. Automatic evidence recording remains disabled by project policy (
tracking_disabled); committed PM comments retain manual receipts. Post-commit identity audit: 7 passed. - All eight exact-head acceptance/security checks pass: three normal OS jobs, three aggregate release gates, Analyze Rust and CodeQL. Linux normal 464, macOS 460, Windows 455, 20 suites each. Aggregate normal + instrumented: Linux 464 + 464; macOS 460 + 460; Windows 455 + 455, 40 suites each. Zero failures/ignored. Every OS reaches 100% lines/regions/functions/branches. Linux: 11,701/11,701 lines / 19,167/19,167 regions / 1,180/1,180 functions / 2,826/2,826 branches; macOS: 11,701/11,701 lines / 19,167/19,167 regions / 1,180/1,180 functions / 2,826/2,826 branches; Windows: 11,700/11,700 lines / 19,168/19,168 regions / 1,181/1,181 functions / 2,828/2,828 branches. The draft-only auto-merge skip is not an acceptance check.
Health is a separate boundary. The documented health --check-only --require-merge-drivers --strict-exit passes in isolation and in a fresh git clone --no-local of this exact head, eight checks each. Full health --strict-exit still reports the two inherited chain mismatches on pm-rust-bj7a and pm-rust-unih; the fresh clone reproduces exactly those two, with their authoritative bytes unchanged. pm-rust-b4yl tracks them; no history was repaired or rewritten. Host global extension version skew is absent under isolated HOME, without configuration changes. Native/oracle strict reads match on the two broken streams (13,029 and 20,573 JSON bytes, empty stderr, exit 1). The orientation feature's own 83 append-only records verify successfully with identical 19,897-byte JSON and empty stderr. The pre-existing allowed unsafe-libyaml unmaintained audit advisory remains.
The PR stays draft and unmerged. The feature claim is released and no item is closed. Replies are posted after pushing; this agent never resolves review threads. Issue #93 retains the closing reference above. The separate read-performance follow-up remains unstarted.
Large-tracker latency receipt
Measured 2026-10-18 against a complete temporary copy of the public pm CLI
tracker: 2,991 items and 6,004 authoritative files. SHA-256 checks after the
run found zero changed authoritative files in either the original or its copy.
Only the copy was passed to either CLI.
Each cell below is cold-process wall time in milliseconds. There are 30 fresh
processes for every command/runtime pair (240 samples), alternating runtime
order each round. Filesystem caches and the oracle's derived indexes are warm
after one untimed validation of every command. p50 is the median; p95 is nearest
rank, the 29th sorted sample of 30. The search term is history; get uses one
existing task. Timed context uses real clocks; the separate byte comparison
above pins clocks.
| Command | Native p50 | Native p95 | Oracle p50 | Oracle p95 |
|---|---|---|---|---|
context --limit 10 | 2592.8 | 5831.6 | 3355.3 | 8429.7 |
list --status open --limit 20 | 2116.0 | 4653.3 | 1269.9 | 3516.6 |
search history --limit 10 | 2200.0 | 4775.4 | 4177.7 | 8293.2 |
get <id> | 1864.8 | 3713.8 | 1118.5 | 2862.6 |
Hardware: four logical CPUs, Intel Core i5-7400, shared Linux host. The harness
ran under nice -n 0, retaining the inherited effective nice 15. Concurrent
package validation remained active. Start load averages (1/5/15 minutes):
18.65/12.19/14.54; end: 21.37/18.95/16.86. The sampled one-minute range was
13.84–25.64. Measurement ran from 07:56:21 to 08:06:32 UTC.
Native used cargo build --locked --release with Rust 1.90.0, source
309df2e95c201a9804e903572301fbecee0e4908. The oracle was the locked
2026.10.14 package on Node v24.19.0. Agent home, global state and author were
isolated. The binary fingerprint stayed constant throughout the run.
Native context and search have lower measured p50/p95. List and get are slower
than the oracle's warm indexed reads; selective lookup/index work is tracked in
pm-rust-wdj4. These observations include
shared-host contention. The complete sample CSV
and summary, load and integrity receipt
retain the underlying measurements.
The latency receipt measures source 309df2e95c201a9804e903572301fbecee0e4908, not the review-fix head.
PM: orientation feature, deferred orientation, read performance. Linked files/docs/tests and append-only PM evidence are committed with the code.