@staix/vault-mem 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-11-01
+
+- `sync` and `doctor` refuse a git URL rewrite (`insteadOf`/`pushInsteadOf`) only when its prefix matches the configured remote or one of origin's configured or effective URLs, explicit `pushurl` included, and name that rule (#86). An unrelated rule, such as a global `https://github.com/` to SSH rewrite with an SSH vault remote, no longer blocks sync.
+
+## [0.3.0] - 2026-11-01
+
+- A vault whose PII policy has members this build does not know (from a newer-format config) fails closed: note writes, `check`, tidy, `promote-from-amem`, `promote`, move and delete and log appends on it are refused with `PII_POLICY` instead of screening with an incomplete policy. Reads and `vaults pii` show still work.
+- Versions coexist on one machine (#82). `vmem mcp` loads every module a tool can run at startup, the agent-mem root included, so a running server keeps its own code and tool list when its install is replaced or a newer release is installed beside it.
+- `vmem setup <target> --root <path>` registers another install root, such as `<install>/releases/<version>/`, resolved to its real path. Without `--root` setup registers the running install as before.
+- `vmem.config.json` accepts an optional `version` (format 1). A config from a newer format is read tolerantly and its unknown keys survive registry writes; at or below format 1 unknown keys stay errors. Log screening accepts the same extended PII policy, and `vaults pii --set` refuses to replace a policy whose unknown members it would drop.
+- The derived index is `indexes/<sha256>-links<N>.sqlite`, named per link-resolution version, so two versions alternating on one vault no longer rebuild each other's links. The first run after upgrading builds it once.
+- `vmem manifest --json` lists the version, the config format, the MCP tool names and the CLI commands.
+- The embedded `@staix/agent-mem` pin moves from 0.11.0 to 0.17.0, at or above agent-mem's 0.13 floor for agent workflows.
+- N-1: 0.2.4 runs beside this release. It keeps its own unversioned index file and reads the config this release writes, since this release never adds `version`; 0.2.4 refuses a config that carries `version` or any other key it does not know.
+
 ## [0.2.4] - 2026-11-01
 
 - Report names (`graph-report-YYMMDD.md`, `lint-report-YYMMDD.md`), graph trend rows, L11 staleness, `promoted_at` (agent-mem and org promotion) and the skill-candidate report date now use the local calendar date, the same clock as the log lines, instead of UTC. A run early in the morning in a timezone ahead of UTC is no longer dated the previous day. `options.today` and `now` overrides still apply. Skill mining's `unique_days` keeps the UTC day of each record's `...Z` timestamp, as Python's `.date()` does.

package/README.md

@@ -25,7 +25,7 @@ Home precedence: `VMEM_HOME` (the pointer is not consulted), else a `home` point
 {"vaults":[{"id":"personal","path":"/absolute/vault","kind":"personal","write":"mcp"}],"denyPaths":[],"piiPatterns":[]}
 ```
 
-Configuration is limited to 64 KiB both on read and after serialization (a change whose pretty-printed result exceeds the limit is refused and the file is unchanged), rejects unknown keys, and is updated under an exclusive lock using a flushed temporary file and atomic rename. Errors name the config file or vault id and path but never echo config or note contents.
+Configuration is limited to 64 KiB both on read and after serialization (a change whose pretty-printed result exceeds the limit is refused and the file is unchanged), rejects unknown keys, and is updated under an exclusive lock using a flushed temporary file and atomic rename. An optional top-level `version` (positive integer, absent means 1) names the config format; this build writes format 1 and never adds `version` itself, so 0.2.4 and older keep reading what it writes. A config whose `version` is newer than this build's format is read tolerantly: unknown keys at the top level, in vaults and in PII policies are kept and written back unchanged by registry commands, while the keys this build knows are still validated. A PII policy with members this build does not know cannot be enforced, so it fails closed: every write on that vault (note writes and `check`, two-step previews and confirms, tidy, `promote-from-amem`, `promote` and log appends) is refused with `PII_POLICY`, naming the members, until the newer vmem that wrote the policy does the write. Reads and `vaults pii` show are unaffected. `vaults pii --set` refuses to replace a policy that carries such members, since the replacement would drop them; change it with the newer vmem. Versions that add a key bump the format. Errors name the config file or vault id and path but never echo config or note contents.
 
 Durability: the temporary file is fsynced before the rename and the home directory is fsynced after it. On Linux this makes the new config durable once the command returns. On macOS directory fsync succeeds but does not flush the drive cache (no `F_FULLFSYNC`), so a power loss right after a change can revert to the previous complete config, never to a partial one. Windows is not a supported platform for durability claims; the rename stays atomic.
 
@@ -33,7 +33,7 @@ Crash recovery: the lock file records the writer's pid, host and start time. Not
 
 Vault fields: `id`, absolute `path` (must contain a real `notes/` directory), `kind` (`personal|org`), `write` (`mcp|cli|none`), optional `pii` (the `allow|deny` shorthand or a policy object, see PII policy below; default `allow` for personal and `deny` for org, and `status`/`vaults list` always report the effective shorthand and `piiPolicy` matrix, including for unhealthy entries), optional `remote` (any nonempty string such as an `https://` or `git@host:path` URL) and optional `registry` (absolute path). For healthy vaults, `doctor` checks locally that the vault is a git repository root with an origin whose fetch and push URLs all match `remote` (URL rewrites are refused), and that `registry` passes the same deny-path, size and project-id validation as log appends. Results appear under each vault's `checks.remote` and `checks.registry`; a failed check exits 1. These checks use no network and do not test reachability. `status` is unchanged. Policy fields are stored for later note-writing stages, not enforced by the read commands. Writer commands enforce write/channel policy and configured deny/PII screening.
 
-The only runtime dependency is the exact first-party pin `@staix/agent-mem@0.11.0`; it is not loaded by registry commands. Public library exports cover configuration, home resolution, registry operations, frontmatter, link resolution and the derived index. No console bin or UI contract is advertised before its implementation.
+The only runtime dependency is the exact first-party pin `@staix/agent-mem@0.17.0`; it is not loaded by registry commands. Public library exports cover configuration, home resolution, registry operations, frontmatter, link resolution and the derived index. No console bin or UI contract is advertised before its implementation.
 
 # PII policy
 
@@ -87,7 +87,7 @@ bun bin/vmem.js links personal "Note or alias" --limit 50 --json
 
 All four commands require a registered vault id. They read only flat, regular `notes/*.md` files (case-sensitive `.md` extension), skip subdirectories and symlink files, and refuse a replaced vault/notes directory. Notes are limited to 2 MiB each. They never write note content, registry configuration or `.obsidian/`. `rebuild` rebuilds the derived cache; other commands scan metadata on every invocation and rehash new or metadata-changed files. Content-identical changes only update metadata; deleted/renamed paths leave the index. SQLite transactions make each scan atomic. A concurrently changing note aborts that scan, so retry after its writer finishes. No watcher, model calls or embeddings run.
 
-The cache is `$VMEM_HOME/indexes/<canonical-vault-path-sha256>.sqlite` using the resolved home, not necessarily the environment variable. Cache files use mode 0600 on creation. The location must be outside every registered vault, including through symlinks; linked cache directories/files are refused. It contains note text and is disposable private derived state. Removing it while commands are stopped allows the next read to build it again. SQLite uses its own transaction lock and a five-second busy timeout. There is no automatic migration or live vault cutover.
+The cache is `$VMEM_HOME/indexes/<canonical-vault-path-sha256>-links<N>.sqlite` using the resolved home, not necessarily the environment variable. `N` is the link-resolution version (currently 2), so two installed vmem versions that resolve links differently keep separate caches instead of rebuilding each other's links; 0.2.4 and older use the unversioned `<sha256>.sqlite`, and a first run after upgrading builds the new file once. Cache files use mode 0600 on creation. The location must be outside every registered vault, including through symlinks; linked cache directories/files are refused. It contains note text and is disposable private derived state. Removing it while commands are stopped allows the next read to build it again. SQLite uses its own transaction lock and a five-second busy timeout. There is no automatic migration or live vault cutover.
 
 Search uses FTS5 `unicode61` over title, description and body with BM25 weights 5:2:1, ascending score and path tie-breaking. Whitespace-separated query terms are literal AND terms, not a raw FTS expression; quote the query as one shell argument. `--type` and `--domain` are exact scalar frontmatter filters. Results include a bounded snippet and metadata, not the full body. Search queries and note targets accept at most 1024 UTF-8 bytes. Search/links default to 50 results, with an enforced 1..500 range. Show defaults to 16384 UTF-8 bytes and permits 1..65536, returning `truncated` and the full note SHA-256. `--section "Exact H2"` selects one real H2 through the next H1/H2, including its H3 children; code-fenced headings are ignored and duplicate/missing names refuse. Truncated reads include bounded `headings` (at most 64 names/8KiB metadata; `headingsTruncated` when omitted) and `nextOffset`. `--offset N` is a UTF-8 byte offset within the selected section or whole note; use the returned `nextOffset` to page even a single section larger than 64 KiB, and compare note hashes across pages. Invalid UTF-8 boundaries and zero-progress byte budgets refuse. Link string fields are capped at 1024 bytes in command results. Oversized arguments fail instead of silently raising a bound.
 
@@ -146,7 +146,7 @@ Readers never create a home, log or lock, and work with `write: none`. They skip
 
 # MCP server
 
-`vmem mcp` serves newline-delimited JSON-RPC 2.0 (MCP tools, protocol 2025-06-18 and earlier) on stdio. stdout carries protocol messages only; it needs no TTY and runs in agent sessions. Requests are limited to 64 KiB per frame and results to 256 KiB (a larger result becomes a structured `LIMIT` refusal). Arguments are validated against each tool's bounded schema (`additionalProperties: false`, string/array/integer caps); invalid arguments or unknown tools return JSON-RPC `-32602`, unknown methods `-32601`, malformed frames `-32700`/`-32600`. The `@staix/agent-mem` root is never loaded at startup.
+`vmem mcp` serves newline-delimited JSON-RPC 2.0 (MCP tools, protocol 2025-06-18 and earlier) on stdio. stdout carries protocol messages only; it needs no TTY and runs in agent sessions. Requests are limited to 64 KiB per frame and results to 256 KiB (a larger result becomes a structured `LIMIT` refusal). Arguments are validated against each tool's bounded schema (`additionalProperties: false`, string/array/integer caps); invalid arguments or unknown tools return JSON-RPC `-32602`, unknown methods `-32601`, malformed frames `-32700`/`-32600`. At startup it loads every module a tool can run, the `@staix/agent-mem` root included, so a server keeps its own code and tool list when its install is replaced or a newer release is installed beside it; restart the host session to pick up the new release.
 
 The vault set is read once at startup: every tool's `vault` property is an enum of the registered ids and defaults to the first `personal` vault. Restart the host session after `vaults add/remove`. Reads go through the same index as the CLI; writes go through `applyWrite`/`appendLog` with channel `mcp`, so they require `write: mcp` and pass the same V01-V10 gates. Every tool returns a JSON result: a receipt, or `{refused: true, issues}` for policy, validation or lookup failures.
 
@@ -183,14 +183,17 @@ vmem setup claude            # dry-run: lists the file and change per host, writ
 vmem setup all --apply       # claude codex kimi pi qwen jcode
 vmem setup agy --apply       # run inside the workspace; writes ./.agents/mcp_config.json
 vmem setup all --undo
+vmem setup all --root ~/.local/share/vmem/releases/0.3.0 --apply   # register a versioned install root
 ```
 
-Setup registers one server entry named `vmem` (`<bun> --smol <package>/bin/vmem.js mcp`) by editing the host's own MCP configuration: `~/.claude.json` (`mcpServers`; `$CLAUDE_CONFIG_DIR/.claude.json` when set), `$CODEX_HOME/config.toml` (`[mcp_servers.vmem]`), `$KIMI_CODE_HOME/mcp.json`, `$PI_CODING_AGENT_DIR/mcp.json`, `$QWEN_HOME/settings.json` (all `mcpServers`), `$JCODE_HOME/mcp.json` (`servers`) and the workspace's `.agents/mcp_config.json` for Antigravity. Defaults are `~/.codex`, `~/.kimi-code`, `~/.pi/agent`, `~/.qwen` and `~/.jcode`; overrides must be absolute. It does not call host CLIs and does not need a TTY. Run it while the host is closed: Claude Code in particular rewrites `.claude.json` while it runs and can overwrite a concurrent change.
+Setup registers one server entry named `vmem` (`<bun> --smol <package>/bin/vmem.js mcp`) by editing the host's own MCP configuration: `~/.claude.json` (`mcpServers`; `$CLAUDE_CONFIG_DIR/.claude.json` when set), `$CODEX_HOME/config.toml` (`[mcp_servers.vmem]`), `$KIMI_CODE_HOME/mcp.json`, `$PI_CODING_AGENT_DIR/mcp.json`, `$QWEN_HOME/settings.json` (all `mcpServers`), `$JCODE_HOME/mcp.json` (`servers`) and the workspace's `.agents/mcp_config.json` for Antigravity. Defaults are `~/.codex`, `~/.kimi-code`, `~/.pi/agent`, `~/.qwen` and `~/.jcode`; overrides must be absolute. It does not call host CLIs and does not need a TTY. `--root <absolute path>` registers another vault-mem install root instead of the running one, for example a versioned `<install>/releases/<version>/` that a newer release is installed beside; the root is resolved to its real path (a `current` link registers the release it names) and must hold the package's `package.json` (a plain file of at most 64 KiB) and `bin/vmem.js`. The report names the root and its version. The current registration changes only on `--apply`; running servers keep their release until the host session restarts. Run it while the host is closed: Claude Code in particular rewrites `.claude.json` while it runs and can overwrite a concurrent change.
 
 Apply is idempotent and touches only the `vmem` entry: other servers and settings are preserved (TOML is edited textually, so comments and other tables stay byte-identical; JSON is re-serialized with its indentation). Configuration files must be plain strict JSON or TOML; links, JSONC and unparsable files are refused per host without writing, and the command exits 1. Apply records the prior `vmem` value in a receipt, `$VMEM_HOME/setup/<host>-<hash of the config path>.json`, so separate host profiles (for example two `CODEX_HOME`s) sharing one `VMEM_HOME` keep separate receipts. The receipt is written before the host file; if the host write fails, the receipt is rolled back. In TOML, every `[mcp_servers.vmem]` and `[mcp_servers.vmem.*]` table belongs to the entry, even when other tables sit between them. Undo restores that prior value (or removes the entry, and the file if setup created it and nothing else was added) only while the entry is still the one setup installed; an entry edited later is left alone and reported as `refused`. Every mode also handles the console plugin manifest (see "Console plugin"): apply writes it, undo removes it while it still points at this install.
 
 `vmem completion bash|zsh|fish` prints a completion script generated from the same command table as `--help`.
 
+`vmem manifest --json` prints `{name, version, configVersion, mcp: {server, tools}, commands}`: the package version, the config format it writes, the MCP tool names and the CLI command names from the same table, for tools that would otherwise hard-code them.
+
 # Promotion from agent-mem
 
 `vmem promote-from-amem` turns one durable agent-mem entry into a vault note and records agent-mem's own vault link back to it. Agent memory is never indexed or copied into a second store, and no agent-mem tool is added: candidates come from agent-mem's `vaultCandidates` selection and the link from its `recordVaultLink`.
@@ -202,7 +205,7 @@ vmem promote-from-amem personal mem:<id> ... --confirm --fingerprint <sha>
 vmem promote-from-amem personal mem:<id> --link-to existing-note  # link an existing note instead of creating one
 ```
 
-- `src/amem/seam.ts` is the only module that imports the `@staix/agent-mem` root (exact pin 0.11.0), and it is loaded lazily: `vmem mcp`, reads, writes and every other command never load it. The project defaults to agent-mem's key for the current directory (`--project` overrides); `AMEM_HOME` selects the memory home as in agent-mem.
+- `src/amem/seam.ts` is the only module that imports the `@staix/agent-mem` root (exact pin 0.17.0, at or above agent-mem's 0.13 floor for agent workflows). Reads, writes and other commands never load it; promotion and mining load it when they run, and `vmem mcp` loads it at startup. The project defaults to agent-mem's key for the current directory (`--project` overrides); `AMEM_HOME` selects the memory home as in agent-mem.
 - Listing and linking require agent-mem's generation profile; a shared-v1 memory home is refused. Candidate listing applies agent-mem's durable selection and policy (secrets, default PII and the vault config's `piiPatterns`) before ordering and `--limit`; previews screen the requested entry with the same policy.
 - The preview prefills the H1 and stem from the entry title, the body from its text, `about[]` as Relevant Notes hints, and provenance `promoted_from: mem:<id>` plus `promoted_at`. `--stem --type --domain --topics --description --title` and `--body file|-` override it; none of this needs a TTY. When a note with the same stem or title exists, the preview is refused with V08 and lists `link-existing <path>` choices; `--link-to` takes one. `--edit` opens `$VISUAL`/`$EDITOR` on the draft only when stdin is a terminal (the only TTY check); the edited text is previewed and confirmed with `--body`.
 - Confirm requires the preview fingerprint, then creates the note through `applyWrite` (V01-V10), appends one `LEARN  <project>  mem:<id> → notes/<stem>.md  <em-dash> promoted: <kind>` event (`--log-project` sets the project field; it defaults to the last segment of the agent-mem project key) and records the vault link last.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/vault-mem",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Validated Obsidian-compatible knowledge vaults for agents and people",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,7 @@
     "bun": ">=1.4.2"
   },
   "dependencies": {
-    "@staix/agent-mem": "0.11.0"
+    "@staix/agent-mem": "0.17.0"
   },
   "devDependencies": {
     "@staix/agent-console": "github:STAIxBWLB/agent-console#bd7234f",

package/src/amem/seam.ts

@@ -1,7 +1,7 @@
 /**
- * The only module that imports the `@staix/agent-mem` root. It is loaded lazily by promotion, so
- * `vmem mcp`, reads and writes never pay for it. No agent memory is indexed or copied here: the seam
- * lists candidates from amem's own selection and records amem's own vault link.
+ * The only module that imports the `@staix/agent-mem` root. Promotion and mining load it lazily, so reads,
+ * writes and other commands never pay for it; `vmem mcp` loads it at start (`preloadAmem`). No agent memory
+ * is indexed or copied here: the seam lists candidates from amem's own selection and records amem's own vault link.
  */
 import type { MemoryStore, View } from "@staix/agent-mem";
 
@@ -17,6 +17,8 @@ export interface AmemSeam {
 }
 export interface AmemOptions { env?: NodeJS.ProcessEnv; project?: string; cwd?: string; piiPatterns?: string[] }
 const ID = /^[a-f0-9]{32}$/;
+/** Load the agent-mem root now. `vmem mcp` calls it at start; every other caller keeps the lazy load. */
+export async function preloadAmem(): Promise<void> { await import("@staix/agent-mem"); }
 function view(value: View): AmemCandidate {
   return { id: value.id, project: value.project, kind: value.kind, title: value.title, text: value.text, about: value.about.map(node => String(node)), at: value.at };
 }

package/src/cli.ts

@@ -6,7 +6,9 @@ import { runOrgCommand } from "./org-commands.ts";
 import { isWriteCommand, runWriteCommand } from "./write-commands.ts";
 import { isReadCommand, runReadCommand } from "./read-commands.ts";
 import { version } from "../package.json";
-import { completionScript, help } from "./commands-table.ts";
+import { COMMANDS, completionScript, help } from "./commands-table.ts";
+import { VMEM_TOOL_NAMES } from "./mcp-vault.ts";
+import { CONFIG_VERSION } from "./config.ts";
 import { runSetup, type SetupMode } from "./setup.ts";
 import { resolveHome } from "./home.ts";
 import { addVault, effectivePii, loadRegistry, recoverRegistry, registryStatus, removeVault, setVaultPii } from "./registry.ts";
@@ -28,12 +30,18 @@ function parse(args: string[], allowed: string[], values: string[]) {
 export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { text: string; code: number } {
   if (!args.length || (args.length === 1 && ["--help", "-h", "help"].includes(args[0]!))) return { text: help(), code: 0 };
   if (args.length === 1 && args[0] === "--version") return { text: version, code: 0 };
+  if (args[0] === "manifest") {
+    const { flags, positional } = parse(args.slice(1), ["--json"], []);
+    if (positional.length) throw new Error("manifest: unexpected arguments");
+    const manifest = { name: "@staix/vault-mem", version, configVersion: CONFIG_VERSION, mcp: { server: "vmem", tools: [...VMEM_TOOL_NAMES] }, commands: COMMANDS.map(c => c.name) };
+    return { text: JSON.stringify(manifest, null, flags["--json"] ? undefined : 2), code: 0 };
+  }
   if (args[0] === "setup") {
-    const rest = args.slice(1), flags = rest.filter(a => a.startsWith("--")), positional = rest.filter(a => !a.startsWith("--"));
-    if (positional.length !== 1 || flags.some(f => !["--apply", "--undo", "--json"].includes(f)) || new Set(flags).size !== flags.length || (flags.includes("--apply") && flags.includes("--undo"))) throw new Error("setup: requires one target and at most one of --apply/--undo");
-    const mode: SetupMode = flags.includes("--apply") ? "apply" : flags.includes("--undo") ? "undo" : "dry-run";
-    const report = runSetup(positional[0]!, mode, { home: resolveHome(env).home, env });
-    return { text: JSON.stringify(report, null, flags.includes("--json") ? undefined : 2), code: [...report.actions, report.console].some(a => a?.change === "refused") ? 1 : 0 };
+    const { flags, positional } = parse(args.slice(1), ["--apply", "--undo", "--json", "--root"], ["--root"]);
+    if (positional.length !== 1 || (flags["--apply"] && flags["--undo"])) throw new Error("setup: requires one target and at most one of --apply/--undo");
+    const mode: SetupMode = flags["--apply"] ? "apply" : flags["--undo"] ? "undo" : "dry-run";
+    const report = runSetup(positional[0]!, mode, { home: resolveHome(env).home, env, ...(typeof flags["--root"] === "string" ? { root: flags["--root"] } : {}) });
+    return { text: JSON.stringify(report, null, flags["--json"] ? undefined : 2), code: [...report.actions, report.console].some(a => a?.change === "refused") ? 1 : 0 };
   }
   if (args[0] === "completion") {
     if (args.length !== 2) throw new Error("completion: requires bash, zsh or fish");
@@ -107,9 +115,15 @@ export function run(args: string[], env: NodeJS.ProcessEnv = process.env): { tex
   }
   return { text: JSON.stringify(result, null, flags["--json"] ? undefined : 2), code };
 }
-/** `vmem mcp`: the vault set is fixed now; stdout carries protocol frames only. */
+/**
+ * `vmem mcp`: the vault set is fixed now; stdout carries protocol frames only. Every module a tool handler
+ * loads lazily, the agent-mem root included, is loaded here at start, so an install replaced under a running
+ * server never mixes two versions in one process.
+ */
 export async function runMcp(env: NodeJS.ProcessEnv = process.env): Promise<void> {
-  const [{ serveMcp }, { createVaultMcp }] = await Promise.all([import("./mcp.ts"), import("./mcp-vault.ts")]);
+  const [{ serveMcp }, { createVaultMcp }, , , , seam] = await Promise.all([import("./mcp.ts"), import("./mcp-vault.ts"),
+    import("./promote.ts"), import("./org-promote.ts"), import("./skills-mine.ts"), import("./amem/seam.ts")]);
+  await seam.preloadAmem();
   const server = createVaultMcp(resolveHome(env).home, env);
   await serveMcp({ tools: server.tools, handlers: server.handlers, name: "vmem", version });
 }

package/src/commands-table.ts

@@ -32,7 +32,8 @@ export const COMMANDS = [
   { name: "promote", usage: "promote <personal-vault> <note> --to ORG [--topics a,b] [--again] [--log-project ID] [--confirm --fingerprint SHA] [--json]", mutates: "confirm" },
   { name: "sync", usage: "sync <vault> [--message TEXT] [--confirm --fingerprint SHA] [--json]", mutates: "confirm" },
   { name: "mcp", usage: "mcp", mutates: false },
-  { name: "setup", usage: "setup <claude|codex|kimi|pi|qwen|jcode|agy|all> [--apply|--undo] [--json]", mutates: "apply" },
+  { name: "setup", usage: "setup <claude|codex|kimi|pi|qwen|jcode|agy|all> [--root PATH] [--apply|--undo] [--json]", mutates: "apply" },
+  { name: "manifest", usage: "manifest [--json]", mutates: false },
   { name: "completion", usage: "completion <bash|zsh|fish>", mutates: false },
 ] as const;
 const RELATIONS = ["supports", "contradicts", "extends", "applies-to", "context-for"] as const;

package/src/config.ts

@@ -19,14 +19,30 @@ export type PiiCell = PiiAction | Partial<Record<PiiSurface, PiiAction>>;
 export interface PiiPattern { name: string; regex: string; action?: PiiCell }
 /** Fine-grained PII policy: per category, optionally per surface; omitted cells take the vault default. */
 export interface PiiSpec { email?: PiiCell; phone?: PiiCell; custom?: PiiCell; patterns?: PiiPattern[]; allow?: string[] }
-export interface VmemConfig { home?: string; vaults: VaultSpec[]; denyPaths?: string[]; piiPatterns?: string[] }
+/**
+ * The config format this build writes. A build that adds a key bumps it. A config whose `version` is newer
+ * than this build is read tolerantly: unknown keys are kept as they are and written back unchanged, so an
+ * older vmem can share a config with a newer one. At or below this version unknown keys stay errors (typos).
+ * An absent `version` means 1, and this build never adds one, so 0.2.4 and older keep reading what it writes.
+ */
+export const CONFIG_VERSION = 1;
+export interface VmemConfig { version?: number; home?: string; vaults: VaultSpec[]; denyPaths?: string[]; piiPatterns?: string[] }
 const controls = /[\x00-\x1f\x7f]/;
-function object(value: unknown, keys: string[], label: string): Record<string, unknown> {
+function object(value: unknown, keys: string[], label: string, tolerant = false): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label}: expected object`);
   const record = value as Record<string, unknown>;
-  for (const key of Object.keys(record)) if (!keys.includes(key)) throw new Error(`${label}: unknown key ${key}`);
+  if (!tolerant) for (const key of Object.keys(record)) if (!keys.includes(key)) throw new Error(`${label}: unknown key ${key}`);
   return record;
 }
+/** True when `config` is in a format newer than this build: its unknown keys are kept, not refused. */
+export function newerFormat(config: unknown): boolean {
+  const version = config && typeof config === "object" ? (config as { version?: unknown }).version : undefined;
+  return typeof version === "number" && Number.isSafeInteger(version) && version > CONFIG_VERSION;
+}
+/** The keys of `record` this build does not know, kept only when the config is newer than this build. */
+function unknown(record: Record<string, unknown>, keys: string[], tolerant: boolean): Record<string, unknown> {
+  return tolerant ? Object.fromEntries(Object.entries(record).filter(([key]) => !keys.includes(key))) : {};
+}
 function string(value: unknown, label: string): string {
   if (typeof value !== "string" || !value.trim() || controls.test(value)) throw new Error(`${label}: expected nonempty string without control characters`);
   return value;
@@ -46,12 +62,12 @@ function strings(value: unknown, label: string): string[] | undefined {
   });
 }
 const ACTIONS = new Set(["allow", "warn", "deny"]);
-function cell(value: unknown, label: string): PiiCell {
+function cell(value: unknown, label: string, tolerant = false): PiiCell {
   if (typeof value === "string") {
     if (!ACTIONS.has(value)) throw new Error(`${label}: expected allow, warn or deny`);
     return value as PiiAction;
   }
-  const record = object(value, [...PII_SURFACES], label), result: Partial<Record<PiiSurface, PiiAction>> = {};
+  const record = object(value, [...PII_SURFACES], label, tolerant), result = unknown(record, [...PII_SURFACES], tolerant) as Partial<Record<PiiSurface, PiiAction>>;
   for (const surface of PII_SURFACES) if (record[surface] !== undefined) {
     if (typeof record[surface] !== "string" || !ACTIONS.has(record[surface] as string)) throw new Error(`${label}.${surface}: expected allow, warn or deny`);
     result[surface] = record[surface] as PiiAction;
@@ -59,54 +75,75 @@ function cell(value: unknown, label: string): PiiCell {
   return result;
 }
 /** Validate `vault.pii`: the `allow`/`deny` shorthand or a PiiSpec object. */
-export function parsePii(value: unknown): "allow" | "deny" | PiiSpec {
+export function parsePii(value: unknown, tolerant = false): "allow" | "deny" | PiiSpec {
   if (value === "allow" || value === "deny") return value;
   if (typeof value === "string") throw new Error("vault.pii: expected allow, deny or a policy object");
-  const raw = object(value, ["email", "phone", "custom", "patterns", "allow"], "vault.pii"), spec: PiiSpec = {};
-  for (const key of ["email", "phone", "custom"] as const) if (raw[key] !== undefined) spec[key] = cell(raw[key], `vault.pii.${key}`);
+  const raw = object(value, PII_KEYS, "vault.pii", tolerant), spec: PiiSpec = unknown(raw, PII_KEYS, tolerant);
+  for (const key of ["email", "phone", "custom"] as const) if (raw[key] !== undefined) spec[key] = cell(raw[key], `vault.pii.${key}`, tolerant);
   if (raw.patterns !== undefined) {
     if (!Array.isArray(raw.patterns) || raw.patterns.length > 32) throw new Error("vault.pii.patterns: expected at most 32 patterns");
     const names = new Set<string>();
     spec.patterns = raw.patterns.map((item, index) => {
-      const p = object(item, ["name", "regex", "action"], `vault.pii.patterns[${index}]`);
+      const p = object(item, PATTERN_KEYS, `vault.pii.patterns[${index}]`, tolerant);
       const name = string(p.name, "vault.pii.patterns.name"), regex = string(p.regex, "vault.pii.patterns.regex");
       if (!/^[a-z][a-z0-9-]{0,31}$/.test(name) || names.has(name)) throw new Error(`vault.pii.patterns: invalid or duplicate name ${name.slice(0, 40)}`);
       if (Buffer.byteLength(regex) > 256) throw new Error("vault.pii.patterns.regex: exceeds 256 bytes");
       try { new RegExp(regex, "u"); } catch { throw new Error(`vault.pii.patterns.${name}: invalid regular expression`); }
       names.add(name);
-      return { name, regex, ...(p.action !== undefined ? { action: cell(p.action, `vault.pii.patterns.${name}.action`) } : {}) };
+      return { ...unknown(p, PATTERN_KEYS, tolerant), name, regex, ...(p.action !== undefined ? { action: cell(p.action, `vault.pii.patterns.${name}.action`, tolerant) } : {}) };
     });
   }
   if (raw.allow !== undefined) spec.allow = strings(raw.allow, "vault.pii.allow");
   return spec;
 }
-export function parseVault(value: unknown): VaultSpec {
-  const v = object(value, ["id", "path", "kind", "write", "pii", "remote", "registry"], "vault");
+const PII_KEYS = ["email", "phone", "custom", "patterns", "allow"], PATTERN_KEYS = ["name", "regex", "action"];
+/** Members of a parsed policy that this build does not know (kept from a newer-format config), as dotted paths. */
+export function piiExtensions(pii: VaultSpec["pii"]): string[] {
+  if (!pii || typeof pii !== "object") return [];
+  const extra = (value: unknown, keys: readonly string[], at: string) => value && typeof value === "object" ? Object.keys(value).filter(key => !keys.includes(key)).map(key => at + key) : [];
+  const record = pii as Record<string, unknown>;
+  return [...extra(record, PII_KEYS, ""), ...(["email", "phone", "custom"] as const).flatMap(key => extra(record[key], PII_SURFACES, `${key}.`)),
+    ...(pii.patterns ?? []).flatMap(p => [...extra(p, PATTERN_KEYS, `patterns.${p.name}.`), ...extra(p.action, PII_SURFACES, `patterns.${p.name}.action.`)])];
+}
+/**
+ * Fail closed: a vault whose PII policy has members this build does not know (kept from a newer-format config)
+ * cannot be screened as that policy asks, so every write and log append on it is refused with this reason.
+ */
+export function unenforceablePii(vault: VaultSpec): string | undefined {
+  const members = piiExtensions(vault.pii);
+  return members.length ? `vault ${vault.id}: PII policy has members this vmem cannot enforce (${members.slice(0, 8).join(", ")}); write with the newer vmem that wrote the policy` : undefined;
+}
+export function parseVault(value: unknown, tolerant = false): VaultSpec {
+  const keys = ["id", "path", "kind", "write", "pii", "remote", "registry"], v = object(value, keys, "vault", tolerant);
   const id = string(v.id, "vault.id");
   if (!/^[a-z][a-z0-9-]{0,31}$/.test(id)) throw new Error("vault.id: invalid id");
   if (v.kind !== "personal" && v.kind !== "org") throw new Error("vault.kind: expected personal or org");
   if (v.write !== "mcp" && v.write !== "cli" && v.write !== "none") throw new Error("vault.write: expected mcp, cli or none");
-  const result: VaultSpec = { id, path: absolute(v.path, "vault.path"), kind: v.kind, write: v.write };
-  if (v.pii !== undefined) result.pii = parsePii(v.pii);
+  const result: VaultSpec = { ...unknown(v, keys, tolerant), id, path: absolute(v.path, "vault.path"), kind: v.kind, write: v.write };
+  if (v.pii !== undefined) result.pii = parsePii(v.pii, tolerant);
   if (v.remote !== undefined) result.remote = string(v.remote, "vault.remote");
   if (v.registry !== undefined) result.registry = absolute(v.registry, "vault.registry");
   return result;
 }
 export function parseConfig(value: unknown): VmemConfig {
-  const raw = object(value, ["home", "vaults", "denyPaths", "piiPatterns"], "config");
+  const keys = ["version", "home", "vaults", "denyPaths", "piiPatterns"];
+  const version = (value as Record<string, unknown> | null)?.version;
+  if (version !== undefined && (!Number.isSafeInteger(version) || (version as number) < 1)) throw new Error("config.version: expected a positive integer");
+  const tolerant = newerFormat(value), raw = object(value, keys, "config", tolerant);
+  const stamp = version === undefined ? {} : { version: version as number };
   if (raw.home !== undefined) {
-    if (Object.keys(raw).length !== 1) throw new Error("config: home pointer must not contain vaults or policy");
-    return { home: absolute(raw.home, "config.home"), vaults: [] };
+    if (["vaults", "denyPaths", "piiPatterns"].some(key => raw[key] !== undefined)) throw new Error("config: home pointer must not contain vaults or policy");
+    return { ...unknown(raw, keys, tolerant), ...stamp, home: absolute(raw.home, "config.home"), vaults: [] };
   }
   if (!Array.isArray(raw.vaults)) throw new Error("config.vaults: expected array");
-  const vaults = raw.vaults.map(parseVault);
+  const vaults = raw.vaults.map(item => parseVault(item, tolerant));
   if (new Set(vaults.map(v => v.id)).size !== vaults.length) throw new Error("config: duplicate vault id");
   if (new Set(vaults.map(v => v.path)).size !== vaults.length) throw new Error("config: duplicate vault path");
   const denyPaths = strings(raw.denyPaths, "denyPaths"), piiPatterns = strings(raw.piiPatterns, "piiPatterns");
   for (const pattern of piiPatterns ?? []) {
     try { new RegExp(pattern); } catch { throw new Error("piiPatterns: invalid regular expression"); }
   }
-  return { vaults, ...(denyPaths ? { denyPaths } : {}), ...(piiPatterns ? { piiPatterns } : {}) };
+  return { ...unknown(raw, keys, tolerant), ...stamp, vaults, ...(denyPaths ? { denyPaths } : {}), ...(piiPatterns ? { piiPatterns } : {}) };
 }
 /** Bounded descriptor read: reject links, devices and oversized/growing files. */
 export function readConfig(home: string): VmemConfig {

package/src/log-format.ts

@@ -1,7 +1,8 @@
 import { localDate } from "./local-date.ts";
 import { screenContent } from "./write-validation.ts";
-import { parsePii } from "./config.ts";
-function validPii(value: unknown): boolean { try { parsePii(value); return true; } catch { return false; } }
+import { newerFormat, parsePii } from "./config.ts";
+/** Known fields are always validated; members unknown to this build are accepted only from a newer-format config. */
+function validPii(value: unknown, config: unknown): boolean { try { parsePii(value, newerFormat(config)); return true; } catch { return false; } }
 import type { LogContext, LogEvent } from "./log-types.ts";
 import type { WriteIssue } from "./write-types.ts";
 
@@ -34,7 +35,7 @@ export function formatLogEvent(event: LogEvent, context: LogContext): { line?: s
   }
   if ((context.channel !== undefined && context.channel !== "cli" && context.channel !== "mcp") ||
       !record(context.vault) || !["personal", "org"].includes(context.vault.kind) ||
-      (context.vault.pii !== undefined && !validPii(context.vault.pii)) ||
+      (context.vault.pii !== undefined && !validPii(context.vault.pii, context.config)) ||
       !record(context.config) || !Array.isArray(context.config.vaults) ||
       (context.config.piiPatterns !== undefined && (!Array.isArray(context.config.piiPatterns) || context.config.piiPatterns.some(value => typeof value !== "string"))) ||
       (context.now !== undefined && !(context.now instanceof Date)) ||

package/src/registry.ts

@@ -2,7 +2,7 @@ import { closeSync, constants, fsyncSync, mkdirSync, openSync, readdirSync, read
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
-import { CONFIG_FILE, MAX_CONFIG_BYTES, parseConfig, parsePii, parseVault, readConfig, type VaultSpec, type VmemConfig } from "./config.ts";
+import { CONFIG_FILE, MAX_CONFIG_BYTES, parseConfig, parsePii, parseVault, piiExtensions, readConfig, type VaultSpec, type VmemConfig } from "./config.ts";
 import { loosenedCells, piiPolicy, piiShorthand } from "./pii.ts";
 export const LOCK_FILE = "config.lock";
 const TEMP = /^\.config-[0-9a-f-]{36}\.tmp$/;
@@ -178,6 +178,9 @@ export function setVaultPii(home: string, id: string, value: unknown, confirm =
     if (!vault) throw new Error(`${join(home, CONFIG_FILE)}: unknown vault id ${id}`);
     const before = piiPolicy(vault);
     if (next === undefined) return { vault: id, pii: piiShorthand(vault), piiPolicy: before };
+    // A replacement would drop policy members a newer vmem wrote and this build cannot carry over.
+    const extensions = piiExtensions(vault.pii);
+    if (extensions.length) throw new Error(`vault ${id}: PII policy has members this vmem does not know (${extensions.slice(0, 8).join(", ")}); change it with the newer vmem that wrote them`);
     const updated: VaultSpec = { ...vault, pii: next }, after = piiPolicy(updated);
     const loosened = loosenedCells(before, after), changed = JSON.stringify(before) !== JSON.stringify(after);
     if (confirm && changed) vault.pii = next;

package/src/setup.ts

@@ -1,4 +1,4 @@
-import { chmodSync, closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -15,7 +15,8 @@ export interface McpEntry { command: string; args: string[] }
 interface HostFile { target: SetupTarget; file: string; format: "json" | "toml"; key: string }
 export interface SetupAction { target: SetupTarget; file: string; change: "add" | "replace" | "unchanged" | "restore" | "remove" | "refused" | "none"; reason?: string }
 export interface ConsoleAction { file: string; module: string; change: "add" | "replace" | "unchanged" | "remove" | "none" | "refused"; reason?: string }
-export interface SetupReport { mode: SetupMode; applied: boolean; entry: McpEntry; actions: SetupAction[]; console?: ConsoleAction; notes: string[] }
+export interface SetupReport { mode: SetupMode; applied: boolean; entry: McpEntry; root?: InstallRoot; actions: SetupAction[]; console?: ConsoleAction; notes: string[] }
+export interface InstallRoot { path: string; version: string }
 interface Receipt { version: 1; target: SetupTarget; file: string; existed: boolean; keyExisted?: boolean; prior: unknown; priorToml?: string[]; installed: McpEntry }
 
 function hosts(env: NodeJS.ProcessEnv, cwd: string): Record<SetupTarget, HostFile> {
@@ -37,12 +38,27 @@ function hosts(env: NodeJS.ProcessEnv, cwd: string): Record<SetupTarget, HostFil
     agy: { target: "agy", file: join(resolve(cwd), ".agents", "mcp_config.json"), format: "json", key: "mcpServers" },
   };
 }
-function readText(file: string): string | null {
-  let stat;
-  try { stat = lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
-  if (!stat.isFile()) throw new Error(`${file}: expected a plain file (links are refused)`);
-  if (stat.size > MAX_HOST_CONFIG) throw new Error(`${file}: exceeds 4 MiB`);
-  return readFileSync(file, "utf8");
+const MAX_PACKAGE_JSON = 64 * 1024;
+/** Bounded plain-file read on one descriptor: links, FIFOs and other non-regular files are refused, never read. */
+function readText(file: string, max = MAX_HOST_CONFIG): string | null {
+  let fd: number;
+  try { fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    if (code === "ELOOP") throw new Error(`${file}: expected a plain file (links are refused)`);
+    throw error;
+  }
+  try {
+    const stat = fstatSync(fd), limit = max >= 1024 * 1024 ? `${max / 1024 / 1024} MiB` : `${max / 1024} KiB`;
+    if (!stat.isFile()) throw new Error(`${file}: expected a plain file (links are refused)`);
+    if (stat.size > max) throw new Error(`${file}: exceeds ${limit}`);
+    const buffer = Buffer.alloc(max + 1);
+    let size = 0, n: number;
+    while (size < buffer.length && (n = readSync(fd, buffer, size, buffer.length - size, null)) > 0) size += n;
+    if (size > max) throw new Error(`${file}: exceeds ${limit}`);
+    return buffer.subarray(0, size).toString("utf8");
+  } finally { closeSync(fd); }
 }
 function atomicWrite(file: string, text: string | null): void {
   if (text === null) { unlinkSync(file); return; }
@@ -155,21 +171,42 @@ export function stableRuntime(execPath: string = process.execPath, onPath: strin
   if (!onPath || !isAbsolute(onPath)) return execPath;
   try { return realpathSync(onPath) === realpathSync(execPath) ? onPath : execPath; } catch { return execPath; }
 }
-export function defaultEntry(): McpEntry {
-  return { command: stableRuntime(), args: ["--smol", fileURLToPath(new URL("../bin/vmem.js", import.meta.url)), "mcp"] };
+/** The root of the running install: the directory that holds `bin/`, `src/` and `package.json`. */
+const OWN_ROOT = fileURLToPath(new URL("..", import.meta.url));
+export function defaultEntry(root: string = OWN_ROOT): McpEntry {
+  return { command: stableRuntime(), args: ["--smol", join(root, "bin", "vmem.js"), "mcp"] };
+}
+/**
+ * A vault-mem install root to register, such as `<install>/releases/<version>/`. It is resolved to its real
+ * path, so a `current` link registers the release it names and an upgrade beside it never changes what running
+ * hosts load.
+ */
+export function installRoot(root: string): InstallRoot {
+  if (!isAbsolute(root)) throw new Error("setup: --root must be an absolute path");
+  let path: string, text: string | null, pkg: { name?: unknown; version?: unknown };
+  try { path = realpathSync(root); text = readText(join(path, "package.json"), MAX_PACKAGE_JSON); }
+  catch (error) { throw new Error(`setup: ${root}: package.json is not readable (${error instanceof Error ? error.message : "read failed"})`); }
+  if (text === null) throw new Error(`setup: ${root} has no package.json`);
+  try { pkg = JSON.parse(text); } catch { throw new Error(`setup: ${root}: package.json is not valid JSON`); }
+  if (!pkg || typeof pkg !== "object") throw new Error(`setup: ${root} is not a vault-mem install root`);
+  if (pkg.name !== "@staix/vault-mem" || typeof pkg.version !== "string") throw new Error(`setup: ${root} is not a vault-mem install root`);
+  try { if (!statSync(join(path, "bin", "vmem.js")).isFile()) throw new Error(); }
+  catch { throw new Error(`setup: ${root} has no bin/vmem.js`); }
+  return { path, version: pkg.version };
 }
 /**
  * Plan, apply or undo vmem MCP registration. Dry-run writes nothing. Apply is idempotent, edits only
  * the `vmem` server entry and records the prior value. Undo restores that prior value only while the
  * entry is still the one setup installed; a later user edit is left alone and reported as refused.
  */
-export function runSetup(target: string, mode: SetupMode, options: { home: string; env?: NodeJS.ProcessEnv; cwd?: string; entry?: McpEntry }): SetupReport {
-  const env = options.env ?? process.env, entry = options.entry ?? defaultEntry();
+export function runSetup(target: string, mode: SetupMode, options: { home: string; env?: NodeJS.ProcessEnv; cwd?: string; entry?: McpEntry; root?: string }): SetupReport {
+  const env = options.env ?? process.env, root = options.root === undefined ? undefined : installRoot(options.root);
+  const entry = options.entry ?? defaultEntry(root?.path);
   if (target !== "all" && !(SETUP_TARGETS as readonly string[]).includes(target)) throw new Error(`setup: unknown target ${target}; use ${SETUP_TARGETS.join("|")}|all`);
   if (!isAbsolute(entry.command) || entry.args.some(arg => arg.includes("\0"))) throw new Error("setup: MCP command must be absolute");
   const table = hosts(env, options.cwd ?? process.cwd());
   const targets = target === "all" ? SETUP_TARGETS.filter(t => t !== "agy") : [target as SetupTarget];
-  const report: SetupReport = { mode, applied: false, entry, actions: [], notes: [
+  const report: SetupReport = { mode, applied: false, entry, ...(root ? { root } : {}), actions: [], notes: [
     "Registers the stdio server `vmem mcp`; restart the host session to load it.",
     "Writes the acon console plugin manifest ($AGENTHUB_HOME/console/plugins/vmem.json); re-run setup after upgrading vmem.",
   ] };
@@ -215,16 +252,16 @@ export function runSetup(target: string, mode: SetupMode, options: { home: strin
       action.change = "refused"; action.reason = error instanceof Error ? error.message : "setup failed";
     }
   }
-  report.console = consoleManifest(mode, env);
+  report.console = consoleManifest(mode, env, root?.path);
   report.applied = mode !== "dry-run" && [...report.actions, report.console].some(a => !["none", "unchanged", "refused"].includes(a.change));
   return report;
 }
 
 /** The acon plugin manifest: `{api, tool, module, sha256}` in the family home, dir 0700 and file 0600 as acon requires. */
-export function consoleManifest(mode: SetupMode, env: NodeJS.ProcessEnv = process.env): ConsoleAction {
+export function consoleManifest(mode: SetupMode, env: NodeJS.ProcessEnv = process.env, root: string = OWN_ROOT): ConsoleAction {
   const family = env.AGENTHUB_HOME?.trim() ? resolve(env.AGENTHUB_HOME) : join(env.HOME?.trim() || homedir(), ".agenthub");
   const dir = join(family, "console", "plugins"), file = join(dir, "vmem.json");
-  const module = fileURLToPath(new URL("./ui/plugin.ts", import.meta.url));
+  const module = join(root, "src", "ui", "plugin.ts");
   const action: ConsoleAction = { file, module, change: "none" };
   try {
     const next = { api: 1, tool: "vmem", module, sha256: createHash("sha256").update(readFileSync(module)).digest("hex") };

package/src/sync.ts

@@ -52,19 +52,30 @@ function gitIn(cwd: string, env: NodeJS.ProcessEnv): Git {
     return out;
   };
 }
+/**
+ * insteadOf/pushInsteadOf rules that could rewrite any of `urls` or origin's configured URLs. Git applies a rule
+ * when its value is a literal prefix of the configured URL, so the raw config values are checked too; this covers
+ * an explicit pushurl, whose rewrite git does not report. A rule without a value is treated as matching.
+ */
+function applicableRewrites(lines: (args: string[]) => string[], urls: string[]): string[] {
+  const all = [...urls, ...lines(["config", "--get-all", "remote.origin.url"]), ...lines(["config", "--get-all", "remote.origin.pushurl"])];
+  return lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]).filter(line => {
+    const at = line.indexOf(" "), prefix = at < 0 ? "" : line.slice(at + 1);
+    return !prefix || all.some(url => url.startsWith(prefix));
+  });
+}
 /** Local-only origin validation shared by doctor and sync; never fetches or pushes. */
 export function originCheck(root: string, remote: string, env: NodeJS.ProcessEnv = process.env): { ok: boolean; origin: string | null; fetchUrls: string[]; pushUrls: string[]; issue?: string } {
   const git = gitIn(root, env);
   if (realpathSync(git(["rev-parse", "--show-toplevel"]).stdout.trim()) !== root) throw new Error("vault path is not the root of its git repository");
   const origin = git(["remote", "get-url", "origin"], { allowFail: true });
   const originUrl = origin.status === 0 ? origin.stdout.trim() : null;
-  // Every effective fetch and push URL must be the configured remote; URL rewrites are refused outright
-  // because git does not report pushInsteadOf rewrites of an explicit pushurl.
+  // Every effective fetch and push URL must be the configured remote, and no URL rewrite may apply to it.
   const lines = (args: string[]) => { const out = git(args, { allowFail: true }); return out.status === 0 ? out.stdout.split("\n").map(line => line.trim()).filter(Boolean) : []; };
   const fetchUrls = lines(["remote", "get-url", "--all", "origin"]), pushUrls = lines(["remote", "get-url", "--push", "--all", "origin"]);
-  const rewrites = lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]);
+  const rewrites = applicableRewrites(lines, [remote, ...fetchUrls, ...pushUrls]);
   const ok = originUrl !== null && rewrites.length === 0 && fetchUrls.length > 0 && pushUrls.length > 0 && [...fetchUrls, ...pushUrls].every(url => sameRemote(url, remote));
-  return { ok, origin: originUrl, fetchUrls, pushUrls, ...(!ok ? { issue: originUrl === null ? "repository has no origin remote" : rewrites.length ? "git url insteadOf/pushInsteadOf rewrites are configured; refusing because the push destination cannot be verified" : "an origin fetch or push URL does not match the configured remote; nothing was fetched or pushed" } : {}) };
+  return { ok, origin: originUrl, fetchUrls, pushUrls, ...(!ok ? { issue: originUrl === null ? "repository has no origin remote" : rewrites.length ? `git url rewrite ${rewrites[0]} applies to the vault remote; refusing because the push destination cannot be verified` : "an origin fetch or push URL does not match the configured remote; nothing was fetched or pushed" } : {}) };
 }
 function planned(path: string): boolean { return STAGE_FILES.includes(path) || STAGE_PREFIXES.some(prefix => path.startsWith(prefix)); }
 /** Parse `status --porcelain=v1 -z` into changed paths (renames contribute both sides). */
@@ -141,7 +152,8 @@ export function syncVault(home: string, request: { vault: string; confirm?: bool
       }
     }
     if (!result.commit && (!hasUpstream ? false : git(["rev-list", "--count", `${upstream}..HEAD`]).stdout.trim() === "0")) return { ...result, ok: true, applied: false, pushed: false };
-    if (lines(["remote", "get-url", "--push", "--all", "origin"]).some(url => !sameRemote(url, spec.remote!)) || lines(["config", "--get-regexp", "^url\\..*\\.(insteadof|pushinsteadof)$"]).length) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("REMOTE", "push destination changed before push; nothing was pushed")] };
+    const pushNow = lines(["remote", "get-url", "--push", "--all", "origin"]);
+    if (pushNow.some(url => !sameRemote(url, spec.remote!)) || applicableRewrites(lines, [spec.remote, ...fetchUrls, ...pushNow]).length) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("REMOTE", "push destination changed before push; nothing was pushed")] };
     const push = git(["push", "--quiet", "--porcelain", "origin", `HEAD:refs/heads/${result.branch}`], { allowFail: true });
     if (push.status !== 0) return { ...result, applied: Boolean(result.commit), pushed: false, issues: [issue("PUSH", `push failed: ${push.stderr.trim().split("\n").at(-1)?.slice(0, 300) ?? "error"}; the local commit was kept`)] };
     // Verify the remote really has our head before reporting success.

package/src/tidy.ts

@@ -4,6 +4,7 @@ import { hostname } from "node:os";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import type { VaultSpec, VmemConfig } from "./config.ts";
+import { unenforceablePii } from "./config.ts";
 import { emitFrontmatter, parseFrontmatter } from "./frontmatter.ts";
 import { extractLinks, normalizeTarget } from "./links.ts";
 import { isDenied } from "./platform.ts";
@@ -335,6 +336,8 @@ export function tidyVault(home: string, request: TidyRequest, options: { env?: N
   const config = loadRegistry(home), vault = config.vaults.find(v => v.id === request.vault);
   if (!vault) return { ...result, issues: [issue("V04", "unknown vault id")] };
   if (vault.write === "none" || (request.channel === "mcp" && vault.write !== "mcp")) return { ...result, issues: [issue("POLICY", "vault write policy refuses this channel")] };
+  const unenforceable = unenforceablePii(vault);
+  if (unenforceable) return { ...result, issues: [issue("PII_POLICY", unenforceable)] };
   const root = realpathSync(vault.path);
   if (root !== vault.path || isDenied(root, config.denyPaths)) return { ...result, issues: [issue("V06", "vault path denied or changed")] };
   // The LINT event must land in the vault this run read and wrote, even if the registry is changed meanwhile.

package/src/vault-index.ts

@@ -9,8 +9,13 @@ import { normalizeTarget, noteKey, proseLines, resolveLinks, type LinkNote, type
 
 export const MAX_NOTE_BYTES = 2 * 1024 * 1024;
 export const MAX_RESULTS = 500;
-/** Bump when link resolution changes, so caches written by an older version recompute every link. 2 = path-only. */
-const LINK_RESOLUTION = 2;
+/**
+ * Bump when link resolution changes. 2 = path-only. The index file is named per value, so two installed versions
+ * that resolve links differently keep separate indexes instead of rebuilding each other's links. 0.2.4 and older
+ * share the unversioned `<digest>.sqlite`; the first run of a newer version builds its own file once.
+ */
+export const LINK_RESOLUTION = 2;
+const indexName = (root: string) => `${digest(root)}-links${LINK_RESOLUTION}.sqlite`;
 export const MAX_READ_BYTES = 64 * 1024;
 export interface IndexedNote extends LinkNote { hash: string; description: string; type: string; domain: string }
 export interface NoteReadResult {
@@ -118,7 +123,7 @@ export class VaultIndex {
     if (!options.memory) {
       mkdirSync(cache, { recursive: true, mode: 0o700 });
       if (lstatSync(cache).isSymbolicLink() || !lstatSync(cache).isDirectory()) throw new Error("index: expected plain cache directory");
-      this.file = join(cache, `${digest(this.root)}.sqlite`);
+      this.file = join(cache, indexName(this.root));
       try {
         const fd = openSync(this.file, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
         closeSync(fd);
@@ -136,7 +141,7 @@ export class VaultIndex {
       CREATE TABLE IF NOT EXISTS links (source TEXT NOT NULL, ordinal INTEGER NOT NULL, data TEXT NOT NULL, PRIMARY KEY(source, ordinal));`);
     // Dry runs reuse the derived cache via a readonly connection, then refresh only changed notes in memory.
     if (options.memory) {
-      const file = join(cache, `${digest(this.root)}.sqlite`);
+      const file = join(cache, indexName(this.root));
       let exists = false;
       try { const stat = lstatSync(file); if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("index: expected plain database file"); exists = true; }
       catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }

package/src/vault-log.ts

@@ -8,6 +8,7 @@ import { formatLogEvent, LOG_TYPES } from "./log-format.ts";
 import type { LogBinding, LogContext, LogReadOptions, LogReadResult, LogReceipt, LogRequest } from "./log-types.ts";
 import type { WriteIssue } from "./write-types.ts";
 import type { VaultSpec, VmemConfig } from "./config.ts";
+import { unenforceablePii } from "./config.ts";
 export const LOG_LOCK = "log.lock";
 export const MAX_LOG_READ_BYTES = 32 * 1024 * 1024;
 export const LARGE_LOG_LINES = 20000;
@@ -60,6 +61,8 @@ function context(home: string, id: string, channel: "cli" | "mcp" | undefined, w
   if (!vault) refuse("L09", "unknown vault id");
   if (channel !== undefined && channel !== "cli" && channel !== "mcp") refuse("POLICY", "unknown log channel");
   if (write && (vault.write === "none" || (channel === "mcp" && vault.write !== "mcp"))) refuse("POLICY", "vault write policy refuses log append");
+  const unenforceable = write ? unenforceablePii(vault) : undefined;
+  if (unenforceable) refuse("PII_POLICY", unenforceable);
   if (realpathSync(vault.path) !== vault.path || !lstatSync(vault.path).isDirectory()) refuse("L09", "registered vault path changed");
   if (isDenied(join(vault.path, "log"), config.denyPaths)) refuse("V06", "log path is denied");
   return { vault, config, channel, ...(write && vault.registry ? { projectIds: registryIds(vault.registry, config.denyPaths) } : {}) };

package/src/write-validation.ts

@@ -28,7 +28,7 @@ const KEYS = new Set([
 export const TYPED_KEYS: Readonly<Record<string, string>> = { decided_at: "decision", decided_by: "decision", email: "person", phone: "person" };
 export const SCHEMA_KEYS: ReadonlySet<string> = KEYS;
 const WIKI_FIELDS = ["topics", "project", "superseded_by", "supersedes", "source_ref"];
-// Exact regex set from @staix/agent-mem v0.11.0 src/memory/screen.ts; parity-tested against its root export.
+// Exact regex set from @staix/agent-mem v0.17.0 src/memory/screen.ts; parity-tested against its root export.
 const SECRETS = [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, /\bAKIA[0-9A-Z]{16}\b/, /\bgh[pousr]_[A-Za-z0-9]{30,}/, /\bgithub_pat_[A-Za-z0-9_]{40,}/, /\bsk-[A-Za-z0-9_-]{20,}/,
   /\bxox[abprs]-[A-Za-z0-9-]{10,}/, /\bAIza[0-9A-Za-z_-]{35}\b/, /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/, /\b(?:password|passwd|secret|api[_-]?key|token)\s*[:=]\s*\S{8,}/i];
 export const SECRET_PATTERNS: readonly RegExp[] = SECRETS;

package/src/writer.ts

@@ -12,6 +12,7 @@ import { canonicalPath, isDenied } from "./platform.ts";
 import { moveSourcePath, notePath, planOperation, refuse, WriteRefusal } from "./write-operations.ts";
 import { MAX_REPORT_BYTES, validateWrite } from "./write-validation.ts";
 import type { PiiSurface } from "./config.ts";
+import { unenforceablePii } from "./config.ts";
 import type { LogBinding } from "./log-types.ts";
 import type { ChangeReceipt, PlannedChange, WriteIssue, WriteReceipt, WriteRequest } from "./write-types.ts";
 export const MUTATION_LOCK = "mutation.lock";
@@ -129,6 +130,8 @@ export function applyWrite(home: string, request: WriteRequest, options: { env?:
     const config = loadRegistry(home), vault = config.vaults.find(value => value.id === request.vault);
     if (options.binding && !matchesBinding(config, request.vault, options.binding)) refuse("VAULT_DRIFT", "vault identity or policy changed since the run started; nothing written");
     if (!vault) refuse("V04", "unknown vault id");
+    const unenforceable = unenforceablePii(vault);
+    if (unenforceable) refuse("PII_POLICY", unenforceable);
     if (request.operation.op !== "check" && (vault.write === "none" || (request.channel === "mcp" && vault.write !== "mcp"))) refuse("POLICY", "vault write policy refuses this channel");
     root = realpathSync(vault.path);
     if (root !== vault.path || isDenied(root, config.denyPaths)) refuse("V06", "vault path denied or changed");