zikaron 0.3.1__tar.gz → 0.3.2__tar.gz

{zikaron-0.3.1 → zikaron-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zikaron
-Version: 0.3.1
+Version: 0.3.2
 Summary: Memory and searchable project knowledge for coding agents
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/nathan-shapiro/Zikaron
@@ -61,11 +61,12 @@ yes, it is out of scope. That store is for what cost somebody time to discover,
 be discovered again by the next agent, at full price. A knowledge base has no such test — it is
 whatever corpus you point it at.
 
-**And, on request, two edit guards for Claude Code** — independent of both stores. One refuses a
-find-replace edit to an authored file (`sed -i`, an inline script, a heredoc into the file) and
-points the agent at `Read` and `Edit`; the other reminds it, after each edit, to re-read what it
-changed. See [Edit guards](#edit-guards-claude-code-on-request); a project may install the memory
-store, the guards, or both.
+**And, on request, guards for Claude Code** — two deterministic hooks, independent of both stores.
+One refuses two kinds of command: a find-replace edit to an authored file (`sed -i`, an inline
+script, a heredoc into the file), pointing the agent at `Read` and `Edit`, and a `pgrep -f` or
+`pkill -f` whose pattern matches the shell running it. The other reminds the agent, after each
+edit, to re-read what it changed. See [Guards](#guards-claude-code-on-request); a project may install the memory store, the
+guards, or both.
 
 It runs entirely on your machine: SQLite databases under `.zikaron/`, a local embedding model, and a
 small background service on a Unix socket. **Zikaron reaches the network for exactly one thing** —
@@ -130,7 +131,7 @@ reads which one it is addressing before it reads a description. Consolidation ne
 | **service** | A long-running process per project. Holds the embedding model in memory and the databases open, and answers requests over a Unix socket. Starts itself when needed and stops itself when idle. |
 | **MCP server** | Translates the agent's tool calls into requests to the service. One process per agent instance; loads no model. |
 | **hook** | A single-shot executable your agent runs on start, before each message, and — under Claude Code — when it spawns a subagent. Deliberately tiny; loads no model and never touches the databases directly. |
-| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each Bash call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
+| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each `Bash` or `Monitor` call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
 | **indexer** | A detached process started per knowledge-base build — by the service on every `add`/`refresh`, whether an agent asked or you did, or by you running the foreground command a build result prints. It outlives the call that started it, loads a model, saturates a core for a minute or more, and exits when the build finishes. If you see one in `ps`, that is a corpus building, not a runaway. |
 
 The service exists for one measured reason: loading the embedding model costs about **780 ms**, and
@@ -242,7 +243,7 @@ cd /path/to/your/project
 zikaron install --project . --harness claude-code    # or: --harness kiro
 ```
 
-Under Claude Code, `--components` adds the [edit guards](#edit-guards-claude-code-on-request), or
+Under Claude Code, `--components` adds the [guards](#guards-claude-code-on-request), or
 installs them alone; without it you get the memory store only, exactly as before:
 
 ```bash
@@ -353,8 +354,8 @@ and under **Claude Code**:
 
 With `--components guards` the install writes `.claude/settings.local.json` alone, and in it only
 hooks: the session-start and per-subagent hooks, which carry a short note about the guards, and the
-two guard hooks — before each Bash call, after each edit. No server, no approval key, no
-consolidator. With `--components both` you get all of the above together, and the start hooks carry
+two guard hooks — before each `Bash` or `Monitor` call, after each edit. No server, no approval
+key, no consolidator. With `--components both` you get all of the above together, and the start hooks carry
 the write policy and the guards' note.
 
 **`settings.local.json`, not `settings.json`**, and it matters if you commit your settings: the hook
@@ -474,10 +475,10 @@ guard, the receipts and the lease are untouched — but an unauthorized consolid
 tokens and could write a poorly-judged long-term record. `permissions.deny` is **not** the fix: it is
 global and unregisters the tool, after which the consolidator itself refuses to start.
 
-### Edit guards (Claude Code, on request)
+### Guards (Claude Code, on request)
 
-`--components guards` (or `both`) installs two deterministic hooks that hold an agent to two rules,
-with no model and no store behind them (`design/edit-guards.md`):
+`--components guards` (or `both`) installs two deterministic hooks that hold an agent to three
+rules, with no model and no store behind them (`design/guards.md`):
 
 - **A find-replace edit to an authored file is refused** — `sed -i`, `perl -pi`, an inline Python
   or node script that writes a file, a heredoc or `echo` redirected into one, and a script under
@@ -489,6 +490,15 @@ with no model and no store behind them (`design/edit-guards.md`):
   re-read of the edited material once that file's editing is done. A Bash command gets no such
   reminder, so when the agent overrides a refusal, the guard's acknowledgement names what the
   command changes and asks for that re-read instead.
+- **A `pgrep -f` or `pkill -f` whose pattern matches its own command is refused.** Claude Code
+  runs each command inside a shell whose command line carries the command's text, so on Linux such
+  a pattern matches that shell: `pkill` kills it, and `pgrep` always finds it, so a check for a
+  process that has exited never sees it gone. The refusal shows where the pattern matched and gives
+  the fix: `-A`, where `pgrep` has it, or a bracketed character (`[m]onth_monitor.py`). On macOS,
+  whose `pgrep` already leaves out the shell, only `-a` brings it back.
+
+Both refusals judge `Bash` and `Monitor` commands alike. An install made by an earlier version
+judges `Bash` alone; re-running it with the same `--components` adds `Monitor`.
 
 They are not a security boundary: a script the guard reads is one run from a scratch directory,
 and a script anywhere else — one of the project's own programs — is never read, by design. A guard
@@ -518,7 +528,7 @@ usually shows something else: told the rule when its session starts, it reaches
 | `--model <id>` | the consolidator's model (default: `claude-sonnet-5` under kiro, `sonnet` under Claude Code) |
 | `--format {object,array}` | **kiro only.** Which hook format to write when the target config has none yet |
 | `--no-trust-tools` | do not pre-approve Zikaron's own tools, so every Zikaron tool call asks permission |
-| `--components {memory,guards,both}` | what to install: the memory store (the default), the edit guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
+| `--components {memory,guards,both}` | what to install: the memory store (the default), the guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
 | `--force` | replace a symlink at a shipped path, and overwrite entries wired to a different Zikaron install that would otherwise be refused. It also stops merging: a server entry — `.mcp.json`'s, or kiro's `mcpServers` — is replaced **whole**, so a key you added to Zikaron's own entry goes, and under Claude Code a Zikaron hook group is replaced whole, so a hook of your own inside it goes too. Both are named in the output |
 
 Both hook formats kiro accepts are supported, and a config that already uses one keeps it: kiro
@@ -565,7 +575,7 @@ write policy goes into the model's context, not to your terminal. Then, from the
 # a service should be running for this project after your first message
 pgrep -af zikaron.service.main
 
-# one line per hook failure, write-policy-override note, or session/environment mismatch; absent means none happened
+# one line per hook failure, missed cold start, write-policy-override note, or session/environment mismatch; absent means none happened
 cat .zikaron/hook.log
 ```
 
@@ -756,9 +766,11 @@ it is `0600` or `0700`. The **installer** also writes harness config — the fil
   config.toml        your per-project overrides, if you wrote any
   service.log        the background service: startup, resolved config, errors, why it stopped,
                      any request running longer than 30 s, and the stack dumps below
-  hook.log           one line per hook failure, write-policy-override note, or session/environment
-                     mismatch. Absent means none happened. Not every line is a failure: an override
-                     that is used but exceeds the injection budget is printed anyway and logged
+  hook.log           one line per hook failure, missed cold start, write-policy-override note, or
+                     session/environment mismatch. Absent means none happened. Not every line is a
+                     failure: `starting` is a message that arrived while the service was still
+                     starting, and an override that is used but exceeds the injection budget is
+                     printed anyway and logged
   warmup.log         the small helper that warms the service when a session starts
   write-policy.md    your policy override, if you wrote one
 ```
@@ -771,19 +783,23 @@ shared by every project you use Zikaron in, under `$XDG_CACHE_HOME/zikaron/model
 A copy inside each project would duplicate it for bytes that are identical by construction, since the
 version fetched is pinned. Removing a project does not remove it; [Uninstall](#uninstall) says how.
 
-The second is the service's Unix socket, which with its lock file sits in
-`$XDG_RUNTIME_DIR/zikaron/` — or `/tmp/zikaron-<uid>/` where that variable is unset, which is every
-Mac — named by a hash of the store's path, `0600` inside a `0700` directory. A socket belongs on a
-runtime filesystem rather than in your project. **Under Claude
-Code**, an over-large consolidator result also spills to a file beside them, carrying that group's
-record prose verbatim and named by the same store hash; it is deleted when the consolidator asks for
-its next group — or, if that process is killed first, by the next one that starts. It is the one
-copy of memory text that lives outside `.zikaron/`, which is why the erasure procedure under
-[Secrets](#secrets) removes it by hand. Nothing spills under kiro.
+The second is the service's Unix socket. It sits in `$XDG_RUNTIME_DIR/zikaron/` — or
+`/tmp/zikaron-<uid>/` where that variable is unset, which is every Mac — named by a hash of the
+store's path, `0600` inside a `0700` directory, beside two lock files: one clients take while they
+start the service, and one the service holds while it has the store open. A socket belongs on a
+runtime filesystem rather than in your project. **Under Claude Code**, an over-large consolidator
+result also spills to a file beside them, carrying that group's record prose verbatim and named by
+the same store hash; it is deleted when the consolidator asks for its next group — or, if that
+process is killed first, by the next one that starts. It is the one copy of memory text that lives
+outside `.zikaron/`, which is why the erasure procedure under [Secrets](#secrets) removes it by hand.
+Nothing spills under kiro.
 
 **What `service.log` tells you about a service that stopped, or stopped answering.** A clean stop
-writes one `stopping: reason=…` line: `idle`, `store_replaced`, `encoder_failed`, or `sigterm` /
-`sigint` when it was asked to stop. A request still running after the 30 s idle poll is logged as
+writes one `stopping: reason=…` line: `idle`, `store_replaced`, `socket_lost` (its socket file was
+removed, so nothing could reach it), `encoder_failed`, or `sigterm` / `sigint` when it was asked to
+stop. A start that found another service already holding the store writes `not starting:
+reason=another_service` and exits, leaving that one to serve it. A request still running after the
+30 s idle poll is logged as
 `long request: method=… session=… age=…` on every poll until it ends — `session=unresolved` if it
 never got that far. Two signals write a dump without stopping the service: `kill -USR2 <pid>` writes
 the requests in flight and every asyncio task's stack, and `kill -USR1 <pid>` writes every thread's
@@ -792,8 +808,8 @@ raw text, without the timestamp and `pid=` every other line carries.
 
 Two notes on reading the rest. `memory.db` can look implausibly small while `memory.db-wal` is large —
 that is normal for a database held open by the service, since recent writes live in the log until a
-checkpoint; the files together are the store. And `hook.log` records only a fixed failure label and an
-error code, never your prompt or a memory's text, so it cannot hold a leaked secret.
+checkpoint; the files together are the store. And `hook.log` records only fixed labels and an error
+code, never your prompt or a memory's text, so it cannot hold a leaked secret.
 
 There is one more log that is not a file: an event table inside `memory.db`. It records what happened
 on every **memory** read and write — used to measure whether the write policy is working, and kept in
@@ -813,6 +829,16 @@ Zikaron is built to fail quietly rather than get in your way. A hook that cannot
 prints a short note asking the agent to tell you, writes one line to `hook.log`, and exits cleanly. It
 never blocks your message, and it never reads the store directly.
 
+The service stops itself after a stretch of idleness, and the next message starts it again. That
+message waits a few seconds longer — the hook allows a start more time than a running service — and
+if the start still is not finished, the message goes without memories and the agent is told so, without
+being asked to report it. `hook.log` records that as `starting`, followed by what the hook was still
+waiting on — `lock` or `poll` before the service answered, or the lateness of its answer after — and
+memories return once it has started, usually with the next message. A run of `starting` lines means
+starts are slower than the hook allows, not that the service is broken; a start that never finishes is
+reported as `transport` once it has gone a minute without a sign of life — which a first run still
+fetching its model over a slow link can also do, until it finishes.
+
 **Run `zikaron doctor` first for anything that smells environmental** — no search results at all, a
 service that will not start, an MCP server that dies on contact. It checks the things about this
 machine that can stop Zikaron working and names what to change for each. The table below is for
@@ -921,7 +947,7 @@ than deleted, because both hold settings that are not Zikaron's. **All three set
 the install writes three** — leaving `enabledMcpjsonServers` behind names two servers that no longer
 exist, which loads nothing and breaks nothing but is not an uninstall.
 
-**The edit guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
+**The guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
 `PostToolUse` hook groups whose command is `zikaron-guard`, and the `SessionStart` and
 `SubagentStart` groups whose command is `zikaron-hook`. To keep the memory store and drop only the
 guards, re-running the installer will not do it — an install never removes a selection — so delete

{zikaron-0.3.1 → zikaron-0.3.2}/README.md

@@ -32,11 +32,12 @@ yes, it is out of scope. That store is for what cost somebody time to discover,
 be discovered again by the next agent, at full price. A knowledge base has no such test — it is
 whatever corpus you point it at.
 
-**And, on request, two edit guards for Claude Code** — independent of both stores. One refuses a
-find-replace edit to an authored file (`sed -i`, an inline script, a heredoc into the file) and
-points the agent at `Read` and `Edit`; the other reminds it, after each edit, to re-read what it
-changed. See [Edit guards](#edit-guards-claude-code-on-request); a project may install the memory
-store, the guards, or both.
+**And, on request, guards for Claude Code** — two deterministic hooks, independent of both stores.
+One refuses two kinds of command: a find-replace edit to an authored file (`sed -i`, an inline
+script, a heredoc into the file), pointing the agent at `Read` and `Edit`, and a `pgrep -f` or
+`pkill -f` whose pattern matches the shell running it. The other reminds the agent, after each
+edit, to re-read what it changed. See [Guards](#guards-claude-code-on-request); a project may install the memory store, the
+guards, or both.
 
 It runs entirely on your machine: SQLite databases under `.zikaron/`, a local embedding model, and a
 small background service on a Unix socket. **Zikaron reaches the network for exactly one thing** —
@@ -101,7 +102,7 @@ reads which one it is addressing before it reads a description. Consolidation ne
 | **service** | A long-running process per project. Holds the embedding model in memory and the databases open, and answers requests over a Unix socket. Starts itself when needed and stops itself when idle. |
 | **MCP server** | Translates the agent's tool calls into requests to the service. One process per agent instance; loads no model. |
 | **hook** | A single-shot executable your agent runs on start, before each message, and — under Claude Code — when it spawns a subagent. Deliberately tiny; loads no model and never touches the databases directly. |
-| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each Bash call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
+| **guard** | Claude Code only, installed on request: a single-shot executable the harness runs before each `Bash` or `Monitor` call and after each edit. Regular expressions over the call, plus one bounded read of a script the call runs from a scratch directory — no model, no service, no store. |
 | **indexer** | A detached process started per knowledge-base build — by the service on every `add`/`refresh`, whether an agent asked or you did, or by you running the foreground command a build result prints. It outlives the call that started it, loads a model, saturates a core for a minute or more, and exits when the build finishes. If you see one in `ps`, that is a corpus building, not a runaway. |
 
 The service exists for one measured reason: loading the embedding model costs about **780 ms**, and
@@ -213,7 +214,7 @@ cd /path/to/your/project
 zikaron install --project . --harness claude-code    # or: --harness kiro
 ```
 
-Under Claude Code, `--components` adds the [edit guards](#edit-guards-claude-code-on-request), or
+Under Claude Code, `--components` adds the [guards](#guards-claude-code-on-request), or
 installs them alone; without it you get the memory store only, exactly as before:
 
 ```bash
@@ -324,8 +325,8 @@ and under **Claude Code**:
 
 With `--components guards` the install writes `.claude/settings.local.json` alone, and in it only
 hooks: the session-start and per-subagent hooks, which carry a short note about the guards, and the
-two guard hooks — before each Bash call, after each edit. No server, no approval key, no
-consolidator. With `--components both` you get all of the above together, and the start hooks carry
+two guard hooks — before each `Bash` or `Monitor` call, after each edit. No server, no approval
+key, no consolidator. With `--components both` you get all of the above together, and the start hooks carry
 the write policy and the guards' note.
 
 **`settings.local.json`, not `settings.json`**, and it matters if you commit your settings: the hook
@@ -445,10 +446,10 @@ guard, the receipts and the lease are untouched — but an unauthorized consolid
 tokens and could write a poorly-judged long-term record. `permissions.deny` is **not** the fix: it is
 global and unregisters the tool, after which the consolidator itself refuses to start.
 
-### Edit guards (Claude Code, on request)
+### Guards (Claude Code, on request)
 
-`--components guards` (or `both`) installs two deterministic hooks that hold an agent to two rules,
-with no model and no store behind them (`design/edit-guards.md`):
+`--components guards` (or `both`) installs two deterministic hooks that hold an agent to three
+rules, with no model and no store behind them (`design/guards.md`):
 
 - **A find-replace edit to an authored file is refused** — `sed -i`, `perl -pi`, an inline Python
   or node script that writes a file, a heredoc or `echo` redirected into one, and a script under
@@ -460,6 +461,15 @@ with no model and no store behind them (`design/edit-guards.md`):
   re-read of the edited material once that file's editing is done. A Bash command gets no such
   reminder, so when the agent overrides a refusal, the guard's acknowledgement names what the
   command changes and asks for that re-read instead.
+- **A `pgrep -f` or `pkill -f` whose pattern matches its own command is refused.** Claude Code
+  runs each command inside a shell whose command line carries the command's text, so on Linux such
+  a pattern matches that shell: `pkill` kills it, and `pgrep` always finds it, so a check for a
+  process that has exited never sees it gone. The refusal shows where the pattern matched and gives
+  the fix: `-A`, where `pgrep` has it, or a bracketed character (`[m]onth_monitor.py`). On macOS,
+  whose `pgrep` already leaves out the shell, only `-a` brings it back.
+
+Both refusals judge `Bash` and `Monitor` commands alike. An install made by an earlier version
+judges `Bash` alone; re-running it with the same `--components` adds `Monitor`.
 
 They are not a security boundary: a script the guard reads is one run from a scratch directory,
 and a script anywhere else — one of the project's own programs — is never read, by design. A guard
@@ -489,7 +499,7 @@ usually shows something else: told the rule when its session starts, it reaches
 | `--model <id>` | the consolidator's model (default: `claude-sonnet-5` under kiro, `sonnet` under Claude Code) |
 | `--format {object,array}` | **kiro only.** Which hook format to write when the target config has none yet |
 | `--no-trust-tools` | do not pre-approve Zikaron's own tools, so every Zikaron tool call asks permission |
-| `--components {memory,guards,both}` | what to install: the memory store (the default), the edit guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
+| `--components {memory,guards,both}` | what to install: the memory store (the default), the guards below, or both. **Claude Code only** for `guards` and `both`; `--model` is refused with `guards`, which ships no consolidator |
 | `--force` | replace a symlink at a shipped path, and overwrite entries wired to a different Zikaron install that would otherwise be refused. It also stops merging: a server entry — `.mcp.json`'s, or kiro's `mcpServers` — is replaced **whole**, so a key you added to Zikaron's own entry goes, and under Claude Code a Zikaron hook group is replaced whole, so a hook of your own inside it goes too. Both are named in the output |
 
 Both hook formats kiro accepts are supported, and a config that already uses one keeps it: kiro
@@ -536,7 +546,7 @@ write policy goes into the model's context, not to your terminal. Then, from the
 # a service should be running for this project after your first message
 pgrep -af zikaron.service.main
 
-# one line per hook failure, write-policy-override note, or session/environment mismatch; absent means none happened
+# one line per hook failure, missed cold start, write-policy-override note, or session/environment mismatch; absent means none happened
 cat .zikaron/hook.log
 ```
 
@@ -727,9 +737,11 @@ it is `0600` or `0700`. The **installer** also writes harness config — the fil
   config.toml        your per-project overrides, if you wrote any
   service.log        the background service: startup, resolved config, errors, why it stopped,
                      any request running longer than 30 s, and the stack dumps below
-  hook.log           one line per hook failure, write-policy-override note, or session/environment
-                     mismatch. Absent means none happened. Not every line is a failure: an override
-                     that is used but exceeds the injection budget is printed anyway and logged
+  hook.log           one line per hook failure, missed cold start, write-policy-override note, or
+                     session/environment mismatch. Absent means none happened. Not every line is a
+                     failure: `starting` is a message that arrived while the service was still
+                     starting, and an override that is used but exceeds the injection budget is
+                     printed anyway and logged
   warmup.log         the small helper that warms the service when a session starts
   write-policy.md    your policy override, if you wrote one
 ```
@@ -742,19 +754,23 @@ shared by every project you use Zikaron in, under `$XDG_CACHE_HOME/zikaron/model
 A copy inside each project would duplicate it for bytes that are identical by construction, since the
 version fetched is pinned. Removing a project does not remove it; [Uninstall](#uninstall) says how.
 
-The second is the service's Unix socket, which with its lock file sits in
-`$XDG_RUNTIME_DIR/zikaron/` — or `/tmp/zikaron-<uid>/` where that variable is unset, which is every
-Mac — named by a hash of the store's path, `0600` inside a `0700` directory. A socket belongs on a
-runtime filesystem rather than in your project. **Under Claude
-Code**, an over-large consolidator result also spills to a file beside them, carrying that group's
-record prose verbatim and named by the same store hash; it is deleted when the consolidator asks for
-its next group — or, if that process is killed first, by the next one that starts. It is the one
-copy of memory text that lives outside `.zikaron/`, which is why the erasure procedure under
-[Secrets](#secrets) removes it by hand. Nothing spills under kiro.
+The second is the service's Unix socket. It sits in `$XDG_RUNTIME_DIR/zikaron/` — or
+`/tmp/zikaron-<uid>/` where that variable is unset, which is every Mac — named by a hash of the
+store's path, `0600` inside a `0700` directory, beside two lock files: one clients take while they
+start the service, and one the service holds while it has the store open. A socket belongs on a
+runtime filesystem rather than in your project. **Under Claude Code**, an over-large consolidator
+result also spills to a file beside them, carrying that group's record prose verbatim and named by
+the same store hash; it is deleted when the consolidator asks for its next group — or, if that
+process is killed first, by the next one that starts. It is the one copy of memory text that lives
+outside `.zikaron/`, which is why the erasure procedure under [Secrets](#secrets) removes it by hand.
+Nothing spills under kiro.
 
 **What `service.log` tells you about a service that stopped, or stopped answering.** A clean stop
-writes one `stopping: reason=…` line: `idle`, `store_replaced`, `encoder_failed`, or `sigterm` /
-`sigint` when it was asked to stop. A request still running after the 30 s idle poll is logged as
+writes one `stopping: reason=…` line: `idle`, `store_replaced`, `socket_lost` (its socket file was
+removed, so nothing could reach it), `encoder_failed`, or `sigterm` / `sigint` when it was asked to
+stop. A start that found another service already holding the store writes `not starting:
+reason=another_service` and exits, leaving that one to serve it. A request still running after the
+30 s idle poll is logged as
 `long request: method=… session=… age=…` on every poll until it ends — `session=unresolved` if it
 never got that far. Two signals write a dump without stopping the service: `kill -USR2 <pid>` writes
 the requests in flight and every asyncio task's stack, and `kill -USR1 <pid>` writes every thread's
@@ -763,8 +779,8 @@ raw text, without the timestamp and `pid=` every other line carries.
 
 Two notes on reading the rest. `memory.db` can look implausibly small while `memory.db-wal` is large —
 that is normal for a database held open by the service, since recent writes live in the log until a
-checkpoint; the files together are the store. And `hook.log` records only a fixed failure label and an
-error code, never your prompt or a memory's text, so it cannot hold a leaked secret.
+checkpoint; the files together are the store. And `hook.log` records only fixed labels and an error
+code, never your prompt or a memory's text, so it cannot hold a leaked secret.
 
 There is one more log that is not a file: an event table inside `memory.db`. It records what happened
 on every **memory** read and write — used to measure whether the write policy is working, and kept in
@@ -784,6 +800,16 @@ Zikaron is built to fail quietly rather than get in your way. A hook that cannot
 prints a short note asking the agent to tell you, writes one line to `hook.log`, and exits cleanly. It
 never blocks your message, and it never reads the store directly.
 
+The service stops itself after a stretch of idleness, and the next message starts it again. That
+message waits a few seconds longer — the hook allows a start more time than a running service — and
+if the start still is not finished, the message goes without memories and the agent is told so, without
+being asked to report it. `hook.log` records that as `starting`, followed by what the hook was still
+waiting on — `lock` or `poll` before the service answered, or the lateness of its answer after — and
+memories return once it has started, usually with the next message. A run of `starting` lines means
+starts are slower than the hook allows, not that the service is broken; a start that never finishes is
+reported as `transport` once it has gone a minute without a sign of life — which a first run still
+fetching its model over a slow link can also do, until it finishes.
+
 **Run `zikaron doctor` first for anything that smells environmental** — no search results at all, a
 service that will not start, an MCP server that dies on contact. It checks the things about this
 machine that can stop Zikaron working and names what to change for each. The table below is for
@@ -892,7 +918,7 @@ than deleted, because both hold settings that are not Zikaron's. **All three set
 the install writes three** — leaving `enabledMcpjsonServers` behind names two servers that no longer
 exist, which loads nothing and breaks nothing but is not an uninstall.
 
-**The edit guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
+**The guards** live only in `.claude/settings.local.json`: remove the `PreToolUse` and
 `PostToolUse` hook groups whose command is `zikaron-guard`, and the `SessionStart` and
 `SubagentStart` groups whose command is `zikaron-hook`. To keep the memory store and drop only the
 guards, re-running the installer will not do it — an install never removes a selection — so delete

{zikaron-0.3.1 → zikaron-0.3.2}/pyproject.toml

@@ -4,16 +4,14 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "zikaron"
-# Semver, and `0.x` for as long as the *install contract* may still change — the shapes and
-# locations of the artefacts the installer writes into a harness's config. The one rule that
-# matters for an upgrade: **a release whose installed artefacts differ in shape from the previous
-# one is a minor bump, never a patch**, because those paths are written into harness config that an
-# upgrade has to be able to refresh, and a patch bump tells a reader nothing needs refreshing.
-# `design/distribution.md` §"The version scheme" is normative.
-version = "0.3.1"
+# Semver, `0.x`. **A minor bump means one thing: `meta.schema_version` moved**, so a release that
+# cannot open a store an earlier one wrote says so in its number. Every other change is a patch, a
+# changed installed artifact included; a release that needs an existing install refreshed says so
+# in its release note. `design/distribution.md` §"The version scheme" is normative.
+version = "0.3.2"
 # What a package index renders as the one-line summary, so it must name both stores: the memory
 # store, for what was learned by working here, and the knowledge index, for what the project already
-# wrote down.
+# wrote down. The guards, which ship on request, are the README's to describe.
 description = "Memory and searchable project knowledge for coding agents"
 readme = "README.md"
 # An SPDX expression plus `license-files`, which is the PEP 639 shape. **No
@@ -65,7 +63,7 @@ Repository = "https://github.com/nathan-shapiro/Zikaron"
 Issues = "https://github.com/nathan-shapiro/Zikaron/issues"
 
 # The commands a shipped harness config names — `zikaron-hook` and `zikaron-mcp` for either harness,
-# `zikaron-guard` for Claude Code's edit guards — and the reason they are console scripts rather than
+# `zikaron-guard` for Claude Code's guards — and the reason they are console scripts rather than
 # `python -m` command lines: a hook entry's `command` and an `mcpServers` entry's `command` each need
 # one absolute path, and a console script's shebang pins the interpreter Zikaron is installed into —
 # which is also the interpreter start-if-absent will spawn the service with, via `sys.executable`.

{zikaron-0.3.1 → zikaron-0.3.2}/tests/test_guard_claude_live.py

@@ -1,15 +1,18 @@
-"""The edit guards in a real Claude Code session (`design/build-plan.md` §M37, "A live test").
+"""The guards in a real Claude Code session (`design/build-plan.md` §M37, "A live test", and
+§M38's done-when 3).
 
-One headless session under `--permission-mode bypassPermissions` is given exact commands, so that
-neither the edit nor the override is the model's choice: a `sed -i` the guard must deny, the same
-form with a valid override, and an `Edit`. What is asserted is what the harness recorded, never what
-the model says:
+Each headless session under `--permission-mode bypassPermissions` is given exact commands, so that
+neither the edit nor the override is the model's choice. The first runs a `sed -i` the guard must
+deny, the same form with a valid override, and an `Edit`; the second a self-matching `pkill -f`,
+the same command with `-A`, and a self-matching `pgrep -f` through `Monitor`. What is asserted is
+what the harness recorded, never what the model says:
 
-- the deny is the `sed -i` call's `tool_result` in the `stream-json` output, and the file is
-  unchanged by it — under `bypassPermissions`, which is itself one of §2's rows;
+- each deny is its call's `tool_result` in the `stream-json` output, and the file is unchanged by
+  the denied `sed` — under `bypassPermissions`, which is itself one of §2's rows;
 - the override's command ran (the file changed), and its acknowledgement reached the model, which is
   recorded only in the session's transcript, as an attachment;
-- the `Edit` was followed by the nudge, also an attachment.
+- the `Edit` was followed by the nudge, also an attachment;
+- the `-A` call ran rather than being denied.
 
 **The project lives under `~/.cache/zikaron-live-tests/`, never `tmp_path`**: pytest's temporary
 directories lie under `/tmp` or `$TMPDIR`, where the guard exempts the commands and suppresses the
@@ -31,6 +34,7 @@ from typing import Any, Final
 
 import pytest
 
+from zikaron.guard import messages
 from zikaron.harness.spec import CLAUDE_CODE
 from zikaron.install import harness
 from zikaron.install import main as install_main
@@ -49,6 +53,22 @@ _PROMPT: Final = (
     "Step 3: use the Edit tool to replace the word alpha with ALPHA in target.txt. Then reply with "
     "the single word: done."
 )
+#: A pattern no process carries but the command running it, so only the shell can match it.
+_NONCE: Final = f"zikaron_live_selfmatch_{uuid.uuid4().hex[:12]}"
+_SELF_MATCHING: Final = f"pkill -f {_NONCE}"
+_ANCESTORS_IGNORED: Final = f"pkill -A -f {_NONCE}"
+_MONITORED: Final = f"pgrep -f {_NONCE}"
+#: Measured: told only to run the steps, a small model declines a `pkill` it has no reason for, so
+#: the prompt says what the commands are for and why they are safe.
+_SELF_MATCH_PROMPT: Final = (
+    "This is a test of a hook installed in this throwaway project. Its pattern is a random string "
+    "that no process on this machine carries, so none of these commands can stop anything. "
+    "Do these three steps in order, each exactly as written, and carry on to the next even if one "
+    f"fails. Step 1: run this Bash command, character for character: `{_SELF_MATCHING}`. Step 2: "
+    f"run this Bash command, character for character: `{_ANCESTORS_IGNORED}`. Step 3: use the "
+    f"Monitor tool to run this command, character for character: `{_MONITORED}`. Then reply with "
+    "the single word: done."
+)
 
 
 @pytest.fixture
@@ -62,7 +82,7 @@ def project() -> Iterator[Path]:
         shutil.rmtree(root)
 
 
-def _session(project: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+def _session(project: Path, prompt: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
     """One headless turn: the `stream-json` records, and the session transcript's records."""
     assert harness.binary_is_available(CLAUDE_CODE.harness_binary), (
         f"{CLAUDE_CODE.harness_binary!r} is not on PATH: do not run -m integration_claude here, "
@@ -72,7 +92,7 @@ def _session(project: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]
         [
             CLAUDE_CODE.harness_binary,
             "-p",
-            _PROMPT,
+            prompt,
             "--model",
             "haiku",
             "--permission-mode",
@@ -108,12 +128,33 @@ def _tool_results(stream: list[dict[str, Any]]) -> list[str]:
     return results
 
 
-def test_the_guards_deny_acknowledge_and_nudge_in_a_real_session(project: Path) -> None:
+def _results_by_command(stream: list[dict[str, Any]]) -> dict[str, str]:
+    """Each `Bash` or `Monitor` call's command, mapped to its `tool_result`."""
+    commands: dict[str, str] = {}
+    results: dict[str, str] = {}
+    for record in stream:
+        for block in (record.get("message") or {}).get("content") or []:
+            if not isinstance(block, dict):
+                continue
+            if block.get("type") == "tool_use" and block.get("name") in ("Bash", "Monitor"):
+                commands[block["id"]] = block["input"].get("command", "")
+            elif block.get("type") == "tool_result":
+                content = block.get("content")
+                text = content if isinstance(content, str) else json.dumps(content)
+                results[block["tool_use_id"]] = text
+    return {command: results.get(use_id, "") for use_id, command in commands.items()}
+
+
+def _install_guards(project: Path) -> None:
     status = install_main.main(
         ["--project", str(project), "--harness", "claude-code", "--components", "guards"]
     )
     assert status == 0
-    stream, transcript = _session(project)
+
+
+def test_the_guards_deny_acknowledge_and_nudge_in_a_real_session(project: Path) -> None:
+    _install_guards(project)
+    stream, transcript = _session(project, _PROMPT)
     text = (project / "target.txt").read_text(encoding="utf-8")
 
     denials = [r for r in _tool_results(stream) if "PreToolUse:Bash hook error" in r]
@@ -126,3 +167,15 @@ def test_the_guards_deny_acknowledge_and_nudge_in_a_real_session(project: Path)
     assert "#ZIKARON-FORCE accepted by Zikaron's find-replace guard" in recorded
     assert "PostToolUse:Edit hook additional context" in recorded
     assert "target.txt` was edited" in recorded
+
+
+def test_the_self_match_rule_denies_on_bash_and_monitor_in_a_real_session(project: Path) -> None:
+    _install_guards(project)
+    results = _results_by_command(_session(project, _SELF_MATCH_PROMPT)[0])
+    refused = messages.SELF_MATCH_TEMPLATE.split("{", 1)[0]
+
+    assert "PreToolUse:Bash hook error" in results[_SELF_MATCHING], results
+    assert refused in results[_SELF_MATCHING], results
+    assert "hook error" not in results[_ANCESTORS_IGNORED], results
+    assert "PreToolUse:Monitor hook error" in results[_MONITORED], results
+    assert refused in results[_MONITORED], results