cyc-stack 0.7.0 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/runtime.md CHANGED
@@ -1,205 +1,101 @@
1
1
  # CYC execution controller
2
2
 
3
- The updated workflow selects `evidenceVersion: 1` in structured start input, retaining original `requirements`, criteria and optional clauses. `reviewPolicy` selects `self-allowed` or `fresh-required`. Review capture/record commands bind an agent-reported review to the actual candidate before dispatch; versioned Verify retains scenario-to-command references and a reason review for decisive red-proof failures. See [versioned evidence examples](work-assessments.md#versioned-evidence-records) for the complete input shapes, conservative whole-source freshness and legacy limits. Unversioned callers remain compatible; a historical fresh-context string is labeled unlinked, never upgraded into a source-linked receipt.
3
+ The controller validates skill handoffs and configured checks; the host performs the methods. It neither launches model fleets nor authorizes publication. Build routes require Scout context/approach/alignment/consumers, Verify semantic review/consumer checks and Deliver retained learning/error history in existing handoffs.
4
4
 
5
- The controller tracks a task through the catalog's skill stages, validates recorded handoffs, runs configured project checks, and refuses unsupported completion. The existing AI host reads and performs the skills. CYC does not launch model calls, create paid agent fleets, or infer authorization to publish work.
6
-
7
- New implementation runs (routes containing Build) record work assessment contract v1. Scout must account for context freshness, existing functionality, alignment, and affected consumers. Verify must record semantic review and consumer checks. Deliver must account for retained learning and the selected error ledger. These are fields in existing handoffs, not new stages. See [assessment examples and the knowledge lifecycle](work-assessments.md). Advisory routes and legacy runs retain their prior handoffs and are explicitly labeled.
5
+ Select `evidenceVersion:1` to retain original requirements, criteria/clauses, named scenarios, source-bound review and case-specific proof judgments. `reviewPolicy` is `self-allowed` or `fresh-required`. [Assessment examples](work-assessments.md#versioned-evidence-records) define these fields. Legacy/advisory callers remain supported and labeled; historical reviewer prose is never upgraded into linked provenance.
8
6
 
9
7
  ## Start with a project and criteria
10
8
 
11
- From an installed project use `node .cyc/engine/bin/cyc.mjs`; inside the CYC source checkout use `node bin/cyc.mjs`. Add `--project PATH` when working from elsewhere. Without that option the CLI looks for `.cyc/config.json` in the current directory and its parents.
12
-
13
- Create explicit acceptance criteria before starting a substantial run:
9
+ Installed CLI: node .cyc/engine/bin/cyc.mjs; source checkout: node bin/cyc.mjs. --project PATH selects a target; otherwise the CLI finds the nearest parent .cyc/config.json. Save inputs under excluded .cyc/runtime before start. Prefer run start --file START.json for multiline/quoted metadata:
14
10
 
15
11
  ```json
16
- [
17
- { "id": "complete", "description": "Marking one assignment finished moves only that assignment." },
18
- { "id": "persist", "description": "Refreshing preserves its finished status." },
19
- { "id": "count", "description": "The remaining-assignment count stays consistent." }
20
- ]
21
- ```
22
-
23
- These are illustrative requirements; discover the actual project behavior before adopting them. Save this file before starting the run or beneath an excluded runtime location. Ordinary project files created later count as source changes.
24
-
25
- ```text
26
- node .cyc/engine/bin/cyc.mjs run start --goal "Add assignment completion" --playbook feature --criterion "Finished work leaves the active list" --criterion "Survives reload" --session <ID> --scope src --scope test
12
+ {"goal":"Repair saved status","playbook":"bug-fix","criteria":[{"id":"reload","description":"Saved status survives reload."}],"allowedPaths":["src","test"],"executionMode":"standalone","session":"workflow-label","contextRetention":{"version":1,"disposition":"required","features":[{"id":"status","doc":"docs/context/status.md","paths":["src/status"]}]}}
27
13
  ```
28
14
 
29
- Each `--criterion` becomes a separate acceptance criterion (`c1`, `c2`, …); `--criteria FILE` accepts a JSON array instead. `--session` ties the run to the conversation that started it (the ID comes from the CYC gate context), so another conversation's run status does not block this conversation's completion gate. A native host session ID that has hook state in this project is stored as that conversation's gate key. Controller operations sharing one working folder are serialized as described below.
30
-
31
- ### Structured input without shell quoting
32
-
33
- Prefer JSON-file input for generated metadata, multiline text, quotes, or literal shell characters. `run start --file START.json` accepts this object; `--project PATH` selects the project independently:
34
-
35
- ```json
36
- {
37
- "goal": "Repair saved customer status\nPreserve compatibility.",
38
- "playbook": "bug-fix",
39
- "criteria": [{"id": "reload", "description": "Saved status survives reload."}],
40
- "allowedPaths": ["src", "test"],
41
- "session": "CURRENT_SESSION_ID"
42
- }
43
- ```
15
+ Use actual authorized mode/context. Optional scout/plan records Scout once at start; invalid input creates no run. Legacy argument commands remain supported: repeated --criterion yields c1,c2,…; --criteria FILE accepts IDs; omitted criteria are explicitly inferred. Fast routes use scout → build → verify → deliver; detailed plan/explore/teach/evaluate retain their chain. Follow returned exact runId/templates; implicit selection requires an unambiguous owned run, never another conversation's sole run.
44
16
 
45
- Save input under `.cyc/runtime/` before starting. `run start --file START.json` also accepts `scout` (the filled Scout assessment) with `plan` (a short approach summary), and records Scout in the same call; an invalid scout creates no run. `run finish --file FINISH.json` accepts `summary`, `assessment` (the filled Verify/Deliver object), `criterionEvidence` (an object mapping criterion IDs to strings), and optional `runId` and `artifacts` (path array). Run commands without `--run` use the single active run in the project, narrowed by `--session` when given, and name the candidates when several are active. JSON input tolerates a byte-order mark and single backslashes in Windows paths. Only invalid escapes are repaired, so a path such as `C:\new` still reads its `\n` as a newline; prefer forward slashes. Paths may use backslashes or be absolute inside the project. Assessments accept `resolution` for a finding's `status`, `fixed` for `resolved`, `reason` for a finding's `evidence`, `pass` for `passed`, and empty lists where a `none` status implies them. Evidence text and findings are never filled in. `passedEvidence` remains available for a single criterion. Use the actual fields returned by `run next`; this abbreviated shape is not a ready assessment:
17
+ JSON accepts BOM/repairs invalid Windows escapes only: use forward slashes because C:\new contains a valid newline escape. Canonical paths stay inside the target. Assessment aliases normalize spelling, not observations. Unknown fields/types and mixed file/field flags reject; matching --run is permitted with finish input. Inputs cannot override config, budgets or protected paths; proofCommands freezes at start.
46
18
 
47
- ```json
48
- {
49
- "runId": "ACTUAL_RUN_ID",
50
- "summary": "Reload preserves status; live host activation unverified.",
51
- "criterionEvidence": {"reload": "Named reload regression passes."},
52
- "assessment": {},
53
- "artifacts": ["src/store.py", "test/test_store.py"]
54
- }
55
- ```
19
+ allowedPaths/--scope restrict net changes to literal files/directory prefixes, not OS writes. Translate brief globs into authorized literal paths without broadening. Omit only for project-wide authorization. protectedPaths, context.ledgerPath and source include/exclude use the same literal rule: missing * or ? components reject before locks/snapshots/capture, never expand. Existing POSIX wildcard filenames remain literal; ordinary future paths, spaces, Unicode and [id] routes are valid. Historical scopes stay frozen; no failed run is widened/reset.
56
20
 
57
- The ordinary stage assessment still applies. Unknown envelope fields, non-object JSON, invalid field types and mixed field flags are rejected before invoking the controller. Do not mix `--file` with `--goal`, `--summary`, or assessment/evidence flags; a matching `--run` is allowed for finish. JSON cannot override project configuration, commands, budgets, or protected paths. Existing argument-based commands and `run record --file` remain available.
21
+ ## Execution capabilities and progress
58
22
 
59
- Most build playbooks are fast: **scout → build → verify → deliver**. Scout replaces frame, understand, impact, and design with one parallel pass and a short plan. The plan, explore, teach, and evaluate playbooks keep the detailed chain.
23
+ New start inputs may set executionMode to native-codex, native-claude, cursor or explicitly authorized standalone. conversationId identifies the real host conversation, session is a separate workflow label, and runId identifies controller work. A label's length does not choose Cursor. Native modes require actual context; standalone cannot downgrade a live native request or create activation evidence. Explicit ownership rejects foreign mutations. Legacy runs retain their original schema/evidence limits. Standalone finish generates run-local delivery.json; native packet tokens, windows, exact-response and blocked-run gates remain active.
60
24
 
61
- Repeated `--scope` arguments and structured `allowedPaths` use literal project-relative files or directory prefixes, such as `src/parser.py` and `tests/test_parser.py`. Translate a task brief's `src/*.py` notation into the actual permitted files or already-authorized directory prefixes; do not broaden task permissions. These entries restrict net changes accepted by the source guard, and do not restrict the operating system's write permissions. Omit scope only when the task legitimately needs project-wide changes. The controller returns a run ID; use that exact ID for subsequent operations. Criteria omitted at start default to an inferred goal criterion, which the state labels as inferred rather than pretending detailed acceptance was established.
25
+ Use --wait-ms 30000 on finish/verify/prove-red. operationComplete differs from workflow finished. Phase/check, elapsed time, actual output, logs and a handle support run wait --run ID --operation OPERATION_ID --wait-ms 30000 (maximum 60000). Silence is not success. Owned run stop requests cancellation outside the check lock; wait for acknowledgement and proof restoration. Conflicts retain halted recovery instead. Locks protect ownership/recovery, not status discovery.
62
26
 
63
- The same literal-path rule applies to `protectedPaths` and `context.ledgerPath`. Startup rejects a `*` or `?` component that does not already name a literal filesystem entry, before creating a run, workspace lock, Git snapshot or original-source capture. The error asks for explicit permitted paths; no patterns are expanded. Existing POSIX names containing those characters remain literal. Bracketed routes such as `routes/[id]`, spaces, Unicode and ordinary future paths remain valid. A permitted missing ordinary path may be intentional, so this is not a general typo detector. Stored older runs keep their frozen literal scopes and guards; no failed run is widened or reset by this validation.
27
+ Optional proofCommands freezes a focused command array at start; --tests selects swapped files, not execution scope. Final verification still runs all broad commands. Focused proof cannot substitute for a compatible measured original broad failure. Finish requests bounded proof judgment and measures broad originals when needed, retaining compatible focused treatment.
64
28
 
29
+ Reuse is opt-in per check: reuse:{kind:"local-deterministic",inputs:["explicit/dependency/path"]}. Include relevant non-source inputs. Keys also cover source/tests/configuration, installed dependencies, environment and executable/toolchain bytes. Unknown/unbounded inputs, links, external/freshness checks or changed inputs disable reuse. The existing baseline cache is reused; no competing evidence cache is introduced. Old records are never upgraded without measurement. CODEX_TOOL_CALL_ID is removed from checks and fingerprints; other environment inputs remain bound.
65
30
 
66
31
  ## Move through the recorded stages
67
32
 
68
33
  `run next` includes read-only tool hints at Scout/Understand/Impact and recipe-list hints at Build/Verify. Use [project tools](project-tools.md) to select context and applicable project checks from the run's changed paths or declared scope. Recipe execution retains diagnostic evidence outside covered source; it cannot advance stages, reset budgets, or replace the required command/test-proof gates.
69
34
 
70
- | Command | Result |
35
+ | Command (always bind --run ID) | Purpose |
71
36
  | --- | --- |
72
- | `run next --run ID` | Current stage, attempt, required criteria, skill location, and recent feedback |
73
- | `run record --run ID --summary TEXT [--artifact PATH...] [--criteria-passed EVIDENCE] [--status failed\|blocked]` | One-line handoff: the controller fills stage, attempt, and criteria and hashes the artifacts itself. Verify and deliver need evidence: `--criteria-passed TEXT` for one criterion; `--criterion-evidence JSON` mapping every ID to its own evidence for multiple criteria |
74
- | `run record --file FILE` | Full form: validate and record a hand-written handoff |
75
- | `run record ... --assessment FILE` | Add the required stage assessment to a quick handoff; assessment artifact hashes are computed by the controller |
76
- | `run review --run ID` | Refresh `.cyc/runs/ID/review.md` from the recorded evidence and current source; reuse for developer review and authorized PRs |
77
- | `run verify --run ID` | Execute configured project checks and retain their receipt |
78
- | `run prove-red --run ID [--tests PATH...]` | Run configured checks with new or changed tests against exact run-start code recovered from the recorded Git base and/or source capture, then restore the candidate bytes that CYC still owns, halting with backups if unexpected edits are detected. Bug fixes and features need a check that fails there while the original control passes; refactors need the new tests to pass there. Test paths (`test/`, `*.test.*`, `*_test.go`, `test_*.py`, ...) are detected or named with `--tests`. Missing/corrupt needed originals are refused before source changes |
79
- | `run finish --run ID --summary TEXT --assessment FILE --criterion-evidence JSON [--artifact PATH...]` | From Build or Verify, in order: refuse incomplete evidence or assessments before running anything; record Build; run `prove-red` when the proof is missing or outdated and no exemption is given; run the checks; record Verify and Deliver from one assessment file; complete; and, in Claude Code and Codex, write this request's review packet from the run's record (`packet` in the result). Artifacts default to the files changed since run start. A failed proof stops with its verdict. A failed check is recorded as a normal failed attempt and nothing else is recorded. Any later refusal names the step it stopped at and leaves the run there for an ordinary `run record`. If a step halts the run, for example because a protected file or a file outside `allowedPaths` changed, finish stops there and returns `failedAt`, the files, and whether Verify was recorded. With `--file`, a test proof exemption may be given as top-level `testProof` or as `assessment.testProof`, not both with different values. From Deliver: record Deliver and complete |
80
- | `run retry --run ID --stage STAGE --reason TEXT` | Return to the current or an earlier stage within the shared budget. In fast playbooks, `frame`, `understand`, `impact`, and `design` map to `scout` |
81
- | `run accept-failure --run ID --check ID --reason TEXT` | Accept a check that already failed on the run-start code, measured by an opt-in baseline or the proof's control run. Also available as `acceptFailures` in `run finish`. Verification then passes only if that check fails the same way (see Baselines) |
82
- | `run status --run ID` | Read the complete current state and history (other commands print a compact summary; add `--verbose` for full output) |
83
- | `readiness --session ID [--since ISO_TIMESTAMP]` | Read current-request controller statuses before delivery. Uses this session's hook `updatedAt` when available; otherwise requires an explicit non-future timestamp. An explicit window is diagnostic and can omit work if chosen incorrectly. Reports no host activation or source-quality guarantee |
84
- | `run recover --run ID` | Read-only explanation of current constraints, historical check results, preserved work and the next justified action; does not resume or reset a run |
85
- | `run pause --run ID` | Preserve a running task as paused |
86
- | `run resume --run ID` | Resume a paused or blocked task without resetting its budget |
87
- | `run stop --run ID` | End the run without claiming success |
88
- | `run complete --run ID` | Check that every stage and required completion condition passed |
89
-
90
- The active host agent reads the current skill, performs its bounded work, and writes the [handoff contract](skill-contract.md). Save packet files beneath `.cyc/runs/ID/`, not beside application source. Do not modify controller state or verification receipts. The response hook has a separate packet format; neither packet substitutes for the other.
91
-
92
- `run next` exposes `assessmentRequired`, an `assessmentTemplate` to fill in (at Verify it covers Verify and Deliver, with consumer checks prefilled from Scout, and `finishWith` shows the call), `workContractVersion`, and `reviewPath`. Both list only the fields the agent must judge. The controller records the rest when they are left out, and says so in each one's reason: `learning` as none, `errorHistory` as none for a run that is not a bug fix and has no failed attempt, and Scout's `context` as none when the project has no `docs/context/INDEX.md` and no ledger. A bug fix's error history, consumer checks and the semantic review always come from the agent. Once the run reaches finishing, the whole finish input is also written once to `.cyc/runs/ID/finish-template.json`. The agent's edits to it are never overwritten; while it is untouched, a run-start baseline that finds a failing check adds that check to its `acceptFailures` with a placeholder reason. The compact CLI output then shows `finishTemplate` first and prints the inline template only with `--verbose`. Any leftover `<placeholder>` value or `a | b` choice is rejected, so a template submitted unedited never passes. The generated review updates at recorded mutations and preserves recovery history while dropping invalidated later assessments. Refresh it after external edits to mark stale results. It lives outside covered source; durable context/ledger files do not. Finish intended project documentation edits before final verification. Pending acceptance uses a referenced run-local draft, never invented approval. The Deliver handoff also records `contextDocs`: the component docs under `docs/context/` among the artifacts and `learning.artifacts`, printed in `review.md` and read by `cyc context review`, which proposes a component doc entry from a completed run's record ([project tools](project-tools.md#component-context-docs)). A passing Verify handoff's semantic review is tied to its source snapshot; later source changes require retrying Verify even if commands have since passed again.
93
-
94
- Pass every configured criterion ID exactly once in each handoff. Early stages can honestly mark task criteria unverified. Passing verification or delivery requires all criteria passed. A successful early stage means its local output is usable, not that the whole feature already works.
95
-
96
- ## Configure meaningful executable checks
97
-
98
- Use `onboard` to inspect setup and locate project evidence sources. After reviewing and authorizing configured commands, `onboard --verify` executes them once and saves a source/configuration-bound diagnostic receipt. This does not replace `run verify`, establish a baseline for `run accept-failure`, or confirm live host activation. See [guided onboarding and recovery](onboarding-recovery.md).
99
-
100
- Before starting a code run, configure actual project checks in `.cyc/config.json`:
101
-
102
- ```json
103
- {
104
- "schemaVersion": 1,
105
- "limits": {
106
- "maxAttempts": 3,
107
- "maxNoProgress": 2
108
- },
109
- "verification": {
110
- "commands": [
111
- {
112
- "id": "tests",
113
- "command": "node",
114
- "args": ["--test"],
115
- "timeoutMs": 900000
116
- }
117
- ]
118
- },
119
- "protectedPaths": []
120
- }
121
- ```
122
-
123
- Use the project's own executable and arguments; this Node example does not imply another language's project must use Node tests. Commands run without shell interpolation, with the project as working directory. On Windows, use an actual executable or explicitly invoke the project's intended runner rather than assuming shell aliases resolve. Inspect commands for intended side effects before authorizing their execution.
124
-
125
- Configuration is captured at run start, and `.cyc/config.json` is protected against changes during that run. Additional `protectedPaths` are separately fingerprinted even when ordinary source snapshots exclude their directory. Do not weaken checks mid-run to obtain a green result. A legitimate configuration correction requires an explicitly explained new run, preserving the earlier outcome rather than hiding it.
37
+ | run next/status | Next stage/attempt/criteria/templates/skills or full state |
38
+ | run record --summary TEXT --assessment FILE | Quick handoff; generated stage/attempt/artifact hashes. Use --file for full packet. |
39
+ | run finish --file FINISH.json --wait-ms 30000 | Normal resumable context → proof/judgment → broad Verify → Deliver/completion |
40
+ | run prove-red [--tests PATH...] / run verify | Execute proof or broad final checks without skipping prerequisites |
41
+ | run review / review-capture / review-record | Generated review/current source provenance; see assessments |
42
+ | run retry --stage STAGE --reason TEXT | Rewind within shared budget (early detailed stages map to Scout on fast routes) |
43
+ | run accept-failure --check ID --reason TEXT | Judge a compatible measured original broad failure |
44
+ | run recover | Read-only constraints, preserved evidence and justified next action |
45
+ | run pause/resume/stop | Pause; resume without budget reset; stop without success |
46
+ | run complete | Require every completion condition; cannot substitute for finish work |
126
47
 
127
- A check without `timeoutMs` may run for 30 minutes, the same default for configured and package-declared checks; the receipt records the limit it ran under. A check that runs out of time is stopped together with the processes it started, and fails with an error naming its limit and how to raise it; one cut short by the run's own deadline (`limits.maxDurationMs`) says so instead. Each check runs through a small Node helper that copies its output to temporary files outside the project, at most 64 MB per stream plus a rolling tail, and removes them afterwards, so output size never fails a check and a check that prints without end cannot fill the disk. The helper is a generated CommonJS file, run without `NODE_OPTIONS` so a preload cannot break it (the check still gets them). It stops the check if the controller ends, calls `taskkill` by its full path on Windows, and reports a check that exits while a process it started still holds its output two seconds later. Without a writable system temp folder, the files go to `.cyc/runtime/checks`. The optional run-start baseline runs checks while holding the operation lock, so a hung check without `timeoutMs` can block other controller commands for up to 30 minutes; give checks that may hang a `timeoutMs`.
48
+ Quick record needs --criteria-passed TEXT for one criterion or --criterion-evidence JSON per ID for multiple criteria; early criteria can be unverified, Verify/Deliver require passed evidence. Failed/blocked handoffs report that status honestly. Full packets follow the [handoff contract](skill-contract.md). Keep input/receipts in excluded run storage; never edit state to pass. Returned commands/templates preserve exact IDs and agent edits. Current review records feed finish; generated projections are not their own evidence. See [assessments](work-assessments.md).
128
49
 
129
- Receipts contain the commands, exit status, bounded output, execution errors, and source fingerprint. Successful execution and an unchanged covered source snapshot are required for a passing receipt. A command that rewrites covered source does not establish verification of a stable candidate; finalize generated artifacts first or select a check that does not mutate the candidate.
50
+ readiness --session ID [--since ISO_TIMESTAMP] diagnoses request-scoped states. Use the actual hook window; explicit non-future windows may omit work and do not certify activation/quality. Response packets remain separate from handoffs.
130
51
 
131
- The runtime cannot judge whether a command is meaningful. `node -e "process.exit(0)"` would not test a feature, even though it exits successfully. Choose checks that exercise the promised behavior and affected consumers. Distinguish existing suite coverage from additional manual observations.
132
-
133
- ## Recovery and budgets
52
+ ## Feature context before completion
134
53
 
135
- There is no wall-clock deadline by default: a long task may take as long as it needs. The loop is bounded by failed attempts (`maxAttempts`, default 3) and repeated unchanged failures (`maxNoProgress`, default 2). A project can opt into a deadline with `limits.maxDurationMs`.
54
+ Current implementation starts receive contextRetention version 1 independently of evidenceVersion or input envelope. Supply a focused features array [{id,doc,paths}] before Build; omission infers existing focused owners or a goal-named record. Each canonical record and the target index join scope before freezing. New source entrypoints must resolve to planned owners; catch-all records and reference-only rows cannot satisfy retention. Meaningful shared-component changes require their focused records too; inference cannot establish semantic completeness.
136
55
 
137
- Baseline checks are **off by default**. Final verification still runs every configured command. Set `verification.baseline: true` only for optional diagnostic background measurements; never wait for these before editing. If covered files change while they run, the baseline is invalid. A matching source/command cache is diagnostic evidence only and may not reflect a changed external service. `run accept-failure` takes the baseline from that measurement when it is complete. Otherwise it uses the proof's control run, which ran every check on the run-start code. Only bug fixes and features have one; refactors, exempt proofs and other playbooks need `verification.baseline: true` set before the run.
56
+ Use learning.context [{id,currentView}] in finish, or author planned records then context prepare --run ID. Finish prepares missing records/index and returns noncomplete needs-context with exact remaining input until authored knowledge, index/mappings, current History/source evidence and freshness pass. It does this before proof/final verification; direct verify/complete cannot skip the gate. Current-view authorship binds to selected source; generated History alone is insufficient. Preparation uses actual available observations and stable run/command references, not future passing claims or self hashes. Sequential writes resume without duplicate current History; they are not atomic across files.
138
57
 
139
- **When the proof skips its control run.** The control run measures the run-start code so that a failure the new tests cause can be told from one that was already there. It cannot change the verdict in two cases, and finish then runs the suite twice (treatment and verify) instead of three times:
140
- - the treatment passes every check, so the new tests would not catch the change; or
141
- - the change only adds new test files (no existing test file is edited, moved or deleted), and every failure in the treatment is in those files, matched by exact project path, with TAP, mocha or jest output complete enough to name the failing tests and nothing else printed. The treatment is then exactly the run-start suite plus the new files, so the run-start suite alone can only pass.
58
+ Default target convention is docs/context/<feature>.md plus INDEX.md. Configure context.directory before start to reuse a project-owned equivalent directory. Engine/runtime storage is invalid; index/ledger/recipe/receipt files are supporting records, excluded from contextDocs. Validation reads planned docs plus index consistency, not every historical Current view. Semantic correctness and adoption remain agent/reviewer judgments.
142
59
 
143
- A test added to an existing test file, a moved or deleted test file, a check that prints no test names (lint, a template check) or anything besides test results (a coverage line, a warning), and output cut short all run the control as before. Test titles are never matched against source text: an edited file can hide a data-driven or renamed old failure behind any title. The proof receipt records `controlSource`. After a skipped control, the treatment has shown every check passing on the run-start code apart from the new files: a finish `acceptFailures` entry is dropped as unnecessary, and `run accept-failure` refuses, since a failure now is a regression.
60
+ An honest nonfeature routine/read-only disposition remains proportional. A feature cannot waive retention through learning:none or an older start shape. Explicit scope/protected-document restrictions remain pending/incomplete without writes. A late need cannot broaden frozen scope. Older stored records preserve their contract and are labeled legacy. Completed-run catch-up requires a new implementation update with a required canonical plan and final executable checks (--update-run ID); fresh verification follows context edits, and a new reply packet cannot restore stale evidence. See [Context](../methods/cyc-context/SKILL.md).
144
61
 
145
- With a run-start baseline, a check that failed there is also listed in the run's `finish-template.json` as an `acceptFailures` entry with a placeholder reason, while the agent has not edited that file, so the agent decides before finishing instead of finding out at verify. Finish refuses a placeholder reason before running anything. A finish entry for a check that passed at run start is dropped with a note in `droppedAcceptFailures`; verify still requires that check to pass.
146
-
147
- An accepted check that still fails does not block completion if it fails exactly as it did on the run-start code, and at least one check passes. "Exactly" means:
148
- - the same exit code and error;
149
- - the same set of output lines, with only timestamps, clock times, durations, and the process ID in node warnings such as `(node:12316)` ignored;
150
- - neither output cut off: each stream keeps its last 32,000 characters, so longer output can be compared only test by test (below), and only when a test failed at the run start;
151
- - no file the run changed named in the output.
152
-
153
- The receipt marks verification `passed-with-accepted-failures`, `review.md` lists each accepted failure with its reason, and `run finish` returns them for the reply to name. A suite can contain both old and new failures, so any of the following leaves the check **unverified** and blocks:
154
- - a new or lost line, such as a new failing test, a new lint error, or a version number that moved;
155
- - a different exit code or a hang;
156
- - truncated output;
157
- - a mention of a changed file;
158
- - a check that printed nothing at the run start.
62
+ ## Configure meaningful executable checks
159
63
 
160
- `acceptedFailuresThatChanged` in the verify output says which of these applied. When verification fails, `failedAtRunStart` lists the failing checks that also failed in the run-start measurement and are not accepted yet. The CLI hint shows the `acceptFailures` entry to add if they are unrelated.
64
+ Use onboard for read-only setup; authorized onboard --verify saves diagnostic evidence, not final verification, failure-acceptance baseline or host activation. Configure genuine project checks **before** starting:
161
65
 
162
- If those checks are the only failures, and each fails exactly as it did then, the stop is logged as `awaiting-acceptance`: a decision still to make, not a failed fix. Once per run, such a stop does not count against the failure budget or require error history. Every later stop counts, whatever changed, so the loop stays bounded. The CLI's accept hint appears only on that stop; otherwise the recovery instruction leads.
66
+ ```json
67
+ {"schemaVersion":1,"limits":{"maxAttempts":3,"maxNoProgress":2},"verification":{"commands":[{"id":"tests","command":"node","args":["--test"],"timeoutMs":900000}]},"protectedPaths":[]}
68
+ ```
163
69
 
164
- Test runner output is compared by test instead of by line, because the new tests add passing lines to the suite. `scripts/test-output.mjs` reads TAP (`node --test`, `tap`), mocha (any reporter: it reads the numbered failures after "N passing"), and jest. Failing tests are keyed by their file and their name under parent suites, and counted. The file comes from the failure's `location` in TAP, a subtest named after a test file for `tap`, the `Context.<anonymous>` stack frame for mocha, and the `FAIL` line for jest. Suites, `describe` groups, and skipped, pending, or todo tests are not tests, and jest's `● Console` is output, not a test. The report is read from the stream the runner writes it to (jest uses stderr, the others stdout); every line of the other stream is other output. TAP is tried first only when the output declares `TAP version`, so a stray `ok` line does not hide a mocha or jest report.
70
+ Commands use executable/argv without shell interpolation in the target working directory; inspect side effects. A successful no-op is not a meaningful check. Configuration is frozen/protected during a run, including protectedPaths even outside ordinary source selection. A legitimate config correction needs an explained new run preserving the old result, never weakened checks.
165
71
 
166
- When a check prints more than the 32,000 characters kept per stream, the whole output is read as the check finishes, and its results are kept whole with the receipt: every failing test with all of its details, the passing count, and every other line. Up to 64 MB of each stream is kept for this; past that only the tail is kept and the results count as cut off, while the exit code still decides whether the check passed. A summary over 4,000,000 characters keeps only counts and also counts as cut off. An accepted check whose output a reader recognizes, and which had a failing test at the run start, is excused if all of these hold:
167
- - no test fails that did not fail at the run start, and none fails more often;
168
- - every old failure still has the same error;
169
- - no failure's stack or error names a changed source file;
170
- - every line that is not a test result, plan, summary, or failure diagnostic also appeared then;
171
- - at least one of its tests passes.
72
+ Default timeout is 30 minutes, distinct from optional run deadline. The runner stops process trees on timeout/controller loss/owned cancellation (full-path taskkill on Windows). The helper excludes NODE_OPTIONS; checks retain it. Logs keep up to 64 MiB per stream plus tails outside source; escaped output holders drain for two seconds after exit. Receipts bind commands, actual exit/errors/output and covered source stability. All-green commands that change covered source do not verify a stable candidate; finalize generated files first.
172
73
 
173
- The proof uses the same names, because its two runs differ only by the new tests. A failure counts as a new test failing on the original code only if all of these hold:
174
- - it sits in a changed test file;
175
- - it is not an old failure renamed or wrapped in place;
176
- - neither output was cut off without a complete summary.
74
+ ## Recovery and budgets
177
75
 
178
- This works even when the suite already failed for an older test, and `proofClaim` names those tests.
76
+ No wall-clock deadline applies unless limits.maxDurationMs is configured. Failed attempts share maxAttempts (default 3) and maxNoProgress (default 2) across stages; retries cannot reset them. No-progress signatures are heuristics. Pause/resume preserves deadlines and invalidates executable verification. Attempt IDs advance on recovery; read run next rather than replaying an earlier packet.
179
77
 
180
- Other output, such as node's dot reporter, and output whose run-start failure was not a test (a coverage threshold, say), is compared by whole output, so it cannot be excused once it is longer than the kept tail. A runner that reports only counts cannot reveal a new failure, so give such checks a reporter that names failures. Report a blocker rather than changing checks to force completion.
78
+ Baseline measurement is off by default. verification.baseline:true measures originals with workspace ownership; edits invalidate it. Compatible explicitly deterministic inputs use the existing cache. Otherwise accepting an old broad failure needs a measured broad original control. Focused proof cannot excuse omitted broad checks. Refactor/exempt runs needing acceptance must arrange broad originals before edits.
181
79
 
182
- With no configured commands, a declared npm test whose package defines `pretest` or `posttest` runs each hook as its own check around `npm test --ignore-scripts`. A posttest that already fails, such as lint or a template check, then leaves the test runner as a check that passes on the run-start code, which the proof needs. `--ignore-scripts` also skips the hooks of npm scripts that the test script runs. So npm test stays whole when any script it reaches has its own hooks, or when it uses a script runner such as `run-s` or `concurrently`.
80
+ Proof roles remain original-only control, originals-plus-new-tests treatment and candidate. Control may be skipped when treatment passes (no decisive red), or only newly added exact-path tests fail with complete named output and no extra diagnostics. Edited/moved/deleted tests, unknown names, cutoff or other errors require control. Do not infer identities from test source. npm pretest/posttest lifecycle checks remain required.
183
81
 
184
- Failures across all stages share one budget. A failed handoff or failed verification consumes that budget; moving to an earlier stage does not provide a fresh allowance. Repeated unchanged failure signatures can exhaust the no-progress threshold sooner. This signature comparison is a heuristic, not a semantic judgment that all meaningful progress has stopped.
82
+ Finish templates list measured old failures with placeholder reasons; fill genuine reasons or fix them. Passing originals do not need acceptance. A failing candidate check may be accepted only with compatible broad original evidence, at least one passing check, and identical exit/error plus stable failures/non-test diagnostics. Timings, dates, durations and Node warning PIDs may differ. Changed-source stack paths, new/lost failures or lines, hangs, empty/cutoff evidence and changed errors block. Parser-aware TAP/mocha/jest comparison retains identity/file/parent path/count/error; unknown formats use conservative line comparison. Large complete output can compare parsed tests within the 64-MiB limit; 32,000-character tails alone cannot prove equality. See scripts/test-output.mjs and its adversarial tests.
185
83
 
186
- Recovery invalidates dependent later handoffs and verification. The attempt identifier advances across stages and recovery, so a packet from an earlier visit to the same stage cannot be replayed. Read the current value from `run next`; do not calculate it yourself. Pause/resume preserves any configured wall-clock deadline and invalidates executable verification so resumed work must be checked again. The controller checks budgets when an operation advances work; it does not continuously monitor a host agent between calls or terminate that agent.
84
+ Once per run, only unchanged measured old failures can stop as awaiting-acceptance without consuming the failure budget; later stops count. Accepted failures remain passed-with-accepted-failures and require disclosure. failedAtRunStart and acceptedFailuresThatChanged distinguish missing judgments from incompatibility.
187
85
 
188
- States distinguish running, paused, blocked, complete, exhausted, halted, and stopped. A blocker is an external prerequisite or needed participation, not a successful outcome. A halted guard preserves changes for review rather than rolling them back. Starting a new run must be an explicit task decision, not an automatic escape from a failed budget.
86
+ Recovery invalidates dependent later handoffs/evidence. States distinguish running, paused, blocked, complete, exhausted, halted and stopped. A blocker is an unmet prerequisite, not success. Halt preserves unexpected source for review, not rollback. The controller checks budgets when advancing; it does not terminate the host agent. New runs require an explicit task decision, never automatic escape from a failed budget.
189
87
 
190
88
  ### Shared working-folder ownership
191
89
 
192
- Controller starts, verification/proof, handoffs, review updates and optional baseline measurements use an exclusive project-local operation record at `.cyc/runs/workspace.lock`. A second controller operation is refused before checks, run writes or failure-budget use; independent working folders remain independent. Existing per-run locks remain. A busy optional baseline records an unavailable diagnostic instead of measuring temporary source. Startup releases ownership before launching its baseline. Read-only recovery reports the owner and defers source interpretation. This is separate from session ownership in the completion gate.
193
-
194
- Proof writes its candidate backup and manifest outside test discovery, then publishes the backup path, candidate source hash and prepared phase in the operation record before replacing source. At phase boundaries and restoration, it compares temporary files with the bytes CYC last placed. A detected edit, deletion, path-type change, restoration error or final source mismatch halts the run, clears current proof/verification and retains the candidate backup. Unexpected regular bytes are also copied into that backup when possible; copy/manifest errors remain disclosed. Other owned paths are restored independently. No successful proof receipt is issued for a conflict. `run recover` and the generated review name the retained evidence and require deliberate comparison/merge; a halted run cannot resume.
90
+ Controller mutations/baselines hold exclusive project-local .cyc/runs/workspace.lock plus per-run locks. A second controller is refused before writes/checks/budget use. Startup releases ownership before optional baseline launch; busy baselines become unavailable. Read-only recovery reports owners and defers source interpretation.
195
91
 
196
- Both locks record the owner's process ID, host name, operating system and, on Linux, process ID namespace, so a container or WSL that shares the host name and the folder is never judged by process IDs it cannot see. The next controller operation reclaims a lock only when it was taken in this same place, is not the current process, its process is no longer running (only "no such process" counts as ended), and it was idle when it ended. Idle means no commit under way (both locks record one before it starts, so a failure whose own record cannot be written still leaves the lock kept), no proof with swapped or halted source (a backup pointer in any phase but `restored`), no publication failure, and no phase this engine does not know. While a check runs, the operation lock also records until when it may run, and the lock is not reclaimed before then: on Windows a check started through `cmd` or another program can outlive a controller killed by force. If that record cannot be written, for example while a scanner holds the lock file, the check still runs and the lock only lacks this protection. Reclaiming a lock left by a run-start measurement records that measurement as failed, so the run stops waiting for it. A reclaimer first creates an exclusive `<lock>.reclaim` guard, then removes the lock only if it still holds exactly the owner record it judged; another process reclaiming at the same moment is refused as busy, and a lock written by a newer operation is left alone. Each reclaim is appended to `.cyc/runs/lock-reclaims.jsonl` with the old owner record. A process ID the system has reused for another program reads as alive, which only ever keeps a lock. Every other lock stays for the operator, and the busy error says why: another host or namespace, an older engine without a host name, an empty or partly written record, a commit or proof that may not have completed, a check that may still be running, or a guard left by a reclaimer that crashed, with that guard's process and whether it still runs.
92
+ Proof publishes its extensionless candidate backup/manifest pointer and phase **before** temporary source replacement. At each boundary/restoration it compares files with its own last bytes. Unexpected edits, deletion, type changes, restore/publication failures or final mismatch halt the run and retain backup evidence; other owned paths restore independently. Unexpected regular bytes are preserved when possible; capture failures are disclosed. No successful proof receipt is issued for conflicts. A killed proof requires deliberate operator comparison, never automatic rollback or lock clearing.
197
93
 
198
- So a killed proof still leaves the operation and per-run locks plus the pre-published backup pointer. Recovery performs no automatic rollback. Confirm the owner has stopped, preserve current files and locks, inspect the backup manifest and compare versions before deliberate operator cleanup. Never clear locks or rewrite state merely to obtain completion. A restored phase records completed source restoration; a remaining backup may already have been removed after that point.
94
+ Locks bind PID, host, OS and Linux PID namespace. Reclaim requires same identity, ended owner and idle phase; commit/publication failures, swapped/halted backups and unknown phases remain protected. Recorded deadlines protect checks outliving the controller; scanner-blocked deadline updates disclose that missing extra protection. Reclaim compares exact owner under its own exclusive guard, preserves newer owners and logs lock-reclaims.jsonl; abandoned baselines become failed. Foreign/unknown owners need operator recovery.
199
95
 
200
- If committing run state or publishing its generated review fails, both operation and per-run locks remain. The owner record retains the backup pointer and, when writable, a publication failure identifying whether state was saved; the run lock records the same failure. Both already record the commit under way, so neither lock is reclaimed as merely abandoned even when the failure record cannot be written. Read-only recovery treats earlier passing fields as unverified, names the retained evidence and warns that the old review may be stale. It does not publish the staged outcome, clear locks or resume the run automatically. A prior durable backup pointer still remains if the later failure record itself cannot be written.
96
+ State/review publication failures retain both locks and backup pointer; commit-in-progress remains protected even if writing the failure record also fails. Recovery marks old passing fields/review unverified; it neither publishes the staged result nor resumes work. A restored phase can retain a pointer whose backup was already removed after restoration.
201
97
 
202
- This coordination covers controller operations and baseline measurement, not arbitrary editors, external tools or independent recipe invocations. Recipes still use the configured runner directly, including recipes intentionally called by a controller command; coordinate separate invocations yourself. Byte checks are not an atomic filesystem compare-and-swap and cannot rule out a write between observation and replacement or through an existing open handle. Use a quiescent, isolated working folder for proof when other actors could write. Local editable locks are workflow coordination, not an access-control or enterprise attestation boundary.
98
+ This coordinates controller work, not arbitrary editors or independent recipes. Locks are local workflow records, not access control/attestation. Byte checks are not filesystem compare-and-swap; an external write/open handle can race observation/replacement. Use an isolated quiescent folder when proof could overlap other writers.
203
99
 
204
100
  ## What the controller establishes—and what it does not
205
101
 
@@ -211,23 +107,17 @@ The source guard compares project state at checkpoints. It is not a filesystem s
211
107
 
212
108
  ### Run-start originals
213
109
 
214
- New bug-fix, feature and refactor runs retain selected originals needed for later proof. A successfully recorded Git working-tree base supplies ordinary tracked files; the existing source scan reuses Git index flags without another inventory scan. Files marked assume-unchanged or skip-worktree are captured because Git can omit their working bytes even when the snapshot command succeeds. Other permitted regular originals are captured as extensionless hash-named blobs in `.cyc/runs/ID/original-source/`, with a `sourceCapture` record in state. If Git cannot record that working tree, capture supplies the permitted selected bytes instead of assuming HEAD matches. This includes permitted ignored inputs explicitly selected through `source.include`; excluded untracked secrets, links, protected files and source outside task scope are not copied. Git source-selection failures still refuse startup rather than silently scanning ignored files.
215
-
216
- Proof accepts recovered filtered or raw Git bytes only when they match the recorded original SHA exactly. For manually held CRLF bytes that disagree with current Git line-ending attributes, it may try a byte-preserving CRLF reconstruction under that same hash check. Equivalent normalized text is insufficient: unreconstructable mixed endings or other filters still refuse proof. This does not rewrite original hashes, captured-file lists or older run state.
217
-
218
- Without a Git commit or Git repository, capture supplies the permitted selected originals, so new runs still require a current proof. Narrow `allowedPaths` to the actual task: unrestricted plain projects can capture all covered regular source. Capture holds originals in memory until the run is recorded, so it has its own limit of 20,000 files and 128 MiB, below the selected-source limits; a larger plain project must narrow `allowedPaths` or commit so Git keeps the originals. Equal bytes within a run share one blob. This is working evidence stored separately from the installed engine, not a complete checkout backup or an automatic retention/pruning policy.
110
+ New bug-fix/feature/refactor runs capture permitted selected originals for exact proof. A recorded Git working tree supplies ordinary tracked bytes; assume-unchanged/skip-worktree files and permitted uncaptured originals use extensionless hash blobs in .cyc/runs/ID/original-source with sourceCapture metadata. Without Git, or if Git cannot record working bytes, capture supplies them. Git selection failure refuses startup instead of reading ignored data. Protected/out-of-scope/link/excluded-secret inputs are not captured.
219
111
 
220
- Captured bytes must match the initial source hashes before the run is recorded and again when used for proof. Protected run storage, including demonstrated junction/casing aliases, is rejected before new records/blobs. Proof keeps the configured commands and working folder; its temporary restoration backup remains outside test discovery. The receipt binds the original source hash, control/treatment results and current test hashes. As before, it establishes a check-level result, not that every new test detects the defect.
112
+ Captured hashes must match before recording and using originals. Filtered or raw Git bytes are accepted only with exact initial SHA; CRLF reconstruction is attempted only under that same check. Equivalent text is insufficient for mixed endings/noninvertible filters. Missing objects/captures remain unavailable, never reconstructed from repaired code. Historical runs do not gain new captures. Honest exemptions remain labeled limitations, not proof receipts.
221
113
 
222
- Existing serialized runs keep their original recovery contract. They do not gain a capture after editing; an older null-base run remains unavailable, and an older untracked file may remain unrecoverable. Missing Git objects, noninvertible content filters or missing/changed needed captures can still prevent exact recovery. Preserve the actual limitation and evidence; never manufacture originals from the repaired code. A supported exemption needs a truthful reason and does not become a proof receipt. Local editable state/capture records are not independent enterprise attestation.
114
+ Capture holds originals until startup records them: max 20,000 files/128 MiB, deduplicated within a run. Larger plain projects must narrow scope or use Git. Storage is separate from the installed engine, not a full backup or retention/pruning policy. Protected storage/junction/casing aliases are refused before recording. Proof backups remain outside test discovery and bind original source, control/treatment and candidate tests; this establishes check-level evidence, not that every assertion detects a defect.
223
115
 
224
- For generated inputs that genuinely affect behavior, configure literal project-relative paths in `source.include`. Use `source.exclude` for additional untracked artifacts; it cannot hide tracked files. Neither field expands glob patterns. Missing `*` or `?` components reject with literal-path guidance; both fields are validated before controller startup writes. Ordinary future paths, spaces, Unicode and bracketed routes remain literal. Existing POSIX wildcard-named components can be named literally, but validation never follows a symlink/junction to establish unresolved wildcard components in its target. Explicit includes do not follow symlinks or include untracked `.env` secrets. Non-Git projects use filesystem traversal with dependency/build defaults and these explicit paths; `.gitignore` is not interpreted without Git. Git file-selection errors in a repository fail rather than silently scanning ignored output.
116
+ source.include/exclude use literal relative paths, never globs. Include real generated inputs; exclude only untracked artifacts (tracked files remain covered). Missing wildcard components reject before startup writes; ordinary future paths, spaces, Unicode and bracketed routes remain literal. Existing literal wildcard names on POSIX do not enable expansion or symlink following. Includes cannot expose untracked .env secrets. Non-Git traversal uses dependency/build defaults, not .gitignore. Selected-source defaults are 200,000 files/2 GiB; positive source.maxFiles/maxBytes can change them. Example: {"source":{"include":["generated/api-types.d.ts"],"exclude":["output"],"maxFiles":300000}}.
225
117
 
226
- Example: `"source": { "include": ["generated/api-types.d.ts"], "exclude": ["output", ".eslintcache"], "maxFiles": 300000 }`. Selected source is limited to 200,000 files and 2 GiB by default; `source.maxFiles` and `source.maxBytes` (positive integers) change those limits, and the error for a larger selection names the setting to change.
118
+ Evidence snapshots fully hash selected files at start, proof swap/restore, final checks, baseline/recipes/onboarding and completion. Intermediate guarded views can reuse .cyc/runs/source-cache.json SHA when size/mtime/ctime/file ID match a file hashed after two seconds stillness. Windows mapped writes/reset timestamps and FAT can defeat that intermediate heuristic; the next full evidence read repairs it. Stale preverification views make checks unstable, never certify stability. Only operation owners update cache; successful/recorded-failure returns publish accumulated updates, thrown refusals publish none and remove only demonstrated wrong entries. Read-only recover/investigate/recipe list write nothing. Git listing bounds are 512 MiB/two minutes. Scope restricts edits, not fingerprint selection. sourceStable/changedPaths explain mutations during passing checks.
227
119
 
228
- Snapshots that record evidence hash every selected file: at run start, before and after a proof's source swap, after verification, baseline, recipe and onboarding commands, and at completion. Between them, guards, review files, status and recovery reuse a file's SHA-256 from `.cyc/runs/source-cache.json` when its size, modification time, change time and file ID all match an entry hashed after the file had been still for two seconds. Ordinary writes move the change time, but not all do: on Windows a write through a memory-mapped view leaves every timestamp unchanged and tools can set the change time back, and FAT keeps none. So a stale cached hash can only affect those intermediate views until the next evidence snapshot, which reads every file and repairs the cache. A stale hash before verification makes the check look unstable, never stable. Only controller operations holding the operation lock update the cache. Their snapshots collect updates in memory, later snapshots in the same operation reuse them, and they are stored when the operation returns, before the lock is released, including an operation that records a failed check or halts a run. An operation that throws, such as a refused proof or completion, stores no new hashes, so a refusal adds nothing to the project. It only removes entries one of its full reads proved wrong (same size, times and file ID, other bytes), so the cache does not go on hiding that change from the next verification. Read-only commands such as `run recover`, `investigate` and `recipe list` write nothing. The cache is a local record like run state, not an attestation. Git file listing allows 512 MB of paths and two minutes. Scope limits still restrict edits, not which files are fingerprinted. Verification outputs `sourceStable` and `changedPaths` so all-green commands with changing source have an actionable explanation.
229
-
230
- A full-content snapshot of 1,000 or more files reads them on up to eight worker threads (`scripts/source-hash-worker.mjs`); smaller ones stay on one thread, since workers take about 25 ms to start. Opening each file is most of the cost, about 0.4 ms on Windows with its file system filters, so on this Windows machine a 60,000-file snapshot that took 25.8–26.0 s on one thread takes 6.8 s (three runs each, alternating; four or six threads were slower, more than eight no faster), and a feature run on that project starts in 15 s instead of 35–37 s and finishes in 57 s instead of 133 s. Workers only read and SHA-256 regular files no larger than `source.maxBytes`, in 1 MiB chunks, so a large file never sits whole in memory; like the earlier `readFileSync`, a read stops at the size the file had when opened, and a file over 2 GiB is now hashed instead of failing with `ERR_FS_FILE_TOO_LARGE`. The main thread applies their results in path order, so file selection, limits, the order of entries and so the snapshot hash, and cache updates are those of a single-threaded read. Links, directories, vanished files, a file the byte limit stops, and read errors go back to the main thread, which inspects them in order, so an error is raised where a single-threaded read raises it and a file over the limit is never read. Workers get no `NODE_OPTIONS` or command-line preloads, and their output never reaches a command's result. If no worker has started after two seconds, or no read has progressed for five (workers report each chunk, so a long read counts as progress), the main thread reads the files it is waiting for itself. Before a snapshot returns or throws, it waits for reads in progress, so no worker still holds a file open, giving up only after five seconds without progress. A copy of `source-snapshot.mjs` without its worker file reads on one thread. Cached views and the delivery gate's size-and-time snapshot stay on one thread.
120
+ Full snapshots of at least 1,000 files use up to eight source-hash-worker threads, reading SHA-256 in 1-MiB chunks and applying results/errors in original path order. Links/type changes/read errors/size limits defer to main-thread policy. Workers exclude preloads/NODE_OPTIONS, expose no output and fall back after two seconds without startup or five without progress; snapshot exit waits for active reads, bounded by five seconds of silence. A missing worker module falls back to one thread. Cached/gate views remain single-threaded. Local performance observations are not generalized savings claims; behavior/order/source limits remain those of the serial reader.
231
121
 
232
122
  Linked paths in the covered project tree are fingerprinted by their identity, but their targets are not recursively verified. Executable verification refuses unsupported symlink/junction coverage rather than issuing a passing receipt. Adding or changing such a link is also a source change. Linked dependencies inside excluded dependency directories remain outside this guard's coverage; use the project's dependency controls for those.
233
123
 
@@ -236,14 +126,8 @@ Use the host's actual sandbox, access controls, and authorization boundaries whe
236
126
 
237
127
  ## Project conventions
238
128
 
239
- Set `context.ledgerPath` to the existing project ledger. Without it, CYC prefers `INCIDENT-LEDGER.md` if present, otherwise `docs/context/error-ledger.md`. New runs freeze `projectLedgerPath` for lookup and `ledgerPath` for recording. If allowed/protected paths prevent shared-ledger edits, recording uses `.cyc/runs/ID/error-history.md`; `ledgerNote` explains the choice. A protected fallback is rejected before creating a run. Existing serialized runs keep their captured selection.
240
-
241
- Run-local storage retains required failure evidence without authorizing shared-document edits. Deliver still requires the exact selected file and checks its hash; protected-source and scope guards remain. The generated review identifies both paths and deferred shared-log promotion. Search relevant earlier run-local histories too, but disclose that they may exist only in this checkout. Explicit project policies still apply; a separate requirement for a committed shared record cannot be waived by this selection. Later promotion needs authorized scope and fresh verification.
242
-
243
- Set `delivery.presentation: "project"` when an existing hook owns reply formatting. CYC then delegates length, visuals and presentation review to project instructions, while its controller-completion gate remains active. Cursor still needs the small identity packet described in its installed rule. Defaults retain CYC presentation checks.
244
-
245
- The delivery gate checks this session's runs in the current checkout and Git-registered worktrees of the same repository. Other sessions and unowned legacy runs in other worktrees are excluded. Arbitrary independent folders are not discovered: use their own activated host session. Worktree discovery is a local protocol check, not proof of live host loading.
129
+ context.ledgerPath selects the existing ledger (otherwise INCIDENT-LEDGER.md, then docs/context/error-ledger.md). Start freezes projectLedgerPath for lookup and ledgerPath for recording. Out-of-scope/protected shared writes use .cyc/runs/ID/error-history.md; a protected fallback rejects before creating the run. Record failures in the selected file, disclose deferred shared promotion and search relevant local histories. Old states retain their selection; explicit shared-record requirements are not waived. See [learning/file order](work-assessments.md#learning-lifecycle-and-final-file-order).
246
130
 
247
- Runs record their starting engine version. An engine version change prevents an active run from advancing; stop it, reload the host, and explicitly start a new run. Legacy runs without version metadata remain labeled unknown.
131
+ delivery.presentation:"project" delegates reply formatting to project instructions while keeping controller completion gates; Cursor still needs its identity/exact-response packet. Default presentation checks remain. Gate discovery includes this session's runs in this checkout and registered Git worktrees, excludes foreign sessions/unowned legacy runs elsewhere and never searches independent folders. This protocol does not prove live host loading.
248
132
 
249
- The `skill` field returned by `run next` points to an internal `methods/cyc-<stage>/SKILL.md` relative to the engine root. `skillFile` gives the same method as an absolute path, so an agent working from the project root can open it directly. These files are read by the orchestrator, not registered as separate slash commands. `/cyc` is the only public entry.
133
+ An active run cannot advance across an engine-version change: stop, reload and explicitly start new work preserving the prior outcome. Old metadata stays unknown. run next returns internal skill and absolute skillFile paths under the engine; methods are supporting resources, and /cyc remains the public entry.