@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-graft/lifecycle.test.ts

@@ -85,17 +85,17 @@ afterEach(() => {
 });
 
 describe("session start", () => {
-	it("resolves the Git working tree, probes the executable, and publishes a status line", async () => {
+	it("resolves the Git working tree, probes the executable, and writes no status line", async () => {
 		const session = await bootSession();
 		expect(session.commandsRun()).toEqual(["git rev-parse --show-toplevel", "graft --version"]);
-		expect(session.ctx.statuses.get("graft")).toBe("graft: ● structural v0.21.1");
+		expect(session.ctx.ui.setStatus).not.toHaveBeenCalled();
 		await session.reset();
 	});
 
 	it("does nothing at all when the extension is disabled by settings", async () => {
 		const session = await bootSession({ settings: { enabled: false } });
 		expect(session.exec).not.toHaveBeenCalled();
-		expect(session.ctx.statuses.get("graft")).toBeUndefined();
+		expect(session.ctx.ui.setStatus).not.toHaveBeenCalled();
 		await session.reset();
 	});
 
@@ -133,7 +133,9 @@ describe("session start", () => {
 		const session = await bootSession({
 			branch: [{ type: "custom", customType: MODE_ENTRY_TYPE, data: { mode: "hybrid" } }],
 		});
-		expect(session.ctx.statuses.get("graft-mode")).toBe("graft mode: hybrid");
+		const status = session.commands.get("graft")!.handler as (args: string, ctx: unknown) => Promise<void>;
+		await status("status", session.ctx);
+		expect(notified(session.ctx)).toContain("hybrid —");
 		await session.reset();
 	});
 
@@ -171,8 +173,8 @@ describe("session start", () => {
 		const ctx = makeCtx({ cwd: repo });
 		const start = handlerFor(harness, "session_start") as (e: unknown, c: unknown) => Promise<void>;
 		await start({ type: "session_start", reason: "startup" }, ctx);
-		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● structural v0.21.1"));
-		expect(harness.commandsRun()).toContain("npm install -g @nanonets/graft@^0.21");
+		await vi.waitFor(() => expect(harness.commandsRun()).toContain("npm install -g @nanonets/graft@^0.21"));
+		await vi.waitFor(() => expect(harness.commandsRun().filter((c) => c.includes("--version"))).toHaveLength(2));
 
 		await start({ type: "session_start", reason: "reload" }, ctx);
 		expect(harness.commandsRun().filter((command) => command.startsWith("npm install"))).toHaveLength(1);
@@ -194,7 +196,7 @@ describe("session start", () => {
 			ctx,
 		);
 		await vi.waitFor(() => expect(notified(ctx)).toContain("npm access denied"));
-		expect(ctx.statuses.get("graft")).toBe("graft: ✕ no cli");
+		expect(ctx.ui.setStatus).not.toHaveBeenCalled();
 	});
 
 	it("reports that Graft needs a Git working tree without probing anything else", async () => {
@@ -210,7 +212,7 @@ describe("session start", () => {
 			{ type: "session_start", reason: "startup" },
 			ctx,
 		);
-		expect(ctx.statuses.get("graft")).toBe("graft: ✕ n/a");
+		expect(ctx.ui.setStatus).not.toHaveBeenCalled();
 		expect(ctx.ui.notify).not.toHaveBeenCalled();
 	});
 });
@@ -224,6 +226,12 @@ describe("mutation awareness", () => {
 		content: [],
 		isError,
 	});
+	/** Whether the graph counts as changed shows up as a rebuild when the turn ends. */
+	const expectRefreshOnAgentEnd = async (session: Booted, expected: boolean) => {
+		await (handlerFor(session, "agent_end") as (e: unknown, c: unknown) => Promise<void>)({}, session.ctx);
+		if (expected) await vi.waitFor(() => expect(session.commandsRun()).toContain("graft build"));
+		else expect(session.commandsRun()).not.toContain("graft build");
+	};
 	const onToolResult = (session: Booted, toolName: string, input: Record<string, unknown>, isError = false) =>
 		(handlerFor(session, "tool_result") as (e: unknown, c: unknown) => Promise<void>)(
 			toolResultEvent(toolName, input, isError),
@@ -233,14 +241,14 @@ describe("mutation awareness", () => {
 	it("marks the graph changed after a successful edit", async () => {
 		const session = await bootSession();
 		await onToolResult(session, "edit", { path: "src/a.ts" });
-		expect(session.ctx.statuses.get("graft")).toBe("graft: ◐ changed v0.21.1");
+		await expectRefreshOnAgentEnd(session, true);
 		await session.reset();
 	});
 
 	it("marks the graph changed after a clearly mutating bash command", async () => {
 		const session = await bootSession();
 		await onToolResult(session, "bash", { command: "rm -rf dist" });
-		expect(session.ctx.statuses.get("graft")).toBe("graft: ◐ changed v0.21.1");
+		await expectRefreshOnAgentEnd(session, true);
 		await session.reset();
 	});
 
@@ -249,7 +257,7 @@ describe("mutation awareness", () => {
 		await onToolResult(session, "read", { path: "src/a.ts" });
 		await onToolResult(session, "bash", { command: "git status" });
 		await onToolResult(session, "edit", { path: "src/a.ts" }, true);
-		expect(session.ctx.statuses.get("graft")).toBe("graft: ● structural v0.21.1");
+		await expectRefreshOnAgentEnd(session, false);
 		await session.reset();
 	});
 });
@@ -283,8 +291,7 @@ describe("proactive refresh", () => {
 			{ type: "session_start", reason: "startup" },
 			ctx,
 		);
-		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● structural v0.21.1"));
-		expect(harness.commandsRun()).toContain("graft build");
+		await vi.waitFor(() => expect(harness.commandsRun()).toContain("graft build"));
 	});
 
 	it("uses the active TokenIn model for the default deep build", async () => {
@@ -314,7 +321,7 @@ describe("proactive refresh", () => {
 			{ type: "session_start", reason: "startup" },
 			ctx,
 		);
-		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● deep v0.21.1"));
+		await vi.waitFor(() => expect(harness.commandsRun().some((c) => c.startsWith("graft build"))).toBe(true));
 		const build = harness.exec.mock.calls.find((call) => (call[1] as string[]).includes("build"))!;
 		expect(build[1]).toEqual(["build", "--deep"]);
 		expect(build[2]).toMatchObject({
@@ -359,7 +366,8 @@ describe("proactive refresh", () => {
 			{ type: "session_start", reason: "startup" },
 			ctx,
 		);
-		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● deep v0.21.1"));
+		await vi.waitFor(() => expect(notified(ctx)).toContain("retrying the deep pass"));
+		await vi.waitFor(() => expect(models).toEqual(["deepseek-v4.1-flash", "glm-5.3-flash"]));
 		expect(models).toEqual(["deepseek-v4.1-flash", "glm-5.3-flash"]);
 		expect(notified(ctx)).toContain("retrying the deep pass");
 	});
@@ -388,12 +396,12 @@ describe("proactive refresh", () => {
 			{ type: "session_start", reason: "startup" },
 			ctx,
 		);
-		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ● structural v0.21.1"));
+		await vi.waitFor(() => expect(harness.commandsRun().some((c) => c.startsWith("graft build"))).toBe(true));
 		const build = harness.exec.mock.calls.find((call) => (call[1] as string[]).includes("build"))!;
 		expect(build[1]).toEqual(["build"]);
 	});
 
-	it("re-indexes after edits, shows the sync phase, and returns to fresh", async () => {
+	it("re-indexes after edits without touching the status line", async () => {
 		const session = await bootSession({ settings: { refreshDebounceSeconds: 0 } });
 		await (handlerFor(session, "tool_result") as (e: unknown, c: unknown) => Promise<void>)(
 			{ type: "tool_result", toolName: "read", toolCallId: "c", input: {}, content: [], isError: false },
@@ -403,12 +411,10 @@ describe("proactive refresh", () => {
 			{ type: "tool_result", toolName: "write", toolCallId: "c1", input: {}, content: [], isError: false },
 			session.ctx,
 		);
-		expect(session.ctx.statuses.get("graft")).toBe("graft: ◐ changed v0.21.1");
 
 		await (handlerFor(session, "agent_end") as (e: unknown, c: unknown) => Promise<void>)({}, session.ctx);
-		expect(session.ctx.statuses.get("graft")).toBe("graft: ⚙ syncing v0.21.1");
-		await vi.waitFor(() => expect(session.ctx.statuses.get("graft")).toBe("graft: ● structural v0.21.1"));
-		expect(session.commandsRun()).toContain("graft build");
+		await vi.waitFor(() => expect(session.commandsRun()).toContain("graft build"));
+		expect(session.ctx.ui.setStatus).not.toHaveBeenCalled();
 		await session.reset();
 	});
 
@@ -449,7 +455,8 @@ describe("proactive refresh", () => {
 			ctx,
 		);
 		await (handlerFor(harness, "agent_end") as (e: unknown, c: unknown) => Promise<void>)({}, ctx);
-		await vi.waitFor(() => expect(ctx.statuses.get("graft")).toBe("graft: ✕ failed v0.21.1"));
+		await vi.waitFor(() => expect(harness.commandsRun()).toContain("graft build"));
+		expect(ctx.ui.setStatus).not.toHaveBeenCalled();
 	});
 });
 
@@ -592,8 +599,7 @@ describe("session shutdown", () => {
 		const session = await bootSession({ settings: { mode: "push" } });
 		await session.reset();
 
-		expect(session.ctx.statuses.get("graft")).toBeUndefined();
-		expect(session.ctx.statuses.get("graft-mode")).toBeUndefined();
+		expect(session.ctx.ui.setStatus).not.toHaveBeenCalled();
 		expect(process.env[TELEMETRY_ENV]).toBeUndefined();
 
 		const before = session.exec.mock.calls.length;
@@ -714,7 +720,8 @@ describe("mode selection through commands", () => {
 		const handler = session.commands.get("graft")!.handler as (args: string, ctx: unknown) => Promise<void>;
 		await handler("mode hybrid", session.ctx);
 		expect(session.entries).toContainEqual({ customType: MODE_ENTRY_TYPE, data: { mode: "hybrid" as RetrievalMode } });
-		expect(session.ctx.statuses.get("graft-mode")).toBe("graft mode: hybrid");
+		await handler("status", session.ctx);
+		expect(notified(session.ctx)).toContain("hybrid —");
 
 		const result = await (handlerFor(session, "before_agent_start") as (e: unknown, c: unknown) => Promise<unknown>)(
 			{ type: "before_agent_start", prompt: "Refactor src/auth.ts" },

package/dist/extensions/pi-graft/tools.ts

@@ -128,6 +128,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	const scoped = (explicit: string | undefined): string | undefined => explicit ?? runtime.settings().in;
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_find_code",
 		label: "Graft: find code",
 		description:
@@ -172,6 +173,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_file_api",
 		label: "Graft: file API",
 		description:
@@ -197,6 +199,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_trace_calls",
 		label: "Graft: trace calls",
 		description:
@@ -240,6 +243,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_find_all",
 		label: "Graft: find all",
 		description:
@@ -278,6 +282,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "deferred",
 		name: "graft_repo_map",
 		label: "Graft: repo map",
 		description:
@@ -303,6 +308,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "deferred",
 		name: "graft_check_freshness",
 		label: "Graft: check freshness",
 		description:

package/dist/extensions/pi-hermes-memory/CHANGELOG.md

@@ -7,8 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Opt-in chunked subprocess consolidation** (`consolidationChunking`, default `false`): stores above `consolidationChunkChars` (new, default `4000`) consolidate in bounded rounds — a head slice of entries per child run, reloading from disk between rounds, so a killed run resumes from partial progress instead of restarting. The rounds share one overall time budget (`consolidationTimeoutMs`, same worst case as the single call this replaces), the loop stops at the target's capacity goal (failure memory is a 2× tier and is no longer over-merged down to the slice size), a slice that cannot shrink is skipped rather than blocking later slices, A store that fits one prompt runs a single unscoped decisive round with the whole remaining store; a child exiting 0 without shrinking is reported as an honest partial instead of silent success, and an over-chunk store already within its capacity goal is a clean no-op. Partial runs report `partial: true` with the reason and are surfaced by the warning path, the store's add-retry error, and `/memory-consolidate`; disappearances outside a round's slice (rogue child deletions, legitimate cross-slice dedup, or concurrent writers — indistinguishable to the parent) are detected and reported rather than resurrected, because re-adding through the cap-enforcing add path cannot converge and resurrection ping-pongs across triggers. An over-chunk store already within its capacity goal is a clean no-op. Single-shot behavior below the threshold is unchanged.
+
 ### Added
 
+- **Usage-hit tracking — the promotion gate for consolidation** (`usageHitTrackingEnabled` / `consolidationUsageSignals`, both default `true`): `memory_search` now records a per-entry recall counter (`hit_count`) and last-recall date (`last_hit_at`), giving consolidation the usage signal neither the write nor the read path could see before — the prompt's "entries older than 30 days without recent references" rule finally has data behind it. Recording is one batched counter update per search and is invisible to search results, ranking, and prompts. Consolidation (direct and subprocess transports, auto and manual) appends a "Usage Signals" section listing the presented entries' recall counts — both halves capped at 20 lines (tracked entries ranked by hits descending, remainders folded into summary lines), framed as tie-breakers: well-recalled entries are load-bearing (prefer keep/merge), never-recalled entries are weaker keep candidates. The section only appears once at least one presented entry has actually been recalled, so stores without tracking history keep byte-identical prompts. `/memory-insights` gains a usage section (top-recalled entries, tracked/total counts). Counters live on the memory row itself — they die with the entry, need no pruning, and survive the legacy schema rebuild and corruption-recovery copies.
+
+- **One-time provider misconfiguration notice** ([#197](https://github.com/chandra447/pi-hermes-memory/issues/197)): when a review or consolidation completion comes back with an empty answer channel and the whole payload parked in the thinking channel, the extension logs a single warning per session naming the provider/model, explaining that a server-side thinking default is swallowing the answer and that the thinking-channel recovery is best-effort, and pointing the user to fix the provider (`Ask your Pi to fix this as well.`). Normal answers, redacted-only completions, and fully empty completions never trigger it.
+
 - **Opt-in memory lifecycle timings**: `PI_TIMING=1` now reports startup synchronization and loading, backfill and live-index callbacks, shutdown flush/index/wait/close, and database open/integrity-check/checkpoint durations. Normal runs produce no timing output.
 
 - **Opt-in SQLite session retention** ([#183](https://github.com/chandra447/pi-hermes-memory/issues/183)): new `sessionRetentionDays` setting (default `0`, disabled). When set to a positive value, sessions whose JSONL source file has not been updated within the window are pruned from SQLite at startup — rows only, the JSONL files themselves are never deleted — and both the deferred backfill and `/memory-index-sessions` skip files outside the window, so pruned sessions stay pruned instead of being re-indexed on every startup. With the default `0`, pruning is fully disabled and startup keeps the legacy count-only backfill preflight.
@@ -16,13 +24,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **Natural-language search now filters common stop words** ([#184](https://github.com/chandra447/pi-hermes-memory/pull/184)): session and memory searches drop function words (`the`, `is`, `what`, …) before FTS5 matching, improving precision for natural-language queries. Intent-bearing words (`can`, `need`, `off`, `like`, `get`, …) are deliberately kept. A query made up entirely of stop words no longer returns an empty result — it degrades to a scoped literal substring search over the original terms.
+- **Startup markdown→SQLite reconcile is gated per scope** ([#227](https://github.com/chandra447/pi-hermes-memory/issues/227)): `session-start.persistence-sync` previously parsed every markdown file and re-upserted every entry into SQLite on every launch, measured at 2.1–7.2s on large stores. Each markdown scope now carries a fingerprint (`extension_metadata`, written in the same transaction as the reconcile), so an unchanged scope skips the per-entry SQL and an unchanged store's startup cost drops to a directory walk plus a few indexed reads per scope. The fingerprint binds markdown bytes and a row count, not the mirror's content, so mirror drift that preserves the count — a hand-edited row, or a search index that lost rows — now waits for a repair instead of being rewritten on every launch; `/memory-sync-markdown` is the forced full repair for both. New and deleted project dirs are still detected by the walk, and a corruption rebuild re-mirrors markdown exactly once.
+- **Compact flush runs on one shared window** ([#225](https://github.com/chandra447/pi-hermes-memory/issues/225)): the pre-compaction flush previously handed its full 30-second timeout to the direct transport and then again to the subprocess fallback, so a failing direct call re-sent the same large prompt to the subprocess and could spend ~60s saving nothing, silently. The flush now owns a single wall-clock window — new `flushCompactTimeoutMs` setting (default `60000`, raised from the hardcoded `30000`); the direct transport runs first and the subprocess receives only the remaining time. Escape still cancels immediately, and the shutdown flush keeps its own shorter silent cap.
+- **Skill discovery guidance now matches how Pi indexes skills** ([#244](https://github.com/chandra447/pi-hermes-memory/issues/244), [#249](https://github.com/chandra447/pi-hermes-memory/pull/249)): `skill_manage`'s parameter hints, tool description, one-shot example, and prompt guidelines had left the indexed `description` as a what-summary while the "when to use" text went into the body — where Pi never looks at discovery time, so a correct skill could silently never load. The guidance now states that `description` is the only indexed field, demonstrates trigger signals in the one-shot example, and keeps `when_to_use` for the expanded scenario and boundaries; the README section and example frontmatter teach the same rule. A behavioural canary (`tests/skill-discovery-contract.test.ts`) pins the index contract through Pi's public `loadSkills`/`formatSkillsForPrompt` API, so a change in how Pi indexes skills fails in CI instead of silently degrading discovery.
 
 ### Fixed
 
+- **Direct review works for providers with ambient credentials**: Pi resolves `amazon-bedrock` with an AWS profile or SSO session to request auth with no API key and no credential header, because the AWS SDK signs the request itself. The direct transport treated that as `no_auth`, so every review, flush, correction save, and consolidation fell back to the `pi -p` subprocess. The auth check now also accepts a provider that Pi reports as configured (`modelRegistry.hasConfiguredAuth`), the same check Pi runs before a prompt. OAuth providers that resolve to no credentials still report `no_auth`.
+
+- **Background memory jobs work on OpenCode** ([#250](https://github.com/chandra447/pi-hermes-memory/issues/250), reported by [@fallleave001](https://github.com/fallleave001)): the direct transport calls `completeSimple` itself, so it bypassed the session plumbing Pi applies to its own completions, and the OpenCode gateway rejected every review, flush, and correction-save completion with `400 missing_session_id` before the model was reached — losing the memory write, then spending an extra `pi -p` spawn on the fallback. The transport now sends `x-opencode-session` with the real Pi session id from `ctx.sessionManager.getSessionId()`, scoped per model to the `opencode` and `opencode-go` providers and to the `opencode.ai` host, alongside the `x-opencode-client` header Pi sends. Other providers are untouched, an operator-configured session header is never overwritten, and a missing session id degrades to the previous behaviour rather than throwing.
+
 - **FTS5 index errors during markdown sync are surfaced instead of hidden** ([#184](https://github.com/chandra447/pi-hermes-memory/pull/184)): when the FTS5 search index is broken, memory writes still succeed in Markdown, but the tool result and `/memory-sync-markdown` now report the degraded search state together with the repair command instead of showing a silent zero-count success. Genuine database corruption is unaffected by the fallback and now recovers through the markdown sync path too: reconciliation runs inside `DatabaseManager.withCorruptionRecovery()`, so a corrupt `sessions.db` is quarantined, rebuilt, and the sync retried instead of failing every memory write.
+- **A failed compact flush is now visible** ([#225](https://github.com/chandra447/pi-hermes-memory/issues/225)): when the flush cannot save before compaction — budget spent, child process killed by its watchdog, or a child error — the TUI shows one warning naming `flushCompactTimeoutMs` instead of failing silently. The watchdog-killed child path was invisible before. Setting `flushCompactTimeoutMs` to `0` or lower now skips the flush silently (an explicit disable, not a failure), and non-finite values fall back to the default.
 - **Rapid Markdown memory writes now reuse a recent recovery snapshot** ([#214](https://github.com/chandra447/pi-hermes-memory/issues/214)): successive overwrites within one hour publish atomically without creating another `.recovery-*` sidecar, while slower writes still take a fresh snapshot for crash recovery.
 - **Policy-only memory writes bypass the Markdown character cap** ([#218](https://github.com/chandra447/pi-hermes-memory/issues/218)): SQLite is the query authority in policy-only mode, so adds, replacements, and atomic mutation plans can exceed the Markdown export limit without triggering automatic consolidation. Legacy-inject mode keeps its existing caps, grace windows, auto-consolidation, failure limits, and FIFO eviction.
 
+- **Policy-only memory usage is reported as a count, not a percentage** ([#248](https://github.com/chandra447/pi-hermes-memory/issues/248), [#252](https://github.com/chandra447/pi-hermes-memory/pull/252), [#258](https://github.com/chandra447/pi-hermes-memory/pull/258)): policy-only mode intentionally does not apply the Markdown character cap, so a capacity percentage named a ceiling nothing was holding the store to — and, clamped at 100%, it read `100% — <count>/<limit> chars` on every write of an over-cap store. The write tool result and the rendered `MEMORY`, `USER PROFILE`, and `PROJECT MEMORY` headers now render `${current} chars` through one `usageLabel(current, limit)` helper gated on the same `capEnforced` predicate the write gates use, so the report and the gates cannot drift apart again; enforced modes keep the previous percentage strings byte-identical.
+
+- **The memory policy no longer forces the rendered system prompt** ([#251](https://github.com/chandra447/pi-hermes-memory/issues/251)): `before_agent_start` returned a full `systemPrompt`, which Pi documents as replacing the complete prompt for the turn, so the structured sections were flattened into opaque text — a section-aware extension (`pi-doppelclaude` rewrites the named sections and refuses to send when its wording survives) or provider lost the sections it keys on, and its guard fired on every turn. The policy now appends through the structured prompt options, which Pi re-renders from on 0.86+; 0.80.6–0.85.x keep the previous replacement path, because there the session applies only a returned `systemPrompt` and never reads the options back.
+- **Corruption rebuilds no longer carry markdown-scope fingerprints** ([#227](https://github.com/chandra447/pi-hermes-memory/issues/227)): the recovery copies coerce invalid values instead of dropping rows, so a copied fingerprint could agree with coerced rows while content drifted; a rebuilt database now re-mirrors markdown exactly once instead of trusting copied fingerprints.
+
 - **SQLite open integrity scans can be disabled** ([#194](https://github.com/chandra447/pi-hermes-memory/issues/194)): set `quickCheckOnOpen` to `false` to skip the asynchronous startup `PRAGMA quick_check`; operation-time corruption recovery remains enabled.
 
 ### Fixed
@@ -37,6 +58,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`memory_search` ranks by relevance instead of recency** ([#118](https://github.com/chandra447/pi-hermes-memory/pull/118)): FTS5 matches were ordered by `last_referenced DESC` alone, so a long note that mentions a query term once outranked a short memory that is entirely about it, purely because it had been touched more recently. The match now joins `memory_fts` and orders by `bm25(memory_fts)` ascending with `last_referenced DESC` as the tie-break, so the densest match wins and recency only decides between equally relevant rows. Result *sets* are unchanged; only their order is.
 
+### Performance
+
+- **The process-incarnation probe no longer runs at extension load** ([#245](https://github.com/chandra447/pi-hermes-memory/issues/245)): `AtomicLockCoordinator` probed its own incarnation at module scope, so merely importing the module — which happens on every Pi launch, before any hermes code runs — paid a `spawnSync` for a lock most sessions never take. On Windows that is `powershell.exe`, measured at **515ms of the 2108ms** `pi-hermes-memory` module import (`PI_TIMING=1`, six extensions loaded). The probe is now memoized and deferred to the first coordinator construction; `AtomicLockCoordinator.shared()` already builds the coordinator on first lock use and the session-start path takes no lock, so the same profile drops to **1466ms** with no change in locking behavior. Separately, the 500ms `timeout` means the probe always returns `null` where PowerShell takes longer than that to start, which this change does not address.
+
 ## [0.9.4] - 2026-08-08
 
 ### Added

package/dist/extensions/pi-hermes-memory/README.md

@@ -122,6 +122,32 @@ Or test locally without installing:
 pi -e /path/to/pi-hermes-memory/src/index.ts
 ```
 
+### DeepSeek Harness
+
+Use persistent memory in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+through [pi2dsh](https://github.com/weijiafu14/pi2dsh):
+
+```bash
+dsh plugin --profile web add -w pi2dsh pi-hermes-memory
+dsh web
+```
+
+If pnpm requests build approval, run `dsh plugin --profile web approve-builds`,
+approve `better-sqlite3` and `esbuild` when listed, then restart `dsh web`.
+
+In one conversation, ask:
+
+> Use memory_add to remember that my project codename is ZEPHYR-7741.
+
+Start a **new session** and ask:
+
+> Use memory_search to recall my project codename.
+
+Use `memory_replace` to update a saved fact and `memory_remove` to delete it.
+The package manages its own memory files and SQLite store under
+`$DSH_HOME/pi2dsh/agent/` (with the default DSH home when `DSH_HOME` is unset).
+For the headless CLI, install into `--profile headless` instead of `web`.
+
 ### Homebrew / Node ABI mismatches
 
 `better-sqlite3` is a native addon. If Pi is installed via Homebrew and the extension was compiled for a different Node ABI, session search may warn:
@@ -274,6 +300,8 @@ For `create` and `update`, the preferred shape is structured input instead of ha
 
 The tool renders these into a valid `SKILL.md` body with `## When to Use`, `## Procedure`, `## Pitfalls`, and `## Verification` automatically. Raw `content` is still supported for compatibility, but structured fields are the recommended path.
 
+Pi discovers skills by the frontmatter `description` alone — `when_to_use` and the other structured fields render into the body, which Pi reads only after the skill has been selected. Put the trigger phrasings a user would actually type (symptoms, error strings, tool names) in `description`.
+
 Global skill creation also has duplicate/similarity guards:
 
 - exact slug match → blocked (update existing via `patch`/`update`)
@@ -285,13 +313,13 @@ Each skill uses a structured `SKILL.md` body:
 ```markdown
 ---
 name: debug-typescript-errors
-description: Step-by-step approach to debugging TS errors in monorepos
+description: Debug TypeScript errors in a monorepo — tsc --noEmit failures, type-check errors in CI, tsconfig extends-chain breakage
 version: 1
 created: 2026-04-26
 updated: 2026-04-26
 ---
 ## When to Use
-When you see TypeScript compilation errors, especially in monorepo setups.
+TypeScript compilation errors in this workspace, especially monorepo setups. Not for runtime-only type issues.
 
 ## Procedure
 1. Read the error message carefully
@@ -488,8 +516,44 @@ Set extension options under `hermesMemory` in `~/.selesai/agent/settings.json`:
 ```json
 {
   "hermesMemory": {
+    "lazyInitialization": false,
+    "memoryMode": "policy-only",
+    "memoryPolicyStyle": "full",
+    "memoryCharLimit": 5000,
+    "userCharLimit": 5000,
+    "projectCharLimit": 5000,
+    "memoryDir": "~/.selesai/agent/pi-hermes-memory",
+    "projectsMemoryDir": "projects-memory",
+    "sessionSearch": { "variant": "legacy" },
+    "sessionRetentionDays": 0,
+    "quickCheckOnOpen": true,
+    "llmModelOverride": "openrouter/deepseek/deepseek-v4-flash",
     "llmThinkingOverride": "off",
-    "consolidationTimeoutMs": 300000
+    "childExtensionPaths": ["~/.selesai/agent/git/github.com/example/custom-provider-extension/index.ts"],
+    "nudgeInterval": 10,
+    "nudgeToolCalls": 15,
+    "reviewRecentMessages": 0,
+    "reviewEnabled": true,
+    "reviewTransport": "direct",
+    "memoryOverflowStrategy": "auto-consolidate",
+    "autoConsolidate": true,
+    "correctionDetection": true,
+    "failureInjectionEnabled": true,
+    "failureInjectionMaxAgeDays": 7,
+    "failureInjectionMaxEntries": 5,
+    "consolidationTimeoutMs": 300000,
+    "consolidationChunking": false,
+    "consolidationChunkChars": 4000,
+    "usageHitTrackingEnabled": true,
+    "consolidationUsageSignals": true,
+    "overflowGraceMs": 180000,
+    "autoConsolidationWarnOnFailure": true,
+    "flushOnCompact": true,
+    "flushCompactTimeoutMs": 60000,
+    "flushOnShutdown": true,
+    "flushMinTurns": 6,
+    "flushRecentMessages": 0,
+    "standingInstructionsEnabled": true
   }
 }
 ```
@@ -498,6 +562,7 @@ The extension reads these options at startup. Values in `settings.json` override
 
 | Setting | Default | Description |
 |---|---|---|
+| `lazyInitialization` | `false` | Opt in to first-use initialization in `policy-only` mode. Defers Markdown/SQLite sync, ordinary memory loading, maintenance and session indexing until a memory operation needs them. `legacy-inject` keeps eager loading to preserve session snapshots. See below for lifecycle tradeoffs. |
 | `memoryMode` | `policy-only` | Prompt behavior: `policy-only` injects only memory policy; `legacy-inject` restores full memory prompt injection |
 | `memoryPolicyStyle` | `full` | Policy text used in `policy-only` mode: `full` preserves the default v0.7 policy; `compact` uses shorter built-in guidance; `custom` uses `memoryPolicyCustomText`; `none` injects no policy text |
 | `memoryPolicyCustomText` | unset | Custom policy text used when `memoryPolicyStyle` is `custom`; blank or missing text falls back to `compact` |
@@ -520,7 +585,11 @@ The extension reads these options at startup. Values in `settings.json` override
 | `reviewTransport` | `direct` | LLM transport for background review, session flush, correction save, and manual consolidation: `direct` uses in-process `completeSimple()` with subprocess fallback; `subprocess` forces legacy `pi -p` only |
 | `memoryOverflowStrategy` | `auto-consolidate` | Legacy-inject behavior when a Markdown memory file reaches its character limit: `auto-consolidate` runs the existing consolidation flow; `reject` returns an error; `fifo-evict` rotates older entries in file order until the new entry fits |
 | `autoConsolidate` | `true` | Legacy alias for `memoryOverflowStrategy` when `memoryOverflowStrategy` is not set (`true` = `auto-consolidate`, `false` = `reject`) |
-| `consolidationTimeoutMs` | `300000` | Maximum time in milliseconds for a consolidation run (auto and `/memory-consolidate` alike). Configured values are used verbatim; a consolidation pays child-process boot plus a full LLM turn, so values below the default are frequently killed mid-run and log a warning at startup |
+| `consolidationTimeoutMs` | `300000` | Maximum time in milliseconds for a consolidation run (auto and `/memory-consolidate` alike). Also bounds the TOTAL time of a chunked consolidation trigger, so a trigger never blocks longer than the single call it replaced. Configured values are used verbatim; a consolidation pays child-process boot plus a full LLM turn, so values below the default are frequently killed mid-run and log a warning at startup |
+| `consolidationChunking` | `false` | Enables chunked subprocess consolidation: stores whose entries exceed `consolidationChunkChars` are consolidated in bounded rounds with per-round timeouts and resume-from-disk, instead of one whole-store child call. Off by default — enable it if whole-store consolidations time out on your model. Has no effect on the direct in-process transport |
+| `consolidationChunkChars` | `4000` | Applies when `consolidationChunking` is enabled: entries above this many chars (joined) split the subprocess work into multiple child runs that share the `consolidationTimeoutMs` budget, reloading from disk between rounds. The loop stops at the target's capacity goal; a store that fits one prompt runs a single unscoped decisive round. Minimum 500 | When the entries to consolidate exceed this many chars, the subprocess path splits consolidation into multiple child runs (rounds) that share the `consolidationTimeoutMs` budget, reloading from disk between rounds so a killed run resumes from partial progress. The loop stops at the target's capacity goal (not the chunk size). A store that fits one prompt runs a single unscoped decisive round with the whole remaining store. Stores at or below the threshold keep the single-shot call shape — the only difference is that a child exiting 0 without shrinking now reports an honest partial result instead of silent success. Has no effect on the direct in-process transport. Minimum 500 |
+| `usageHitTrackingEnabled` | `true` | Record per-entry recall counts (`hit_count`, `last_hit_at`) every time `memory_search` returns an entry. Recording is invisible — it changes no prompt, ranking, or result — and the counters feed consolidation usage signals and the `/memory-insights` usage section. Set to `false` to stop recording |
+| `consolidationUsageSignals` | `true` | Feed recorded `memory_search` recalls into consolidation prompts as per-entry "Usage Signals" (the promotion gate: well-recalled entries are load-bearing, never-recalled entries are weaker keep candidates — tie-breakers, never removal orders). Inert until entries have actually been recalled, so fresh stores see byte-identical prompts until real usage accrues |
 | `overflowGraceMs` | `180000` | Wall-clock grace period after a memory overflow before automatic consolidation is retried; this gives the active agent time to consolidate manually. Set to `0` to disable the grace period |
 | `autoConsolidationWarnOnFailure` | `true` | Log failed automatic consolidation attempts to the session console. Set to `false` to suppress only this warning; the memory tool result still reports the failure reason |
 | `correctionDetection` | `true` | Detect user corrections and save immediately |
@@ -532,10 +601,56 @@ The extension reads these options at startup. Values in `settings.json` override
 | `failureInjectionMaxAgeDays` | `7` | Legacy mode only: maximum age in days for injected failure memories |
 | `failureInjectionMaxEntries` | `5` | Legacy mode only: maximum number of failure memories to inject |
 | `flushOnCompact` | `true` | Flush memories before Pi compacts context |
+| `flushCompactTimeoutMs` | `60000` | Approximate ceiling in milliseconds for the pre-compaction flush (direct + optional subprocess). Both transports share this one window; the subprocess fallback gets only the remainder, never a second full window. The child's watchdog teardown can add ~5s past the window. Configured values are used verbatim; values below the default warn at startup the same way `consolidationTimeoutMs` does, while `0` or lower silently disables the compact flush. Raise this for slow/local models; lower it if you would rather compact fast than wait for a save |
 | `flushOnShutdown` | `true` | Flush memories when session ends |
 | `flushMinTurns` | `6` | Minimum turns before flush triggers |
 | `flushRecentMessages` | `0` | Recent messages included in session flush (`0` = all) |
 
+### Optional Lazy Initialization
+
+For installations on slow or shared storage, enable:
+
+```json
+{
+  "memoryMode": "policy-only",
+  "lazyInitialization": true
+}
+```
+
+With this option, opening Pi or sending an ordinary prompt does not initialize
+the memory database or read the ordinary memory stores. Tools and commands are
+still registered immediately. The first memory search, write, or data-dependent
+memory command waits for migration, synchronization and loading. Concurrent
+callers share the load; a failed load can be retried by the next operation.
+
+Important boundaries:
+
+- Pinned `STANDING.md` instructions and skill discovery remain available at
+  startup. Pins in a legacy storage root are read independently of migration or
+  SQLite; the primary file, even if empty, takes precedence. `/memory-pin` writes
+  to the primary path without dropping the legacy instructions it loaded.
+- `legacy-inject` ignores the lazy option and preserves its startup snapshot.
+- Automatic review, correction capture and flush retain their existing triggers;
+  when a trigger fires, it initializes memory before reading or writing it.
+  Lazy initialization does not disable automatic learning or its model costs.
+- Session indexing starts after memory activation. Until then, Pi's original
+  JSONL session files remain the source of history. First use joins the scheduled
+  catch-up pass to completion (at most 50 changed files), without using the
+  five-second shutdown timeout. Use `/memory-index-sessions` for a larger backlog.
+  Anchor-mode session search
+  reads JSONL directly and does not activate the memory database.
+- Closing an unused session does not initialize memory just to index it. A
+  configured flush that meets its minimum-turn threshold can still activate it.
+  Shutdown joins in-flight preparation and memory tool/command execution before
+  closing SQLite. Escape cancels a tool's wait without cancelling shared work.
+- Project listing, prompt preview and anchor search do not activate SQLite.
+- This defers data initialization, not extension SDK imports. The direct
+  completion SDK remains a static import so Pi's jiti aliases also work in
+  production installs without package-local SDK peers. First use pays the
+  deferred data-loading cost; this is not a guarantee of faster searches.
+
+The default remains `false`, so existing installations keep eager initialization.
+
 ## Diagnosing lifecycle latency
 
 Run Pi with timing enabled to see which memory lifecycle step is slow:
@@ -547,6 +662,7 @@ PI_TIMING=1 pi
 `pi-hermes-memory` writes these spans to stderr only when timing is enabled:
 
 - `session-start.persistence-sync` and `session-start.load`
+- `memory-init.persistence-sync` and `memory-init.load` instead, when lazy initialization is enabled
 - `session-backfill.check` and `session-backfill.callback`
 - `live-index.callback`
 - `shutdown.flush`, `shutdown.active-index`, `shutdown.index-waits`, and `shutdown.database-close`
@@ -554,6 +670,26 @@ PI_TIMING=1 pi
 
 The deferred backfill, live-index, and integrity-check spans may appear after startup spans because they run on later timer turns. `/reload` does not run `shutdown.flush`; other shutdown reasons keep the configured direct completion and subprocess fallback. Use the measured spans before changing indexing, checkpoint, or synchronization policy.
 
+From a development checkout, compare eager and lazy extension initialization
+without model calls or access to your real memory:
+
+```bash
+node --import tsx scripts/benchmark-memory-startup.mjs
+node --import tsx scripts/benchmark-memory-startup.mjs --lazy
+```
+
+The benchmark uses a disposable agent root with synthetic memories for 20
+projects. It reports import, registration, session startup and first-search
+times separately; it does not measure the full Pi TUI. Run variants sequentially
+and repeat to account for filesystem cache effects. Set `TMPDIR` to a directory
+on shared storage to measure that storage's data initialization cost.
+
+`npm run check:production` packs the checkout, installs it in a temporary directory
+without dev/peer dependencies, and loads it through Pi's real jiti loader. It
+exercises the direct-completion path against a loopback HTTP fixture, not a paid
+model or real memory. npm access is required to install production dependencies;
+native install scripts are disabled because the fixture writes no memories.
+
 ## Where Data Lives
 
 ```