@hecer/yoke 1.18.0 → 1.20.0

package/docs/SOL-PI.md

@@ -0,0 +1,41 @@
+# SoL-Pi with Yoke
+
+Yoke can add NVIDIA's SoL-Pi extension to opted-in Pi invocations. The extension is off by default. This guide records the published evidence and the limits of Yoke's integration so you can decide whether to enable it.
+
+## What the paper measured
+
+The [SoL-Pi paper](https://arxiv.org/abs/2609.20519) reports benchmark runs on fixed tasks, models, harness configurations, and API prices. “Token traffic” below is recorded model-token traffic; scores are benchmark scores. The authors tested 51 publicly released tasks from EdgeBench, a subset of its 134 tasks.
+
+On EdgeBench with GPT-5.6 Sol, the paper reports:
+
+| Configuration | Recorded token traffic | API cost | Average score |
+| --- | ---: | ---: | ---: |
+| Pi baseline | 2.1538 billion | $1,339 | 44.833 |
+| SoL-Pi Efficiency, all four mechanisms | 1.0990 billion (49.0% lower) | $894 (33.2% lower) | 42.003 (93.7% of Pi) |
+| SoL-Pi Performance, ObservationPack alone | 2.0224 billion (6.1% lower) | $1,271 | 47.208 (5.3% above Pi) |
+
+The complete efficiency configuration used fewer tokens and cost less in those runs, but scored lower than Pi. The separate performance configuration was the best-scoring single mechanism for GPT-5.6 Sol; it was not the full four-mechanism stack.
+
+The paper also ran the complete stack with Opus 5, a backend not used to search for the mechanisms. It reports 44.7% less token traffic and 33.5% lower API cost than Pi ($1,158 versus $1,741), with an average score of 42.224 versus Pi's 44.756 (94.3% of Pi's score).
+
+Results vary by benchmark. On 63 CPU-only Terminal-Bench 4 tasks, SoL-Pi solved 15 of 63 while Pi solved 18 of 63; total API cost was $211.12 versus $286.45 (26.3% lower), and cost per solved task was $14.07 versus $15.91 (11.6% lower). On six IMO 2026 problems, both systems passed three; SoL-Pi's reported cost per passed problem was $20.90 versus Pi's $25.32.
+
+These are the paper's measurements, not measurements of Yoke's pinned extension build. They are not a project-level prediction or guarantee of savings. Your tasks, models, provider prices, cache billing, and enabled mechanisms can produce different cost and capability results. Yoke does not measure or promise a savings percentage for an individual project.
+
+## Defaults and runtime
+
+The `solpi.enabled` project setting defaults to `false`. Yoke adds the pinned SoL-Pi extension only to a Pi invocation when that setting is enabled. Each mechanism—`actionFusion`, `observationPack`, `evidencePreservingReducer`, and `onlineContextCompact`—also defaults to `false`; enabling the extension does not turn those mechanisms on. `cacheWriteReadRatio` defaults to `12.5` and is an input to the compaction decision, not a live price lookup or bill estimate.
+
+Yoke pins SoL-Pi to [`d7ecfc089944f0d04b80122a0a9a6ca0d786f3d0`](https://github.com/NVlabs/SoL-Pi/tree/d7ecfc089944f0d04b80122a0a9a6ca0d786f3d0). The pinned upstream lists Node.js 22.19 or newer and `@earendil-works/pi-coding-agent@0.84.2` as its tested runtime baseline. Yoke checks the Node.js version but does not enforce the Pi version; other Pi releases are unverified. Yoke does not install Pi or set up provider authentication. Review the [pinned extension source](https://github.com/NVlabs/SoL-Pi/tree/d7ecfc089944f0d04b80122a0a9a6ca0d786f3d0) before enabling it.
+
+## Trust, permissions, and data
+
+Pi project trust and extension approval remain Pi's responsibility. Yoke does not grant trust or add an automatic approval flag. If Pi requires the project to be trusted before loading project-local settings or an extension, trust it through Pi yourself.
+
+SoL-Pi runs inside the Pi process with that process's filesystem, process, network, and credential permissions. It is not a separate sandbox or permission boundary. Pi's selected tool permissions still apply: Yoke's safe Pi profile allows `read,bash,edit,write`, while its read-only profile allows `read,grep,find,ls`; the unsafe profile does not add an explicit tool allowlist. Action Fusion can run a model-requested validation command through Pi's shell tool. Review the extension at its pinned revision and choose Pi permissions appropriate for the project before enabling it.
+
+When enabled, Evidence-Preserving Reducer may send eligible diagnostic-log content to its configured reducer model using Pi-managed authentication. Logs can contain project data. Its evidence checks validate the reduced receipt against the archived source; they do not make the source private or act as a complete redaction step. Leave the reducer off for logs that must stay local, and follow the data rules for the provider that receives the request. See the upstream [SoL-Pi security policy](https://github.com/NVlabs/SoL-Pi/blob/d7ecfc089944f0d04b80122a0a9a6ca0d786f3d0/SECURITY.md).
+
+## Configuration ownership
+
+The project's `.yoke/config.yaml` is the durable source for Yoke's SoL-Pi settings; the dashboard edits the same project settings. For an enabled Pi invocation, Yoke writes the corresponding temporary extension configuration to `.pi/sol-pi.json` in that invocation's workspace, the project-local path SoL-Pi reads. When the invocation ends, Yoke restores the file's previous contents or removes the temporary file and the `.pi` directory if Yoke created it. Pi only loads project-local extension configuration for a trusted project. Keep persistent SoL-Pi choices in Yoke's project configuration. Pi installation, project trust, and provider credentials remain owned by Pi and the user. See the pinned upstream [configuration contract](https://github.com/NVlabs/SoL-Pi/blob/d7ecfc089944f0d04b80122a0a9a6ca0d786f3d0/docs/configuration.md).

package/docs/VERIFIED-PROJECTS.md

@@ -33,7 +33,7 @@ After intentionally editing protected tests, use `yoke check . --protect --refre
 ## Durable goals across providers
 
 ```sh
-yoke goal set . --objective="Finish guest checkout" --attempts=3 --minutes=30
+yoke goal set . --objective="Finish guest checkout" --criteria=guest-checkout --attempts=3 --minutes=30
 yoke goal run . --runner=codex
 yoke goal resume . --runner=claude --model=<installed-model-id>
 yoke goal resume . --runner=gemini --model=<installed-model-id>
@@ -42,9 +42,9 @@ yoke goal handoff .
 yoke goal pause .
 ```
 
-Goals keep objective, attempts, failure context and check IDs in `.yoke/goal.json`. They share the story-loop lock. Each implementation attempt is followed by independent executable acceptance. A completed goal is checked again on a later run. Failed work stays in the project; goal execution itself does not commit or publish it. Goal handoff is readable context for native agent goal facilities; Yoke does not invent or call an undocumented native goal API.
+Goals keep objective, explicit acceptance binding, attempts, failure context and check IDs in `.yoke/goal.json`. They share the story-loop lock and worker capacity. A completed goal is checked again on a later run. Failed work stays in the project; goal execution itself does not commit or publish it. Native Codex goals are optional through `--native-goal`; see the [goal guide](GOALS.md) for capability negotiation and migration of unbound goals.
 
-`--minutes` limits cumulative agent execution time. Verification is measured separately and commands retain their verification timeout. `--tokens=N` is a checkpoint budget: it prevents another attempt when measured consumption is exhausted or unknown, but cannot promise a hard token cap within a single provider call. An interrupted attempt is persisted before dispatch; recovery accounts for it conservatively and reconciles recorded provider processes before continuing. Unknown process ownership blocks execution. Pause takes effect at an attempt boundary; it does not instantly kill an in-flight agent.
+`--minutes` limits cumulative admitted provider execution time. Optional `--wall-minutes` also includes capacity waits and independent checks. `--tokens=N` blocks further execution when measured usage is exhausted or unknown, and reports post-call overruns even when checks pass; providers with end-of-call telemetry cannot promise a hard mid-call cap. Interrupted attempts are charged conservatively and recorded process ownership is reconciled before continuation. A pause requests cancellation of Yoke-owned asynchronous execution and retains unfinished work and evidence.
 
 Explicitly extend total budgets without deleting history:
 
@@ -65,7 +65,7 @@ Failed or paused isolated story worktrees are retained. Resume the same story wi
 yoke loop run . --isolate --resume-worktree --parallel=1 --candidates=1
 ```
 
-Yoke validates the registered worktree, repository, original target commit and PRD digest. Changed target/PRD state is refused; inspect retained edits and reconcile deliberately. This flag is for serial isolated recovery; parallel workers retain their existing coordinator lifecycle. `yoke loop cleanup` remains an explicit cleanup operation; inspect its removal flags before discarding unfinished work. Existing projects should rerun retrofit to add ignore entries for checks, events and goals.
+Yoke validates the registered worktree, repository, original target commit and PRD digest. Changed target/PRD state is refused; inspect retained edits and reconcile deliberately. This flag is for serial isolated recovery. Parallel retained candidates resume through the dispatcher without reimplementation when their recovery binding remains valid. `yoke loop cleanup` is an explicit discard operation. Existing projects should rerun retrofit to add runtime ignore entries for checks, events, goals, saved runs and recovery evidence.
 
 ## Spend fewer model calls
 

package/docs/code-intelligence-stdio-fix-2026-09-27.md

@@ -0,0 +1,8 @@
+# Code Intelligence stdio correction
+
+Acceptance criteria:
+- Serena and Graphify adapters initialize and call tools against newline-delimited JSON-RPC stdio servers.
+- Existing Graft and client tests remain green; TypeScript builds.
+- ReferDock uses explicit installed executable paths where Windows shims cannot be spawned.
+- Real read-only probes report backend failures honestly; no cloud graph processing or package upgrades are required.
+- Installed runtime changes retain backups and receive independent review before release.

package/docs/parallel-execution.md

@@ -80,6 +80,21 @@ one serial integration lane when integration measurements exist. Older runs with
 remain visible as missing integration history; forecasts are empirical ranges, not deadlines, and do
 not predict future contention from other projects.
 
+### Rejected integration recovery
+
+Worker and integrated-tree gates receive the same `YOKE_STORY` context. A rejected
+candidate is retained with its reason and an `integration-recovery.json` proof record;
+it is not silently discarded and regenerated. The next parallel run can reuse it
+without a new implementation model call when canonical project/worktree ownership,
+Git registration, target base and PRD digest still match. Integration gates run again.
+Changed target or PRD state blocks recovery and requires explicit reconciliation.
+Generated worktree names are shorter and Windows path limits are checked before setup.
+
+Goals also use the worker pool. Their asynchronous checks use a separate default-one
+check pool; see [goal resources](GOALS.md). These are concurrency permits, not hard CPU
+or RAM quotas. Current controlled comparisons do not establish general efficiency gains
+over direct Codex; see the [measured comparison](CODEX-COMPARISON-2026-09-29.md).
+
 ## Safe task decomposition
 
 Make a preview with:

package/docs/superpowers/plans/2026-09-30-goals-resources-release.md

@@ -0,0 +1,78 @@
+# Goals, verification and recovery implementation plan
+
+> **For agentic workers:** Implement independent parallel and resume components with dispatching-parallel-agents; integrate goal policy centrally. Write each regression before changing production behavior.
+
+**Goal:** Correct the reproduced completion/resource/integration failures, provide optional persistent native Codex Goals, and prepare a validated 1.20.0 release.
+
+**Architecture:** Yoke owns objective-specific executable acceptance and project integration. A negotiated optional native adapter owns a Codex thread, paused at verification boundaries. All actual provider calls use the same admission pool; local goal checks have abortable execution and a separate shared check budget. Durable run identity restores the correct mode and limits.
+
+**Tech stack:** TypeScript, Node 20+, Zod, Vitest, native CLI/app-server stdio; no new dependency.
+
+**Spec:** docs/GOALS-RESOURCE-AUDIT-2026-09-29.md and docs/CODEX-COMPARISON-2026-09-29.md. Recommendations in those dated reports become implementation scope here; historic results remain historic.
+
+## Constraints and decisions
+
+- Preserve the original dirty checkout; use the existing codex/benchmark-goals-2026-09-29 worktree.
+- Native goals remain optional, capability negotiated, and never required for other providers. No global CLI configuration changes.
+- Bind each goal to explicitly selected criterion IDs and a stable objective/contract digest. Old unbound goals require explicit binding before accepting completion; provide CLI migration command.
+- Preserve --minutes as cumulative agent-time budget; add explicit cumulative wall-time budget. Report token overshoot and unknown consumption, never silently reset them.
+- Disable unmanaged native multi-agent delegation for managed provider calls; reserve one pool unit per actual call, not an outer unit plus nested units.
+- Keep protected acceptance, scope controls, commits and safe-boundary exploration semantics. No weaker test gates or fabricated CPU/USD savings.
+- Prepare the release locally; tagging, npm publication and GitHub release are not performed by a preparation request.
+
+## Review focus
+
+Goal contract unrelated to new objective; stale/edited contracts; abort while admission is queued; planner/worker token accounting; dashboard resuming a stale goal instead of active explore run; expired exploration deadline; unavailable native protocol versus genuine authentication errors; native complete while Yoke check fails; retained worktree ownership; Windows full generated path length.
+
+## Task 1 — Parallel integration and recoverable candidates
+
+Files: src/loop/dispatcher.ts, parallel-command.ts, parallel-adapters.ts, merge-queue.ts; tests/loop parallel/dispatcher suites; reporter integration centrally.
+
+- [x] Add failing story-environment regression using independent scopes and an environment-dependent verifier.
+- [x] Preserve verification environment across worker and integration phases and restore previous environment on errors.
+- [x] Persist concrete rejection reasons and recoverable candidate ownership; retain implemented work safely and enable existing recovery paths.
+- [x] Shorten generated worktree names without weakening ownership validation; test Windows path failure handling.
+- [x] Run covering tests and deterministic control probe.
+
+## Task 2 — Durable run identity and resume
+
+Files: src/loop/run-state.ts, run-command.ts, src/dashboard/server.ts, run-state/dashboard tests.
+
+- [x] Add failing mode/provider/selection/deadline and unrelated-goal resume tests.
+- [x] Persist validated safe run options under owned project lock; restore the interrupted run's mode.
+- [x] Preserve absolute exploration deadline and user pauses; explicitly fresh CLI run gets a new deadline.
+- [x] Verify expired deadline starts no provider and unsafe permissions do not silently carry over.
+
+## Task 3 — Objective acceptance, policy and budgets
+
+Files: src/goals/command.ts, contracts.ts/admission.ts as needed, src/check/command.ts async counterpart, src/cli.ts, src/retrofit/config.ts, goals/check tests.
+
+- [x] Add failing unrelated-green-contract test, explicit binding/digest mutation tests, saturated pool and configured-selection tests.
+- [x] Bind goal objective to selected criteria and contract revision; add goal bind CLI and documented legacy migration.
+- [x] Resolve explicit provider/model/effort/bare overrides then project runner configuration; centrally disable unmanaged delegation.
+- [x] Admit actual implementation and planner calls through the pool and release in finally.
+- [x] Add abortable checks with shared local check admission; preserve fingerprints and protected contract evidence.
+- [x] Add cumulative wall-time option and post-attempt overshoot/unknown-usage accounting, streamed cancellation where supported; preserve safe pause and interrupted work.
+
+## Task 4 — Optional native Codex adapter
+
+Files: src/goals/codex-native.ts, tests/goals/codex-native.test.ts; central goal integration/config.
+
+- [x] Test initialized RPC transport, unsupported capability, malformed replies, thread start/resume, abort and bounded cleanup.
+- [x] Persist objective-bound thread identity; execute bounded turns with native goals paused between turns so independent checks arbitrate continuation.
+- [x] Synchronize completion/pause/budget/blocker states after Yoke checks; unavailable method can fall back, real execution/auth errors cannot silently downgrade.
+- [x] Test provider switches and existing-thread/model mismatch; prevent competing auto-continuation.
+
+## Task 5 — Review, measurements and release preparation
+
+- [x] Review merged components, fix covering regressions and rerun deterministic audit probes with updated expected outcomes.
+- [x] Run authenticated corrected parallel benchmark and report accepted quality/time/tokens with original sample limits.
+- [x] Run TypeScript/build, full tests, metadata checks and package dry run in isolated state.
+- [x] Add dated 1.20.0 CHANGELOG entry with implemented behavior, binding migration, default/native limits and actual validation limits.
+- [x] Synchronize package/lock/provider manifest/README versions; link compact guides for goals/resources/recovery.
+- [x] Read-only provenance audit for changed reports; prepare matching release notes and build archive.
+
+## Progress ledger
+
+- 2026-09-30: Plan created; three independent implementers assigned parallel correctness, durable resume, native adapter. Controller owns goal policy, check execution, integration, release preparation. Historic benchmark failures remain in reports.
+- 2026-09-30: Implementation and review complete. Final prepublish pipeline passed (1,418 tests, 2 skipped, 155 files), lint/build/Canon/metadata/package checks and zero-vulnerability audit passed. Authenticated parallel and native accounting fixtures succeeded with their stated limits. Local 1.20.0 archive and changelog-derived notes prepared; publication remains out of scope.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Cross-agent coding harness for eight supported CLIs: curated skill canon, mechanical safety gates, autonomous loop with proof artifacts. CLI: npm i -g @hecer/yoke",
   "contextFileName": "GEMINI-EXTENSION.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "One harness, eight agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi and Hermes: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {
@@ -23,6 +23,10 @@
     "bench/run-matrix.mjs",
     "bench/run-parallel-matrix.mjs",
     "bench/analyze-routing-study.mjs",
+    "bench/compare-codex.mjs",
+    "bench/analyze-codex-comparison.mjs",
+    "bench/probe-goal-integration.mjs",
+    "bench/probe-parallel-gate-context.mjs",
     "bench/fixtures",
     "bench/results",
     "docs",