@gtrabanco/pi-agentic-workflow 0.30.0 → 0.34.0

package/README.md

@@ -213,6 +213,47 @@ notification. `requirements` is keyed by phase state (`pre-freeze`, `post-freeze
 matching `path-protection-records@1` `justification` row in the unit's
 `decisions.md`.
 
+## Memory substrate — Engram (optional, ask-first)
+
+The workflow's units save and recall their decisions through Engram, the memory
+layer its skills document. This package can register Engram's MCP server for the
+session, and it does so **only when you say so**:
+
+```json
+{
+  "memory": { "engram": true }
+}
+```
+
+Registration goes through Pi's own `registerMcpServer`, which is
+**session-scoped and not persisted** — the package registers on every session
+start, so nothing outlives the session and nothing is written to your `mcp.json`
+behind your back. Five rules decide the outcome, and the package reports it
+verbatim:
+
+| Situation | What happens |
+|---|---|
+| no `memory.engram` opt-in (the shipped default is `false`) | nothing is registered and nothing is said (the opt-out stays quiet) |
+| no readable opt-in — the file exists but does not validate | nothing is registered; you are told the config is invalid, because unreadable consent is never read as a refusal you made |
+| no `engram` binary on `PATH` | nothing is registered; you are told the install route |
+| you already declared `engram` in a `mcp.json` Pi reads — your user file, or `<cwd>/.pi/mcp.json` in a trusted project | nothing is registered — your declaration takes precedence |
+| binary present, opted in | the server is registered and the notification states exactly what was written |
+
+Install Engram with:
+
+```sh
+pi install npm:gentle-engram@latest
+```
+
+That is the only documented route on purpose: the CLI's own setup subcommand
+pins whatever version ran it and keeps serving that version until it is run
+again, so an updated binary can sit unused behind a stale registration.
+
+An older Pi host whose `ExtensionAPI` has no `registerMcpServer` is reported
+instead of failing the session. The workflow-side protocol — when units save,
+the recall order, the degraded path — lives in `unit-lane`'s memory reference,
+not here.
+
 ## When a configured model is unavailable
 
 Default: the command **refuses to start** and tells you why — the model is not in

package/dist/config/defaults.js

@@ -17,6 +17,9 @@ export const DEFAULT_CONFIG = {
     // Feature 63 — model profiles: recommended built-in profiles, empty
     // named profiles, empty order (default-only), and default demotion policy.
     recommendedModels: true,
+    // Feature 66 — the memory substrate is ask-first: nothing is provisioned
+    // until the operator opts in.
+    memory: { engram: false },
     profiles: {},
     profileOrder: [],
     profileFallback: { ...DEFAULT_PROFILE_FALLBACK },

package/dist/config/merge.js

@@ -127,6 +127,11 @@ export function mergeConfigs(globalFile = {}, projectFile = {}) {
         pathProtection: intersectPathPolicy(SHIPPED_PATH_POLICY, mergePathProtectionOverrides(globalFile.pathProtection, projectFile.pathProtection)),
         // Feature 63 — model profiles.
         recommendedModels: pick(true, projectFile.recommendedModels, globalFile.recommendedModels),
+        // Feature 66 — the consent switch resolves like any other boolean knob:
+        // project wins, then global, then the shipped "no".
+        memory: {
+            engram: pick(false, projectFile.memory?.engram, globalFile.memory?.engram) === true,
+        },
         profiles: mergeProfiles(globalFile.profiles, projectFile.profiles),
         profileOrder: pick([], projectFile.profileOrder, globalFile.profileOrder),
         profileFallback: mergeProfileFallback(globalFile.profileFallback, projectFile.profileFallback),

package/dist/config/schema.d.ts

@@ -13,9 +13,4 @@ export type ParseResult = {
     ok: false;
     issues: ConfigIssue[];
 };
-/**
- * Parse and validate one config file's text. A blank file is an empty config so
- * the loader can treat "nothing declared" like "nothing present" without a
- * second read.
- */
 export declare function parseConfigFile(text: string): ParseResult;

package/dist/config/schema.js

@@ -20,6 +20,7 @@ const ROOT_KEYS = new Set([
     "profiles",
     "profileOrder",
     "profileFallback",
+    "memory",
 ]);
 const ROUTE_KEYS = new Set(["model", "thinking"]);
 const COMMAND_NAME = /^[a-z0-9][a-z0-9._-]*$/u;
@@ -331,7 +332,7 @@ function validateConfig(value) {
         if (!ROOT_KEYS.has(key)) {
             issues.push({
                 path: `$.${displayKey(key)}`,
-                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback)`,
+                message: `unknown config key "${key}" (allowed: default, commands, onUnavailableRoute, onSettle, pathProtection, advance, recommendedModels, profiles, profileOrder, profileFallback, memory)`,
             });
         }
     }
@@ -401,6 +402,11 @@ function validateConfig(value) {
             config.recommendedModels = value.recommendedModels;
         }
     }
+    if (value.memory !== undefined) {
+        const memory = checkMemory(value.memory, "$.memory", issues);
+        if (memory)
+            config.memory = memory;
+    }
     if (value.profiles !== undefined) {
         if (!isRecord(value.profiles)) {
             issues.push({ path: "$.profiles", message: "must be an object mapping profile names to profile definitions" });
@@ -436,6 +442,30 @@ function validateConfig(value) {
  * the loader can treat "nothing declared" like "nothing present" without a
  * second read.
  */
+/** Strict validator for the `memory` consent block (feature 66, AC3). */
+function checkMemory(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: `must be a JSON object, got ${describe(value)}` });
+        return undefined;
+    }
+    let unknown = false;
+    for (const key of Object.keys(value)) {
+        if (key !== "engram") {
+            unknown = true;
+            issues.push({ path: `${path}.${displayKey(key)}`, message: `unknown memory key "${key}" (allowed: engram)` });
+        }
+    }
+    const out = {};
+    if (value.engram !== undefined) {
+        if (typeof value.engram !== "boolean") {
+            issues.push({ path: `${path}.engram`, message: `must be a boolean, got ${describe(value.engram)}` });
+        }
+        else {
+            out.engram = value.engram;
+        }
+    }
+    return unknown ? undefined : out;
+}
 export function parseConfigFile(text) {
     if (text.trim() === "")
         return { ok: true, config: {} };

package/dist/config/types.d.ts

@@ -75,6 +75,9 @@ export interface ConfigFile {
     /** When true (default), the built-in provider profiles are included in the
      *  resolution chain (feature 63, AC1). */
     recommendedModels?: boolean;
+    /** Feature 66 (AC3/D3): the memory-substrate consent surface — Engram's MCP
+     *  registration is ask-first, so nothing is provisioned unless this says so. */
+    memory?: MemoryConfigFile;
     /** Named user profiles keyed by profile name (feature 63, AC5). */
     profiles?: Record<string, ProfileFile>;
     /** Ordered list of profile names to probe; empty means ["default"] only
@@ -92,6 +95,16 @@ export type UnavailableRoutePolicy = "stop" | "inherit";
  */
 export type SettlePolicy = "keep" | "restore";
 /** One rejected field inside one config file, addressed by a JSON-path-ish string. */
+/** What an operator WRITES under `memory` (feature 66). */
+export interface MemoryConfigFile {
+    /** Opt in to the package registering the Engram MCP server when its binary
+     *  resolves. Absent or `false` registers nothing. */
+    engram?: boolean;
+}
+/** What the extension READS: every `memory` knob resolved (feature 66). */
+export interface MemoryConfig {
+    engram: boolean;
+}
 export interface ConfigIssue {
     path: string;
     message: string;
@@ -118,6 +131,8 @@ export interface EffectiveConfig {
     profileOrder: string[];
     /** The effective profile-fallback demotion policy (feature 63). */
     profileFallback: ProfileFallbackConfig;
+    /** Feature 66: the memory-substrate consent surface. */
+    memory: MemoryConfig;
     /** Feature 63: declaredness of the implicit `default` profile. */
     declared: {
         default: RouteDeclaration;

package/dist/extension/engram.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Engram MCP provisioning (feature 66, P4 — AC3, decision D3).
+ *
+ * The memory substrate's registration is **ask-first and reversible**, which is
+ * why it goes through Pi's own consent surface instead of writing a
+ * machine-global `mcp.json` behind the operator's back:
+ *
+ *  - `pi.registerMcpServer(name, config)` is session-scoped and NOT persisted
+ *    (Pi's contract), so the package registers on every session start and nothing
+ *    outlives the session unless the operator asks for it.
+ *  - Registration happens only when the `engram` binary actually resolves — a
+ *    registered-but-broken server would surface as an extension error on every
+ *    session, which is a worse default than not registering.
+ *  - A server the operator already declared in an `mcp.json` Pi reads — the
+ *    user file or, for a trusted project, `<cwd>/.pi/mcp.json` — wins (Pi gives
+ *    it precedence), so the package reports that and does not shadow it.
+ *  - The operator's `memory.engram` config key is the consent switch: absent or
+ *    `false` registers nothing. This module never provisions without it.
+ *
+ * Every outcome is reported verbatim — "exactly what was written" is the rule
+ * the sibling `init-workspace` consent flow already follows, and a
+ * provisioning step the operator cannot read back is one they cannot trust.
+ *
+ * The install route is `pi install npm:gentle-engram@latest`. The CLI's own
+ * setup subcommand is deliberately NOT the documented route: it pins whatever
+ * version it ran with and keeps serving it until it is run again, so an updated
+ * binary can sit unused behind a stale registration.
+ *
+ * Pi-free by construction — the binary lookup, the environment, the "already
+ * declared" names and the register callback are all injected, so every branch
+ * is tested with no Pi session, no PATH and no real binary.
+ */
+/** The name the server is registered under, and what `mcp.json` would declare. */
+export declare const ENGRAM_SERVER_NAME = "engram";
+/** The argv the workflow's runners use (pi's own registration, measured). */
+export declare const ENGRAM_ARGS: readonly ["mcp", "--tools=agent"];
+/** The one documented install route (D3). */
+export declare const ENGRAM_INSTALL_ROUTE = "pi install npm:gentle-engram@latest";
+export type EngramStatus = "registered" | "not-consented" | "config-invalid" | "binary-missing" | "already-declared" | "unsupported-host";
+export interface EngramServerConfig {
+    command: string;
+    args: string[];
+}
+export interface EngramProvisionInput {
+    /** The operator's consent: `config.memory.engram`. Absent means no. */
+    consented: boolean;
+    /** True when the package's config file exists but does not parse or validate.
+     *  Consent is then UNKNOWN, not refused: `loadConfig` fails closed to the
+     *  shipped default, so reading `consented` off that default would tell an
+     *  opted-in operator to opt in — `config/load.ts` calls a present-but-invalid
+     *  file a problem, never a silent default, and `dispatch.ts` refuses on the
+     *  same flag. Checked before consent. */
+    configInvalid?: boolean;
+    /** Absolute path of the resolved `engram` binary, or null when not found. */
+    binaryPath: string | null;
+    /** Server names the operator already declared (a `mcp.json` name wins), read
+     *  from every scope Pi itself reads — see `declaredMcpServerPaths`. */
+    declaredNames: readonly string[];
+    /** Pi's registrar, injected so this module never imports Pi. `null` when the
+     *  host's ExtensionAPI predates `registerMcpServer` — the package's peer floor
+     *  is a range, so an older host degrades instead of throwing. */
+    register: ((name: string, config: EngramServerConfig) => void) | null;
+}
+export interface EngramReport {
+    status: EngramStatus;
+    /** Present only when `status === "registered"`: exactly what was written. */
+    server?: {
+        name: string;
+    } & EngramServerConfig;
+    /** One line an operator can read back; states what was written or why not. */
+    message: string;
+}
+/**
+ * The server names an operator already declared in an `mcp.json` file. Pi gives
+ * a declared server precedence over an extension registration, so the caller
+ * passes this in and the module reports rather than shadows. Unreadable or
+ * malformed JSON yields `[]`: a file this module cannot parse is not evidence
+ * of a declaration, and refusing to register on it would be a silent gap.
+ */
+export declare function readDeclaredServerNames(path: string): string[];
+/**
+ * The union of the names declared across the `mcp.json` files Pi reads. One
+ * file's declaration is not evidence about the other's.
+ */
+export declare function readDeclaredServerNamesFrom(paths: readonly string[]): string[];
+/**
+ * The `mcp.json` files Pi reads for one session: the user-level file, and — for
+ * a trusted project only — `<cwd>/.pi/mcp.json`, whose entry replaces a
+ * same-named user entry (Pi's `mcp.md`: project configuration is read only after
+ * trust is granted, and "a project entry replaces a user-level entry with the
+ * same name"). The anti-shadow guard has to consult the same surface the host
+ * applies: reading only the user file let a project declaration slip past it, so
+ * the package registered anyway and then reported precedence over a file it had
+ * never opened.
+ */
+export declare function declaredMcpServerPaths({ agentDir, cwd, projectTrusted, }: {
+    agentDir: string;
+    cwd: string;
+    projectTrusted: boolean;
+}): string[];
+/**
+ * Resolve `engram` on `PATH` without a shell, honouring `PATHEXT` on Windows.
+ * Injected `exists`/`env` keep the lookup testable; the production caller takes
+ * the defaults.
+ */
+export declare function resolveEngramBinary({ env, exists, platform, }?: {
+    env?: Record<string, string | undefined>;
+    exists?: (path: string) => boolean;
+    platform?: NodeJS.Platform;
+}): string | null;
+/**
+ * Decide and perform the registration, in the order that makes the outcome
+ * truthful: a config that cannot be read first (its consent is unknown, never
+ * refused), then consent (never provision unasked), then the binary (never
+ * register a server that cannot start), then the operator's own declaration
+ * (never shadow it). Returns the report; it never throws and never mutates
+ * anything beyond the injected `register` call.
+ */
+export declare function provisionEngram(input: EngramProvisionInput): EngramReport;

package/dist/extension/engram.js

@@ -0,0 +1,187 @@
+/**
+ * Engram MCP provisioning (feature 66, P4 — AC3, decision D3).
+ *
+ * The memory substrate's registration is **ask-first and reversible**, which is
+ * why it goes through Pi's own consent surface instead of writing a
+ * machine-global `mcp.json` behind the operator's back:
+ *
+ *  - `pi.registerMcpServer(name, config)` is session-scoped and NOT persisted
+ *    (Pi's contract), so the package registers on every session start and nothing
+ *    outlives the session unless the operator asks for it.
+ *  - Registration happens only when the `engram` binary actually resolves — a
+ *    registered-but-broken server would surface as an extension error on every
+ *    session, which is a worse default than not registering.
+ *  - A server the operator already declared in an `mcp.json` Pi reads — the
+ *    user file or, for a trusted project, `<cwd>/.pi/mcp.json` — wins (Pi gives
+ *    it precedence), so the package reports that and does not shadow it.
+ *  - The operator's `memory.engram` config key is the consent switch: absent or
+ *    `false` registers nothing. This module never provisions without it.
+ *
+ * Every outcome is reported verbatim — "exactly what was written" is the rule
+ * the sibling `init-workspace` consent flow already follows, and a
+ * provisioning step the operator cannot read back is one they cannot trust.
+ *
+ * The install route is `pi install npm:gentle-engram@latest`. The CLI's own
+ * setup subcommand is deliberately NOT the documented route: it pins whatever
+ * version it ran with and keeps serving it until it is run again, so an updated
+ * binary can sit unused behind a stale registration.
+ *
+ * Pi-free by construction — the binary lookup, the environment, the "already
+ * declared" names and the register callback are all injected, so every branch
+ * is tested with no Pi session, no PATH and no real binary.
+ */
+import { accessSync, constants, readFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
+/** The directory a project keeps its own agent config in — Pi's `.pi/`. */
+const PROJECT_DIR = ".pi";
+/** The name the server is registered under, and what `mcp.json` would declare. */
+export const ENGRAM_SERVER_NAME = "engram";
+/** The argv the workflow's runners use (pi's own registration, measured). */
+export const ENGRAM_ARGS = ["mcp", "--tools=agent"];
+/** The one documented install route (D3). */
+export const ENGRAM_INSTALL_ROUTE = "pi install npm:gentle-engram@latest";
+/**
+ * The server names an operator already declared in an `mcp.json` file. Pi gives
+ * a declared server precedence over an extension registration, so the caller
+ * passes this in and the module reports rather than shadows. Unreadable or
+ * malformed JSON yields `[]`: a file this module cannot parse is not evidence
+ * of a declaration, and refusing to register on it would be a silent gap.
+ */
+export function readDeclaredServerNames(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" || parsed === null)
+            return [];
+        const servers = parsed.mcpServers;
+        if (typeof servers !== "object" || servers === null)
+            return [];
+        return Object.keys(servers);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The union of the names declared across the `mcp.json` files Pi reads. One
+ * file's declaration is not evidence about the other's.
+ */
+export function readDeclaredServerNamesFrom(paths) {
+    const names = new Set();
+    for (const path of paths) {
+        for (const name of readDeclaredServerNames(path))
+            names.add(name);
+    }
+    return [...names];
+}
+/**
+ * The `mcp.json` files Pi reads for one session: the user-level file, and — for
+ * a trusted project only — `<cwd>/.pi/mcp.json`, whose entry replaces a
+ * same-named user entry (Pi's `mcp.md`: project configuration is read only after
+ * trust is granted, and "a project entry replaces a user-level entry with the
+ * same name"). The anti-shadow guard has to consult the same surface the host
+ * applies: reading only the user file let a project declaration slip past it, so
+ * the package registered anyway and then reported precedence over a file it had
+ * never opened.
+ */
+export function declaredMcpServerPaths({ agentDir, cwd, projectTrusted, }) {
+    const paths = [join(agentDir, "mcp.json")];
+    if (projectTrusted)
+        paths.push(join(cwd, PROJECT_DIR, "mcp.json"));
+    return paths;
+}
+/**
+ * Resolve `engram` on `PATH` without a shell, honouring `PATHEXT` on Windows.
+ * Injected `exists`/`env` keep the lookup testable; the production caller takes
+ * the defaults.
+ */
+export function resolveEngramBinary({ env = process.env, exists = isExecutable, platform = process.platform, } = {}) {
+    const pathValue = env.PATH ?? env.Path ?? "";
+    if (pathValue === "")
+        return null;
+    const extensions = platform === "win32" ? splitExtensions(env.PATHEXT) : [""];
+    for (const dir of pathValue.split(delimiter)) {
+        if (dir === "")
+            continue;
+        for (const extension of extensions) {
+            const candidate = join(dir, `${ENGRAM_SERVER_NAME}${extension}`);
+            if (exists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+function splitExtensions(pathext) {
+    const raw = (pathext ?? ".EXE;.CMD;.BAT;.COM").split(";").filter((value) => value !== "");
+    return [...raw, ""];
+}
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decide and perform the registration, in the order that makes the outcome
+ * truthful: a config that cannot be read first (its consent is unknown, never
+ * refused), then consent (never provision unasked), then the binary (never
+ * register a server that cannot start), then the operator's own declaration
+ * (never shadow it). Returns the report; it never throws and never mutates
+ * anything beyond the injected `register` call.
+ */
+export function provisionEngram(input) {
+    const { consented, configInvalid, binaryPath, declaredNames, register } = input;
+    if (configInvalid === true) {
+        return {
+            status: "config-invalid",
+            message: `pi-agentic-workflow: Engram not registered — the package's config file is invalid, so ` +
+                `its consent could not be read and nothing was written (fix the reported problems and ` +
+                `the next session reads the switch again).`,
+        };
+    }
+    if (!consented) {
+        return {
+            status: "not-consented",
+            message: `pi-agentic-workflow: Engram not registered — set "memory": { "engram": true } in ` +
+                `pi-agentic-workflow.json to opt in (nothing was written).`,
+        };
+    }
+    if (binaryPath === null) {
+        return {
+            status: "binary-missing",
+            message: `pi-agentic-workflow: Engram not registered — no "engram" binary on PATH, so ` +
+                `nothing was written. Install it with: ${ENGRAM_INSTALL_ROUTE}`,
+        };
+    }
+    if (register === null) {
+        return {
+            status: "unsupported-host",
+            message: `pi-agentic-workflow: Engram not registered — this Pi host exposes no ` +
+                `registerMcpServer, so the server was not added (nothing was written).`,
+        };
+    }
+    if (declaredNames.includes(ENGRAM_SERVER_NAME)) {
+        return {
+            status: "already-declared",
+            message: `pi-agentic-workflow: Engram not registered — "${ENGRAM_SERVER_NAME}" is already ` +
+                `declared in an mcp.json Pi reads, which takes precedence (nothing was written).`,
+        };
+    }
+    const config = { command: binaryPath, args: [...ENGRAM_ARGS] };
+    register(ENGRAM_SERVER_NAME, config);
+    return {
+        status: "registered",
+        server: { name: ENGRAM_SERVER_NAME, ...config },
+        message: `pi-agentic-workflow: registered MCP server "${ENGRAM_SERVER_NAME}" → ` +
+            `${binaryPath} ${ENGRAM_ARGS.join(" ")} (session-scoped; Pi does not persist it)`,
+    };
+}

package/dist/extension/index.js

@@ -9,6 +9,7 @@ import { readGitStatusBounded } from "./receipt-guard.js";
 import { createPickerComponent, PICKER_MAX_VISIBLE, pagedSelect } from "../settings/picker.js";
 import { createHintStore, createSerenaReadinessStore, stateFilePath } from "../routing/state.js";
 import { createSerenaReadinessGate, readInitWorkspaceRevision } from "../routing/serena-readiness.js";
+import { provisionEngram, readDeclaredServerNamesFrom, resolveEngramBinary, declaredMcpServerPaths } from "./engram.js";
 import { runSettingsConsole } from "../settings/console.js";
 import { readConfigFile, writeConfigFile } from "../settings/store.js";
 import { SETTINGS_COMMAND } from "../routing/types.js";
@@ -172,6 +173,48 @@ function resolveExistingPrefix(target) {
         }
     }
 }
+/**
+ * Pi's MCP registrar, read structurally rather than imported: the package's
+ * peer floor is a range, and a host older than `registerMcpServer` must degrade
+ * (the provisioning module reports `unsupported-host`) instead of throwing at
+ * load.
+ */
+function mcpRegistrar(pi) {
+    const candidate = pi.registerMcpServer;
+    if (typeof candidate !== "function")
+        return null;
+    return (name, config) => {
+        candidate.call(pi, name, config);
+    };
+}
+/**
+ * The server names the operator already has declared — the set the anti-shadow
+ * guard is judged against. Both surfaces are unioned: Pi's own `getMcpServers()`
+ * (read structurally for the same peer-floor reason as the registrar; it is the
+ * merged view the host applies), and the `mcp.json` files Pi reads for this
+ * session, user file and trusted project file alike. Either one answering is
+ * enough to refuse; reading only the user file was the F6 defect, which
+ * registered over a project declaration and then reported precedence over a
+ * file it had never opened.
+ */
+function declaredServerNames(pi, agentDir, ctx) {
+    const names = new Set(readDeclaredServerNamesFrom(declaredMcpServerPaths({ agentDir, cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted() })));
+    const candidate = pi.getMcpServers;
+    if (typeof candidate === "function") {
+        try {
+            const listed = candidate.call(pi);
+            if (Array.isArray(listed)) {
+                for (const server of listed)
+                    if (typeof server?.name === "string")
+                        names.add(server.name);
+            }
+        }
+        catch {
+            // A host that cannot answer is not a declaration: the file reads stand.
+        }
+    }
+    return [...names];
+}
 export default function extension(pi) {
     const agentDir = getAgentDir();
     const hint = createHintStore({ path: stateFilePath(agentDir) });
@@ -214,13 +257,37 @@ export default function extension(pi) {
             writeFile: writeConfigFile,
         }),
     });
-    // The readiness nudge's first chance (AC9): a session that opens here hears
-    // it, and the gate latches so the command path never repeats it. Soft by
-    // construction — the gate swallows a broken read and a failed latch.
+    // One `session_start` listener carries both first chances, in this order.
+    //
+    // The readiness nudge (AC9) hears the session here, and the gate latches so
+    // the command path never repeats it — soft by construction, because the gate
+    // swallows a broken read and a failed latch.
+    //
+    // Memory substrate (feature 66, AC3) comes second: ask-first,
+    // registrable-not-persisted. Registration runs on the session rather than at
+    // load so an older Pi host is reported instead of throwing, and so the
+    // operator reads back exactly what was written. Nothing is provisioned
+    // without the `memory.engram` opt-in, and a config file that does not parse
+    // is never read as one: its consent is unknown, and the refusal says so
+    // instead of telling an opted-in operator to opt in.
     pi.on("session_start", (_event, ctx) => {
         const message = serenaReadiness.check(ctx.cwd);
         if (message)
             ctx.ui.notify(message, "warning");
+        const projectTrusted = ctx.isProjectTrusted();
+        const loaded = loadConfig({ agentDir, cwd: ctx.cwd, projectTrusted });
+        const report = provisionEngram({
+            consented: loaded.config.memory?.engram === true,
+            configInvalid: !loaded.ok,
+            binaryPath: resolveEngramBinary(),
+            declaredNames: declaredServerNames(pi, agentDir, ctx),
+            register: mcpRegistrar(pi),
+        });
+        // The opt-out stays silent; every other outcome is stated once, in the
+        // module's own words (it already says what was written, or why not).
+        if (report.status !== "not-consented") {
+            ctx.ui.notify(report.message, report.status === "registered" ? "info" : "warning");
+        }
     });
     pi.on("model_select", (event) => router.noteModelSelect(event.model));
     pi.on("thinking_level_select", (event) => router.noteThinkingLevelSelect(event.level));