@hecer/yoke 1.9.0 → 1.11.0

package/docs/VERIFIED-PROJECTS.md

@@ -1,167 +1,167 @@
-# Verified projects, goals and measured execution
-
-Available in Yoke 1.7.0. These additions do not require a cloud account or replace your provider CLI. Model availability, reasoning controls, structured output and telemetry depend on the selected provider; unknown usage is never a measured zero. Live authenticated provider comparison and calibrated time/cost benchmarks remain separate validation work.
-
-## Check an existing project
-
-```sh
-yoke check .
-yoke check . --json
-yoke check . --requirement="Guest checkout completes"
-```
-
-Checks run without retrofit. Exit codes: `0` passed, `1` failed, `2` unverified or unavailable. A free-text requirement stays unverified until you map its behavior to an executable acceptance contract. Passing a project suite does not establish arbitrary product correctness.
-
-Create `.yoke/acceptance.yaml` with tests that inspect application behavior:
-
-```yaml
-version: 1
-protected:
-  - tests/acceptance/checkout.test.mjs
-  - tests/acceptance/helpers.mjs
-criteria:
-  - id: guest-checkout
-    text: A guest can complete checkout and receives one order confirmation.
-    commands:
-      - node --test tests/acceptance/checkout.test.mjs
-```
-
-List every local test helper, fixture and configuration file whose modification could weaken this contract. Paths must resolve inside the project. `yoke check . --protect` pins the manifest, listed files and existing package manifests/lockfiles outside the worker checkout. Autonomous goals require explicit protected test infrastructure and establish this pin automatically. Protection is change detection within the local execution model, not an OS security boundary against a hostile process using your account. Review the contract before running a goal.
-
-After intentionally editing protected tests, use `yoke check . --protect --refresh` to approve the new baseline. Ordinary checks and retries never refresh it. Source, acceptance and configuration identity are checked before and after verification; changed inputs invalidate evidence. Gitlinks/submodule directories currently fail closed because recursive identity is not implemented. Evidence is stored in `.yoke/checks/<id>.json`; it describes that checked snapshot and is not a permanent success certificate.
-
-## Durable goals across providers
-
-```sh
-yoke goal set . --objective="Finish 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>
-yoke goal status .
-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.
-
-`--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.
-
-Explicitly extend total budgets without deleting history:
-
-```sh
-yoke goal budget . --attempts=5 --minutes=60
-yoke goal budget . --tokens=200000
-# Only if you deliberately want to remove the checkpoint token limit:
-yoke goal budget . --clear-token-budget
-```
-
-Unknown historical token usage cannot be made known by increasing its limit. Inspect interrupted work and keep that limitation visible.
-
-## Recover an isolated story
-
-Failed or paused isolated story worktrees are retained. Resume the same story with:
-
-```sh
-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.
-
-## Spend fewer model calls
-
-Add explicit project rules to `.yoke/config.yaml`:
-
-```yaml
-routing:
-  enabled: true
-  strategy: cost
-  maxCandidates: 2
-  workers:
-    - id: fast
-      agent: claude
-      model: <your-fast-model-id>
-      costTier: low
-      capabilities: [docs, tests]
-    - id: strong
-      agent: codex
-      model: <your-strong-model-id>
-      costTier: high
-      capabilities: [implementation]
-  rules:
-    - area: docs
-      worker: fast
-      escalateTo: strong
-```
-
-The first matching rule bypasses the routing controller. Its optional area and story ID selectors both have to match when supplied. Independent gate failure escalates the next attempt, including after loop restart; an unavailable or unknown worker falls back to the parent. Without an explicit escalation target the parent handles the failed rule. Other stories retain adaptive routing. Gate-driven routing observations are local and bounded when read. These are measured outcomes, not guarantees that a named inexpensive model can handle every task.
-
-For deterministic operations, configure exact executable arguments:
-
-```yaml
-actions:
-  - storyId: regenerate-types
-    file: node
-    args: [scripts/generate-types.mjs]
-    timeoutMs: 60000
-```
-
-Actions use no model, run without a shell, have bounded output/time and still pass the ordinary story gates before commit. They currently require serial execution with one candidate. On Windows use an executable such as `node` and its script path; shell-only `.cmd` wrappers are not automatically enabled. Commands are project-authored configuration, never free-form model-generated commands. Projects consisting entirely of configured actions do not need a model CLI unless they enable a model-based review or planning workflow.
-
-Implementation/review prompts now select task-relevant project context deterministically within a 6,000-character budget. A stable project/glossary prefix precedes ranked historical references with source paths and content hashes. Excerpts point back to complete files. This does not claim a fixed token count or guaranteed provider cache hit. Mandatory verification always reruns; no broad result cache or selective-test bypass was introduced.
-
-## Parallelism and time estimates
-
-Stories can declare relative file/directory scopes:
-
-```yaml
-- id: api-types
-  title: Update API types
-  priority: 1
-  area: api
-  writes: [src/api, tests/api]
-  needs: []
-  acceptance: ["Replace with executable structured criteria in strict projects"]
-  passes: false
-```
-
-Overlapping declared scopes cannot run simultaneously, including while integration is pending. Dependencies, areas, explicit priorities and concurrency limits also apply. Equal-priority work that unlocks a longer dependency chain is scheduled first. Declarations are advisory scheduling input, not filesystem write enforcement; absent declarations preserve previous behavior. Final integrated gates remain mandatory.
-
-Versioned local events record status, phase duration, attempts and available usage. Retention is bounded to 1,000 events. Estimates combine historical and current durations, preserve failed-attempt cost and expose sample counts and empirical ranges. Schedule estimates simulate dependency, scope and concurrency constraints. Predictions and later errors are attached to completed attempt events so accuracy can be evaluated. Ranges describe observed data; they are not calibrated probabilities or exact deadlines. No history means no justified time estimate.
-
-## Local project dashboard
-
-### Execution defaults in 1.8.0
-
-New setups enable routing, `loop.parallel: auto` and `loop.isolate: true`. Existing explicit settings remain authoritative. At execution time, automatic routing uses configured profiles; without profiles it keeps the selected parent. Explicit `--routing` without profiles still reports a configuration error. Routing rules bypass the controller and can escalate following failed independent gates, including across worktrees and restarts. Routing now also runs asynchronously inside parallel workers. An explicit task provider affinity takes precedence over routing.
-
-Automatic parallelism allows at most three Yoke workers when every pending task declares nonempty write scopes. Dependencies and overlapping scopes still constrain dispatch. Unknown scopes, configured tool actions and worktree recovery select serial execution. Use `--parallel=N`, `--parallel=auto`, `--no-routing` or `--no-isolate` to override defaults. Serial worktrees retain failed work and require deliberate recovery; the default does not discard an existing recovery tree. Quality repair budgets and opt-in competing candidates retain their existing policies.
-
-Integration retains an execution slot until its candidate lands. Yoke loop runners disable native delegation so it cannot multiply the default worker budget: Codex disables multi_agent; Claude disallows Agent, Task, TeamCreate and SendMessage; Gemini uses a separate temporary system-settings copy that disables experimental agents and its always-on investigator/help overrides. Existing Gemini system policy and system-default paths are preserved; unreadable or malformed policy blocks launch. Original settings are never overwritten. The temporary copy is removed on normal exit; forced process termination may leave a private temporary directory. Explicit competing candidate counts remain a separate opt-in workload.
-
-### Dashboard views
-
-- **Now:** reported task and worker activity, requested provider/model, elapsed worker time, phase, integration, blockers, status age, backlog and empirical remaining-time ranges. The view refreshes every five seconds while visible and not being operated with keyboard focus. A stale status is marked rather than asserted to be live.
-- **Usage & time:** last 24 hours, 7/30/90/365 days or custom dates, grouped by UTC day, Monday-based week or month. Displays reported input/output and cache categories, cost coverage, consumption charts, per-model time buckets, per-task usage and summed phase/call durations. The overview also compares projects for the same period.
-- **Results:** recorded acceptances, ended attempts, explicitly successful outcomes, repair phases, rule-driven escalations and recorded tokens/time per acceptance. Saved acceptance evidence and goal attempts remain available; their timestamps may fall outside the statistics period.
-
-The short activity list still retains at most 1,000 events. Compact measurements now also persist under `.yoke/history/YYYY-MM-DD/` independently of that retention and across runs. They contain identifiers, model/provider evidence and measurements, not prompts or full status snapshots. Runtime history is excluded from Yoke commits and added to new project ignore rules. Available reviewer, quality critic and repair usage is recorded separately; absent usage is counted as unknown. Recent and archived records are deduplicated by event ID.
-
-Dates and buckets use UTC. The custom end date is inclusive; the API uses an exclusive upper timestamp. Usage belongs to the time the provider reports it, and durations to their end time. Tokens per elapsed minute divide recorded input/output by the full selected interval. Tokens per call minute use summed reported call duration, which can overlap across workers. Neither is measured generation speed. Cache categories are shown separately without adding them to input again.
-
-Historical activity that was never recorded or already expired cannot be reconstructed. Queue/human waiting time that lacks measurements remains unknown; phase and attempt durations are summed worker time, not automatically elapsed project time. Queries allow at most 366 days and bounded reads (8 MiB per shard, 32 MiB overall, 50,000 records); skipped, malformed or oversized history is reported as incomplete. History currently requires local disk retention rather than automatic monthly compaction. Unknown model identity is never replaced by a requested model, and missing charges are not estimated from token counts.
-
-```sh
-yoke projects add /path/to/project
-yoke projects list
-yoke dashboard .
-yoke dashboard --no-register --port=4100
-yoke projects remove <opaque-project-id>
-```
-
-Open the printed loopback URL. The dashboard displays project goals, backlog, worker/status data, evidence, blockers, events, usage availability and schedule ranges. It can request a goal pause through the same service as the CLI. Start, resume and budget changes remain explicit CLI operations. Removing registration only removes the registry reference.
-
-The HTTP service binds to `127.0.0.1`, validates Host/Origin, requires a per-session token for pause, sends a restrictive CSP and renders project strings as text. It does not serve arbitrary local files or allow remote registration. Missing/corrupt/oversized project data is shown as unavailable. Shared project registration and protected acceptance live under `YOKE_STATE_DIR` or `~/.yoke/state`; existing routing history retains its `YOKE_REGISTRY_DIR` location. The dashboard is local, not a hosted multi-user service.
-
-## Remaining validation and product work
-
-Live Codex/Claude/Gemini comparisons, measured competitive development-time/cost studies and estimate calibration require representative real projects and authenticated runs. Equal adapter contracts do not imply equal model capability. Cloud/team access, automatic selective test reuse, web-based start/resume controls and commercial rollout are not included in this local foundation. The complete saved direction is in [PRODUCT-DIRECTION-2026-09-05.md](PRODUCT-DIRECTION-2026-09-05.md).
+# Verified projects, goals and measured execution
+
+Available in Yoke 1.7.0. These additions do not require a cloud account or replace your provider CLI. Model availability, reasoning controls, structured output and telemetry depend on the selected provider; unknown usage is never a measured zero. Live authenticated provider comparison and calibrated time/cost benchmarks remain separate validation work.
+
+## Check an existing project
+
+```sh
+yoke check .
+yoke check . --json
+yoke check . --requirement="Guest checkout completes"
+```
+
+Checks run without retrofit. Exit codes: `0` passed, `1` failed, `2` unverified or unavailable. A free-text requirement stays unverified until you map its behavior to an executable acceptance contract. Passing a project suite does not establish arbitrary product correctness.
+
+Create `.yoke/acceptance.yaml` with tests that inspect application behavior:
+
+```yaml
+version: 1
+protected:
+  - tests/acceptance/checkout.test.mjs
+  - tests/acceptance/helpers.mjs
+criteria:
+  - id: guest-checkout
+    text: A guest can complete checkout and receives one order confirmation.
+    commands:
+      - node --test tests/acceptance/checkout.test.mjs
+```
+
+List every local test helper, fixture and configuration file whose modification could weaken this contract. Paths must resolve inside the project. `yoke check . --protect` pins the manifest, listed files and existing package manifests/lockfiles outside the worker checkout. Autonomous goals require explicit protected test infrastructure and establish this pin automatically. Protection is change detection within the local execution model, not an OS security boundary against a hostile process using your account. Review the contract before running a goal.
+
+After intentionally editing protected tests, use `yoke check . --protect --refresh` to approve the new baseline. Ordinary checks and retries never refresh it. Source, acceptance and configuration identity are checked before and after verification; changed inputs invalidate evidence. Gitlinks/submodule directories currently fail closed because recursive identity is not implemented. Evidence is stored in `.yoke/checks/<id>.json`; it describes that checked snapshot and is not a permanent success certificate.
+
+## Durable goals across providers
+
+```sh
+yoke goal set . --objective="Finish 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>
+yoke goal status .
+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.
+
+`--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.
+
+Explicitly extend total budgets without deleting history:
+
+```sh
+yoke goal budget . --attempts=5 --minutes=60
+yoke goal budget . --tokens=200000
+# Only if you deliberately want to remove the checkpoint token limit:
+yoke goal budget . --clear-token-budget
+```
+
+Unknown historical token usage cannot be made known by increasing its limit. Inspect interrupted work and keep that limitation visible.
+
+## Recover an isolated story
+
+Failed or paused isolated story worktrees are retained. Resume the same story with:
+
+```sh
+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.
+
+## Spend fewer model calls
+
+Add explicit project rules to `.yoke/config.yaml`:
+
+```yaml
+routing:
+  enabled: true
+  strategy: cost
+  maxCandidates: 2
+  workers:
+    - id: fast
+      agent: claude
+      model: <your-fast-model-id>
+      costTier: low
+      capabilities: [docs, tests]
+    - id: strong
+      agent: codex
+      model: <your-strong-model-id>
+      costTier: high
+      capabilities: [implementation]
+  rules:
+    - area: docs
+      worker: fast
+      escalateTo: strong
+```
+
+The first matching rule bypasses the routing controller. Its optional area and story ID selectors both have to match when supplied. Independent gate failure escalates the next attempt, including after loop restart; an unavailable or unknown worker falls back to the parent. Without an explicit escalation target the parent handles the failed rule. Other stories retain adaptive routing. Gate-driven routing observations are local and bounded when read. These are measured outcomes, not guarantees that a named inexpensive model can handle every task.
+
+For deterministic operations, configure exact executable arguments:
+
+```yaml
+actions:
+  - storyId: regenerate-types
+    file: node
+    args: [scripts/generate-types.mjs]
+    timeoutMs: 60000
+```
+
+Actions use no model, run without a shell, have bounded output/time and still pass the ordinary story gates before commit. They currently require serial execution with one candidate. On Windows use an executable such as `node` and its script path; shell-only `.cmd` wrappers are not automatically enabled. Commands are project-authored configuration, never free-form model-generated commands. Projects consisting entirely of configured actions do not need a model CLI unless they enable a model-based review or planning workflow.
+
+Implementation/review prompts now select task-relevant project context deterministically within a 6,000-character budget. A stable project/glossary prefix precedes ranked historical references with source paths and content hashes. Excerpts point back to complete files. This does not claim a fixed token count or guaranteed provider cache hit. Mandatory verification always reruns; no broad result cache or selective-test bypass was introduced.
+
+## Parallelism and time estimates
+
+Stories can declare relative file/directory scopes:
+
+```yaml
+- id: api-types
+  title: Update API types
+  priority: 1
+  area: api
+  writes: [src/api, tests/api]
+  needs: []
+  acceptance: ["Replace with executable structured criteria in strict projects"]
+  passes: false
+```
+
+Overlapping declared scopes cannot run simultaneously, including while integration is pending. Dependencies, areas, explicit priorities and concurrency limits also apply. Equal-priority work that unlocks a longer dependency chain is scheduled first. Declarations are advisory scheduling input, not filesystem write enforcement; absent declarations preserve previous behavior. Final integrated gates remain mandatory.
+
+Versioned local events record status, phase duration, attempts and available usage. Retention is bounded to 1,000 events. Estimates combine historical and current durations, preserve failed-attempt cost and expose sample counts and empirical ranges. Schedule estimates simulate dependency, scope and concurrency constraints. Predictions and later errors are attached to completed attempt events so accuracy can be evaluated. Ranges describe observed data; they are not calibrated probabilities or exact deadlines. No history means no justified time estimate.
+
+## Local project dashboard
+
+### Execution defaults in 1.8.0
+
+New setups enable routing, `loop.parallel: auto` and `loop.isolate: true`. Existing explicit settings remain authoritative. At execution time, automatic routing uses configured profiles; without profiles it keeps the selected parent. Explicit `--routing` without profiles still reports a configuration error. Routing rules bypass the controller and can escalate following failed independent gates, including across worktrees and restarts. Routing now also runs asynchronously inside parallel workers. An explicit task provider affinity takes precedence over routing.
+
+Automatic parallelism allows at most three Yoke workers when every pending task declares nonempty write scopes. Dependencies and overlapping scopes still constrain dispatch. Unknown scopes, configured tool actions and worktree recovery select serial execution. Use `--parallel=N`, `--parallel=auto`, `--no-routing` or `--no-isolate` to override defaults. Serial worktrees retain failed work and require deliberate recovery; the default does not discard an existing recovery tree. Quality repair budgets and opt-in competing candidates retain their existing policies.
+
+Integration retains an execution slot until its candidate lands. Yoke loop runners disable native delegation so it cannot multiply the default worker budget: Codex disables multi_agent; Claude disallows Agent, Task, TeamCreate and SendMessage; Gemini uses a separate temporary system-settings copy that disables experimental agents and its always-on investigator/help overrides. Existing Gemini system policy and system-default paths are preserved; unreadable or malformed policy blocks launch. Original settings are never overwritten. The temporary copy is removed on normal exit; forced process termination may leave a private temporary directory. Explicit competing candidate counts remain a separate opt-in workload.
+
+### Dashboard views
+
+- **Now:** reported task and worker activity, requested provider/model, elapsed worker time, phase, integration, blockers, status age, backlog and empirical remaining-time ranges. The view refreshes every five seconds while visible and not being operated with keyboard focus. A stale status is marked rather than asserted to be live.
+- **Usage & time:** last 24 hours, 7/30/90/365 days or custom dates, grouped by UTC day, Monday-based week or month. Displays reported input/output and cache categories, cost coverage, consumption charts, per-model time buckets, per-task usage and summed phase/call durations. The overview also compares projects for the same period.
+- **Results:** recorded acceptances, ended attempts, explicitly successful outcomes, repair phases, rule-driven escalations and recorded tokens/time per acceptance. Saved acceptance evidence and goal attempts remain available; their timestamps may fall outside the statistics period.
+
+The short activity list still retains at most 1,000 events. Compact measurements now also persist under `.yoke/history/YYYY-MM-DD/` independently of that retention and across runs. They contain identifiers, model/provider evidence and measurements, not prompts or full status snapshots. Runtime history is excluded from Yoke commits and added to new project ignore rules. Available reviewer, quality critic and repair usage is recorded separately; absent usage is counted as unknown. Recent and archived records are deduplicated by event ID.
+
+Dates and buckets use UTC. The custom end date is inclusive; the API uses an exclusive upper timestamp. Usage belongs to the time the provider reports it, and durations to their end time. Tokens per elapsed minute divide recorded input/output by the full selected interval. Tokens per call minute use summed reported call duration, which can overlap across workers. Neither is measured generation speed. Cache categories are shown separately without adding them to input again.
+
+Historical activity that was never recorded or already expired cannot be reconstructed. Queue/human waiting time that lacks measurements remains unknown; phase and attempt durations are summed worker time, not automatically elapsed project time. Queries allow at most 366 days and bounded reads (8 MiB per shard, 32 MiB overall, 50,000 records); skipped, malformed or oversized history is reported as incomplete. History currently requires local disk retention rather than automatic monthly compaction. Unknown model identity is never replaced by a requested model, and missing charges are not estimated from token counts.
+
+```sh
+yoke projects add /path/to/project
+yoke projects list
+yoke dashboard .
+yoke dashboard --no-register --port=4100
+yoke projects remove <opaque-project-id>
+```
+
+Open the printed loopback URL. The dashboard displays project goals, backlog, worker/status data, evidence, blockers, events, usage availability and schedule ranges. It can request a goal pause through the same service as the CLI. Start, resume and budget changes remain explicit CLI operations. Removing registration only removes the registry reference.
+
+The HTTP service binds to `127.0.0.1`, validates Host/Origin, requires a per-session token for pause, sends a restrictive CSP and renders project strings as text. It does not serve arbitrary local files or allow remote registration. Missing/corrupt/oversized project data is shown as unavailable. Shared project registration and protected acceptance live under `YOKE_STATE_DIR` or `~/.yoke/state`; existing routing history retains its `YOKE_REGISTRY_DIR` location. The dashboard is local, not a hosted multi-user service.
+
+## Remaining validation and product work
+
+Live Codex/Claude/Gemini comparisons, measured competitive development-time/cost studies and estimate calibration require representative real projects and authenticated runs. Equal adapter contracts do not imply equal model capability. Cloud/team access, automatic selective test reuse, web-based start/resume controls and commercial rollout are not included in this local foundation. The complete saved direction is in [PRODUCT-DIRECTION-2026-09-05.md](PRODUCT-DIRECTION-2026-09-05.md).

package/docs/WINDOWS-RUNNER-VALIDATION.md

@@ -0,0 +1,104 @@
+# Windows runner correction — 2026-09-06
+
+AI-assisted implementation and validation record for issue #5. These changes are
+included in 1.10.0; installed 1.9.0 packages and existing processes must be updated/restarted to use them.
+
+## Reproduction and correction
+
+On this machine, Codex 0.153.4 running the Microsoft Store PowerShell executable
+under `codex sandbox -P :workspace` reproduced `CreateProcessAsUserW failed:
+-1073283067`. The System32 Windows PowerShell executable succeeded under the
+same sandbox profile. A first end-to-end probe exposed a second entry point:
+the WindowsApps `pwsh.exe` app-execution alias failed with access denied.
+
+Yoke now filters Store PowerShell directories and their aliases from the provider's
+own PATH, prefers an available native PowerShell executable and tests it in the
+actual isolated working directory before starting the model. The same PATH is
+passed to Codex and its shell environment. This changes neither machine/user PATH
+nor sandbox privileges. Native PowerShell 7 is preferred; Windows PowerShell is
+the fallback when no native `pwsh.exe` is available. Projects requiring PowerShell
+7 should install a native distribution and make it available on PATH.
+
+The preflight uses the installed CLI's built-in `:workspace` or `:read-only`
+permission profile. An unsupported CLI/profile or failing shell blocks execution
+with an actionable message. No permission escalation or unsandboxed retry occurs.
+The preflight itself has a 30-second execution deadline, followed by bounded
+process-tree cleanup; an outer 90-second guard bounds an unresponsive supervisor.
+Environment values, prompts and raw authentication diagnostics are not stored in
+the supervision record.
+
+Windows npm launchers are resolved to their JavaScript entry point and invoked
+with a native Node argv array; executable providers are launched directly. Unknown
+batch launcher formats are rejected. This removes the provider/watchdog use of
+`shell: true` and preserves spaces, quotes, percent signs and shell metacharacters
+as literal arguments.
+
+## Supervision and failure behavior
+
+Both serial and parallel implementation providers have independent output,
+successful-tool/edit progress and overall timers. Defaults:
+
+```yaml
+loop:
+  timeoutMinutes: 20          # output inactivity; existing setting
+  progressTimeoutMinutes: 20 # no observed successful tool result or edit
+  maxCallMinutes: 30         # overall provider call
+```
+
+The two new settings accept positive values up to 1,440 minutes. Disabling the
+old output timeout does not disable the other bounds. Successful tool/edit events
+are evidence of activity, not proof that the product requirement has been met.
+
+Codex structured failed-tool events and its actual `exec_command failed:
+CreateProcess` stderr diagnostic stop the worker immediately. Terminal provider
+authentication errors are separate from optional MCP startup warnings; the latter
+alone do not fail the task. Failed infrastructure cannot produce a candidate or
+story success merely because existing tests happen to pass, and does not train
+capability escalation. Explicit `bare` startup settings now survive capability
+profile selection.
+
+Process records under `.yoke/supervision/` expose PID, process identity, supervisor
+heartbeat, current attempt, last output, last successful tool/edit and terminal reason. Status CLI
+and dashboard show these separately. Backlog ratios are labeled as backlog, not
+overall product completion. Live identity checks distinguish an existing PID from
+the recorded process. Tree termination checks that identity before reaping;
+unconfirmed termination retains ownership/evidence and blocks a subsequent worker.
+No retry/restart is triggered merely by an observer timing out. Failed worktrees
+remain available for inspection.
+
+## Validation
+
+- Model-free reproduction: Store executable failed with the reported code;
+  native System32 PowerShell passed in the same permission profile.
+- Both safe and read-only preflights passed with a 30,707 UTF-16-character inherited
+  environment in a path containing spaces. This simulates a large environment;
+  it does not reconstruct every variable in the original Visual Studio session.
+- Actual Yoke isolated safe-mode run: `codex-light`, requested `gpt-5.6-luna` at low
+  effort; task started 18:49:44 UTC and completed 18:52:52 UTC. Real shell commands,
+  file creation, two independent acceptance commands, verification and commit
+  integration succeeded. One model call, no assessment call. Recorded input
+  345,821 tokens (321,024 cached subset), output 2,353; monetary cost and actual
+  reported model identity remain unknown.
+- Regression tests cover literal argv, packaged aliases, streaming failure,
+  optional MCP diagnostics, total timeout despite heartbeat output, retained
+  redacted proof, no new worker after unconfirmed termination, and an actual
+  child failure propagated through capability routing and the worker gate.
+- Full suite: 1,170 passed, two skipped across 128 files at the recorded full-run
+  checkpoint. Final focused validation: 119 passed across five files, plus a
+  successful build and documentation consistency check.
+
+The original DeviceLane process was observed alive. It was not restarted or
+terminated, its retained worktree was not modified, and its application task was
+not claimed complete. Issue #5 was not closed or externally commented on. The fix
+must be installed before it can supervise a newly started DeviceLane run; it cannot
+retrofit supervision into an already running old process.
+
+Primary implementation reference consulted:
+[OpenAI shell detection](https://github.com/openai/codex/blob/main/codex-rs/shell-command/src/shell_detect.rs).
+The local executable probes above, rather than assumptions about upstream release
+contents, establish the behavior observed here.
+
+Read-only provenance audit: supported scan complete, no C2PA located; verification,
+signer trust and Markdown metadata privacy unknown. The audit states: "No conforming
+verifier was supplied." and "Keyed model-level watermarks cannot be checked without
+the provider's key." No authorship inference or watermark removal was performed.

package/docs/community-outreach-2026-08-20.md

@@ -0,0 +1,85 @@
+# Yoke community outreach — 2026-08-20
+
+These posts are intentionally feedback-first. They disclose the creator relationship, avoid vote requests, and link directly to the free MIT-licensed project.
+
+## Hacker News — Show HN
+
+**Title**
+
+Show HN: Yoke – safety-gated autonomous coding loops for Claude, Codex, and Gemini
+
+**URL**
+
+https://github.com/HECer/yoke
+
+**First comment**
+
+Hi HN — I built Yoke after repeatedly seeing the same failure mode in long-running coding-agent loops: the agent says a task is done, but the tests were not actually run, the working tree is inconsistent, or a later iteration breaks earlier work.
+
+Yoke is an MIT-licensed TypeScript CLI that puts mechanical gates around those loops. A story only passes after the configured verification command succeeds, review approves it, and the commit lands. Stories run in isolated worktrees, and optional Playwright evidence can attach screenshots to acceptance criteria. It generates native project instructions for Claude Code, Codex CLI, and Gemini CLI from one canon rather than asking all three tools to interpret the same generic prompt.
+
+You can try it without signing up:
+
+    npm i -g @hecer/yoke
+    yoke new my-app
+
+I would especially value feedback from people who already run Ralph-style or overnight agent loops: which gate feels essential, which feels like ceremony, and what would stop you from trying this on a real repository?
+
+I am the creator and will be around to answer technical questions.
+
+## Reddit — r/ClaudeCodeTLDR weekly showcase (English)
+
+I built **Yoke**, a free MIT-licensed harness for running Claude Code, Codex CLI, or Gemini CLI in autonomous coding loops with mechanical safety gates.
+
+The problem I wanted to solve was the gap between an agent saying “done” and the repository actually being in a verified state. Yoke uses isolated worktrees and only marks a story complete after the configured tests pass, review approves it, and the commit lands. It can also require Playwright screenshot evidence for visual acceptance criteria.
+
+Claude Code was both a target runtime and part of the development/review workflow; the project also generates native instructions for Codex and Gemini from the same canon.
+
+It is free to use, requires no account, and the quickstart is:
+
+    npm i -g @hecer/yoke
+    yoke new my-app
+
+Repo: https://github.com/HECer/yoke
+
+I’m the creator. I’d love blunt feedback from people who already use long-running Claude Code loops: would these gates make you trust an overnight run more, or does the workflow look too heavy? If you try it, which part is confusing first?
+
+## Reddit — r/ChatGPTCoding self-promotion thread (English)
+
+I built **Yoke**, an MIT-licensed CLI for people using Claude Code, Codex CLI, or Gemini CLI for longer autonomous coding runs.
+
+Instead of trusting the agent’s “done” message, Yoke gates each story on a real verification command, review approval, and an atomic commit. It also isolates stories in worktrees and can collect Playwright screenshots as acceptance evidence.
+
+Install and try it without an account:
+
+    npm i -g @hecer/yoke
+    yoke new my-app
+
+https://github.com/HECer/yoke
+
+I’m the creator. I’m mainly looking for honest feedback: if you already run coding agents for more than one task at a time, what would make you try this, and what looks like unnecessary process?
+
+## German-language developer communities (draft for communities that explicitly permit project showcases)
+
+**Titel**
+
+Feedback gesucht: Yoke – abgesicherte autonome Coding-Loops für Claude, Codex und Gemini
+
+**Text**
+
+Ich habe **Yoke** gebaut, ein kostenloses, MIT-lizenziertes CLI für längere autonome Coding-Läufe mit Claude Code, Codex CLI oder Gemini CLI.
+
+Der Auslöser war die Lücke zwischen „der Agent sagt, er sei fertig“ und einem tatsächlich verifizierten Repository. Yoke markiert eine Story erst dann als erledigt, wenn der konfigurierte Test-/Verify-Befehl erfolgreich war, ein Review zugestimmt hat und der Commit sauber gelandet ist. Einzelne Stories laufen isoliert in Worktrees; für visuelle Akzeptanzkriterien können Playwright-Screenshots als Nachweis verlangt werden.
+
+Ausprobieren ohne Account:
+
+    npm i -g @hecer/yoke
+    yoke new meine-app
+
+Repo: https://github.com/HECer/yoke
+
+Ich bin der Entwickler des Projekts. Mich interessiert vor allem ehrliches Feedback von Leuten, die Coding-Agents länger oder autonom laufen lassen: Würden solche Gates euer Vertrauen erhöhen, oder wirkt der Ablauf zu schwergewichtig? Was wäre beim ersten Ausprobieren vermutlich die größte Hürde?
+
+## Disclosure note
+
+The outreach copy in this file was drafted with AI assistance on the creator's instructions. Add a human-readable AI-assistance disclosure wherever a community's rules require it; do not infer human authorship from the absence of machine-readable provenance.