protect-context 1.0.0 → 1.2.0

package/README.md

@@ -29,6 +29,8 @@ The suite is **advisory-first**. It records evidence and makes unsafe or
 repetitive behavior visible; it is not a sandbox and does not prove that a
 change is correct. [`SPEC.md`](./SPEC.md) is the frozen v1.0 contract.
 
+![Architecture: the pi extension, MCP server, and Python CLI share a project-local .agent-guard store for rules, journal entries, and evidence; only pi injects briefs automatically](./docs/images/shared-store.svg)
+
 ## Contents
 
 - [Why this exists](#why-this-exists)
@@ -249,6 +251,8 @@ And the always-on one-line widget:
 PC Δ+88L/6f 0loop ev5 ctx8%
 ```
 
+![Illustrative pi widget: Δ+123L/4f means 123 changed lines across 4 files, 1loop means one command at the blocking threshold, ev2 counts two verification runs this session, and ctx41% shows context usage](./docs/images/status-widget.svg)
+
 ## Interface comparison
 
 | Capability | pi extension | MCP server | CLI |
@@ -314,8 +318,8 @@ protect-context status
 protect-context verify "pytest -q" [--timeout 180]
 protect-context evidence [--limit 5]
 protect-context contract list
-protect-context contract add "Keep the public API stable"
-protect-context contract remove ID
+protect-context contract add "Keep the public API stable" [--global]
+protect-context contract remove ID [--global]
 protect-context note correction "use rg, not grep" --tags search
 protect-context journal [--limit 5] [--type decision]
 protect-context orientation
@@ -350,6 +354,68 @@ fully checked. Version probes have a two-second per-tool timeout, share a
 15-second overall deadline, and decode at most 4 KiB of output; a missing
 version is reported as an incomplete preflight.
 
+### Making it yours: the personal layer
+
+The twelve seeds and the config defaults are the same for everyone, on purpose:
+they are the floor that makes the guardrail comparable across machines. What is
+*yours* goes in a personal layer that every project inherits:
+
+```text
+built-in defaults  <  ~/.config/protect-context/  <  .agent-guard/
+                        contract.json                 contract.json
+                        config.json                   config.json
+```
+
+The directory is `$PC_USER_DIR`, else `$XDG_CONFIG_HOME/protect-context`, else
+`~/.config/protect-context`. Write it from the owner surfaces:
+
+```console
+$ protect-context contract add "Prefer stdlib over new dependencies" --global
+added 13-prefer-stdlib-over-new-dependencies to personal layer
+…
+
+$ protect-context contract list          # every project sees it
+personal layer: 1 from /home/you/.config/protect-context/contract.json (applies to every project; a project row with the same id or text wins)
+```
+
+The same flag works in pi: `/guard-contract add <text> --global` and
+`/guard-contract remove <id> --global`. Without it, writes go to the project
+store as before, and `guard_contract` (the agent-callable tool) never touches
+the personal layer.
+
+Rules that make the layering predictable:
+
+- **The project wins.** A project row with the same id overrides the personal
+  one, and a personal constraint identical in text to a project row is not
+  listed twice. Give a personal override the same id (e.g. `03-stay-in-scope`) to
+  reword a seed for every repo.
+- **Defaults mean "no opinion".** The extension seeds `config.json` with every
+  default value; a project value equal to the built-in default therefore does not
+  pin it, so your personal `ctx_warn_pct` still applies. Any *different* project
+  value is an explicit choice and wins.
+- **Nothing is created behind your back.** The layer is never seeded or repaired:
+  a missing file means "no personal constraints", and an unreadable one is
+  ignored in memory and left untouched. Deleting a personal constraint requires
+  `--global`; a project-scope remove says so instead of silently doing nothing.
+- **Each layer has its own lease.** A `--global` write locks the personal
+  directory, not the project store, so two projects writing personal state cannot
+  race each other.
+
+### Sharing a contract with a team
+
+`.agent-guard/` is runtime state and normally gitignored. If a team wants one
+shared owner contract, track only that file:
+
+```gitignore
+.agent-guard/*
+!.agent-guard/contract.json
+```
+
+Runtime files (events, evidence, journal, session state) stay local, while
+`contract.json` becomes reviewable in pull requests. Personal constraints still
+apply on top — each teammate's personal layer is weaker than the shared project
+row.
+
 The nine catastrophic patterns that trigger the pi confirmation are frozen and
 deliberately narrow, so benign lookalikes stay silent:
 
@@ -362,6 +428,7 @@ deliberately narrow, so benign lookalikes stay silent:
 | Variable | Effect |
 |---|---|
 | `PC_SESSION_ID` | Names the session used for evidence and loop views, so parallel hosts do not share a view |
+| `PC_USER_DIR` | Overrides the personal-layer directory (default `$XDG_CONFIG_HOME/protect-context` or `~/.config/protect-context`) |
 
 ### Runtime store and concurrency
 
@@ -370,6 +437,18 @@ Runtime files stay in the frozen `.agent-guard/` layout and are gitignored:
 `config.json` · `contract.json` · `journal.jsonl` · `events.jsonl` ·
 `verify_runs.jsonl` · `state.json`
 
+The optional personal layer lives outside the repository at
+`~/.config/protect-context/` (`contract.json`, `config.json`) and is never
+written implicitly; see *Making it yours* above.
+
+Ledgers bound themselves instead of growing forever: once `events.jsonl`,
+`verify_runs.jsonl` or `journal.jsonl` passes 1 MiB it rotates to
+`<name>.1.jsonl`, keeping at most three rotated segments and dropping the oldest.
+Reads concatenate the segments oldest-first, so recent rows and the highest
+evidence id always survive; `budget` and loop streaks describe the retained
+window. Session baselines are keyed per session inside `state.json`, so parallel
+pi sessions in one repo no longer overwrite each other's watermarks.
+
 Python and TypeScript use the same atomic-directory lease at
 `.agent-guard/.lock.d`, with an owner token, PID/hostname checks, bounded
 waiting, and conservative stale recovery. Python also takes its legacy local
@@ -418,7 +497,7 @@ machine: there are no network calls and no LLM calls in the guardrail logic.
 |---|---|
 | `session_start` | Seed config if missing, scan orientation, freeze the diff baseline, start the status widget |
 | `before_agent_start` | Build the brief; inject orientation and/or brief as a hidden message when their digests changed |
-| `tool_call` (bash) | Match the nine risky patterns → one grouped confirm; check the loop fingerprint → block at the threshold |
+| `tool_call` (bash) | Match the nine risky patterns → one grouped confirm; check the loop fingerprint → block at the threshold; record the normalized command, with `ok=false` when the call was refused |
 | `tool_execution_start` / `tool_execution_end` | Record bash outcomes and verify results into the shared loop state and evidence ledger |
 | `turn_end` | Refresh the widget: diff stats, open loops, evidence count, context percentage |
 | `session_compact` | Re-inject trusted context so compaction cannot silently erase it |
@@ -452,6 +531,8 @@ fingerprint across both bash and `guard_verify`. At `loop_block_after` the
 attempt is refused, with the prior failure count and a change-strategy nudge —
 the single cheapest intervention in the suite.
 
+![Verification workflow: run a command, persist its evidence, and cite the result. With the default threshold, two failures of the same normalized command block its third attempt; only that command succeeding resets its streak](./docs/images/evidence-loop.svg)
+
 ### Scope audit
 
 Diffs are computed with `git` porcelain/numstat over tracked, staged, and

package/extension/index.ts

@@ -32,11 +32,19 @@ import {
   loadState,
   saveState,
   readJsonl,
+  sessionState,
+  type SessionState,
   storeDir,
   verifyRunsPath,
   withStoreLock,
 } from "./lib/store.ts";
-import { addConstraintWithStatus, contractLines, loadContract, removeConstraint } from "./lib/contract.ts";
+import {
+  addConstraintWithStatus,
+  contractLines,
+  loadContract,
+  personalConstraintCount,
+  removeConstraint,
+} from "./lib/contract.ts";
 import {
   appendJournal,
   isJournalType,
@@ -81,6 +89,14 @@ export default function (pi: ExtensionAPI) {
   let session = { id: "", started: "", gitHead: null as string | null, gitUnborn: false };
   let cfg: GuardConfig = { ...DEFAULT_CONFIG, preflight_tools: [...DEFAULT_CONFIG.preflight_tools] };
   let state = defaultState("", null);
+  // Live view of THIS session's baseline inside `state.sessions`; the scratch
+  // default only covers handlers that fire before session_start.
+  let view: SessionState = {
+    started: "",
+    git_head: null,
+    brief_digest: null,
+    notify_watermarks: { ctx_pct: 0, diff_lines: 0, diff_files: 0 },
+  };
   const startTimes = new Map<string, { start: number; tool: string; cmd: string | null }>();
   let lastDiff = { lines: 0, files: 0, available: false, lowerBound: false };
   let lastCtxPct: number | null = null;
@@ -146,7 +162,7 @@ export default function (pi: ExtensionAPI) {
     return `pc-${Math.random().toString(36).slice(2, 10)}`;
   }
 
-  async function runGit(ctx: ExtensionContext, args: string[]): Promise<string | null> {
+  async function runGit(_ctx: ExtensionContext, args: string[]): Promise<string | null> {
     try {
       const res = await pi.exec("git", args, { timeout: 5000 });
       if (res.code !== 0) return null;
@@ -492,19 +508,26 @@ export default function (pi: ExtensionAPI) {
       loadContract(ctx.cwd); // seeds contract.json from DEFAULT_CONTRACT if missing
 
       const prev = loadState(ctx.cwd);
-      if (prev && prev.current_session?.id === session.id && prev.notify_watermarks) {
-        state = { ...prev, counters: prev.counters ?? {} };
+      state = prev ?? defaultState(session.id, null);
+      // A session keeps ITS OWN baseline: a second pi session in the same
+      // project must not reset this one's digest or watermarks (SPEC §2).
+      const returning = prev !== null && prev.sessions[session.id] !== undefined;
+      view = sessionState(state, session.id);
+      if (returning && view.started !== "") {
         // Extension reloads can fire session_start again for the same pi
         // session. Preserve the original baseline from state instead of
         // silently resetting it to a newer commit.
-        session.started = prev.current_session.started || new Date().toISOString();
-        session.gitHead = prev.current_session.git_head;
+        session.started = view.started;
+        session.gitHead = view.git_head;
       } else {
         session.started = new Date().toISOString();
         session.gitHead = head?.trim() || null;
-        state = defaultState(session.id, session.gitHead);
-        saveState(ctx.cwd, state);
+        view.started = session.started;
+        view.git_head = session.gitHead;
+        view.brief_digest = null;
       }
+      state.current_session = { id: session.id, started: session.started, git_head: session.gitHead };
+      saveState(ctx.cwd, state);
       // A null baseline inside a repository means the session began before a
       // first commit (or before repository creation). Keep using the empty
       // tree even if HEAD appears later, so commits cannot erase session diff.
@@ -541,7 +564,7 @@ export default function (pi: ExtensionAPI) {
         lastEvidence: last ? { id: last.id, exit: last.exit, cmd: last.cmd, ms: last.ms } : null,
       });
       const digest = sha1Hex(brief);
-      const briefDue = brief.trim() !== "" && (cfg.brief_mode !== "changed" || state.brief_digest !== digest);
+      const briefDue = brief.trim() !== "" && (cfg.brief_mode !== "changed" || view.brief_digest !== digest);
 
       // Orientation (goal #4): injected once per distinct digest, like the
       // brief. Lazily re-scanned if session_start did not populate it.
@@ -563,7 +586,7 @@ export default function (pi: ExtensionAPI) {
       if (parts.length === 0) return undefined;
 
       if (orientDue && orientDigest !== null) state.counters.orient_sha1 = orientDigest;
-      if (briefDue) state.brief_digest = digest;
+      if (briefDue) view.brief_digest = digest;
       saveState(ctx.cwd, state);
       return { message: { customType: BRIEF_CUSTOM_TYPE, content: parts.join("\n\n"), display: false } };
     }),
@@ -590,6 +613,15 @@ export default function (pi: ExtensionAPI) {
             // block reason as the result) — mark it so the end handler does
             // not record the decline as a failed command.
             blockedToolCallIds.add(event.toolCallId);
+            // Record the refused attempt: otherwise the shared audit trail keeps
+            // no trace of the command the guard refused to run (SPEC §2).
+            withStoreLock(storeDir(ctx.cwd), () => {
+              appendJsonlLocked(
+                eventsPath(ctx.cwd),
+                toolCallEvent(session.id, "bash", { cmd: fp, blocked: true }),
+              );
+              loopLedgerMemo = loopLedgerStamp(ctx.cwd);
+            });
             return { block: true, reason: `guard: risky command declined (${risk})` };
           }
         } else {
@@ -614,9 +646,15 @@ export default function (pi: ExtensionAPI) {
       const blockedFailures = withStoreLock(storeDir(ctx.cwd), () => {
         if (loopLedgerMemo !== loopLedgerStamp(ctx.cwd)) rebuildLoopStateUnlocked(ctx.cwd);
         const failures = loopState.get(fp)?.failures ?? 0;
-        if (shouldBlockLoop(failures, cfg.loop_block_after)) return failures;
-        appendJsonlLocked(eventsPath(ctx.cwd), toolCallEvent(session.id, "bash"));
-        loopLedgerMemo = loopLedgerStamp(ctx.cwd);
+        if (shouldBlockLoop(failures, cfg.loop_block_after)) {
+          appendJsonlLocked(
+            eventsPath(ctx.cwd),
+            toolCallEvent(session.id, "bash", { cmd: fp, blocked: true }),
+          );
+          loopLedgerMemo = loopLedgerStamp(ctx.cwd);
+          return failures;
+        }
+        appendJsonlLocked(eventsPath(ctx.cwd), toolCallEvent(session.id, "bash", { cmd: fp }));
         return null;
       });
       if (blockedFailures !== null) {
@@ -705,10 +743,10 @@ export default function (pi: ExtensionAPI) {
           const step = Math.floor(usage.percent / 10) * 10;
           const contextDue =
             step >= cfg.ctx_warn_pct &&
-            (step > state.notify_watermarks.ctx_pct ||
+            (step > view.notify_watermarks.ctx_pct ||
               (cfg.ctx_warn_pct === 0 && state.counters.ctx_zero_notified !== 1));
           if (contextDue) {
-            state.notify_watermarks.ctx_pct = step;
+            view.notify_watermarks.ctx_pct = step;
             markZeroThreshold(cfg.ctx_warn_pct, "ctx_zero_notified");
             saveState(ctx.cwd, state);
             if (ctx.hasUI) {
@@ -733,7 +771,7 @@ export default function (pi: ExtensionAPI) {
       };
       if (diff.repo && diff.available) {
         const { files, lines } = diff;
-        const wm = state.notify_watermarks;
+        const wm = view.notify_watermarks;
         if (lines >= cfg.diff_hard_lines) {
           if (thresholdDue(lines, cfg.diff_hard_lines, wm.diff_lines, "diff_hard_zero_notified")) {
             wm.diff_lines = Math.max(wm.diff_lines, cfg.diff_hard_lines);
@@ -777,7 +815,7 @@ export default function (pi: ExtensionAPI) {
   // trusted journal entries and orientation even when their text is unchanged.
   pi.on("session_compact", async (_event, ctx) =>
     attempt(ctx, async () => {
-      state.brief_digest = null;
+      view.brief_digest = null;
       delete state.counters.orient_sha1;
       saveState(ctx.cwd, state);
       return undefined;
@@ -820,15 +858,25 @@ export default function (pi: ExtensionAPI) {
     handler: async (args, ctx) =>
       attempt(ctx, async () => {
         const trimmed = (args ?? "").trim();
+        // `--global` edits the personal layer (~/.config/protect-context) so one
+        // constraint applies to every project; it is a owner-only surface.
+        const global_requested = /(^|\s)--global(\s|$)/.test(trimmed);
         const parts = trimmed.split(/\s+/);
         const verb = parts[0] ?? "";
-        const rest = parts.slice(1).join(" ").trim();
+        const rest = parts
+          .slice(1)
+          .filter((part) => part !== "--global")
+          .join(" ")
+          .trim();
+        const scope = global_requested ? "user" : "project";
         if (verb === "" || verb === "list") {
           const current = loadContract(ctx.cwd);
           const lines = contractLines(current);
+          const personal = personalConstraintCount();
           if (ctx.hasUI) {
+            const note = personal > 0 ? `\npersonal layer: ${personal} (applies to every project)` : "";
             ctx.ui.notify(
-              `contract (${current.constraints.length}):\n${lines.join("\n")}\nNudge: add missing constraints with /guard-contract add <text>.`,
+              `contract (${current.constraints.length}):\n${lines.join("\n")}${note}\nNudge: add missing constraints with /guard-contract add <text>.`,
               "info",
             );
           }
@@ -836,14 +884,15 @@ export default function (pi: ExtensionAPI) {
         }
         if (verb === "add") {
           if (rest === "") {
-            if (ctx.hasUI) ctx.ui.notify("usage: /guard-contract add <text>", "warning");
+            if (ctx.hasUI) ctx.ui.notify("usage: /guard-contract add <text> [--global]", "warning");
             return undefined;
           }
           // Slash commands are direct owner interaction and therefore trusted
           // by brief prioritization; model-callable writes use provenance tags.
-          const result = addConstraintWithStatus(ctx.cwd, rest, "user");
+          const result = addConstraintWithStatus(ctx.cwd, rest, "user", scope);
           const c = result.constraint;
           const total = result.total;
+          const where = scope === "user" ? " (personal layer — every project)" : "";
           if (ctx.hasUI) {
             // SPEC §5 caps the re-injected brief at 12 contract lines: a
             // constraint past the cap would be silently DROPPED while the
@@ -852,21 +901,29 @@ export default function (pi: ExtensionAPI) {
             const ack = !result.added
               ? `constraint ${c.id} already exists\nNudge: no duplicate was written.`
               : over
-              ? `added ${c.id}\nwarning: ${total} constraints exceed the ${BRIEF_MAX_CONTRACT_LINES}-line brief cap — ` +
+              ? `added ${c.id}${where}\nwarning: ${total} constraints exceed the ${BRIEF_MAX_CONTRACT_LINES}-line brief cap — ` +
                 `only the ${BRIEF_MAX_CONTRACT_LINES} highest-priority owner/seed constraints are re-injected.` +
                 `\nNudge: keep the contract tight — fewer, sharper constraints survive re-injection.`
-              : `added ${c.id}\nNudge: the brief re-injects on your next prompt.`;
+              : `added ${c.id}${where}\nNudge: the brief re-injects on your next prompt.`;
             ctx.ui.notify(ack, result.added && over ? "warning" : "info");
           }
           return undefined;
         }
         if (verb === "remove") {
-          const removed = rest !== "" && removeConstraint(ctx.cwd, rest);
+          const removed = rest !== "" && removeConstraint(ctx.cwd, rest, scope);
           const safeId = truncLine(rest, 80);
+          // A project-scope remove cannot delete personal state: point at it
+          // instead of claiming the id does not exist.
+          const inPersonalLayer =
+            !removed &&
+            scope === "project" &&
+            loadContract(ctx.cwd).constraints.some((constraint) => constraint.id === rest);
           if (ctx.hasUI) {
             ctx.ui.notify(
               removed
                 ? `removed ${safeId}\nNudge: the contract re-injects on your next prompt.`
+                : inPersonalLayer
+                ? `${safeId} lives in the personal layer\nNudge: re-run with /guard-contract remove ${safeId} --global.`
                 : `no constraint '${safeId}'\nNudge: run /guard-contract list first.`,
               removed ? "info" : "warning",
             );

package/extension/lib/config.ts

@@ -4,7 +4,7 @@
 
 import { existsSync } from "node:fs";
 import { DEFAULT_CONFIG, type GuardConfig } from "./defaults.ts";
-import { configPath, readJson, storeDir, withStoreLock, writeJson } from "./store.ts";
+import { configPath, readJson, storeDir, userConfigPath, withStoreLock, writeJson } from "./store.ts";
 
 function isInteger(v: unknown): v is number {
   return typeof v === "number" && Number.isInteger(v);
@@ -19,8 +19,11 @@ function strArray(v: unknown): string[] | null {
  * Merge a partial config over the frozen defaults. Unknown keys are ignored;
  * wrong-typed values fall back to the default (deterministic, test-pinned).
  */
-export function mergeConfig(partial: Record<string, unknown> | null | undefined): GuardConfig {
-  const cfg: GuardConfig = { ...DEFAULT_CONFIG, preflight_tools: [...DEFAULT_CONFIG.preflight_tools] };
+export function mergeConfig(
+  partial: Record<string, unknown> | null | undefined,
+  base: GuardConfig = DEFAULT_CONFIG,
+): GuardConfig {
+  const cfg: GuardConfig = { ...base, preflight_tools: [...base.preflight_tools] };
   if (!partial || typeof partial !== "object") return cfg;
 
   const p = partial as Record<string, unknown>;
@@ -38,20 +41,51 @@ export function mergeConfig(partial: Record<string, unknown> | null | undefined)
 
 export interface LoadedConfig {
   config: GuardConfig;
+  /** Unknown keys from the personal/project files, preserved but never
+   * interpreted by the guard (strongest layer wins). Kept out of
+   * `GuardConfig` so a typo in a known key still fails to type-check. */
+  extras: Record<string, unknown>;
   path: string;
   existed: boolean;
 }
 
-/** Load `.agent-guard/config.json` merged over defaults. Missing file →
- * defaults; extension startup can request an on-disk seed so an extension-only
- * install has the documented configuration surface without first running the
- * Python CLI. Existing corrupt files are never overwritten. */
+const KNOWN_KEYS = new Set(Object.keys(DEFAULT_CONFIG));
+
+/** Unknown keys of one layer, for pass-through only. */
+function layerExtras(raw: Record<string, unknown> | null): Record<string, unknown> {
+  if (!raw) return {};
+  return Object.fromEntries(Object.entries(raw).filter(([key]) => !KNOWN_KEYS.has(key)));
+}
+
+/** Project values identical to the built-in default mean "no opinion". A seeded
+ * project file records every default, so reading those as explicit choices
+ * would shadow the personal layer forever. */
+function explicitProjectKeys(raw: Record<string, unknown> | null): Record<string, unknown> | undefined {
+  if (!raw) return undefined;
+  const defaults: Record<string, unknown> = Object.fromEntries(Object.entries(DEFAULT_CONFIG));
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (JSON.stringify(value) === JSON.stringify(defaults[key])) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/** Load `.agent-guard/config.json` over the personal layer
+ * (`~/.config/protect-context/config.json`) over the defaults (SPEC §2).
+ * Extension startup can request an on-disk seed so an extension-only install
+ * has the documented configuration surface without the Python CLI; the seed is
+ * the built-in defaults, never the merged view. Corrupt files are never
+ * overwritten. */
 function readLoadedConfig(cwd: string): LoadedConfig {
   const path = configPath(cwd);
   const existed = existsSync(path);
-  const raw = readJson<Record<string, unknown>>(path);
-  const config = mergeConfig(raw ?? undefined);
-  return { config, path, existed };
+  const personalRaw = readJson<Record<string, unknown>>(userConfigPath());
+  const projectRaw = readJson<Record<string, unknown>>(path);
+  const personal = mergeConfig(personalRaw ?? undefined);
+  const config = mergeConfig(explicitProjectKeys(projectRaw), personal);
+  const extras = { ...layerExtras(personalRaw), ...layerExtras(projectRaw) };
+  return { config, extras, path, existed };
 }
 
 export function loadConfig(cwd: string, seedMissing = false): LoadedConfig {
@@ -61,7 +95,7 @@ export function loadConfig(cwd: string, seedMissing = false): LoadedConfig {
   // by defaults between an optimistic exists() and writeJson().
   return withStoreLock(storeDir(cwd), () => {
     const loaded = readLoadedConfig(cwd);
-    if (!loaded.existed) writeJson(loaded.path, loaded.config);
+    if (!loaded.existed) writeJson(loaded.path, DEFAULT_CONFIG);
     return loaded;
   });
 }

package/extension/lib/contract.ts

@@ -4,7 +4,15 @@
 
 import { existsSync } from "node:fs";
 import { DEFAULT_CONTRACT, type Constraint, type Contract } from "./defaults.ts";
-import { contractPath, readJson, storeDir, withStoreLock, writeJson } from "./store.ts";
+import {
+  contractPath,
+  readJson,
+  storeDir,
+  userContractPath,
+  userDir,
+  withStoreLock,
+  writeJson,
+} from "./store.ts";
 import { normalizeOneLine } from "./text.ts";
 
 /** Free-text cap (chars): constraint text flows into re-injected briefs (goal #12). */
@@ -75,8 +83,41 @@ function saveContractUnlocked(cwd: string, contract: Contract): void {
   writeJson(contractPath(cwd), contract);
 }
 
+/** Personal-layer rows: a missing file means "no personal constraints" (never
+ * seeded), and an unreadable one is ignored in memory so a transient error can
+ * never become a write. SPEC §2: the personal layer is owner-only surface. */
+function personalConstraints(): Constraint[] {
+  const data = readJson<unknown>(userContractPath());
+  if (!data || typeof data !== "object" || Array.isArray(data)) return [];
+  const rows = (data as { constraints?: unknown }).constraints;
+  return Array.isArray(rows) ? rows.filter(isConstraint) : [];
+}
+
+/** Project rows first, then personal rows the project does not already carry
+ * (same id or identical text): the project overrides the personal layer. */
+export function mergeConstraints(project: Constraint[], personal: Constraint[]): Constraint[] {
+  const out: Constraint[] = [];
+  const ids = new Set<string>();
+  const signatures = new Set<string>();
+  for (const row of [...project, ...personal]) {
+    const id = normalizeOneLine(row.id, 80);
+    const signature = normalizeOneLine(row.text, TEXT_CAP);
+    if (ids.has(id) || signatures.has(signature)) continue;
+    ids.add(id);
+    signatures.add(signature);
+    out.push(row);
+  }
+  return out;
+}
+
+/** Effective contract (project + personal) while the caller holds the lease. */
+function effectiveContractUnlocked(cwd: string, forMutation = false): Contract {
+  const project = loadContractUnlocked(cwd, forMutation);
+  return { version: 1, constraints: mergeConstraints(project.constraints, personalConstraints()) };
+}
+
 export function loadContract(cwd: string): Contract {
-  return withStoreLock(storeDir(cwd), () => loadContractUnlocked(cwd));
+  return withStoreLock(storeDir(cwd), () => effectiveContractUnlocked(cwd));
 }
 
 export function saveContract(cwd: string, contract: Contract): void {
@@ -99,36 +140,102 @@ export interface AddConstraintResult {
   total: number;
 }
 
-export function addConstraintWithStatus(cwd: string, text: string, source = "agent"): AddConstraintResult {
+export type ContractScope = "project" | "user";
+
+/** Lease for the layer being written: the project store, or the personal
+ * directory (two projects must never share the wrong lease). */
+function scopeRoot(cwd: string, scope: ContractScope): string {
+  return scope === "user" ? userDir() : storeDir(cwd);
+}
+
+/** Personal rows for a read-modify-write cycle. A missing personal layer is not
+ * an error (it is never seeded); a damaged one fails closed so a mutation
+ * cannot silently erase owner data. */
+function personalForMutation(): Constraint[] {
+  const file = userContractPath();
+  if (!existsSync(file)) return [];
+  const data = readJson<unknown>(file);
+  if (!data || typeof data !== "object" || !Array.isArray((data as { constraints?: unknown }).constraints)) {
+    throw new ContractIntegrityError(`personal contract is malformed; repair ${file} before mutating it`);
+  }
+  const rows = (data as { constraints: unknown[] }).constraints;
+  const valid = rows.filter(isConstraint);
+  if (valid.length !== rows.length) {
+    throw new ContractIntegrityError(`personal contract contains malformed rows; repair ${file} before mutating it`);
+  }
+  return valid;
+}
+
+/** Project rows without seeding or writing, as a basis for personal-layer
+ * mutations (never hold the user lease while writing the project store). */
+function projectRowsReadonly(cwd: string): Constraint[] {
+  const data = readJson<unknown>(contractPath(cwd));
+  if (!data || typeof data !== "object" || !Array.isArray((data as { constraints?: unknown }).constraints)) {
+    return cloneDefaultContract().constraints;
+  }
+  const rows = (data as { constraints: unknown[] }).constraints;
+  const valid = rows.filter(isConstraint);
+  return rows.length > 0 && valid.length === 0 ? cloneDefaultContract().constraints : valid;
+}
+
+function scopeRows(cwd: string, scope: ContractScope): Constraint[] {
+  return scope === "user" ? personalForMutation() : loadContractUnlocked(cwd, true).constraints;
+}
+
+function saveScope(cwd: string, scope: ContractScope, constraints: Constraint[]): void {
+  const contract: Contract = { version: 1, constraints };
+  if (scope === "user") {
+    writeJson(userContractPath(), contract);
+    return;
+  }
+  saveContractUnlocked(cwd, contract);
+}
+
+/** Constraints the personal layer contributes to the effective contract. */
+export function personalConstraintCount(): number {
+  return personalConstraints().length;
+}
+
+export function addConstraintWithStatus(
+  cwd: string,
+  text: string,
+  source = "agent",
+  scope: ContractScope = "project",
+): AddConstraintResult {
   const cleanText = normalizeOneLine(text, TEXT_CAP);
   if (cleanText === "") throw new Error("constraint text must not be blank");
-  return withStoreLock(storeDir(cwd), () => {
-    const contract = loadContractUnlocked(cwd, true);
-    const existing = contract.constraints.find((constraint) => normalizeOneLine(constraint.text, TEXT_CAP) === cleanText);
-    if (existing) return { constraint: existing, added: false, total: contract.constraints.length };
+  return withStoreLock(scopeRoot(cwd, scope), () => {
+    const rows = scopeRows(cwd, scope);
+    // Dedupe and number against the EFFECTIVE contract: a personal constraint
+    // must never be duplicated into a project, and ids never collide.
+    const effective =
+      scope === "user"
+        ? mergeConstraints(projectRowsReadonly(cwd), personalConstraints())
+        : mergeConstraints(rows, personalConstraints());
+    const existing = effective.find((constraint) => normalizeOneLine(constraint.text, TEXT_CAP) === cleanText);
+    if (existing) return { constraint: existing, added: false, total: effective.length };
     const constraint: Constraint = {
-      id: nextConstraintId(contract.constraints),
+      id: nextConstraintId(effective),
       text: cleanText,
       added: new Date().toISOString().slice(0, 10),
       source: normalizeOneLine(source, 40) || "agent",
     };
-    contract.constraints.push(constraint);
-    saveContractUnlocked(cwd, contract);
-    return { constraint, added: true, total: contract.constraints.length };
+    rows.push(constraint);
+    saveScope(cwd, scope, rows);
+    return { constraint, added: true, total: effective.length + 1 };
   });
 }
 
-export function addConstraint(cwd: string, text: string, source = "agent"): Constraint {
-  return addConstraintWithStatus(cwd, text, source).constraint;
+export function addConstraint(cwd: string, text: string, source = "agent", scope: ContractScope = "project"): Constraint {
+  return addConstraintWithStatus(cwd, text, source, scope).constraint;
 }
 
-export function removeConstraint(cwd: string, id: string): boolean {
-  return withStoreLock(storeDir(cwd), () => {
-    const contract = loadContractUnlocked(cwd, true);
-    const before = contract.constraints.length;
-    contract.constraints = contract.constraints.filter((c) => c.id !== id);
-    if (contract.constraints.length === before) return false;
-    saveContractUnlocked(cwd, contract);
+export function removeConstraint(cwd: string, id: string, scope: ContractScope = "project"): boolean {
+  return withStoreLock(scopeRoot(cwd, scope), () => {
+    const rows = scopeRows(cwd, scope);
+    const kept = rows.filter((c) => c.id !== id);
+    if (kept.length === rows.length) return false;
+    saveScope(cwd, scope, kept);
     return true;
   });
 }

package/extension/lib/events.ts

@@ -10,10 +10,11 @@ export interface EventRecord {
   session: string;
   kind: EventKind;
   tool: string;
+  /** null on an ordinary tool_call; false when the call was refused. */
   ok: boolean | null;
   ms: number | null;
   out_chars: number | null;
-  /** Only set for bash tool_result events; fingerprint-normalized. */
+  /** bash rows only, fingerprint-normalized (tool_call and tool_result). */
   cmd: string | null;
   exit: number | null;
 }
@@ -22,16 +23,22 @@ function nowIso(): string {
   return new Date().toISOString();
 }
 
-export function toolCallEvent(session: string, tool: string): EventRecord {
+export function toolCallEvent(
+  session: string,
+  tool: string,
+  opts: { cmd?: string | null; blocked?: boolean } = {},
+): EventRecord {
   return {
     ts: nowIso(),
     session,
     kind: "tool_call",
     tool,
-    ok: null,
+    // A refused call (loop block / declined risk confirm) has no result, so the
+    // attempt is recorded as ok=false; an ordinary call has no outcome yet.
+    ok: opts.blocked ? false : null,
     ms: null,
     out_chars: null,
-    cmd: null,
+    cmd: opts.cmd ?? null,
     exit: null,
   };
 }

package/extension/lib/store.ts

@@ -20,8 +20,8 @@ import {
   realpathSync,
 } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
-import { hostname } from "node:os";
-import { dirname, join } from "node:path";
+import { hostname, homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
 import { performance } from "node:perf_hooks";
 
 export const STORE_DIR_NAME = ".agent-guard";
@@ -36,6 +36,26 @@ export function ensureStore(cwd: string): string {
   return dir;
 }
 
+export const USER_DIR_ENV = "PC_USER_DIR";
+
+/** Personal layer directory (SPEC §2): PC_USER_DIR, else $XDG_CONFIG_HOME,
+ * else ~/.config, always under `protect-context/`. Read at call time so tests
+ * and dotfiles-managed machines can redirect it. */
+export function userDir(): string {
+  const override = (process.env[USER_DIR_ENV] ?? "").trim();
+  if (override !== "") return override;
+  const xdg = (process.env.XDG_CONFIG_HOME ?? "").trim();
+  return join(xdg !== "" ? xdg : join(homedir(), ".config"), "protect-context");
+}
+
+export function userContractPath(): string {
+  return join(userDir(), "contract.json");
+}
+
+export function userConfigPath(): string {
+  return join(userDir(), "config.json");
+}
+
 export function configPath(cwd: string): string {
   return join(storeDir(cwd), "config.json");
 }
@@ -338,6 +358,7 @@ export function withStoreLock<T>(dir: string, fn: () => T, options: StoreLockOpt
 /** Append one JSON record as a single O_APPEND line write. The caller must
  *  already hold the store lock (see withStoreLock). */
 export function appendJsonlLocked(file: string, record: unknown): void {
+  maybeRotateLedger(file);
   appendFileSync(file, `${JSON.stringify(record)}\n`, "utf8");
 }
 
@@ -371,11 +392,50 @@ export function fileStamp(file: string): string | null {
 
 const jsonlCache = new Map<string, { mtimeMs: number; size: number; data: unknown[] }>();
 
-/** Read a JSONL file into object records; missing file → []. Malformed and
- * non-object lines are skipped, matching the Python ledger reader. Results
- * are cached by mtime+size. */
-export function readJsonl<T>(file: string): T[] {
-  if (!existsSync(file)) return [];
+/** Ledger bounding (SPEC §2): a ledger rotates to `<stem>.N.jsonl` once it
+ *  passes LEDGER_MAX_BYTES, keeping at most LEDGER_SEGMENTS rotated files.
+ *  Readers concatenate oldest-first, so "last N rows" stays correct and the
+ *  newest evidence id (the basis for `ev-NNNN`) is never rotated away. */
+export const LEDGER_MAX_BYTES = 1_048_576;
+export const LEDGER_SEGMENTS = 3;
+
+function segmentPath(file: string, index: number): string {
+  const name = basename(file);
+  const dot = name.lastIndexOf(".");
+  const stem = dot === -1 ? name : name.slice(0, dot);
+  const ext = dot === -1 ? "" : name.slice(dot);
+  return join(dirname(file), `${stem}.${index}${ext}`);
+}
+
+/** Existing ledger files for `file`, OLDEST first: rotated segments (highest
+ *  index first) and the live file last. */
+export function ledgerFiles(file: string): string[] {
+  const files: string[] = [];
+  for (let index = LEDGER_SEGMENTS; index >= 1; index -= 1) {
+    const segment = segmentPath(file, index);
+    if (existsSync(segment)) files.push(segment);
+  }
+  if (existsSync(file)) files.push(file);
+  return files;
+}
+
+function maybeRotateLedger(file: string): void {
+  let size: number;
+  try {
+    size = statSync(file).size;
+  } catch {
+    return;
+  }
+  if (size < LEDGER_MAX_BYTES) return;
+  // Caller holds the store lease, so the shift cannot race another writer.
+  for (let index = LEDGER_SEGMENTS - 1; index >= 1; index -= 1) {
+    const src = segmentPath(file, index);
+    if (existsSync(src)) renameSync(src, segmentPath(file, index + 1));
+  }
+  renameSync(file, segmentPath(file, 1));
+}
+
+function readOneJsonl<T>(file: string): T[] {
   const st = statOf(file);
   if (!st) return [];
   const cached = jsonlCache.get(file);
@@ -400,6 +460,15 @@ export function readJsonl<T>(file: string): T[] {
   return data as T[];
 }
 
+/** Read a ledger into object records, oldest row first across rotated
+ *  segments; missing file → []. Malformed and non-object lines are skipped,
+ *  matching the Python ledger reader. Results are cached by mtime+size. */
+export function readJsonl<T>(file: string): T[] {
+  const data: unknown[] = [];
+  for (const segment of ledgerFiles(file)) data.push(...readOneJsonl<unknown>(segment));
+  return data as T[];
+}
+
 export function readJson<T>(file: string): T | null {
   if (!existsSync(file)) return null;
   try {
@@ -430,21 +499,78 @@ export function writeJson(file: string, value: unknown): void {
 // ---------------------------------------------------------------------------
 // state.json (SPEC §2)
 
-export interface GuardState {
-  current_session: { id: string; started: string; git_head: string | null };
+export interface SessionState {
+  started: string;
+  git_head: string | null;
   brief_digest: string | null;
   notify_watermarks: { ctx_pct: number; diff_lines: number; diff_files: number };
+  /** ISO timestamp of the last touch, used only to bound the file. */
+  updated?: string;
+}
+
+/** Baseline that belongs to ONE pi session. Concurrent sessions in one project
+ *  keep separate entries so they cannot clobber each other (SPEC §2). */
+export interface GuardState {
+  current_session: { id: string; started: string; git_head: string | null };
+  sessions: Record<string, SessionState>;
   /** Opaque passthrough on the Python side; the extension stores digests here
    *  (e.g. the orientation digest) alongside numeric counters. */
   counters: Record<string, number | string>;
 }
 
+/** How many per-session baselines to retain (newest first, current always). */
+export const SESSION_KEEP = 8;
+
 export function defaultState(sessionId: string, gitHead: string | null): GuardState {
   return {
     current_session: { id: sessionId, started: new Date().toISOString(), git_head: gitHead },
+    sessions: {},
+    counters: {},
+  };
+}
+
+function freshSession(started: string, gitHead: string | null): SessionState {
+  return {
+    started,
+    git_head: gitHead,
     brief_digest: null,
     notify_watermarks: { ctx_pct: 0, diff_lines: 0, diff_files: 0 },
-    counters: {},
+  };
+}
+
+/** Live per-session entry of `state`, created (and touched) when absent. */
+export function sessionState(state: GuardState, sessionId: string): SessionState {
+  const existing = state.sessions[sessionId];
+  const entry = existing ?? freshSession(state.current_session.started || "", state.current_session.git_head ?? null);
+  entry.updated = new Date().toISOString();
+  state.sessions[sessionId] = entry;
+  return entry;
+}
+
+function numberOrZero(candidate: unknown): number {
+  return typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0 ? candidate : 0;
+}
+
+function readWatermarks(raw: unknown): SessionState["notify_watermarks"] {
+  const value =
+    raw !== null && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : {};
+  return {
+    ctx_pct: numberOrZero(value.ctx_pct),
+    diff_lines: numberOrZero(value.diff_lines),
+    diff_files: numberOrZero(value.diff_files),
+  };
+}
+
+function readSession(raw: unknown): SessionState | null {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  const gitHead = value.git_head;
+  return {
+    started: typeof value.started === "string" ? value.started : "",
+    git_head: typeof gitHead === "string" || gitHead === null ? gitHead : null,
+    brief_digest: typeof value.brief_digest === "string" ? value.brief_digest : null,
+    notify_watermarks: readWatermarks(value.notify_watermarks),
+    updated: typeof value.updated === "string" ? value.updated : undefined,
   };
 }
 
@@ -458,16 +584,29 @@ export function loadState(cwd: string): GuardState | null {
     !Array.isArray(value.current_session)
       ? (value.current_session as Record<string, unknown>)
       : {};
-  const rawWatermarks =
-    value.notify_watermarks !== null &&
-    typeof value.notify_watermarks === "object" &&
-    !Array.isArray(value.notify_watermarks)
-      ? (value.notify_watermarks as Record<string, unknown>)
-      : {};
-  const numberOrZero = (candidate: unknown): number =>
-    typeof candidate === "number" && Number.isFinite(candidate) && candidate >= 0
-      ? candidate
-      : 0;
+  const gitHead = rawSession.git_head;
+  const sessions: Record<string, SessionState> = {};
+  if (value.sessions !== null && typeof value.sessions === "object" && !Array.isArray(value.sessions)) {
+    for (const [id, entry] of Object.entries(value.sessions as Record<string, unknown>)) {
+      const parsed = readSession(entry);
+      if (parsed) sessions[id] = parsed;
+    }
+  }
+  const currentId = typeof rawSession.id === "string" ? rawSession.id : "";
+  // Legacy v1 files kept one digest/watermark pair at the top level; migrate it
+  // into the current session's entry in memory rather than dropping it.
+  if (currentId !== "" && sessions[currentId] === undefined) {
+    const legacyDigest = typeof value.brief_digest === "string" ? value.brief_digest : null;
+    const legacyWatermarks = readWatermarks(value.notify_watermarks);
+    if (legacyDigest !== null || Object.values(legacyWatermarks).some((n) => n > 0)) {
+      sessions[currentId] = {
+        started: typeof rawSession.started === "string" ? rawSession.started : "",
+        git_head: typeof gitHead === "string" || gitHead === null ? gitHead : null,
+        brief_digest: legacyDigest,
+        notify_watermarks: legacyWatermarks,
+      };
+    }
+  }
   const rawCounters =
     value.counters !== null && typeof value.counters === "object" && !Array.isArray(value.counters)
       ? (value.counters as Record<string, unknown>)
@@ -478,23 +617,31 @@ export function loadState(cwd: string): GuardState | null {
       counters[key] = candidate;
     }
   }
-  const gitHead = rawSession.git_head;
   return {
     current_session: {
-      id: typeof rawSession.id === "string" ? rawSession.id : "",
+      id: currentId,
       started: typeof rawSession.started === "string" ? rawSession.started : "",
       git_head: typeof gitHead === "string" || gitHead === null ? gitHead : null,
     },
-    brief_digest: typeof value.brief_digest === "string" ? value.brief_digest : null,
-    notify_watermarks: {
-      ctx_pct: numberOrZero(rawWatermarks.ctx_pct),
-      diff_lines: numberOrZero(rawWatermarks.diff_lines),
-      diff_files: numberOrZero(rawWatermarks.diff_files),
-    },
+    sessions,
     counters,
   };
 }
 
+/** Persist state.json, keeping the file bounded (SESSION_KEEP entries, the
+ *  current session always among them so its baseline is never pruned). */
 export function saveState(cwd: string, state: GuardState): void {
-  writeJson(statePath(cwd), state);
+  const currentId = state.current_session.id;
+  const ordered = Object.entries(state.sessions).sort(([, a], [, b]) =>
+    String(b.updated ?? b.started ?? "").localeCompare(String(a.updated ?? a.started ?? "")),
+  );
+  const reserve = currentId !== "" && state.sessions[currentId] !== undefined ? 1 : 0;
+  const kept: Record<string, SessionState> = {};
+  for (const [id, entry] of ordered) {
+    if (id === currentId) continue;
+    if (Object.keys(kept).length >= SESSION_KEEP - reserve) break;
+    kept[id] = entry;
+  }
+  if (reserve === 1) kept[currentId] = state.sessions[currentId];
+  writeJson(statePath(cwd), { ...state, sessions: kept });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "protect-context",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Pi extension that adds agent guardrails: context brief, verification evidence, loop blocking, diff-scope warnings, and a durable journal.",
   "type": "module",
   "license": "MIT",