@sema-agent/core 7.68.0 → 7.68.2
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/CHANGELOG.md +55 -0
- package/dist/core/checkpoint-requirements.d.ts +20 -1
- package/dist/core/checkpoint-requirements.js +11 -5
- package/dist/core/engine-capabilities.d.ts +8 -1
- package/dist/core/engine-capabilities.js +1 -1
- package/dist/core/file-history-store.d.ts +229 -44
- package/dist/core/file-history-store.js +288 -93
- package/dist/core/runner/contracts.d.ts +1 -1
- package/dist/core/runner/file-history-request.d.ts +10 -2
- package/dist/core/runner/file-history-request.js +17 -1
- package/dist/core/runner/file-history-restore.d.ts +11 -4
- package/dist/core/runner/file-history-restore.js +19 -5
- package/dist/core/runner/prepare-file-history.js +3 -3
- package/dist/core/runner/rewind-files.js +11 -8
- package/dist/core/store-contracts/file-history-store-contract.js +210 -13
- package/dist/core/task-spec-members.d.ts +2 -1
- package/dist/core/task-spec-members.js +1 -1
- package/dist/core/task-spec.d.ts +7 -0
- package/dist/core/tool-roster.d.ts +12 -0
- package/dist/core/tool-roster.js +12 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/stores/file/file-history-store.d.ts +5 -3
- package/dist/stores/file/file-history-store.js +42 -60
- package/package.json +2 -2
- package/test/export-surface.snapshot.json +17 -1
- package/wire-changes/core-stores-sql@7.68.1.json +39 -0
- package/wire-changes/core-stores-sql@7.68.2.json +39 -0
- package/wire-changes/core@7.68.1.json +95 -0
- package/wire-changes/core@7.68.2.json +612 -0
- package/wire-changes/mods-kernel@7.68.1.json +39 -0
- package/wire-changes/mods-kernel@7.68.2.json +39 -0
- package/wire-changes/primitives@7.68.1.json +39 -0
- package/wire-changes/primitives@7.68.2.json +39 -0
- package/wire-changes/wiki-gate@7.68.1.json +39 -0
- package/wire-changes/wiki-gate@7.68.2.json +39 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,58 @@
|
|
|
1
|
+
## 7.68.2 — 2026-11-13
|
|
2
|
+
|
|
3
|
+
### A file rewind writes a recorded version only under the directory it was recorded under — one recorded elsewhere is refused file by file, a run that does not accept a partial restore moves nothing, and the preview and the restore name every file (#4328, closes the write shapes of #4446; behavior change; narrowing: six, below, open to veto @server @cli @client-core; widening: two, below, open to veto @server @cli; hard-breaking: none at runtime — compliance-kit cells a backend that has not followed reads red, below; closed sets: `FILE_HISTORY_REFUSAL_CLASSES` +2 (`recorded_elsewhere`, `place_unrecorded`; the same two on a refused file's `FileRestoreApplyOutcome.class`), `ENGINE_CAPABILITIES` +1 (`file_history.recorded_place`), new `FileRestoreApplyOutcome.action` (`write`, `delete`); exports: +6 functions, +2 types, none removed; signatures: `restore` and `diffStats` of `FileHistoryStore` and of both bundled stores take an optional last parameter `options` (`FileHistoryRestoreOptions`); wire: optional members only — `TaskSpec.unplacedHistoryRecordedUnder`, `RewindFilesRequest.unplacedHistoryRecordedUnder`, `files` on the restore result and the preview, `recordedUnder` / `action` on a refused row, `failed` on a `files` row, `absoluteEntriesOmitted` on the export envelope)
|
|
4
|
+
|
|
5
|
+
- **Before.** (#4446, as the 7.68.1 notes disclose it.) A version carried no fact of where it belonged: its key was relative to the root of the leg that recorded it, its `parentIdent` relative to the same root, and a restore joined the key on the root of the leg that asked. A later leg handed another root — the terminal's `/cd` / `!cd`, entering or leaving a worktree, the same session continued in another worktree; an embedder's `cwd` per leg, a fork handed another root, the deletion cascade's `adoptScope` — had the file at the same relative path under its root written with the earlier root's bytes and the rewound turn's created files deleted there, answered `complete`, while the files under the earlier root stayed as they were. Two more write paths rode the same restore. A run that does not accept a partial restore wrote every restorable file before it reached the one it refused, then answered `rewind.restore_failed` (measured: a target replaced by a symbolic link — `b.txt` written, `a.txt` refused). A fork's rewind to a turn carried from its source wrote the source's edits outside its directory back over the source's later edits (measured: `o.txt` back to `o-0` over the source's `o-2`). The preview listed names and line counts only.
|
|
6
|
+
- **Now.** One rule: a tracked entry is one file, and its identity is the directory its versions record — `parentIdent` now holds the parent's absolute real path (the nearest existing ancestor's real path with the rest of the path appended; the member is unchanged). A restore writes or deletes a version only when the place it would land on (this leg's root + the key) is that directory; otherwise the file is refused `recorded_elsewhere`, its row naming the directory (`recordedUnder`) — unless the file at its own directory already holds the version, which is a restore with nothing to do (`identical`). A version that records no directory — every version an engine before this one recorded — is refused `place_unrecorded`, unless the rewind names the directory such versions were recorded under (`unplacedHistoryRecordedUnder`, an absolute path, on `TaskSpec` and `Runner.rewindFiles`): the same comparison then judges it, and a version that records its directory never reads it. A directory renamed in place only in letter case or Unicode normal form on a volume that does not tell those apart is the same directory (its real path is the recorded one folded, and no component of the recorded path is a link); a recorded directory that now resolves elsewhere through a link is not, and nothing is written through it (`link_safety`). A boundary re-reads each tracked file where it was recorded and versions it again when that place changed, so every turn this engine runs stands on versions that name their place; it HOLDS a file (keeps its last version, reads nothing) whose recorded directory no longer resolves to itself or which is a symbolic link there now; it reads the file in that recorded directory as it stands, never through the path the leg's root joined with the key spells (so a link inside the root pointed elsewhere cannot redirect the read); and it reads a file whose history records no place (an earlier engine's, an imported one) only when its path under the root, links followed, lies under the root's real path — a key that runs through a link inside the root out of it is never read and records no place (closed in this release, pre-existing: an engine ≤ 7.68.1 read such a file and stored its bytes in the history, and an export carried them; an entry such an engine already gave a place outside the root is read there — KL-4328-l, in the known limits below); a second file whose relative name another directory's file already keys is tracked under its own absolute key, and a file already tracked under its absolute key (first edited from a leg whose root did not hold it) stays that one entry when a later leg's root holds it. A run that does not accept a partial restore, and the preview, plan first — the store's own `restore` on a view of the environment that reads the disk and performs no write: the preview is that plan's projection, and the run refuses on the plan, nothing written and nothing deleted (`Runner.rewindFiles` without `dryRun`, and a run with `acceptPartialRestore`, restore file by file as before and answer the ledger). **The zero-change guarantee ends when the plan passes**: a write that fails after it is a partial restore, reported file by file with the files already written named — a file whose bytes landed stays named when the step after the write fails: a mode change that throws leaves it in the store's ledger with `modeNotPreserved` (on 7.68.1 it was reported `failed` though its content was restored), and a file the store answers `failed` after its write or delete landed is a `files` row with that `action` and `failed: { reason }` (the run's sentence names it `written` / `deleted`). A history carried into another session (a fork's carry, the deletion cascade's step 10) or exported takes only its entries under a root-relative key (`fileHistoryEntryTravels`); an export counts what it left out (`absoluteEntriesOmitted`), never naming the paths. A version's place never crosses the export door: an export leaves out every place (`fileHistoryParentIdentTravels`), the import door refuses an envelope that carries one (`unsupported_format`, in the absolute key's words), and a root-relative `parentIdent` — an older engine's form, or whatever an envelope carries — is read as no place, never joined onto a root or a named directory. So an imported version records no place, and no value an envelope this release imports becomes a path the engine reads bytes from: an imported key is read only under the root's real path (above; the gap between that check and the read is KL-4328-k, and entries an engine ≤ 7.68.1 imported and already placed outside the root are KL-4328-l, both below), and the check resolves the key's real location — a lookup that reads no bytes and answers the same either way (a carry within one store keeps its places: they were recorded on this machine). The restore result, the run's `rewind.restore_failed` detail and the preview answer `files`: one row per file, `{ path, targetPath, action, refused? }` — `path` the history key (a relative name, or an absolute key where the relative name was another directory's file's), `targetPath` the absolute path this rewind writes or deletes (on a refused row, where it would have), `refused: { class, reason, recordedUnder? }`. `reason` is for a person; a consumer branches on `class` only, and `class` is an open set. `files` absent = an engine before this one (no per-file facts — not "nothing refused"). `filesChanged` stays: the keys of the rows not refused.
|
|
7
|
+
- **More refused (narrowings, open to veto).** ① A rewind on a leg handed another root than the one the versions were recorded under: P1 parent → child, P2 child → parent, another worktree, X1 / X2, a fork handed another root, the deletion cascade on both hops — per file, nothing written; on the verb `partial` (the same-directory files restore), on a run `rewind.restore_failed` with nothing moved. ② A whole root moved or copied to another path: refused at the new path (the version records the old one). ③ Versions recorded by an earlier engine: `place_unrecorded` until the rewind names their directory; a turn this engine runs re-versions the tracked set, so a rewind to it restores. The directory is named, never read off the version: the key's own parent under it is the place, so an earlier engine's version whose parent directory was reached through a link inside the root is refused even when named (`link_safety`: the named directory's path to the file runs through the link; rare). ④ A fork's rewind to a turn carried from its source no longer restores the source's edits outside its directory: those entries are not carried, so they appear neither in the fork's preview nor in its result. ⑤ A session synced in (export, then import on another store or machine): a rewind to a turn recorded before the sync is `place_unrecorded` wherever it runs — today it writes by relative key at whatever root the rewind runs on — until the rewind names the directory those versions were recorded under (`unplacedHistoryRecordedUnder`: restored there, `recorded_elsewhere` anywhere else); the first turn after the sync records this machine's places. And an envelope an engine ≤ 7.68.1 exported carrying an absolute `parentIdent` (a parent directory that resolved outside the root through a link) is refused whole at the import door (rare; KL-4328-g). And on a lane whose root path changes from leg to leg (a remote mount rotating), the earlier legs' versions are refused (KL-4328-b). ⑥ A file a session's history records no place for (an earlier engine's version, or a synced one) whose path under the root runs through a link out of the root — a linked directory inside the repository pointing elsewhere — is no longer re-read at a boundary: no new version, and its bytes are not stored (on ≤ 7.68.1 each boundary read the outside file and stored it); edits to it from this release on get no restore point, and a rewind refuses it (`place_unrecorded`, or `link_safety` when the directory is named). A file this engine tracks first records its own place and is read there (a file the model edits through such a link records the directory the link resolves to).
|
|
8
|
+
- **Write errors closed.** Every shape in ① (the same relative path under the new root written, the rewound turn's created names deleted); the fork rewind over the source's file outside its directory (G0, above); a same-named file below the root the session never touched, written back after a leg there (K1); the write-then-discover order of a run that refuses its restore.
|
|
9
|
+
- **Widened (open to veto @server).** A session whose history held an entry under an absolute key exported an envelope the import door refused whole (`unsupported_format`, "is an ABSOLUTE key" — measured). Such a session's file history now imports without those entries (counted in `absoluteEntriesOmitted`), and the imported relative entries are written only where the rewind names the directory they were recorded under (⑤). The door's own refusal is unchanged: an envelope that carries an absolute key is refused whole (pinned). **Widened (open to veto @cli @server).** On a volume that does not tell letter case apart (the macOS default), a directory inside the root renamed only in letter case (`Sub` → `sub`), or only in Unicode normal form (NFC → NFD), since the version was recorded: 7.68.1 refused it `link_safety`, it now restores in that directory (measured on darwin, both bundled stores — the normal-form shape by the release review; the root renamed so, and a root renamed between Unicode normal forms, restored on 7.68.1 too and still do). A directory swapped for a link to another stays refused (pinned).
|
|
10
|
+
- **Not changed.** A rewind on the same directory however it is spelled (`/tmp` and `/private/tmp`, a symbolic link to it, another letter case on a case-insensitive volume, the root renamed in letter case or Unicode form only); a `cd` the model runs inside a leg (it does not change the leg's root); a file created under a new deep directory (removed) and a file whose directory was deleted since (recreated); a conversation-only rewind; two Runners on one root; a fork on its source's directory. In this release a fork that works in a tree of its own still records no file history (the coarse rule, the carry's two-root judgment and their two sentences stay; they only refuse, and leave in 7.69.0).
|
|
11
|
+
- **Known limits.** Twelve, KL-4328-a … KL-4328-l, each stated in full in the next section; none is changed by this release, and KL-4328-l reads more widely than 7.68.1 on one shape.
|
|
12
|
+
- **The 7.68.1 known defect (#4446), item by item.** *When*: every entrance it lists — `!cd` / `/cd`, entering or leaving a worktree, the session continued in another worktree, an embedder's `cwd` per leg, a fork handed another root, `adoptScope` as the deletion cascade calls it — on all three entries: closed, each file refused, nothing written or deleted. *What happens*: the same relative path under the new root written, the same-named file deleted — closed; `complete` — now `partial` on the verb, `rewind.restore_failed` on a run; the restore the person asked for still does not happen at the new root, and now says so — each refused row names the directory its version was recorded under, and a rewind from that directory restores it; the preview — now each file with the path it writes or deletes (`targetPath`) and `delete` marked; `adopt_failed`'s sentence — rewritten: a rewind to a point before the fork is refused, as a point with no boundary on the fork, or file by file as recorded elsewhere where the fork's history was filled through another channel. *Still open*: a lane handing each leg a new instance at the same path (KL-4328-a; the advice "check the preview before a rewind" still applies there), an absolute-key entry an earlier engine already carried into a fork (KL-4328-d), and versions an earlier engine recorded, refused until the rewind names their directory (③ above).
|
|
13
|
+
- **Rolling upgrade and rollback.** A version this engine records names its place as an absolute path in `parentIdent`, a member an engine ≤ 7.68.1 reads as a root-relative parent identity: such an engine refuses a rewind to a turn recorded on this release file by file (`link_safety`, its sentence "restore target's parent chain changed identity since it was recorded"), nothing written; the turns it then records are versions with no place here (`place_unrecorded` until the directory is named, ③). Measured on one file store at one root: rows this release wrote, read by the published 7.68.1 — both turns refused `link_safety`, the file untouched; 7.68.1's next turn, read back by this release — `place_unrecorded`. So workers of the two versions sharing one store, or a rollback, refuse a rewind to a turn the other version recorded; neither writes a wrong root. An export from this release carries no place, and an engine ≤ 7.68.1 imports it as an export of its own (read from code).
|
|
14
|
+
- **Rules.** −1 reading (where a version restores: the leg's root decided it; now the version's own directory), −1 reading (a root-relative `parentIdent` was joined onto the root as a parent identity; now it is no place), +1 comparison in the shared restore half (the existing link-safety check of the recorded parent is the same comparison), +1 projection (preview = plan), +2 predicates (`fileHistoryEntryTravels` read by carry and export; `fileHistoryParentIdentTravels` read by export and the import door — one rule with the absolute key's: nothing absolute crosses the door), +2 refusal classes. A file's key: its absolute key when the store already tracks it there, else its root-relative name unless another directory's file holds that name — one file, one entry, and the retraction reads the same choice from the tracked set (it replaces "the root-relative name under whichever root the leg was handed", which tracked one file under two keys after a root change). +1 judgment: a file with no recorded place is read only where its path, links followed, lies under the root (it replaces "the key joined on the leg's root is read"); one sameness of a recorded place (its real path, or the recorded spelling folded by letter case and Unicode form with no link on it) read by the restore check, the boundary re-read and the first touch's key — it replaces byte equality, no rule added; "a file whose bytes landed is named" is one reading over the mode change and the store's own failure. Retired: the bundled stores' own preview arithmetic (`diffStats` is the plan's projection). Kept until 7.69.0: the coarse fork rule and the carry's two-root judgment.
|
|
15
|
+
- **Pins.** `test/file-history-recorded-place.test.ts` — P1 / P2 / another worktree × the three entries (rows, preview = plan, nothing written), P4 × three, X2, K1, W1 / FC × three, R8, six spellings of one directory × three, D1 / D2, a root moved / copied, ATOM-symlink, the failure after the plan, O1 × three + the re-versioning turn, O3, O4, O5 (stores the released v7.68.0 wrote, `test/fixtures/file-history-v7680/`), R17, the input's door and its two statements, the capability word, R17 (synced versions refused until named; named: restored there, refused elsewhere) and R17b (the first boundary after the sync records places), a forged envelope (`id_rsa` × an absolute place / a `..` escape / a link-directory name: refused at the door or read as no place, and an env probe sees no path outside the root handed to it), a file directly under the filesystem root, a store that reads through the env's text and path members, one file one entry (absolute-key reuse, the retraction's key, a waiting touch that does not write back a stale tracked set), an imported key through a link out of the root × {link kept, link removed} and a tracked file or its directory swapped for a link (no bytes read, nothing stored, the boundary keeps the file), a mode change that throws after the write and a store that answers a landed file failed (the file named), a root / an inner directory renamed in letter case and a root renamed between Unicode forms on a case-insensitive volume (restored; a directory swapped for a link refused), a folded spelling whose directory reads as a link or cannot be read (refused), a row an older engine left through a link kept inside the root × {an edit by the model through Write, an edit by the person} × both stores, then a turn under a directory below (a rewind at the first root to that turn restores the file as it was then — a boundary that held the row at its older version wrote the older bytes back), a place a link inside the root led to × {link kept} (captured and restored) and × {the link pointed elsewhere before the boundary's read} (the read stays in the recorded directory), K1 the other way (a rewind at the first root restores the file as it was when the turn under the second root began), Write / Edit through a link inside the root × {a directory below, a sibling tree} (keyed by the real path; restored as it was then), an ordinary backslash-named directory (a POSIX name) re-read from another root, KL-4328-l as it stands × {link removed, replaced by a directory} (a known limit, not a contract). `test/file-history-carried-absolute-keys.test.ts` — G1 / G2 / G0 × three, EX. `test/file-history-same-path-new-instance.test.ts` — KL-4328-a × three (the same cells green on v7.68.0). Compliance kit (`fileHistoryStoreContract`): E4 and the track-key coordinate cell now refuse a moved root; the import round trip restores where the rewind names the directory; new cells K1, K2, W1, older versions + the input, carry, export (entries and places).
|
|
16
|
+
- **Consumers.** @server — wiring, first: **following half is the one way to write wrong: minting a second file's absolute key (`fileHistoryTrackKeyForEdit` / `fileHistoryTrackKeyForAnnul`, the W1 cell) and the carry filter (`fileHistoryEntryTravels` in `adoptScope`, the carry cell) are followed in the same release or not at all** — the first without the second has a fork's rewind write the file its source still edits, and the carry cell's failure names that combination. Hard gates on taking this release: the cells `adoptScope carries only the entries that travel…` (your `INSERT…SELECT` copies every row: filter on `key_kind = 'root-relative'` and copy only the kept keys' boundary rows), `K1 one relative name, two files…` (your boundary re-read joins the key on the leg's root: read it through `fileHistoryResolveTrackedFile(env, root, key, versions, keyDescriptor?, signal?)` — async; its `held` answer = keep the entry's last version and read nothing — and version again on `fileHistoryPlaceProvenDifferent` beside the mode rule; this signature replaces the synchronous `(root, key, versions, keyDescriptor?)` the pre-pickup notes named, so a binding wired to that form fails to compile) and `K2 a boundary reads no file through a link out of the root…` (green with the same change as K1: an imported key that runs through a link inside the root out of it, and a tracked file swapped for a link, are held and their outside bytes never read — your store reads them today, a pre-existing hole). Also a hard gate: `export carries only the entries that travel, and no version's place…` — your SQL export leaves out every `parentIdent` that `fileHistoryParentIdentTravels` answers `false` for (the places your captures record from this release on), and every absolute-key entry (`fileHistoryEntryTravels`); not following ⇒ a 7.68.2 import door refuses your envelopes whole (`unsupported_format`). Your sync entry (a client's pushed envelope → `importHistory`) refuses whole, on this release, an envelope an exporter ≤ 7.68.1 wrote with an absolute `parentIdent` (a parent directory resolved outside the root through a link; rare — KL-4328-g); a synced session's rewind to a turn before the sync is `place_unrecorded` unless your rewind entry passes `unplacedHistoryRecordedUnder` — the caller's assertion, forwarded by the host; the engine does not check it against where the imported history really came from, and a wrong one writes by relative key at the declared root (KL-4328-h). May be held back by name in your binding (`ContractAssertionRunner` receives the cell name): `W1 a second file whose root-relative name…` (never before the carry cell; not following ⇒ W1 / FC over-refuse). Green by reusing the two shared halves: the moved-root cell, the diffStats cell; the older-versions cell and the import round-trip cell need your `restore` to pass its sixth parameter (`options`) on to `applyFileRestoreViaEnv` (not passing it ⇒ older and imported versions are always `place_unrecorded`). A `files` row gains an optional `failed: { reason }` (a file whose write or delete landed and which the store then answered failed; only on a restore, never on a preview) — a reader that does not know it still sees the row's `action`. Optional: copy `recordedUnder` / `action` onto your refused rows (not copied ⇒ the directory reaches a shell only inside `reason`). The engine previews by planning your `restore` (it no longer calls your `diffStats`): your `restore` must keep writing nothing to your own tables. Not following anything ⇒ the reroot shapes, atomicity and older versions are closed on your store with zero code; K1 reads as today; W1 / FC over-refuse. The import door's code for the new refusals (a malformed `absoluteEntriesOmitted`, a version carrying a place, a non-string `parentIdent`) is `unsupported_format`. @cli @client-core: read `files`, not only `filesChanged` — a preview whose every file is refused (a rewind on a leg handed another root) answers `filesChanged: []` with zero counts, which a shell reading only those shows as "nothing to change"; show each `files` row (its `targetPath`, and `delete` as a deletion) in the rewind preview, and on a failed restore a row's `failed` as "written (or deleted), then failed"; on a refused row show `recordedUnder` ("recorded under …: rewind from that directory"); `place_unrecorded` carries no `recordedUnder` (read it as absent) and covers both versions an earlier engine recorded and versions that came with a synced session; branch on `class` only; a fork's rewind no longer lists its source's files outside its directory; gate on `file_history.recorded_place`. After a session sync, say "N files' restore points did not come with the session" from the envelope's `absoluteEntriesOmitted`. @test: black-box criteria are in the release post (the same-root forms unchanged; each reroot form refused with nothing written on all three entries; the moved root refused; the older store refused, and restored when its directory is named).
|
|
17
|
+
|
|
18
|
+
### Known limits, not changed by this release: what the first slice of the file-rewind fix (#4328) does not cover
|
|
19
|
+
|
|
20
|
+
Each limit is stated in full here. Unless an item says otherwise, its fix is the rewind's final form (#4328): a version that records the root it was recorded under.
|
|
21
|
+
|
|
22
|
+
- **KL-4328-l — entries an earlier engine imported through a link inside the root are still read outside the root after the upgrade, and on one shape more widely than on 7.68.1.** *Which sessions*: a session whose file history an engine ≤ 7.68.1 imported (a session sync) holding a key whose path under the root runs through a link inside the root to a directory outside it (`lnk/secret.txt`, `lnk` pointing elsewhere), on which that engine then ran a turn — the turn recorded the outside directory as the file's place. The engine's own write tools do not mint such an entry: they key a file by its real path, so a file the model edits through such a link is tracked under the outside file's absolute key and restores correctly (measured through the real Write and Edit tools, then a turn under a directory below or in a sibling tree, then a rewind at the first root; NotebookEdit and the tool that saves a tool result read from code). A host that calls a store's own `trackEdit` with a path through such a link does mint it, on this release too. *What happens after the upgrade*: every boundary reads that outside file and stores its bytes in the history store — as 7.68.1 did while the link stood — **and also after the link is removed or replaced by a real directory of the same name, a shape 7.68.1 does not read (it read the path under the root): this release is wider there**. A rewind to such a turn reads the outside file once more (a hash comparison) and refuses it (`recorded_elsewhere`), writing nothing; 7.68.1, with the link removed, wrote the bytes it had stored into a recreated file under the root, and with a directory in its place refused it (`link_safety`). *Why it is not closed here*: a version does not record the root it was recorded under, so the engine cannot tell "the link is gone" from "the session moved to another root"; closing it by judging the recorded path's shape made a rewind write older bytes back on such a session after a turn under a directory below, answering `complete` (measured, and withdrawn before release). *Not affected*: entries imported or recorded from this release on — an imported key through such a link is never read (the compliance kit's K2 cell); a deployment that never imported a file history on an engine ≤ 7.68.1 (and whose host never handed a store's `trackEdit` such a path) holds no such entry.
|
|
23
|
+
- **KL-4328-k — the gap between a boundary's check and its read.** A boundary checks where a tracked file really is before it reads it (an entry that records no place: under the root's real path; an entry that records one: the place still resolves to itself and the file there is no link), and then reads it; a link swapped in between the two — an ancestor directory, or the file itself — is read (reproduced with a deterministic swap). This narrows what 7.68.1 read through such a link (any history that carried such a key, unchecked) to a process rewriting the tree at the moment of the boundary. It closes when the execution environment offers a member that opens a path without following links component by component, or answers a held handle's real location, and the capture checks the handle it reads.
|
|
24
|
+
- **KL-4328-h — `unplacedHistoryRecordedUnder` is the caller's word; never fill it with the current root by default.** The engine does not check the directory named for versions that record none against where that history was really recorded. Named wrongly, those versions are written and deleted by relative key under the named directory: a host that fills it with the current leg's root by default brings the 7.68.1 defect back for them (measured: a turn recorded under one root on 7.68.1, rewound on this release under another root with that other root named — its same-named file written with the first root's bytes, answered `complete`). Pass it only when the caller knows where those versions were recorded; left out, they are refused `place_unrecorded`.
|
|
25
|
+
- **KL-4328-a — two workspace instances at one path are one place.** The place is a path, so a lane that hands each leg a new instance at the same path rewinds there as recorded (measured; what a rebuilt instance holds is the host's lane fact); the directory named for older versions is a path too.
|
|
26
|
+
- **KL-4328-b — a lane whose root path changes from leg to leg refuses the earlier legs' versions.** The place is compared as the absolute real path the leg's execution environment sees, so where the workspace path differs between instances a rewind to an earlier instance's versions is refused (read from the server's code: its container, e2b and k8s lanes use fixed workspace paths; in reach are a host lane's random temporary root, and an image or template swapped between legs that moves the workspace's real path). A host checks its lane by reading `env.canonicalPath(<workspace root>)` on two of its instances.
|
|
27
|
+
- **KL-4328-c — the same path on another machine is the same place** (not measured; as before).
|
|
28
|
+
- **KL-4328-d — an entry under an absolute key that an earlier engine already carried into a fork is still restored by the fork's rewind** (measured on a store v7.68.0 wrote).
|
|
29
|
+
- **KL-4328-e — entries under an absolute key do not travel with a session**: a fork's carry and an export leave them out (an export counts them in `absoluteEntriesOmitted`).
|
|
30
|
+
- **KL-4328-f — "nothing written when one file is refused" holds for what the plan can read.** A failure that only the write meets (a guarded write's precondition, an I/O error, a cancel) leaves a partial restore, every landed file named.
|
|
31
|
+
- **KL-4328-g — an envelope an engine ≤ 7.68.1 exported with an absolute `parentIdent` is refused whole at the import door** (`unsupported_format`; a parent directory that resolved outside the root through a link; rare).
|
|
32
|
+
- **KL-4328-i — a named directory that does not exist** refuses each file `recorded_elsewhere` (a directory deleted since is a legitimate answer, not a bad value).
|
|
33
|
+
- **KL-4328-j — two legs on two roots touching the same relative name for the first time at the same moment track it as one entry**: no wrong write (a rewind at the second root is refused), but the second file's edits have no restore point (measured at the store by the release review).
|
|
34
|
+
|
|
35
|
+
## 7.68.1 — 2026-11-13
|
|
36
|
+
|
|
37
|
+
### A tool approval an engine before 7.67.0 parked resumes when its tool names no peer — built-in, caller and host tools; an MCP tool's row is still asked again (#4424; behavior change: a v10 row that carries its tool identity without the word `raw_name_identity` is read as written when the identity recomputes from the row's own `toolName` and `contractId` for a source that names no peer; narrowing: none; widening: one, below, open to veto @server @cli @client-core; hard-breaking: none; closed sets: none; exports: none; wire: none)
|
|
38
|
+
|
|
39
|
+
- **Before.** 7.67.0 (#2726) made a parked approval's `pendingAction.capabilityId` a word member of the reader requirements, so every tool approval row an engine from 7.63.0 up to 7.66.x parked — Bash, Write, a caller tool, AskUserQuestion, Skill, a background child's, a workflow member's — was refused after the upgrade: `checkpoint.invalid_outcome` / `requirements_damaged`, "on the row but not declared: raw_name_identity". The only way on was to expire the row and run the task again.
|
|
40
|
+
- **Now.** The class table names, at the identity's entry, the reading an earlier engine gave it (a digest member, no word), and the requirement judge reads a row without the word as written exactly when the row's own content shows the two readings agree: its `capabilityId` is the identity `mintCapabilityId` mints over the row's own `toolName` and `contractId` for a source that names no peer (`builtin`, `caller`, `host`, `synthetic`). Such a tool is reached through its own definition, never under a name a server lists, so its identity holds no server name under either reading. Measured on rows the v7.66.1 engine wrote: Bash, Write (with `targets`), a caller tool, AskUserQuestion, Skill (with its grant binding), a background child and a workflow member each read `ok` and resume — the approved call runs once, the row is resolved; on v7.68.0 the same rows are refused. Measured as well on rows minted on 7.63.0, 7.64.0, 7.65.0, 7.66.0 and 7.66.1 (Bash, Write with `targets`, a caller tool, an MCP tool; the requirement table did not change between those tags): the non-MCP rows read `ok` on this engine, the MCP rows are refused.
|
|
41
|
+
- **Still refused, and why.** An MCP tool's row (whether its server's name folds, `foo.bar` → `foo_bar`, or not, `put`): an earlier engine's row of `foo.bar` holds exactly the identity this engine mints for `foo_bar`, so no content of the row says which of the two it bound. An A2A or external tool's row: its identity names a peer, and this reading admits only identities that name none. A row whose identity does not recompute from its own name and contract (a member changed), a row missing any other word, a row declaring a word it does not carry, and a row whose digest does not match its content: refused as before, the same code, reason and sentence.
|
|
42
|
+
- **Rolling upgrade and rollback.** The mint is unchanged: a row this engine parks is the row v7.68.0 parks, byte for byte (`requires` still names `raw_name_identity` on every row that carries an identity), so 7.67.x and 7.68.0 workers read this engine's rows and this engine reads theirs, as before. A 7.66.x worker still reads a row this engine parks as newer (`version_newer`).
|
|
43
|
+
- **Assumes.** Only the MCP listing hands a tool the server's name (`mcpRemoteName`, set by the MCP materializer, absent on every other tool by contract). A host that wraps an MCP server's tool as its own caller tool does not hand that member on: the caller mount rebuilds the tool from its declared members only, so 7.63.0, 7.66.1, 7.67.3, 7.68.0 and this release mint it the same caller identity, with no server name (measured). Such a tool's old row and new row both bind the name the host gave it; if the server renames the tool after the approval and the host wraps it again, the resumed call goes to the renamed tool. A v7.68.0 row does the same: this release does not introduce it.
|
|
44
|
+
- **Rules.** +1 class option (`earlier`: the reading a member had before it owed a word, with a pure predicate over the record that holds it), judged once in the generic requirement judge for every member that declares one — no word is named in the judge; +1 predicate (`identityHoldsNoServerName`); the mount's "names a peer" rule becomes one function (`rosterSourceNamesPeer`) read by the mount's admission and the predicate. Retired: none.
|
|
45
|
+
- **Pins.** `test/backlog4424-earlier-identity-reading.test.ts` over `test/fixtures/backlog4424-v7661-rows.json` (rows and whole stores the v7.66.1 engine wrote, provenance inside) — R the nine non-MCP rows read `ok` and the only word this engine's reading adds is `raw_name_identity`; M the two MCP rows refused with the same words; E the background child's and the workflow member's stores resumed for real, the call runs once; B1 / H2 / H4 the Bash, MCP and caller lanes end to end on a row rewritten to the earlier form (an MCP server swapping `foo.bar` for `foo_bar` receives nothing; a caller tool `foo_bar` beside an MCP `foo.bar` runs, the MCP row is refused); H hostile rows; S the stamp over every v7.66.1 row equals what v7.68.0 stamped; G the predicate. `test/backlog2726-mcp-raw-name-identity.test.ts` U1–U4 unchanged and green. Six mutations, each red on its cells (predicate always true ⇒ an earlier `foo.bar` approval runs `foo_bar`).
|
|
46
|
+
- **Consumers.** @server: tool approval cards a 7.152.x (core ≤ 7.66.x) worker parked for built-in, caller and host tools can be approved again after the upgrade; MCP, A2A and external tool cards still list as damaged and are expired and run again. @cli @client-core: such a card lists as an approvable card again (its `rowVerdict` is `ok`). @test: the black-box form is a Bash or caller-tool card parked on 7.66.x and decided on this engine (runs), and an MCP card on the same path (refused, nothing sent).
|
|
47
|
+
|
|
48
|
+
### Known defect, not changed by this release (#4446; present in every published version): a file rewind can write into, and delete files in, a directory its history was not recorded in
|
|
49
|
+
|
|
50
|
+
- **When.** A later leg of the same session is handed a different working root than an earlier leg — in a terminal: the user's `!cd` / `/cd`, entering or leaving a worktree, continuing the same session in another worktree of the same repository; for an embedder: a different `cwd` passed to legs of one session, a fork handed another root, or `adoptScope` called on a fork as the session-deletion cascade does — and the files are then rewound to a turn recorded under the earlier root. The three entries read the same: `Runner.rewindFiles`, `rewindFilesTo`, `resumeAt` with `restoreFiles`.
|
|
51
|
+
- **What happens.** The history keys each file relative to a root, and the restore joins it on the root of the leg that asks for the restore: a file at the same relative path under the new root is written with the old root's bytes, and where the rewound turn created a file, the file of that name under the new root is deleted. The restore the person asked for does not happen either: the files under the earlier root are left as they are. The restore answers `complete`. The preview shows file names and added / removed line counts only: no root, and nothing marks a file that will be deleted. In the fork shape, the engine's `adopt_failed` sentence ("Nothing was carried; a rewind to a point before the fork is refused …") says the opposite of what happens when the fork's history address was already filled through another channel.
|
|
52
|
+
- **Evidence.** Measured at the engine level (7.68.0, 7.67.3) and on the shipped server 7.153.0 embedding 7.67.3 (the fork shape is not reachable through that server's HTTP; it is through the engine directly); the shell's entrances are read from its code. A `cd` the model runs inside a leg does not change the leg's root (read from code).
|
|
53
|
+
- **Until it is fixed.** Do not rewind files in a session whose working directory has changed (a conversation rewind is not affected). Before a rewind, check whether the preview's file names include files you changed or created under the current directory.
|
|
54
|
+
- **The fix.** Each recorded version keeps where it was recorded, and the restore checks each file and refuses the one that does not match — in design (#4328), a precondition of the 7.69.0 release.
|
|
55
|
+
|
|
1
56
|
## 7.68.0 — 2026-11-13
|
|
2
57
|
|
|
3
58
|
### `incarnationCell(existing, tokenless?)` can give a row that holds no token an unmarked one — a host giving a token to an old row no longer has to pick between no token and one that moves the row's file-history scope to an address (#4394; additive: one optional parameter, the default is byte for byte today's; behavior change: none for any call that passes one argument; narrowing: none; widening: none; hard-breaking: none; closed sets: none on the wire (the parameter takes two words); exports: none added, none removed; wire: none)
|
|
@@ -19,6 +19,7 @@ export type FeatureWordsAreRequirementWords = AssertAllKeysHandled<Exclude<Exclu
|
|
|
19
19
|
* `ignorable` member is shown and never decided. */
|
|
20
20
|
export type RequirementClass = {
|
|
21
21
|
readonly word: RequirementWord;
|
|
22
|
+
readonly earlier?: EarlierReading;
|
|
22
23
|
} | {
|
|
23
24
|
readonly digest: "decision-read";
|
|
24
25
|
} | {
|
|
@@ -35,6 +36,15 @@ export type RequirementClass = {
|
|
|
35
36
|
export type RequirementTable = {
|
|
36
37
|
readonly [key: string]: RequirementClass;
|
|
37
38
|
};
|
|
39
|
+
/** How an earlier engine read a member that owes a word now: as a digest member, so a row it minted holds the member at the same
|
|
40
|
+
* path and in the same digest, and declares no word for it. `agrees` answers, from the record that holds the member alone, whether
|
|
41
|
+
* this engine's reading of the member gives what that earlier one gave: where it does, the absent word is the earlier mint's and the
|
|
42
|
+
* row reads as written; where it cannot show that, the absent word is damage. A pure function of the record's own members — never a
|
|
43
|
+
* deployment fact, a registry or a clock — total, and `false` whenever the record cannot show it. */
|
|
44
|
+
export interface EarlierReading {
|
|
45
|
+
readonly was: "decision-read";
|
|
46
|
+
readonly agrees: (record: object) => boolean;
|
|
47
|
+
}
|
|
38
48
|
/** A table over EVERY key of record `T` — a member left out is a compile error at the table. */
|
|
39
49
|
export type RequirementTableFor<T> = {
|
|
40
50
|
readonly [K in keyof T]-?: RequirementClass;
|
|
@@ -335,6 +345,10 @@ export declare const PENDING_ACTION_REQUIREMENTS: {
|
|
|
335
345
|
};
|
|
336
346
|
readonly capabilityId: {
|
|
337
347
|
readonly word: "raw_name_identity";
|
|
348
|
+
readonly earlier: {
|
|
349
|
+
readonly was: "decision-read";
|
|
350
|
+
readonly agrees: (pending: object) => boolean;
|
|
351
|
+
};
|
|
338
352
|
};
|
|
339
353
|
readonly contractId: {
|
|
340
354
|
readonly digest: "decision-read";
|
|
@@ -907,6 +921,10 @@ export declare const CHECKPOINT_REQUIREMENTS: {
|
|
|
907
921
|
};
|
|
908
922
|
readonly capabilityId: {
|
|
909
923
|
readonly word: "raw_name_identity";
|
|
924
|
+
readonly earlier: {
|
|
925
|
+
readonly was: "decision-read";
|
|
926
|
+
readonly agrees: (pending: object) => boolean;
|
|
927
|
+
};
|
|
910
928
|
};
|
|
911
929
|
readonly contractId: {
|
|
912
930
|
readonly digest: "decision-read";
|
|
@@ -1026,7 +1044,8 @@ export type CheckpointRequirementsVerdict = {
|
|
|
1026
1044
|
* Judge a row's requirement list and digest against this engine and against the row's content, before the claim.
|
|
1027
1045
|
* - below v10: neither the list nor the digest may be present (no release of those versions wrote one);
|
|
1028
1046
|
* - v10: the list must be an array of strings; a word this engine lacks ⇒ `lacking` (a newer row); the digest's word
|
|
1029
|
-
* must be declared (every v10 mint writes it); the words this engine knows must EQUAL the recomputed words
|
|
1047
|
+
* must be declared (every v10 mint writes it); the words this engine knows must EQUAL the recomputed words, but for a
|
|
1048
|
+
* recomputed word an earlier engine's mint left off ({@link EarlierReading}: every member carrying it agrees on its record); the
|
|
1030
1049
|
* digest must EQUAL the recomputed digest — a lost member, a lost element, a changed value is damage.
|
|
1031
1050
|
* Rows above v10 never reach it (the version ceiling refuses them first). Reads `requires` and the digest once each.
|
|
1032
1051
|
*/
|
|
@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
|
|
|
2
2
|
import { canonicalize, MAX_DEPTH, UNCANONICALIZABLE } from "./canonical-json.js";
|
|
3
3
|
import { CHECKPOINT_FEATURES, checkpointVersionOf, encodeAtFidelity } from "./checkpoint-features.js";
|
|
4
4
|
import { memberPresent } from "./own-property-receipt.js";
|
|
5
|
+
import { identityHoldsNoServerName } from "./tool-roster.js";
|
|
5
6
|
export const REQUIREMENT_WORDS = Object.freeze([
|
|
6
7
|
"resource",
|
|
7
8
|
"binding",
|
|
@@ -145,7 +146,7 @@ export const PENDING_ACTION_REQUIREMENTS = {
|
|
|
145
146
|
boundGrantDigest: { word: "skill_card_binding" },
|
|
146
147
|
boundGrants: SHOWN,
|
|
147
148
|
boundGrantAbsence: SHOWN,
|
|
148
|
-
capabilityId: { word: "raw_name_identity" },
|
|
149
|
+
capabilityId: { word: "raw_name_identity", earlier: { was: "decision-read", agrees: (pending) => identityHoldsNoServerName(pending) } },
|
|
149
150
|
contractId: DECISION_READ,
|
|
150
151
|
shapeDigest: DECISION_READ,
|
|
151
152
|
implementationRevision: DECISION_READ,
|
|
@@ -219,7 +220,7 @@ function digestedMembers(record, table, path, out) {
|
|
|
219
220
|
const value = Reflect.get(record, key);
|
|
220
221
|
const at = path === "" ? key : `${path}.${key}`;
|
|
221
222
|
if ("word" in cls)
|
|
222
|
-
out.push({ path: at, word: cls.word, value });
|
|
223
|
+
out.push({ path: at, word: cls.word, value, ...(cls.earlier !== undefined ? { earlier: { reading: cls.earlier, record } } : {}) });
|
|
223
224
|
else if ("digest" in cls)
|
|
224
225
|
out.push({ path: at, value });
|
|
225
226
|
else if ("members" in cls)
|
|
@@ -238,7 +239,11 @@ const membersOf = (cp) => {
|
|
|
238
239
|
return out;
|
|
239
240
|
};
|
|
240
241
|
export function checkpointRequirementsFor(cp) {
|
|
241
|
-
return
|
|
242
|
+
return wordsOf(membersOf(cp));
|
|
243
|
+
}
|
|
244
|
+
const wordsOf = (members) => [...new Set(members.flatMap((m) => (m.word !== undefined ? [m.word] : [])))].sort();
|
|
245
|
+
function earlierMintLeftOff(members, word) {
|
|
246
|
+
return members.every((m) => m.word !== word || (m.earlier !== undefined && m.earlier.reading.agrees(m.earlier.record)));
|
|
242
247
|
}
|
|
243
248
|
class RowNotEncodable extends Error {
|
|
244
249
|
at;
|
|
@@ -351,8 +356,9 @@ export function judgeCheckpointRequirements(cp) {
|
|
|
351
356
|
const got = digestOrUnencodable(cp);
|
|
352
357
|
return { kind: "damaged", why: "at" in got ? unencodableWhy(got.at) : "the v10 row declares no content digest" };
|
|
353
358
|
}
|
|
354
|
-
const
|
|
355
|
-
const
|
|
359
|
+
const members = membersOf(cp);
|
|
360
|
+
const carried = wordsOf(members);
|
|
361
|
+
const undeclared = carried.filter((w) => !declaredSet.has(w) && !earlierMintLeftOff(members, w));
|
|
356
362
|
const unbacked = [...declaredSet].filter((w) => !carried.includes(w)).sort();
|
|
357
363
|
if (undeclared.length > 0 || unbacked.length > 0) {
|
|
358
364
|
return {
|
|
@@ -39,7 +39,14 @@
|
|
|
39
39
|
* else, each handed to the model once, and a wake with nothing handed over ends `config.nothing_to_wake` before any model
|
|
40
40
|
* request. An engine without the word refuses the key (`config.spec_unknown_key`), so a shell that wakes a session gates
|
|
41
41
|
* on the word.
|
|
42
|
+
* - `file_history.recorded_place` — a file version records the directory it was recorded under (its absolute real path) and a
|
|
43
|
+
* rewind (`Runner.rewindFiles`, `rewindFilesTo`, `resumeAt` + `restoreFiles`) writes or deletes it only there: a version
|
|
44
|
+
* recorded under another directory is refused per file (`recorded_elsewhere`, with `recordedUnder`), one that records none
|
|
45
|
+
* (`place_unrecorded`) unless the rewind names where such versions were recorded (`unplacedHistoryRecordedUnder`, which an
|
|
46
|
+
* engine without the word refuses as an unknown key); a run that does not accept a partial restore moves nothing when any
|
|
47
|
+
* file would be refused (the restore is planned first); and the preview and the restore answer `files`, one row per file. A
|
|
48
|
+
* shell gates on the word, not on a version number.
|
|
42
49
|
*/
|
|
43
|
-
export declare const ENGINE_CAPABILITIES: readonly ["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake"];
|
|
50
|
+
export declare const ENGINE_CAPABILITIES: readonly ["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake", "file_history.recorded_place"];
|
|
44
51
|
/** One word of {@link ENGINE_CAPABILITIES}. */
|
|
45
52
|
export type EngineCapability = (typeof ENGINE_CAPABILITIES)[number];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
export const ENGINE_CAPABILITIES = Object.freeze(["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake"]);
|
|
1
|
+
export const ENGINE_CAPABILITIES = Object.freeze(["inherit_env.own_credentials_withheld", "inherit_env.own_credential_values_withheld", "mods.skill_seat", "user_attachments.read_state", "task.wake", "file_history.recorded_place"]);
|