knodin 0.8.7 → 0.9.0

package/docs/BACKUP-RETENTION.md

@@ -0,0 +1,54 @@
+# Backup discovery and retention
+
+Knodin graph promotions leave completed snapshots named
+`db.sqlite.backup.<13-digit epoch-ms>.<8-hex-id>` beside the live database.
+They are promotion snapshots, not a supported restore interface. Malformed and
+legacy names are inventory-only and are never pruning candidates.
+
+Nothing is deleted by default. Inspect one checkout or bounded portfolio roots:
+
+```bash
+knodin backups list
+knodin backups list ~/code --depth 5 --json
+knodin backups prune                 # preview only
+knodin backups prune ~/code --apply # explicit one-shot deletion
+```
+
+The default plan retains every snapshot younger than three days and at least
+the newest completed snapshot per repository. Apply revalidates every candidate
+under Knodin's repository lifecycle lease. A promotion marker, unsafe or absent
+live `db.sqlite`, symlink, changed candidate, lease contention, containment
+ambiguity, or permission failure is reported as a skip instead of being deleted.
+Discovery never follows directory symlinks and prunes common dependency/build
+trees. It unions explicit roots with valid absolute checkout paths in
+`$XDG_CONFIG_HOME/knodin/repositories.yaml`.
+
+## Opt-in ongoing retention
+
+Installation is the consent boundary:
+
+```bash
+knodin backups retention install ~/code
+knodin backups retention status
+knodin backups retention doctor
+knodin backups retention remove
+```
+
+Options are `--retention-days` (3), `--keep-newest` (1), `--depth` (5),
+`--schedule` (`04:17` local), and `--dry-run`. Installation writes a versioned
+policy to `$XDG_CONFIG_HOME/knodin/backup-retention.json` and owned receipt/run
+state beneath `$XDG_STATE_HOME/knodin/backup-retention/`. Ordinary Knodin use
+may then clean only its current repository, at most once daily. Removal disables
+this behavior and deletes only scheduler files whose content still matches the
+recorded receipt.
+
+macOS uses a copied LaunchAgent with a daily trigger and `RunAtLoad`. Linux uses
+a persistent user systemd timer. Windows uses one Scheduled Task with daily and
+logon triggers. Unsupported scheduler environments do not weaken one-shot
+preview/apply pruning. Structured run logs are retained for at most 30 days and
+each daily log is bounded to 5 MiB.
+
+If a personal `mem-watchdog` currently handles these files, leave it running
+until `knodin backups retention doctor` reports healthy and a native run has
+been verified. Then disable the watchdog through its own configuration. Knodin
+does not modify or remove it.

package/docs/CLI.md

@@ -35,6 +35,12 @@ knodin repos search --help
 knodin update --help
 ```
 
+Backup discovery and pruning are native and cross-platform. `knodin backups
+list` and the default `knodin backups prune` are read-only; deletion requires
+`--apply`, while recurring cleanup requires the separate `knodin backups
+retention install` consent step. See `docs/BACKUP-RETENTION.md` for safety,
+scheduler, logging, and removal details.
+
 `repos search` resolves configured system memberships independently for every
 discovered checkout. Symbol search remains primary. When it returns no matches,
 or a multi-term query has only weak single-term symbol coverage, Knodin performs

package/docs/DOCTOR-AND-UPDATES.md

@@ -12,14 +12,17 @@
 - graph health;
 - configured registry/channel;
 - cached latest **trusted** release state; and
+- read-only backup inventory, reclaimable bytes, installed-retention health,
+  last run, skips, and remediation; and
 - the manager-safe action boundary when a signed update is known.
 
 A manager is reported as known only from manager-owned environment evidence or
 an identified shim. A path substring is labeled a medium-confidence heuristic,
 not proof.
 
-The former npm `latest` lookup has been removed from production paths. Doctor,
-CLI status, and MCP status now consume the same signed-only state as:
+Signed authorization remains separate from package-manager availability.
+Doctor, CLI status, and MCP status expose both states without treating registry
+metadata as signing authority. The existing signed commands remain:
 
 ```bash
 knodin update status
@@ -29,10 +32,37 @@ knodin update apply
 knodin update rollback
 ```
 
-Until the production root ceremony embeds an independently reviewed root and
-pin, these commands report `trust-unconfigured` and make no request. A user
-configuration file containing both a root path and its digest is deliberately
-inert: accepting both from one mutable file would not be independent pinning.
+Manager-aware commands bind availability and execution to the active executable
+chain, package root, manager receipts, and PATH evidence:
+
+```bash
+knodin update available
+knodin update upgrade [version] [--apply]
+knodin update pin <version> [--apply]
+knodin update unpin
+knodin update acknowledge
+knodin update auto status|enable|disable|run
+```
+
+Homebrew ownership queries only bounded `knodin/homebrew-tap` version metadata;
+npm, mise, Volta, nvm, fnm, and asdf ownership queries only bounded npm registry
+metadata. Duplicate installations, stale links, PATH shadowing, missing safety
+metadata, and ambiguous ownership are approval-required states. Doctor prints
+exact ownership evidence and manual cleanup guidance; Knodin never removes a
+competing installation.
+
+`upgrade` and `pin` are plans unless `--apply` is explicit. Apply writes and
+fsyncs a durable journal around every manager and verification boundary, holds
+the user-level exclusive update lease, and verifies an immutable multi-language
+fixture. Exact rollback is verified by the same fixture and creates a distinct
+automatic rollback pin. `npm install --global .` and other global source-tree
+installations are not used by validation or activation.
+
+Until the production root ceremony embeds a maintainer-attested root and
+source-bound digest pin, these commands report `trust-unconfigured` and make no
+request. A user configuration file containing both a root path and its digest
+is deliberately inert: accepting both from one mutable file would let the same
+mutable input replace the root and its pin.
 
 After activation, an interactive ordinary command may atomically claim a due
 background check. The foreground command does not wait for the network.
@@ -62,12 +92,14 @@ adapter; mise, Volta, nvm/fnm/asdf, Homebrew, and unknown ownership remain
 manager is ever asked to resolve a mutable version or tag, and a rollback is not
 reported successful until the restored installation passes its health check.
 
-Automatic activation also requires a certified sandbox smoke test. None is
-enabled in the production CLI yet, so `apply-patch`/`apply-minor` policies stop
-after verified quarantine instead of executing untrusted code. C64 supplies
-the provenance/SBOM and five-channel attestation machinery; the production
-release must populate it, and C65 must supply compromised-channel and recovery
-evidence before this gate can open.
+Automatic manager activation is limited to releases explicitly marked
+non-breaking patch updates after a 24-hour publication delay. It remains
+disabled on a platform until the release timing matrix proves the complete
+fixture at p95 ≤20 seconds and a hard limit of 60 seconds. Missing metadata,
+minor/major changes, prereleases, ambiguity, and a failed or timed-out fixture
+always require approval. The threshold-signed policy continues to
+govern signed authorization and quarantine; manager availability never
+substitutes for it.
 
 Run `knodin status --deep` for graph details and follow its typed repair steps:
 `knodin repair` repairs graph data, while `knodin init` restores lifecycle

package/docs/SIGNED-UPDATES.md

@@ -17,12 +17,12 @@ must produce verified evidence before activation is enabled.
 
 The metadata model has four disjoint Ed25519 roles:
 
-| Role | Purpose | Maximum signed lifetime | Required threshold |
-| --- | --- | ---: | ---: |
-| `root` | Delegates keys and rotates trust | 366 days | At least 2 |
-| `targets` | Authorizes immutable release artifacts and channels | 93 days | At least 2 |
-| `snapshot` | Binds an exact targets version, length, and digest | 32 days | At least 1 |
-| `timestamp` | Publishes the current snapshot and bounds freezes | 8 days | At least 1 |
+| Role        | Purpose                                             | Maximum signed lifetime | Required threshold |
+| ----------- | --------------------------------------------------- | ----------------------: | -----------------: |
+| `root`      | Delegates keys and rotates trust                    |                366 days |         At least 2 |
+| `targets`   | Authorizes immutable release artifacts and channels |                 93 days |         At least 2 |
+| `snapshot`  | Binds an exact targets version, length, and digest  |                 32 days |         At least 1 |
+| `timestamp` | Publishes the current snapshot and bounds freezes   |                  8 days |         At least 1 |
 
 Root and targets thresholds prevent one stolen signing key from authorizing a
 release. All four roles must use separate, content-addressed keys. A root
@@ -84,8 +84,7 @@ old threshold. Recovery tests additionally cover missed sequential rotations,
 skipped roots, intermediate mirror disagreement, and malicious version jumps.
 
 An isolated 0.4.3 adversarial drill executed the trust, policy, CLI, and release-
-attestation suites together: 4 files and 52 scenarios passed on macOS with Node
-26. Its machine-readable record is
+attestation suites together: 4 files and 52 scenarios passed on macOS with Node 26. Its machine-readable record is
 `docs/evidence/0.4.3-update-defense-drill.json`. The record separately identifies
 the post-tag commit from which the drill executed and the immutable 0.4.3 source
 commit whose implementation it exercised, plus the environment, command,
@@ -95,10 +94,10 @@ they do not certify a real npm/Homebrew mutation path or replace the production
 ceremony and live drills.
 
 The verifier cannot make the first installation trustworthy by itself. A
-production release still requires an offline root-key ceremony, independent
-pin distribution, durable trusted-state storage, compromised-key rotation
-drills, and verified artifacts on every approved channel. Until that ceremony
-and C64–C65 are complete:
+production release still requires a maintainer-attested root-key ceremony,
+source-embedded digest pin, durable trusted-state storage, compromised-key
+rotation drills, and verified artifacts on each enabled channel. Until that
+ceremony is complete:
 
 - the former npm `latest` hint is not used by doctor, status, MCP, or update commands;
 - no release is authorized by `src/update-trust.ts` in production;
@@ -108,28 +107,36 @@ and C64–C65 are complete:
 
 ## Production key ceremony gate
 
-Private root keys must be created and retained offline under separate
-custodians. No production private key or recovery secret belongs in this
+Private root keys must be created and retained offline by the maintainer. No
+production private key or recovery secret belongs in this
 repository, CI variables, npm, Homebrew, GitHub, GHES, or Artifactory. Before
 activating signed checks, the release owners must record:
 
-- custodians and a two-person approval path;
-- public key IDs and the independently reviewed root-envelope digest;
+- the accountable maintainer/custodian;
+- public key IDs and the maintainer-attested root-envelope digest;
 - offline backup and recovery controls;
 - online targets/snapshot/timestamp key storage and rotation periods;
 - emergency revocation and root-rotation rehearsal evidence; and
 - the exact knodin source commit that first embeds the trusted root pin.
 
-This external ceremony is deliberately a release gate rather than generated
-test material masquerading as production trust.
-
-The fail-closed preparation contracts and multi-custodian rehearsal procedure
+The fail-closed preparation contracts and solo-maintainer ceremony procedure
 are in [`ROOT-CEREMONY-RUNBOOK.md`](ROOT-CEREMONY-RUNBOOK.md). Their import seam
-accepts public material only and always returns `productionActivation: false`;
-it does not alter the production `trust-unconfigured` behavior.
+accepts public material only and always returns `productionActivation: false`.
 
 ## Client policy and recovery
 
+Package-manager availability is deliberately not a signature. The
+manager-aware `available`, `upgrade`, `pin`, `unpin`, `acknowledge`, and `auto`
+commands resolve the active owner and query only that owner's bounded channel.
+The signed commands below retain their threshold authorization contract.
+
+Executable replacement is serialized against repository lifecycle work with a
+user-level lease. Every manager and verification boundary is fsynced in a
+durable journal. An interrupted candidate or rollback remains unverified and
+ordinary graph/MCP/lifecycle commands fail closed until recovery re-verifies it
+or performs exact rollback. Candidate and rollback double failure persists
+`terminal-unhealthy`; it is never reported as rollback success.
+
 The implemented policy modes are `notify-only`, `download-verify-only`,
 `apply-patch`, and `apply-minor`; major updates always require manual approval.
 Policies also bound release age, approved channels, enterprise mirror origins,

package/docs/releases/0.9.0.md

@@ -0,0 +1,43 @@
+# knodin 0.9.0
+
+This release prevents repository configuration from changing after the final
+index and adds manager-aware, verified update workflows. It is marked breaking,
+requires explicit approval to install, and does not enable automatic updates.
+
+- Plain `knodin init` now owns only graph-local state and lifecycle hooks.
+  Agent instructions, MCP configuration, and repository skill directories are
+  changed only by explicit `knodin configure` or scoped initialization.
+- `knodin repair` repairs graph state without configuration churn. Compatible
+  Knodin configuration entries are byte-identical no-ops, including existing
+  whitespace, foreign entries, and `type: stdio`.
+- Configuration writes occur before the final index. Lifecycle leases, durable
+  event draining, bounded drift reconciliation, disk fingerprints, database
+  generations, and final deep health checks prevent a successful command from
+  reporting a graph that disagrees with disk.
+- `knodin doctor` reports managed-file differences, ownership evidence, tracked
+  state, and exact manual restore, remove, or ignore instructions without
+  reverting, removing, reformatting, staging, or ignoring files itself.
+- Update commands now detect Homebrew and npm-family ownership, fail closed for
+  ambiguous or shadowed installations, coordinate with repository lifecycle
+  work, and retain a durable verification and rollback journal.
+- Candidate and rollback verification use an immutable multi-language fixture
+  and reject empty, partial, stale, ambiguous, truncated, unavailable, or
+  incorrect graph evidence. Exact rollback pins and human-readable attention
+  notices remain until explicitly acknowledged or unpinned.
+- Update verification reuses the machine-scoped local model cache while keeping
+  repository and configuration fixtures isolated, avoiding redundant model
+  downloads without weakening semantic-readiness checks.
+- Opt-in backup retention adds bounded inventory, preview/apply pruning,
+  scheduler installation, status, doctor, and removal across supported
+  platforms. Destructive runs fail closed on invalid policy or ownership
+  receipts, active lifecycle work, unsafe live databases, promotion markers,
+  changed candidates, and scheduler artifacts outside Knodin-owned paths.
+- Failed retention reinstallation restores the prior policy and scheduler bytes,
+  and generated lifecycle hooks keep structured JSONL records separate from
+  process diagnostics.
+
+Automatic update eligibility remains disabled by default. Linux fixture runs
+met the recorded performance threshold; macOS did not meet the p95 threshold in
+the recorded local run, and Windows has not been certified. The 24-hour
+publication window is only a delay and is not evidence that a release is
+healthy.

package/package.json

@@ -1,6 +1,9 @@
 {
 	"name": "knodin",
-	"version": "0.8.7",
+	"version": "0.9.0",
+	"knodin": {
+		"compatibility": "breaking"
+	},
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
 	"repository": {
@@ -25,6 +28,7 @@
 		"docs/prompts/declare-multi-repository-system.md",
 		"docs/DEAD-CODE-AND-IMPACT.md",
 		"docs/DOCTOR-AND-UPDATES.md",
+		"docs/BACKUP-RETENTION.md",
 		"docs/DIAGNOSTICS.md",
 		"docs/BEHAVIORAL-CONTRACT.md",
 		"docs/DEMO.md",
@@ -66,6 +70,7 @@
 		"docs/releases/0.8.5.md",
 		"docs/releases/0.8.6.md",
 		"docs/releases/0.8.7.md",
+		"docs/releases/0.9.0.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",
@@ -100,6 +105,7 @@
 		"mirror:sync": "sh tools/hooks/sync-ghes-mirror.sh",
 		"test:pack-install": "tsx scripts/pack-install-smoke.ts",
 		"test:package-managers": "tsx scripts/package-manager-smoke.ts",
+		"verify:update-fixture": "npm run build && tsx scripts/verify-update-fixture.ts",
 		"test:naming-screen": "node --test scripts/naming-screen.test.js",
 		"measure:schema": "tsx scripts/measure-tool-schema.ts",
 		"check:dependency-deprecations": "tsx scripts/check-dependency-deprecations.ts",

package/roadmap/competitive-roadmap.md

@@ -286,6 +286,14 @@ approved and numbered.
 
 ### Track B — Parked external-evidence ledger
 
+Release-governance note (2026-08-15): Knodin has one founder/maintainer. Track B
+remains a historical capability and research ledger, but its external-human,
+multi-custodian, and mandatory three-platform rows are not publication gates.
+Production trust uses a digest-bound maintainer attestation; a release certifies
+only the platforms actually measured, and automatic updates remain disabled on
+unmeasured or unsupported platforms. Technical signature, provenance, rollback,
+channel, and verifier checks remain fail-closed.
+
 Track B parked (10 items, external). The owner parked C60–C67 on 2026-08-02,
 parked C91 after its code-readiness increment on 2026-08-05, and parked C92
 and C94 on 2026-08-06 because their acceptance depends on C91 evidence.