@zhivex-ai/harness 1.3.0 → 1.4.0-rc.6

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.
Files changed (73) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +30 -8
  3. package/SECURITY.md +1 -1
  4. package/SUPPORT.md +2 -2
  5. package/contracts/engine-api.json +70 -0
  6. package/contracts/public-api.json +162 -0
  7. package/contracts/stable-api-signatures.json +9 -9
  8. package/dist/acp-cli.js +38 -12
  9. package/dist/cli/arguments.d.ts +5 -1
  10. package/dist/cli/memory.d.ts +2 -0
  11. package/dist/{cli-entry-bx3vjw7h.js → cli-entry-4k1cf0m3.js} +38 -12
  12. package/dist/{cli-entry-1gfg3brj.js → cli-entry-9c2k0zwz.js} +1086 -446
  13. package/dist/{cli-etsmtst3.js → cli-s1rs15vv.js} +136 -24
  14. package/dist/cli.js +2 -2
  15. package/dist/client/check-evidence.d.ts +17 -0
  16. package/dist/client/run-document.d.ts +12 -0
  17. package/dist/compat/cli-options.d.ts +12 -1
  18. package/dist/compat/code-support.d.ts +4 -0
  19. package/dist/compat/code-support.js +12 -4
  20. package/dist/context/compaction.d.ts +5 -0
  21. package/dist/context/project-memory-context.d.ts +6 -0
  22. package/dist/context/task-memory.d.ts +33 -1
  23. package/dist/engine/acp.js +8 -8
  24. package/dist/engine/client.js +7 -7
  25. package/dist/engine/desktop-state-v1.js +5 -5
  26. package/dist/engine/index.d.ts +4 -0
  27. package/dist/engine/index.js +88 -11
  28. package/dist/engine/mcp-stdio-v1.js +4 -4
  29. package/dist/engine/service.js +8 -8
  30. package/dist/hostile-repository-demo.js +1260 -712
  31. package/dist/{index-azmwjp95.js → index-0g939pfs.js} +13 -12
  32. package/dist/{index-6m08wvab.js → index-2tgb2b4e.js} +3 -3
  33. package/dist/{index-w2sj0wkw.js → index-49ys3s4q.js} +64 -14
  34. package/dist/{index-hnaxfpb5.js → index-4j1h4j8c.js} +137 -42
  35. package/dist/{index-8zzhggxv.js → index-a1q355va.js} +125 -2
  36. package/dist/{index-8vm2m34s.js → index-dj5z774k.js} +18 -2
  37. package/dist/{index-z0qxmkm2.js → index-e6r04a18.js} +1 -1
  38. package/dist/{index-yb239ghk.js → index-r0tdj04h.js} +21 -6
  39. package/dist/{index-h0mqx2ed.js → index-rd0s3gqj.js} +300 -4
  40. package/dist/{index-42gp2hy8.js → index-vtqfjnab.js} +98 -27
  41. package/dist/{index-2jrdcj6b.js → index-wq2tax80.js} +15 -1
  42. package/dist/{index-a97bezbz.js → index-z6br6qdn.js} +44 -23
  43. package/dist/index.js +11 -11
  44. package/dist/persistence/project-memory-command.d.ts +11 -0
  45. package/dist/persistence/project-memory.d.ts +109 -0
  46. package/dist/persistence/sdk-store-identity.d.ts +4 -0
  47. package/dist/persistence/sessions.d.ts +4 -0
  48. package/dist/runtime/error-diagnostics.d.ts +35 -0
  49. package/dist/runtime/harness.d.ts +5 -1
  50. package/dist/runtime/run-interruption.d.ts +1 -1
  51. package/dist/runtime/runtime-checkpoints.d.ts +3 -0
  52. package/dist/runtime/task-acceptance-native.d.ts +10 -0
  53. package/dist/runtime/time-to-safe-fix.d.ts +35 -0
  54. package/dist/service-cli.js +8 -8
  55. package/dist/{service-client-cli-3365rfav.js → service-client-cli-b52c67hx.js} +2 -2
  56. package/dist/verify-historical-migrations.js +1021 -456
  57. package/dist/zhx.js +2 -2
  58. package/docs/CLI.md +4 -0
  59. package/docs/CLIENT_PROTOCOL.md +10 -0
  60. package/docs/CODE_RELEASE.md +136 -19
  61. package/docs/CONTEXT_ENGINEERING.md +25 -0
  62. package/docs/DURABLE_OPERATIONS.md +60 -1
  63. package/docs/ENGINE_API.md +23 -9
  64. package/docs/EXTENSIBILITY.md +1 -1
  65. package/docs/FIRST_USE.md +6 -6
  66. package/docs/LOCAL_SERVICE.md +10 -4
  67. package/docs/PROJECT_MEMORY.md +157 -0
  68. package/docs/README.md +2 -0
  69. package/docs/STABILITY.md +1 -1
  70. package/docs/WORKSPACE_CHECKPOINTS.md +11 -1
  71. package/evaluations/representative-assembly-matrix.json +55 -1
  72. package/examples/README.md +4 -4
  73. package/package.json +12 -11
package/dist/zhx.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  HARNESS_VERSION,
4
4
  shortCliHelp
5
- } from "./cli-entry-bx3vjw7h.js";
5
+ } from "./cli-entry-4k1cf0m3.js";
6
6
  import {
7
7
  __require
8
8
  } from "./cli-entry-1bx83sw4.js";
@@ -16,6 +16,6 @@ if (argv.length === 1 && ["--version", "-v", "version"].includes(argv[0])) {
16
16
  process.stdout.write(`${shortCliHelp(HARNESS_VERSION)}
17
17
  `);
18
18
  } else {
19
- const { runCli } = await import("./cli-etsmtst3.js");
19
+ const { runCli } = await import("./cli-s1rs15vv.js");
20
20
  await runCli(argv);
21
21
  }
package/docs/CLI.md CHANGED
@@ -795,3 +795,7 @@ An envelope link matches the recorded patch identifier; envelope integrity and
795
795
  expiry are checked separately. Patch bytes and producer authenticity remain
796
796
  unverified. No envelope v1 fields are added. Concurrent source changes and hard
797
797
  capacity limits reject export; bounded tree/history truncation is reported.
798
+
799
+ ## Experimental project memory (unreleased)
800
+
801
+ `zhx memory` supports `remember`, `list`, `read`, `update`, `forget`, `suggest`, `accept`, `context`, `clear`, `enable` and `disable`. Content is one quoted argument. Updates, acceptance and forgetting require the current revision. `--source` supplies a provenance label; `--no-memory` disables curated retrieval and SDK memory loading/capture for a local run/chat/resume invocation. Existing workspace/tenant/user/namespace flags select scope. See [Project memory](PROJECT_MEMORY.md) for bounds, review, deletion semantics and next-release pairing.
@@ -255,3 +255,13 @@ a tool. Rule paths and host filesystem locations are omitted.
255
255
  While a host-prepared runtime is active, the query reflects that runtime. Before
256
256
  preparation and after release it reflects the base host; decision events retain
257
257
  the digest and backend of the runtime that evaluated them.
258
+
259
+ ## Recorded check evidence
260
+
261
+ Beta run-result JSON adds `verification`: numeric exit codes, timeout and pass
262
+ flags for known check tools, with counts and `coverage: "recorded-checks-only"`.
263
+ It omits command argv, repository output and arbitrary tool payloads.
264
+ `taskVerified: false` distinguishes this observation from contractual task success
265
+ or human acceptance. Existing status/exit-code and schema-version contracts remain
266
+ unchanged. Code inspection/export derives the same safe projection from completed
267
+ tool-journal entries; the engine inspection API signature is unchanged.
@@ -1,47 +1,164 @@
1
1
  # Code release procedure
2
2
 
3
- Code is released independently of Harness. The prepared stable release is
3
+ ## Current RC preparation: 2026-10-05
4
+
5
+ This checkout prepares Code `0.3.0-rc.6`, pinned exactly to Harness
6
+ `1.4.0-rc.6`, for npm `next`. The matched engine includes the reviewed bounded
7
+ activity projection fix from [PR185](https://github.com/Zhivex/zhivex-harness/pull/185).
8
+ Retain terminal/local browser contracts, existing SDK/model pins, approval and
9
+ transport protections, provider/API tiers and RC.4 migration requirements.
10
+ Desktop stays private alpha with the same engine binding. Stable Code `0.2.0`
11
+ and Harness `1.3.0` on `latest`, and published Code `0.3.0-rc.1` and Harness
12
+ `1.4.0-rc.1` on `next`, remain unchanged.
13
+
14
+ Harness [RC.5 attempt 1](https://github.com/Zhivex/zhivex-harness/actions/runs/37384044231)
15
+ passed offline/live and 42/42 representative gates but remains held at npm review.
16
+ Its immutable tag/source does not contain PR185; neither RC.5 package was published
17
+ and no Code RC.5 tag/release was started. Do not approve, cancel, alter or relaunch
18
+ the held campaign as part of this preparation. See the authoritative
19
+ [Harness release procedure](https://github.com/Zhivex/zhivex-harness/blob/main/docs/RELEASE.md)
20
+ for exact immutable identities and preserved RC.4 failure history. The RC.5 and
21
+ older preparation snapshots below remain historical; their passing evidence and
22
+ approvals do not certify or authorize RC.6.
23
+
24
+ This preparation creates no tags, paid calls, campaign dispatch or publication.
25
+ After review and user integration, require all four successful exact-main workflows
26
+ (`ci.yml`, `codeql.yml`, `code-journey.yml`, `web.yml`) and direct-main CodeQL.
27
+ New explicit campaign/publication authority is required before any Harness
28
+ `v1.4.0-rc.6` or Code `code-v0.3.0-rc.6` tag/dispatch. Harness must first pass its
29
+ unchanged protected exact-artifact, OCI, live and representative gates and actual
30
+ registry integrity/provenance verification. Code's protected OIDC workflow then
31
+ uses the matching reviewed SHA with `channel=next`, `mode=oidc` and explicit
32
+ confirmation, resolving the actual published Harness dependency without overrides.
33
+ Retained-artifact terminal/web, four-manager acceptance and registry bytes with
34
+ source-bound provenance remain mandatory. Preserve stable `latest` and all history.
35
+
36
+ ## Historical RC.5 preparation: 2026-10-05
37
+
38
+ This checkout prepares Code `0.3.0-rc.5`, pinned exactly to Harness
39
+ `1.4.0-rc.5`, for npm `next`. Retain the published SDK pins, existing terminal
40
+ and local browser contracts, API/provider tiers and the RC.4 migration
41
+ requirements. Desktop remains private alpha with its matched engine binding.
42
+ Stable Code `0.2.0`/Harness `1.3.0` on `latest` and published Code
43
+ `0.3.0-rc.1`/Harness `1.4.0-rc.1` on `next` remain unchanged.
44
+
45
+ Harness RC.4 [attempt 1](https://github.com/Zhivex/zhivex-harness/actions/runs/37360365544)
46
+ failed offline before retaining a release tarball or running paid/provider gates.
47
+ Its annotated tag, original source and failed evidence are immutable; the
48
+ approved single campaign was consumed. RC.5 includes the reviewed test
49
+ correction on new source. See the authoritative [Harness release procedure](https://github.com/Zhivex/zhivex-harness/blob/main/docs/RELEASE.md)
50
+ for that failure identity, exact-source gates and the new campaign approval.
51
+ The RC.4 preparation snapshot below is historical.
52
+
53
+ Preparation approval does not create tags, dispatch a campaign or publish either
54
+ package. After review and integration, require all four exact-main workflows
55
+ (`ci.yml`, `codeql.yml`, `code-journey.yml`, `web.yml`) and direct-main CodeQL.
56
+ A separately approved Harness `v1.4.0-rc.5` campaign must pass unchanged protected
57
+ gates and actual registry integrity/provenance verification first. Code then
58
+ uses a new annotated `code-v0.3.0-rc.5` tag on the same SHA, `channel=next`,
59
+ `mode=oidc` and explicit publication confirmation. Its protected workflow must
60
+ resolve the real published Harness dependency without overrides, verify the
61
+ retained artifact with terminal/web and four-manager acceptance, and confirm
62
+ registry bytes and source-bound provenance. Preserve stable `latest` and all
63
+ historical tags/artifacts; earlier approval does not authorize this publication.
64
+
65
+ ## Historical RC.4 preparation: 2026-10-05
66
+
67
+ This checkout prepares Harness `1.4.0-rc.4` and Code `0.3.0-rc.4`, both on
68
+ `next`, with Code pinned exactly to the Harness candidate. npm currently reports
69
+ Harness `1.3.0` and Code `0.2.0` on `latest`; those stable tags must not move.
70
+ Harness `1.4.0-rc.1` and Code `0.3.0-rc.1` are already published on `next`
71
+ from `9a1b1d25296567262438178d25cccfc474643aeb`; preserve those immutable
72
+ versions and annotated tags. RC.2 and RC.3 remain unpublished; preserve their tags,
73
+ retained artifacts and failed attempts at their original source commits.
74
+ [RC.3 attempt 1](https://github.com/Zhivex/zhivex-harness/actions/runs/37244691105)
75
+ failed Meta multi-process continuity at phase 2; the other five providers and all
76
+ mixed routes passed. The immediate JSON evaluation failure has an unknown upstream
77
+ cause because the original stream was not retained. Meta 0.2.9 fixes reasoning
78
+ usage reporting; it does not establish or resolve that historical cause.
79
+ RC.4 integrates the published SDK batch and bounded continuity evidence, retaining
80
+ the same model pins, ceilings, acceptance checks and certification gates. RC.4
81
+ requires its own exact artifact and source-bound certification. Both matched RC.4
82
+ candidates remain unpublished; no live calls were made during preparation.
83
+ Review and integrate the preparation PR, then
84
+ require the latest successful `ci.yml`, `codeql.yml`, `code-journey.yml` and
85
+ `web.yml` main-push runs for the exact release SHA, including the separate CodeQL
86
+ security result. Run Harness's existing preparation and protected release workflow
87
+ for annotated `v1.4.0-rc.4` with `channel=next`. Its exact-artifact, OCI, live and
88
+ representative gates remain mandatory. Paid certification requires separate
89
+ campaign approval. After Harness registry integrity and provenance verification,
90
+ run Code's protected OIDC workflow at annotated `code-v0.3.0-rc.4` on the same SHA,
91
+ with `channel=next`, `mode=oidc` and publication confirmation. Code must resolve
92
+ the real published engine without overrides and pass retained-artifact terminal
93
+ and web acceptance, four-manager checks and provenance verification. Keep stable
94
+ `latest` unchanged. The older publication records below are historical.
95
+
96
+
97
+ ## Historical stable publication on 2026-10-02
98
+
99
+ Code is released independently of Harness. The recorded October 2 stable release is
4
100
  `@zhivex-ai/code@0.1.0`, with the sole binary `zhivex-code`, npm tag `latest`,
5
- and the exact dependency `@zhivex-ai/harness@1.3.0`. Harness must first be
6
- published and verified through its protected release workflow. Code RC2 is
7
- already published on `next` and RC1 is still on `latest`; trusted
8
- publishing succeeded in [run 36902929707](https://github.com/Zhivex/zhivex-harness/actions/runs/36902929707).
9
- The stable release uses that existing OIDC path; no new credentials or publisher
10
- configuration are part of preparation. This document records preparation, not
11
- successful stable publication.
12
-
13
- ## Release preparation
101
+ and the exact dependency `@zhivex-ai/harness@1.3.0`. Harness was published and
102
+ verified first in [run 37031040747](https://github.com/Zhivex/zhivex-harness/actions/runs/37031040747). Code passed real registry
103
+ resolution, four-manager installed acceptance and source-bound provenance in
104
+ [run 37036369187](https://github.com/Zhivex/zhivex-harness/actions/runs/37036369187) at `aa86de8d700f893253559b00c1f7191e7dab48b9`.
105
+ Attempt 1 accepted publication but failed while registry metadata still reported
106
+ the version absent. Attempt 2 recovered only the failed publish job using the
107
+ retained artifact; identical bytes skipped npm publication and verification passed.
108
+ At that publication, Code `0.1.0-rc.2` remained on `next`; `0.1.0-rc.1` was historical. The existing OIDC publisher and
109
+ protected environment were preserved. See [publication evidence](https://github.com/Zhivex/zhivex-harness/blob/main/docs/reports/evidence/stable-publication-2026-10-02.json).
110
+
111
+ ## Historical Code 0.2.0 preparation
112
+
113
+ That preparation used `@zhivex-ai/code@0.2.0` with the same exact published
114
+ Harness `1.3.0` dependency. Code `0.1.0` was the verified npm `latest` release
115
+ until the separately approved `0.2.0` publication. That candidate added guided
116
+ approval diffs, reviewed checkpoints, per-run estimated budgets and the offline
117
+ first-use tutorial. See the [candidate changelog](https://github.com/Zhivex/zhivex-harness/blob/main/packages/code/CHANGELOG.md)
118
+ and [release readiness](https://github.com/Zhivex/zhivex-harness/blob/main/docs/reports/CODE_0_2_0_READINESS_2026-10-03.md).
119
+
120
+ That was a Code-only release: no Harness version change or new paid six-provider
121
+ certification campaign is required. Engine API tiers and provisional provider
122
+ support remain unchanged; estimated budgets are not guaranteed financial caps.
123
+
124
+ ## Historical Code 0.2.0 release procedure
14
125
 
15
126
  1. Merge the Code release PR after required review and successful checks.
16
- 2. Wait for the latest `ci.yml` and `codeql.yml` **push runs on main** to succeed
127
+ 2. Wait for the latest `ci.yml`, `codeql.yml` and `code-journey.yml` **push runs on main** to succeed
17
128
  for the exact commit. Keep the Code manifest, version and engine pin unchanged
18
129
  after selecting that commit.
19
130
  3. Wait for Harness `1.3.0` publication and successful registry/provenance
20
131
  verification as ordered in [the Harness release procedure](https://github.com/Zhivex/zhivex-harness/blob/main/docs/RELEASE.md).
21
132
  From a clean checkout of that main commit, create an annotated
22
- `code-v0.1.0` tag and push it. Never move or overwrite release tags.
133
+ `code-v0.2.0` tag and push it. Never move or overwrite release tags.
23
134
  4. Dispatch `release-code.yml` **at that tag**, with input `tag` matching it and
24
135
  `channel=latest`, `mode=oidc`, and `confirm_publication=true`. Dispatching
25
136
  main while supplying a different tag is rejected.
26
137
 
27
138
  ```sh
28
- gh workflow run release-code.yml --ref code-v0.1.0 \
29
- -f tag=code-v0.1.0 -f channel=latest -f mode=oidc -f confirm_publication=true
139
+ gh workflow run release-code.yml --ref code-v0.2.0 \
140
+ -f tag=code-v0.2.0 -f channel=latest -f mode=oidc -f confirm_publication=true
30
141
  ```
31
142
 
32
- The workflow validates tag identity, main ancestry, exact CI/CodeQL, Code source
143
+ The workflow validates tag identity, main ancestry, exact CI/CodeQL/installed journeys, Code source
33
144
  and package boundaries. It downloads the pinned Harness version from npm and
34
145
  verifies its integrity and SLSA artifact/workflow/tag/source binding; missing
35
146
  publication or provenance stops the release.
36
- It builds Code once, inspects package contents, installs it against the actual
147
+ It builds Code once, admits only metadata, flat built JavaScript and the two
148
+ named tutorial modules, and installs it against the actual
37
149
  registry dependency without overrides, and tests the retained Code and Harness
38
150
  artifacts with npm, pnpm, Yarn and Bun. The paired matrix uses explicit engine
39
151
  artifact overrides; the separate standalone installation proves npm resolution.
40
- This does not claim every future engine version or installation order is certified.
152
+ The retained Code tarball also passes offline installed PTY journeys without
153
+ repacking. The separate `code-journey.yml` workflow runs on every PR and main
154
+ push on Linux/macOS with Node 22.13.0/24, retaining the tested tarball, digest,
155
+ report and transcript. Removing path filters ensures each selected main SHA can
156
+ produce its own journey evidence. This does not claim every future engine
157
+ version or installation order is certified.
41
158
 
42
159
  The workflow generates genuine npm/Sigstore provenance using pinned npm 11.6.1
43
160
  inside the GitHub-hosted build job. It retains `code.tgz`, `code.sigstore.json`,
44
- `SHA512SUMS`, and installed acceptance in `code-release-<full-source-sha>`.
161
+ `SHA512SUMS`, installed acceptance, and the offline PTY report/transcript in `code-release-<full-source-sha>`.
45
162
  Bootstrap mode **does not publish**. No npm token is copied into GitHub.
46
163
 
47
164
  ## Historical first publication / future package bootstrap
@@ -64,7 +181,7 @@ commit SHA. Install npm 11.6.1 into an isolated tools directory and set
64
181
  ```sh
65
182
  (cd release-code-artifacts && shasum -a 512 -c SHA512SUMS)
66
183
  bun run scripts/code-release.ts inspect release-code-artifacts/code.tgz
67
- CODE_EXPECTED_SHA="$(git rev-list -n 1 code-v0.1.0)" \
184
+ CODE_EXPECTED_SHA="$(git rev-list -n 1 code-v0.2.0)" \
68
185
  node scripts/code-bootstrap-provenance.cjs verify \
69
186
  release-code-artifacts/code.tgz release-code-artifacts/code.sigstore.json
70
187
  node "$CODE_PROVENANCE_NPM_ROOT/bin/npm-cli.js" publish \
@@ -226,6 +226,29 @@ operator sources separately. The CLI persists them in session/run metadata.
226
226
  Library callers using `compactHarnessMessages` should pass its returned array
227
227
  directly into `runHarness`; if serializing it separately, also retain the original
228
228
  `zhivexTaskSources` metadata. A summary alone cannot reconstruct full requests.
229
+ The first terminal checkpoint retains generated assistant text before a client
230
+ can manually compact the displayed report. Local client session continuations
231
+ also retain the three most recent redacted assistant text responses in `zhivexAssistantResponses`, separately from operator
232
+ requests and acceptance records. Each response is limited to 64000 characters;
233
+ truncation is explicit. This lets a user refer to a late heading in a long report
234
+ without enlarging every provider prompt. Harness and Code consoles carry only
235
+ this bounded context within the selected session, including after `/compact`
236
+ and restart; `/clear` resets it. Manual in-process compaction preserves the
237
+ association through copied message arrays. If serializing compacted messages,
238
+ also retain `zhivexAssistantResponses` from the saved checkpoint.
239
+ `read_task` with
240
+ `source: "assistant_response"` and an optional case-sensitive literal `query`
241
+ reads the newest matching retained response in pages of at most 4000 characters.
242
+ An explicit `id` selects a retained response and `offset` selects a page. Missing,
243
+ evicted or corrupt sources fail explicitly. Retrieval uses current run metadata
244
+ only; it cannot query another session or project. Continuations inherit only this
245
+ bounded context from a previous run already validated against the same session
246
+ and scope. Callers creating runs directly must retain that metadata if passing
247
+ only compacted messages. Recovered assistant text is always marked untrusted and
248
+ unverified. It cannot authorize tools, change operator requirements, supply
249
+ acceptance evidence or replace exact-diff approval. Actual tool policy, approvals,
250
+ budgets and current source verification still apply.
251
+
229
252
  `repair_plan` records the hypothesis, expected behavior, up to eight known paths,
230
253
  and the next check in the durable tool journal. Its optional `verifier` records
231
254
  exact `command`, `args` and a bounded `purpose`. Neither tool creates approval
@@ -426,3 +449,5 @@ that `endLine` is an absolute line number, not a count. The runtime does not
426
449
  execute, rename or silently repair malformed calls. Durable error receipts stay
427
450
  unchanged; the model must issue a corrected request, and edits still require
428
451
  current read evidence and approval.
452
+
453
+ Project memory is a separate kind of explicit operator context in the existing durable memory table. It is projected per request as untrusted data, with revision-based review and hard byte/entry budgets. It does not become project instructions or skills. See [Project memory](PROJECT_MEMORY.md).
@@ -70,7 +70,64 @@ Loading a run reconstructs its complete state for compatibility with approvals,
70
70
 
71
71
  Logical backups contain hydrated history rather than database references, so restoration does not require the original artifact tables. Exports up to 64 MiB retain the legacy JSON format; larger exports use the versioned `ZHIVEX-STATE-SEGMENTS-1` transport with bounded frames, including split strings. RC13 reads both formats and verifies the same logical checksum before import. Older versions cannot read segmented exports. File I/O and checksum serialization are incremental; the public backup/import APIs still hydrate the complete logical bundle in memory. Segmented files have no aggregate 64 MiB ceiling. A state-limit failure records a bounded terminal diagnostic on the last durable checkpoint; the unsaved payload is not claimed as preserved. Use `/status` to inspect the failed run before `/continue`. Recovery retains tool journal receipts and never re-executes an operation itself.
72
72
 
73
- Incremental SQLite history uses the published Core 1.26.0 and Agents 1.10.1 packages. No local dependency patch is required. Install this checkout with `bun install --frozen-lockfile`.
73
+ The current candidate pins Core 1.30.1 and Agents 1.10.3. New stores require no
74
+ conversion. Before upgrading an existing shared SDK store, stop its workers and
75
+ upgrade them together with a complete backup. Verified legacy runs retain their
76
+ physical keys and remain readable; new runs use canonical keys that distinguish
77
+ omitted user/namespace fields from literal `*`/`default` values. Older workers
78
+ cannot resolve new keys. Conflicting run identities or journal entries without
79
+ verifiable ownership require offline reconciliation before executing tools.
80
+
81
+ Memory migration is conditional: it applies to legacy **SDK agent-memory arrays**
82
+ without a canonical identity envelope in `zhivex_agent_memory` (or the file-store
83
+ memory directory). It does not apply to CLI session-index rows, run history,
84
+ curated project memory, empty stores or already canonical SDK memory. The CLI
85
+ already enabled curated project memory by default in RC.1. Normal RC.1 CLI
86
+ sessions therefore do not require SDK-memory conversion solely because they are
87
+ older. Programmatic callers that omitted `projectMemory` used the historical SDK
88
+ memory integration and may have affected records. Explicit custom memory keys
89
+ retain their application-owned format. Harness ignores SDK memory-hook failures,
90
+ so an affected record supplies no captured SDK context and cannot be updated
91
+ until migrated; its bytes are not deleted. Session history remains separate.
92
+
93
+ For the default SQLite store, use the original pre-upgrade binary to create a
94
+ provider-free logical backup after runs are terminal and approvals resolved:
95
+
96
+ ```bash
97
+ zhx state export /absolute/private/pre-upgrade.json --workspace /absolute/workspace
98
+ # Only after every worker sharing this directory has stopped:
99
+ cp -Rp /absolute/state-directory /absolute/private/pre-upgrade-state
100
+ ```
101
+
102
+ Repeat the actual `--state-dir`, `--tenant`, `--user` and `--namespace` options when
103
+ customized; do not invent a new scope. The default state directory is
104
+ `<workspace>/.zhivex-harness`; use its real path in the copy command and a private
105
+ destination outside it. Export rejects active runs, leases and pending approval
106
+ authority. A scoped logical export does not replace the complete stopped store
107
+ backup needed for migration. Retain the complete stopped state directory as well,
108
+ including SQLite WAL/SHM files or all file-store journals/indices/history, and
109
+ the original executable. `state export` supports SQLite; it is not a file-store
110
+ backup command. Paused approval resume remains bound to its original artifact.
111
+
112
+ There is **no Harness CLI command that converts legacy SDK memory**. State
113
+ export/import preserves those rows and does not establish their owner. The
114
+ [supported SDK procedure](https://github.com/Zhivex/zhivex-ai-sdk/blob/4a93004395a80c183b1257bb1d02fb3a3d4050e1/docs/maintainers/AGENT_STORE_MIGRATION.md)
115
+ uses `createSqliteAgentMemoryStore` or `createFileAgentMemoryStore` from
116
+ `@zhivex-ai/core/ops`: establish each owner from trusted application records,
117
+ read the exact source key with `key: () => verifiedLegacyKey`, and save under the
118
+ verified `runId`, `agentId` and `scope` into a new table/directory using the default
119
+ key and `selectMessages: state => state.messages`. Reload and compare the full
120
+ message array, verify other scopes cannot read it, then configure callers to use
121
+ the new store. Keep ambiguous records quarantined; never infer ownership from a
122
+ legacy key or edit run scope to bypass validation.
123
+
124
+ Logical backups preserve canonical run, journal, idempotency and SDK memory
125
+ identities alongside verified legacy rows. Canonical SDK memory keys bind
126
+ restoration to the SDK identity envelope; import validates each key against the
127
+ bound scope and retained run/agent identity.
128
+ The backup schema version remains 1, and legacy bundles remain readable. Restore
129
+ new candidate backups with this candidate or newer compatible readers; keep a
130
+ complete pre-upgrade backup and the original artifact for downgrade.
74
131
 
75
132
  ## Provider handoff safety
76
133
 
@@ -218,3 +275,5 @@ To disable cumulative token ceilings explicitly, use `--no-token-budget` (librar
218
275
  through resume. Token accounting and compaction continue; cost, time, steps, tools,
219
276
  approvals, and provider per-request limits remain enforced. Stored numeric token
220
277
  ceilings are inactive until `unlimitedTokens` is set back to `false`.
278
+
279
+ Next-version [project memory](PROJECT_MEMORY.md) reuses the existing SDK memory table and state export records. Historical state is not harvested into curated memory. Forget/clear remove current memory content, while backups, run histories and SQLite WAL retention remain separate. Older importers reject the new reserved memory key safely.
@@ -1,9 +1,9 @@
1
1
  # Engine API and Code integration
2
2
 
3
3
  This checkout adds terminal-independent package entrypoints for
4
- Harness 1.3.0 (prepared for `latest`). They are not present in the previously published Harness 1.2.0.
5
- Stable publication is pending the protected workflow; use the documented
6
- local candidate smoke to validate these bytes. Do not install registry 1.2.0 and
4
+ Harness 1.3.0 (published and verified on `latest`). They are not present in the previously published Harness 1.2.0.
5
+ The protected workflow validated the exact stable tarball, live gates and
6
+ registry integrity/provenance; local candidate smoke remains contributor evidence. Do not install registry 1.2.0 and
7
7
  expect the new entrypoints to exist.
8
8
 
9
9
  ## Entry points
@@ -68,9 +68,9 @@ switching presentation does not migrate state or authorize new effects.
68
68
  ## Terminal product
69
69
 
70
70
  `packages/code` is the independently built terminal product. Its current version
71
- is `0.1.0`, prepared for independent publication to `latest` with the exact
72
- engine dependency `@zhivex-ai/harness@1.3.0`. Publication remains gated by
73
- reviewed main, CI and registry evidence in the [Code release procedure](CODE_RELEASE.md).
71
+ is `0.1.0`, independently published and verified on `latest` with the exact
72
+ engine dependency `@zhivex-ai/harness@1.3.0`. Reviewed main, CI and registry
73
+ evidence are recorded in the [Code release procedure](CODE_RELEASE.md).
74
74
  Code imports declared package APIs, never Harness source paths. Its build leaves
75
75
  Harness external.
76
76
 
@@ -115,7 +115,7 @@ The new subpaths were introduced after RC3 and are published in RC7. Stable
115
115
  1.3.0 retains their declared tiers.
116
116
  Desktop migration and packaged acceptance are documented in
117
117
  the repository-only report `docs/reports/HAR_HU_39_2026-09-29.md`. Its dependency is pinned to the
118
- exact prepared engine version and checked for required contracts/artifact identity; this does
118
+ exact engine version and checked for required contracts/artifact identity; this does
119
119
  not claim compatibility with the earlier published RC3 bytes or a broader range.
120
120
 
121
121
  ```sh
@@ -270,12 +270,22 @@ or changing the snapshot invalidates verification. Recovery reconciles check
270
270
  receipts against the durable tool journal; ambiguous or interrupted effects are
271
271
  not replayed automatically.
272
272
 
273
+ For native execution, acceptance limits reviewed edit tools to the declared exact
274
+ write paths and `run_check` to the declared package scripts. Other effect tools
275
+ and delegation are unsupported for native task contracts. Host-observed receipts
276
+ bind selected/protected file digests and `package.json` before/after each check;
277
+ subsequent changes invalidate them. Native scripts run on the host: this is not
278
+ an OCI sandbox, a complete repository snapshot, or an isolated import transaction.
279
+ The experimental Code helpers `resolvePackageCheckCommand`, `nativeTaskSnapshot`,
280
+ `TASK_ACCEPTANCE_EVIDENCE_KEY` and `checkEvidence` support this bounded host workflow.
281
+
273
282
  The host-owned `zhivexTaskAcceptanceEvidenceV1` metadata adds acceptance outcomes
274
283
  without changing SDK run statuses or `ChangeEnvelope` v1. Active work is `pending`;
275
284
  terminal work without sufficient delivery evidence is `incomplete`; failed runs
276
285
  or scope violations are `failed`. A completed run with a normal stop becomes
277
- `verified` only after a confirmed import and a final inspection of delivered host
278
- files and snapshot bytes. Required human review produces `pending_review` instead.
286
+ `verified` only after required checks and a final inspection of delivered host
287
+ files: a confirmed import/full snapshot for OCI, or the watched-file snapshot for
288
+ native execution. Required human review produces `pending_review` instead.
279
289
  Model prose cannot supply this evidence. The `none` backend does not receive OCI
280
290
  acceptance guarantees. Recovered import metadata is diagnostic evidence only until
281
291
  its delivery can be confirmed; it cannot alone restore a verified outcome.
@@ -318,3 +328,7 @@ input/output/cache tokens and terminal completion for the current invocation.
318
328
  It retains at most 128 requests plus an omitted count and contains no prompt or
319
329
  result text. Missing usage is null, including an interrupted paid request; these
320
330
  measurements do not claim invoice accuracy or provider tokenizer equivalence.
331
+
332
+ ## Experimental project memory
333
+
334
+ The `/engine` surface exports `openHarnessProjectMemory`, `executeHarnessMemoryCommand`, `HARNESS_MEMORY_COMMANDS`, `HARNESS_PROJECT_MEMORY_SCHEMA_VERSION`, `HARNESS_PROJECT_MEMORY_LIMITS` and their memory types. `createHarness` accepts the experimental `projectMemory: true` host opt-in option. These additions use existing local persistence; no client protocol change is required. See [Project memory](PROJECT_MEMORY.md) for contracts and release implications.
@@ -8,7 +8,7 @@ Built-in registrations are Meta, Qwen, OpenAI, and Gemini. Each registration own
8
8
 
9
9
  Library callers can use `DEFAULT_PROVIDER_REGISTRY`, `BUILTIN_PROVIDER_REGISTRATIONS`, `createProviderRegistry`, or `DEFAULT_PROVIDER_REGISTRY.extend(...)`, then pass the registry to `resolveHarnessConfig`, `createProviderModel`, provider diagnostics, or `createHarness({ providerRegistry })`. Registration IDs, environment-variable names, defaults, diagnostics, and factories are validated before they become selectable.
10
10
 
11
- The coordinated stable SDK batch pins `@zhivex-ai/agents@1.10.2`, `@zhivex-ai/core@1.28.0`, `@zhivex-ai/meta@0.2.8`, `@zhivex-ai/qwen@0.16.3`, `@zhivex-ai/openai@0.13.7`, and `@zhivex-ai/gemini@0.13.0`. Qwen 0.16.2 types malformed Responses tool arguments and malformed SSE events; Core 1.28.0 satisfies its published dependency range. These exact versions are pinned in the lockfile. Stable SDK publication does not replace Harness release-bound certification. Qwen `0.11.x` normalizes missing, placeholder, and continuation tool-call identifiers inside the adapter; Harness retains its deterministic provider-boundary normalizer as defense in depth until the exact candidate passes the complete release-bound representative matrix. A Core override keeps one runtime contract identity across every adapter, while Core `1.13.0` corrects compaction usage accounting and interaction-group retention. OpenAI `0.11.2` preserves synthetic assistant history in Responses, so the harness no longer requires its compaction transport or accounting workarounds.
11
+ The coordinated stable SDK batch pins `@zhivex-ai/agents@1.10.3`, `@zhivex-ai/core@1.30.1`, `@zhivex-ai/meta@0.2.9`, `@zhivex-ai/qwen@0.16.4`, `@zhivex-ai/openai@0.14.1`, `@zhivex-ai/gemini@0.13.0`, `@zhivex-ai/anthropic@0.13.2`, and `@zhivex-ai/vertex@1.2.4`. Qwen 0.16.2 types malformed Responses tool arguments and malformed SSE events; Core 1.30.1 satisfies the updated Agents, Anthropic, OpenAI and Vertex `^1.30.0` ranges and Qwen `^1.29.0` range. These exact versions are pinned in the lockfile. Stable SDK publication does not replace Harness release-bound certification. Qwen `0.11.x` normalizes missing, placeholder, and continuation tool-call identifiers inside the adapter; Harness retains its deterministic provider-boundary normalizer as defense in depth until the exact candidate passes the complete release-bound representative matrix. A Core override keeps one runtime contract identity across every adapter, while Core `1.13.0` corrects compaction usage accounting and interaction-group retention. OpenAI `0.11.2` preserves synthetic assistant history in Responses, so the harness no longer requires its compaction transport or accounting workarounds.
12
12
 
13
13
  OpenAI is based on the GPT-5.6 family: `gpt-5.6-luna` is the default, with `gpt-5.6-terra` and `gpt-5.6-sol` available through `--model`. Availability remains organization-dependent while the upstream family is in limited preview, and the adapter uses the Responses API by default.
14
14
 
package/docs/FIRST_USE.md CHANGED
@@ -1,13 +1,13 @@
1
1
  # First use
2
2
 
3
- This guide targets the prepared stable `1.3.0` release. These exact-version commands become available after protected publication to npm `latest`; currently latest resolves to 1.2.0.
3
+ This guide targets candidate `1.4.0-rc.6`, pending publication to npm `next`. The versioned install commands below become available only after protected publication. npm `latest` remains stable 1.3.0.
4
4
 
5
5
  ## Install and start
6
6
 
7
7
  Install Node.js 22.13.0 or newer and Git. Then:
8
8
 
9
9
  ```sh
10
- npm install -g @zhivex-ai/harness@1.3.0
10
+ npm install -g @zhivex-ai/harness@1.4.0-rc.6
11
11
  cd /path/to/your/project
12
12
  zhx
13
13
  ```
@@ -82,16 +82,16 @@ For command execution, configure [OCI isolation](EXECUTION_ENVIRONMENTS.md).
82
82
  With Bun 1.4.0 or newer and a supported Node runtime:
83
83
 
84
84
  ```sh
85
- bun add --global @zhivex-ai/harness@1.3.0
85
+ bun add --global @zhivex-ai/harness@1.4.0-rc.6
86
86
  zhx
87
87
  ```
88
88
 
89
89
  For a disposable version/help/environment check without a global installation:
90
90
 
91
91
  ```sh
92
- bunx @zhivex-ai/harness@1.3.0 --version
93
- bunx @zhivex-ai/harness@1.3.0 --help
94
- bunx @zhivex-ai/harness@1.3.0 doctor
92
+ bunx @zhivex-ai/harness@1.4.0-rc.6 --version
93
+ bunx @zhivex-ai/harness@1.4.0-rc.6 --help
94
+ bunx @zhivex-ai/harness@1.4.0-rc.6 doctor
95
95
  ```
96
96
 
97
97
  For source development, use the [contributor guide](https://github.com/Zhivex/zhivex-harness/blob/main/CONTRIBUTING.md).
@@ -69,10 +69,16 @@ Sequences may have gaps because the database also contains other sessions/scopes
69
69
 
70
70
  The SQLite transaction saves event and materialized snapshot together. Defaults:
71
71
  10,000 retained events per project/scope, seven-day event retention, 64 KiB per event,
72
- 256 KiB retained text per run, 1,000 runs and 2 MiB per session snapshot. Overflow
73
- fails explicitly; snapshots mark truncated text. The existing session store bounds
74
- session creation. Snapshot state is retained for reconstruction while old events are
75
- pruned. An expired cursor returns `cursorExpired: true`, the current snapshot and a
72
+ 256 KiB retained text per run, 1,000 runs and 2 MiB per session snapshot. The snapshot
73
+ is a bounded UI projection. When valid activity exceeds its byte budget, older run
74
+ previews are compacted in order: text, prompt, then tool summaries. Run identities
75
+ and statuses remain present, affected runs set `truncated: true`, and the current
76
+ run's preview is preserved until older previews have been compacted. This does not
77
+ delete journal events or change policy-evidence retention. Corrupt or unbounded
78
+ metadata, database failures and mandatory evidence failures still fail explicitly.
79
+ Already-redacted text is split into Unicode-safe events within the 64 KiB event
80
+ limit. The existing session store bounds session creation. Snapshot state is
81
+ retained for reconstruction while old events are pruned. An expired cursor returns `cursorExpired: true`, the current snapshot and a
76
82
  new recovery cursor; replace the view from that snapshot and continue. A cursor ahead
77
83
  of the session's sequence is rejected.
78
84