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

package/docs/PROJECT_MEMORY.md

@@ -0,0 +1,157 @@
+# Project memory (experimental, RC candidate)
+
+Project memory keeps explicit operator notes across separate sessions. It is
+local, inspectable and correctable. No provider calls, external database,
+credentials or integrations are needed to manage it. Suggestions are never
+generated automatically; hosts may submit a suggestion for operator review.
+
+## CLI
+
+Use `zhx` or `zhivex-code` with Harness 1.4.0-rc.6 (Code 0.3.0-rc.6), pending publication. Commands
+print bounded JSON, including the selected workspace/scope hashes. Quote content
+as one argument. Memory commands do not start a model or read credentials.
+
+```sh
+zhx memory remember "Database migrations use SQLite" --source "Operator decision"
+zhx memory list
+zhx memory read <id>
+zhx memory update <id> <revision> "Database migrations need explicit review"
+zhx memory forget <id> <revision>
+zhx memory suggest "Candidate database convention" --source "Model suggestion, reviewed separately"
+zhx memory read <suggestion-id>
+zhx memory accept <suggestion-id> <reviewed-revision>
+zhx memory context "database migrations"
+zhx memory disable
+zhx memory enable
+zhx memory clear
+zhx run --no-memory "Inspect database migrations"
+```
+
+`remember` and `update` are explicit operator writes. `suggest` creates a pending
+record; editing it leaves it pending. `accept` requires the exact revision that
+the operator reviewed. No model tool can remember, update, accept or forget a
+record. Host applications must keep these write operations behind their own
+operator interface; an API call is not proof of human consent. `--source` is a
+user-supplied provenance label, not a verified citation or execution receipt.
+Records retain origin, creation/update/review timestamps and revision. API writes
+can specify `expiresAt`; expired entries remain inspectable but are not retrieved.
+
+`disable` persists opt-out for this project and scope and blocks writes/acceptance.
+Read, list, forget and clear remain available. `clear` removes all pending and
+accepted entries while preserving the opt-out setting. `--no-memory` disables
+curated retrieval and SDK memory loading/capture for one local run/chat/resume
+invocation. It does not remove messages already in a resumed run's history.
+Service mode does not accept this flag: the service host owns runtime configuration.
+
+## Scope and bounds
+
+Scope always includes the canonical workspace directory and the existing
+tenant/user/namespace fields. Existing `--workspace`, `--state-dir`, `--tenant`,
+`--user` and `--namespace` flags select it explicitly. The default namespace is
+already workspace-derived. Even with a shared state directory and the same
+explicit namespace, separate workspace directories remain isolated. A renamed
+or copied project gets a different binding; there is no automatic merge, global
+scope, Git-remote identity inference or cross-user permission inference. Directory
+symlink aliases of the same canonical workspace use the same project. These
+scope labels are host-owned selectors, not authentication: users with access to
+the same OS-owned database can edit it directly.
+
+| Bound | Limit |
+| --- | --- |
+| Accepted and pending entries together | 128 |
+| Entry content | 4,096 UTF-8 bytes |
+| Provenance label | 512 UTF-8 bytes |
+| Current document | 256 KiB |
+| Retrieved entries per model request | 3 |
+| Complete rendered context, including metadata | 6,000 UTF-8 bytes |
+| Freshness review interval | 30 days |
+
+Retrieval ranks literal, case-insensitive query terms against content; ties use
+update time and ID. It has no embeddings or semantic recall guarantee. Short
+terms and a small English stop list are ignored. Only matching accepted entries
+are selected. Entire entries that exceed the remaining budget are skipped.
+`memory context "query"` exposes exactly that projection and its byte count.
+Stale entries are labelled; expiry excludes them. Updating a reviewed entry
+refreshes its review time. Byte limits are hard bounds, not exact model token
+counts; the existing overall runtime token budget still applies. Empty memory
+adds no model context.
+
+## Engine API and trust boundary
+
+```ts
+import { openHarnessProjectMemory } from "@zhivex-ai/harness/engine";
+const memory = await openHarnessProjectMemory({ workspace, stateDirectory, scope });
+try {
+  const note = memory.remember({ content: "Use reviewed migrations", source: "Operator" });
+  memory.update(note.id, note.revision, { content: "Review SQLite migrations", source: "Operator correction" });
+  console.log(memory.list(), memory.retrieve("SQLite migrations"));
+} finally { memory.close(); }
+```
+
+`openHarnessProjectMemory`, its types, constants and the host command dispatcher
+are experimental `/engine` additions. No client protocol commands or remote
+service endpoints are added. Local CLI hosts explicitly enable curated project memory and project relevant
+notes on every model request, including resumed runs. Engine hosts opt in with
+`createHarness({ projectMemory: true, ... })`. Omitting the option preserves the
+historical SDK memory integration and opens no curated store. Explicit `false`
+disables both curated and SDK memory, including caller-supplied `memory`.
+These rules also apply to caller-supplied run stores. With `true` or omission,
+caller-supplied SDK `memory` remains an explicit host integration.
+
+Memory reaches the model in a labelled user-context message before the current
+user request, never as system instructions. The projection is ephemeral and is
+not appended to durable run messages. It cannot grant approvals, change execution
+or filesystem permissions, bypass tool policy, certify checks, or create skills.
+Runtime approval checks still apply even when a remembered note claims authority.
+This is an enforced separation of permission state; a model can still be influenced
+by malicious text and must not be assumed immune to prompt injection.
+
+Only explicit content is persisted. Tool output, repository files, conversation
+summaries and model responses are not silently converted into curated memory.
+Known secret patterns are rejected and the existing host secret guard still
+applies. Pattern checks are best effort: they can miss secrets or reject innocent
+text. Do not store credentials or private material you do not want retained.
+
+## Storage, deletion and compatibility
+
+Memory reuses `operations.sqlite` and the SDK's existing `zhivex_agent_memory`
+table with a fully project/scope-bound key outside the SDK's scoped run/agent key
+namespace. Its leading colon cannot match a nonempty URI-encoded SDK namespace,
+regardless of the run or agent ID. A versioned envelope in the existing row format
+holds current records and the enabled setting. There is no
+second memory database or vector store. File-backed run hosts use the same SQLite
+state index that already serves sessions. Writes use SQLite transactions and
+expected revisions so concurrent edits cannot silently replace newer records.
+
+Forget and clear remove content from the active row; earlier revisions and
+deleted-content tombstones are not retained by this feature. SQLite secure-delete
+is enabled for writes, but WAL pages, filesystem snapshots and previous backups
+can still retain bytes. This is not forensic erasure. Existing run histories,
+legacy SDK memory rows, exported state, host logs and model/provider transcripts
+have separate retention. If a model quotes a memory in its response, that quote
+may enter run history. Deleting a memory does not rewrite those histories.
+Explicitly importing an older backup can restore a previously forgotten note.
+
+New state exports include the bound project document using the existing memory
+record shape. Imports validate the envelope/binding, preserve opt-out, and reject
+different destination content; identical imports remain idempotent. Historical
+v1 backups without project memory still import. Older importers reject a backup
+with the new reserved record because it is not a run-bound SDK memory record;
+use the next-version engine to restore such backups. Whole-database host snapshots
+already include the row. There is no configuration or SQL table schema migration.
+
+Legacy automatic last-assistant SDK records are not promoted into curated memory.
+The stable engine default preserves its historical SDK memory integration.
+Explicit curated mode, including local CLI hosts, stops automatic last-assistant
+capture; caller-provided SDK memory remains supported unless memory is explicitly
+disabled. The API additions can ship in a future Harness minor release with a
+matched next Code release and
+updated exact engine dependency. Any broader removal of the stable SDK memory
+default would require a major release under [API stability](STABILITY.md). Candidate package versions remain Harness
+1.3.0 / Code 0.2.0 for development only: they are not publishable replacements for
+the already released artifacts. Release preparation must select new versions,
+update the Code pin and rerun the release gates. Nothing in this change publishes
+a version.
+
+No terminal layout, menu or visual design changes are included. A future `/memory`
+console flow needs coordination with the separate TUI audit/proposals task.

package/docs/README.md

@@ -40,3 +40,5 @@ Primary guides are maintained in English. Historical reports preserve their orig
 language and evidence. Maintainer procedures and reports remain in the repository
 and are excluded from the npm package. Published validation applies to the exact
 release artifact, not automatically to later source changes.
+
+- [Project memory](PROJECT_MEMORY.md): experimental explicit notes, review, retrieval budgets and deletion semantics.

package/docs/STABILITY.md

@@ -4,7 +4,7 @@ The additive [engine entrypoints](ENGINE_API.md) are enumerated in
 [`../contracts/engine-api.json`](../contracts/engine-api.json). Aliases preserve
 their existing root tiers; newly exposed helpers have explicit tiers. The root
 compatibility surface remains unchanged. These entrypoints are source changes
-for the prepared 1.3.0 release and are available in the published RC7; they are absent from registry 1.2.0. Stable package numbering does not upgrade any export tier.
+for the published 1.3.0 release and were available in the published RC7; they are absent from registry 1.2.0. Stable package numbering does not upgrade any export tier.
 
 [`../contracts/public-api.json`](../contracts/public-api.json) is the machine-checked 1.0 baseline for the package root, binaries, CLI commands/subcommands, exit codes, and document schemas. Every runtime and type export is present in the snapshot and belongs to exactly one explicit tier. Exports listed as stable form the intended 1.x compatibility surface; Time-to-Safe-Fix exports are experimental; the explicitly listed beta exports may evolve under the policy below.
 

package/docs/WORKSPACE_CHECKPOINTS.md

@@ -24,4 +24,14 @@ After interruption in `applying`, retry checks every captured file. If all have
 
 There is no single transaction spanning SQLite and filesystem updates. Journaling exposes that boundary and makes recovery conservative. An interrupted partial filesystem update is detected, not automatically rolled back.
 
-Snapshot storage is bounded to 100 records per workspace/scope (captures and restores combined), 2 MiB per record. There is currently no automatic eviction or checkpoint deletion API. Portable state export/import preserves captures and completed restore records with workspace/scope and conversation lineage validation. Unfinished restore operations block export and import because their filesystem recovery state and reviewed authorization are local to the original database. Older bundles without checkpoint records remain readable. Close the checkpoint store before state maintenance or update operations.
+## Reviewed retention
+
+Snapshot storage is bounded to 100 records per workspace/scope (captures and restores combined), 2 MiB per record. There is no automatic eviction. The existing host API supports explicit reviewed removal of stored checkpoint records and completed restore records:
+
+1. Call `prepareRetention({ checkpointIds, completedRestoreIds })` with the exact selected record IDs. It returns the normalized `selection`, affected `records`, record counts, serialized bytes removed and a `planId` bound to the complete scoped inventory.
+2. Present that plan to the operator and enforce explicit review in the integrating host. Possession of the plan ID does not itself grant authorization.
+3. Call `applyRetention(plan.selection, plan.planId)` to revalidate the inventory and remove the reviewed records in one SQLite transaction under the workspace mutation lock.
+
+Pending or unknown restore evidence cannot be removed. A checkpoint referenced by a retained restore operation cannot be removed; completed referencing operations must be included in the reviewed selection or removed first. Inventory changes invalidate the plan, and a failure rolls back the entire selected database removal. Retention changes neither workspace files nor conversation sessions. It does not provide general filesystem deletion or repository rollback.
+
+Portable state export/import preserves captures and completed restore records with workspace/scope and conversation lineage validation. Unfinished restore operations block export and import because their filesystem recovery state and reviewed authorization are local to the original database. Older bundles without checkpoint records remain readable. Close the checkpoint store before state maintenance or update operations.

package/evaluations/representative-assembly-matrix.json

@@ -53,7 +53,13 @@
     "v1.3.0-rc.5",
     "v1.3.0-rc.6",
     "v1.3.0-rc.7",
-    "v1.3.0"
+    "v1.3.0",
+    "v1.4.0-rc.1",
+    "v1.4.0-rc.2",
+    "v1.4.0-rc.3",
+    "v1.4.0-rc.4",
+    "v1.4.0-rc.5",
+    "v1.4.0-rc.6"
   ],
   "expectedModels": [
     {
@@ -471,6 +477,54 @@
         "qwen": "qwen3.8-flash",
         "openai": "gpt-6-luna"
       }
+    },
+    {
+      "releaseTag": "v1.4.0-rc.1",
+      "models": {
+        "meta": "muse-spark-1.3-contributor",
+        "qwen": "qwen3.8-flash",
+        "openai": "gpt-6-luna"
+      }
+    },
+    {
+      "releaseTag": "v1.4.0-rc.2",
+      "models": {
+        "meta": "muse-spark-1.3-contributor",
+        "qwen": "qwen3.8-flash",
+        "openai": "gpt-6-luna"
+      }
+    },
+    {
+      "releaseTag": "v1.4.0-rc.3",
+      "models": {
+        "meta": "muse-spark-1.3-contributor",
+        "qwen": "qwen3.8-flash",
+        "openai": "gpt-6-luna"
+      }
+    },
+    {
+      "releaseTag": "v1.4.0-rc.4",
+      "models": {
+        "meta": "muse-spark-1.3-contributor",
+        "qwen": "qwen3.8-flash",
+        "openai": "gpt-6-luna"
+      }
+    },
+    {
+      "releaseTag": "v1.4.0-rc.5",
+      "models": {
+        "meta": "muse-spark-1.3-contributor",
+        "qwen": "qwen3.8-flash",
+        "openai": "gpt-6-luna"
+      }
+    },
+    {
+      "releaseTag": "v1.4.0-rc.6",
+      "models": {
+        "meta": "muse-spark-1.3-contributor",
+        "qwen": "qwen3.8-flash",
+        "openai": "gpt-6-luna"
+      }
     }
   ],
   "expectedCases": [

package/examples/README.md

@@ -1,20 +1,20 @@
-# Examples for Zhivex Harness 1.2
+# Examples for Zhivex Harness 1.3
 
 ## Isolated Bun installation
 
-Requirements: Bun 1.4.0+, Node.js 22.13.0+, and Git on macOS or Linux. After protected 1.3.0 publication, this installs the stable artifact in a temporary consumer, without building the source checkout or changing global tools:
+Requirements: Bun 1.4.0+, Node.js 22.13.0+, and Git on macOS or Linux. After protected RC publication, this installs the 1.4.0-rc.6 candidate artifact in a temporary consumer, without building the source checkout or changing global tools:
 
 ```bash
 harness_demo_dir=$(mktemp -d)
 cd "$harness_demo_dir"
 printf '{"name":"harness-first-run","private":true}\n' > package.json
-bun add --exact --ignore-scripts @zhivex-ai/harness@1.3.0
+bun add --exact --ignore-scripts @zhivex-ai/harness@1.4.0-rc.6
 ./node_modules/.bin/zhx --version
 ./node_modules/.bin/zhx --help
 ./node_modules/.bin/zhx doctor --provider openai --json
 ```
 
-Version must print `1.3.0`; help lists commands. Doctor does not contact a provider. Without `OPENAI_API_KEY`, it reports the missing credential and exits with code `3`; inspect the JSON checks before proceeding. A directory without Git initialization can also produce a diagnostic warning. No paid model call is required for these checks. Both `zhx` and `zhivex-harness` are installed aliases; Bun manages installation, and their shebang runs Node.
+Version must print `1.4.0-rc.6`; help lists commands. Doctor does not contact a provider. Without `OPENAI_API_KEY`, it reports the missing credential and exits with code `3`; inspect the JSON checks before proceeding. A directory without Git initialization can also produce a diagnostic warning. No paid model call is required for these checks. Both `zhx` and `zhivex-harness` are installed aliases; Bun manages installation, and their shebang runs Node.
 
 To continue in your actual project, use the [global installation and credential setup](../README.md#installation), then `zhx init --profile daily --provider openai` and `zhx doctor --profile daily`. Real tasks require the selected provider credential in the process environment. Profiles store provider/model choices, never credentials. See [CLI](../docs/CLI.md) and [support](../SUPPORT.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhivex-ai/harness",
-  "version": "1.3.0",
+  "version": "1.4.0-rc.6",
   "description": "Governed, provider-portable runtime for coding agents with durable approvals and isolated repository execution.",
   "type": "module",
   "license": "MIT",
@@ -135,7 +135,8 @@
     "docs/adr/0002-isolated-mcp-stdio.md",
     "docs/VERTEX.md",
     "docs/TOOL_POLICY.md",
-    "docs/fixtures/mcp-stdio-contract-v1.json"
+    "docs/fixtures/mcp-stdio-contract-v1.json",
+    "docs/PROJECT_MEMORY.md"
   ],
   "scripts": {
     "models:check": "bun run scripts/validate-model-catalog.ts",
@@ -204,22 +205,22 @@
     "smoke:mcp:installed": "bun run build && bun scripts/mcp-installed-smoke.ts"
   },
   "dependencies": {
-    "@zhivex-ai/agents": "1.10.2",
-    "@zhivex-ai/anthropic": "0.13.1",
-    "@zhivex-ai/core": "1.28.0",
+    "@zhivex-ai/agents": "1.10.3",
+    "@zhivex-ai/anthropic": "0.13.2",
+    "@zhivex-ai/core": "1.30.1",
     "@zhivex-ai/gemini": "0.13.0",
-    "@zhivex-ai/meta": "0.2.8",
-    "@zhivex-ai/openai": "0.13.7",
-    "@zhivex-ai/qwen": "0.16.3",
-    "@zhivex-ai/vertex": "1.2.2",
+    "@zhivex-ai/meta": "0.2.9",
+    "@zhivex-ai/openai": "0.14.1",
+    "@zhivex-ai/qwen": "0.16.4",
+    "@zhivex-ai/vertex": "1.2.4",
     "google-auth-library": "11.1.0",
     "zod": "4.6.5"
   },
   "overrides": {
-    "@zhivex-ai/core": "1.28.0"
+    "@zhivex-ai/core": "1.30.1"
   },
   "devDependencies": {
-    "@agentclientprotocol/sdk": "1.5.1",
+    "@agentclientprotocol/sdk": "1.7.0",
     "@modelcontextprotocol/server": "2.2.0",
     "@types/bun": "1.4.2",
     "@types/node": "^26.6.3",