@gtrabanco/pi-agentic-workflow 0.26.0 → 0.31.0

package/README.md

@@ -146,6 +146,47 @@ set of routes, and you can define as many as you like under `profiles`:
   The built-in `nan` profile is shown but not editable — create a profile to
   override it.
 
+## Serena (ships by default)
+
+Installing this package also gives you **Serena's language-server tools** —
+`serena_find_symbol`, `serena_find_referencing_symbols`,
+`serena_get_symbols_overview`, `serena_find_declaration`, diagnostics and the
+rest. Two declarations make that work, and they ship together: the exact-pinned
+`@bacnh85/pi-serena` dependency, and a second `pi.extensions` entry pointing at
+that dependency's own extension. Pi installs a package's dependencies but
+activates only the package's own `pi.extensions` entries, so the pin alone would
+install a toolset nothing ever loaded.
+
+**You must run `/init-workspace` once per project.** This package never writes or
+repairs `.serena/project.yml` — `init-workspace` is its only writer, so there is
+one implementation of that contract and no drift. A project whose config is
+missing, lists no `language_servers`, or was provisioned by an older bundled
+`init-workspace` gets **one** notification per session state pointing at
+`/init-workspace`; the latch lives in this package's state file, so a restart does
+not re-nag.
+
+Serena itself is a local tool: install the machine half with `uv tool install -p
+3.13 serena-agent` (or `/init-workspace`, which offers it). Nothing is uploaded
+and no key is configured.
+
+**Switching it off.** pi owns package resources, so the off switch is pi's, not a
+key of ours: `pi config` opens the resource picker (tab switches scope) and lets
+you disable the package's resources, and the same filter is expressible in
+settings under `packages`:
+
+```json
+{
+  "packages": [
+    { "source": "npm:@gtrabanco/pi-agentic-workflow", "extensions": ["./dist/extension/index.js"] }
+  ]
+}
+```
+
+That keeps the workflow's own extension and commands and drops the Serena
+extension entry, so the `serena_*` tools are never registered. There is no
+settings key inside this package for it: the entry is declared in the manifest,
+and a config key cannot gate a manifest-declared extension.
+
 ## Path protection (optional)
 
 The Tier 2 preventive guard blocks a `write` / `edit` tool call to an existing
@@ -172,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/factory.d.ts

@@ -43,6 +43,12 @@ export interface ExtensionDeps<M extends ModelRef = ModelRef> {
     loadConfig?: (ctx: InvocationContext<M>) => LoadedConfig;
     /** P4: profile demotion state store (optional — defaults to file-backed). */
     profileState?: import("../routing/state.js").ProfileStateStore;
+    /**
+     * Feature 67 D5/AC9: the Serena readiness nudge. Consulted at the first
+     * workflow-command dispatch, so a session that never starts through
+     * `session_start` still hears it once.
+     */
+    serenaReadiness?: import("../routing/serena-readiness.js").SerenaReadinessGate;
 }
 export interface ExtensionHandle<M extends ModelRef = ModelRef> {
     router: Router<M>;

package/dist/extension/factory.js

@@ -31,11 +31,19 @@ export function createExtension(deps) {
     // P4: build the profile state store when not provided.
     const profileState = deps.profileState ?? createProfileStateStore({ path: stateFilePath(agentDir) });
     const router = createRouter({ surface, loadConfig: read, hint, settingsCommand: SETTINGS_COMMAND, knownCommands, profileState });
+    // Said once per state, not once per command: the gate latches in memory for
+    // this session and in the package's state file for later ones.
+    const reportSerenaReadiness = (ctx) => {
+        const message = deps.serenaReadiness?.check(ctx.cwd);
+        if (message)
+            ctx.notify(message, "warning");
+    };
     for (const command of catalogue.commands) {
         registrar.registerCommand(command.name, {
             ...(command.description ? { description: command.description } : {}),
             handler: async (args, ctx) => {
                 reportCatalogueIssues(ctx);
+                reportSerenaReadiness(ctx);
                 await router.dispatch(command, args, ctx);
             },
         });
@@ -44,6 +52,7 @@ export function createExtension(deps) {
     // and the same two config files, never a separate route surface (OB-5, AC6).
     const settingsHandler = async (_args, ctx) => {
         reportCatalogueIssues(ctx);
+        reportSerenaReadiness(ctx);
         // Bound for the console: two verbs and the session they act on, so it cannot
         // reach for `settle` or `dispatch` by accident.
         const routing = {