@mnemom/mnemom 0.17.11-next.0 → 0.17.11-next.1

package/dist/commands/agent-doctor.d.ts

@@ -9,11 +9,14 @@
  * Checks: settings file, coding-agent CLI, Anthropic key source, gateway health
  * (200 + the x-mnemom-verdict header that proves the governance pipeline is
  * live), Remote-Control capability (node + openssl + the --remote-control flag),
- * claude.ai login (informational — Remote Control needs it), and CLI auto-update status.
+ * claude.ai login (informational — Remote Control needs it), the agent's governance
+ * modes (off by default for new agents), and CLI auto-update status.
  */
 type Mark = "ok" | "warn" | "miss" | "info";
 export interface DoctorOptions {
     cli?: string;
+    /** The agent slug a launch would use (--agent / launcher.toml); default agent-<handle>. */
+    agent?: string;
 }
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
 export declare function agentDoctorCommand(options?: DoctorOptions): Promise<void>;
@@ -29,4 +32,17 @@ export interface CodeAccessProbe {
  * anything inconclusive → info, never a MISS (the launch preamble fails open too).
  */
 export declare function probeCodeAccess(): Promise<CodeAccessProbe>;
+export interface GovernanceProbe {
+    mark: Mark;
+    text: string;
+    hint?: string;
+}
+/**
+ * The governance line: the composed (every layer, strictest wins) integrity and
+ * Safe House modes of the agent a launch would use. Signed out, no such agent,
+ * or an unreadable card → info with the off-by-default note, never a MISS
+ * (governance never blocks a launch). On → info naming the per-turn cost; the
+ * agent's own card says off but a stricter layer keeps it on → warn.
+ */
+export declare function probeGovernance(agent: string | undefined): Promise<GovernanceProbe>;
 export {};

package/dist/commands/agent-doctor.js

@@ -9,7 +9,8 @@
  * Checks: settings file, coding-agent CLI, Anthropic key source, gateway health
  * (200 + the x-mnemom-verdict header that proves the governance pipeline is
  * live), Remote-Control capability (node + openssl + the --remote-control flag),
- * claude.ai login (informational — Remote Control needs it), and CLI auto-update status.
+ * claude.ai login (informational — Remote Control needs it), the agent's governance
+ * modes (off by default for new agents), and CLI auto-update status.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -19,11 +20,12 @@ import { resolveAgentAuth } from "../lib/subscription-login.js";
 import { isProdGateway, resolveAnthropicDoor, resolveGatewayHost, singleCellError, } from "../lib/agent.js";
 import { getApiUrl, getGatewayUrl } from "../lib/config.js";
 import { LAUNCHER_CONFIG_PATH } from "../lib/launcher-config.js";
-import { getCodeEntitlement, MnemomApiError } from "../lib/api.js";
+import { getAgentByName, getCardSources, getCodeEntitlement, MnemomApiError } from "../lib/api.js";
 import { isLoggedIn } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
 import { isCodeNotEnabled, sourceLabel } from "./agent-invite.js";
 import { probeUpdateStatus } from "../lib/update/doctor.js";
+import { describeModes, GOVERNANCE_OPT_IN_HINT, resolveDefaultSlug } from "./agent-setup.js";
 const MARK = { ok: "[ ok ]", warn: "[warn]", miss: "[MISS]", info: "[info]" };
 const out = (line = "") => console.log(line);
 /** Run the preflight and print the checklist. Sets process.exitCode on failure. */
@@ -115,6 +117,9 @@ export async function agentDoctorCommand(options = {}) {
     // ── Mnemom Agent access (invited cohort gate) ──
     const gate = await probeCodeAccess();
     add(gate.mark, gate.text, gate.hint);
+    // ── governance (off by default for new agents) ──
+    const gov = await probeGovernance(options.agent);
+    add(gov.mark, gov.text, gov.hint);
     // ── CLI auto-update ──
     const upd = await probeUpdateStatus();
     add(upd.mark, upd.text, upd.hint);
@@ -217,3 +222,74 @@ export async function probeCodeAccess() {
         return { mark: "info", text: `Mnemom Agent access: could not determine (${detail})` };
     }
 }
+const OPT_IN_HINT = GOVERNANCE_OPT_IN_HINT.trim();
+/**
+ * The governance line: the composed (every layer, strictest wins) integrity and
+ * Safe House modes of the agent a launch would use. Signed out, no such agent,
+ * or an unreadable card → info with the off-by-default note, never a MISS
+ * (governance never blocks a launch). On → info naming the per-turn cost; the
+ * agent's own card says off but a stricter layer keeps it on → warn.
+ */
+export async function probeGovernance(agent) {
+    const offByDefault = {
+        mark: "info",
+        text: "governance: off by default for new agents (AIP integrity analysis, Safe House screening)",
+        hint: `${OPT_IN_HINT} Agents set up before this default keep their cards.`,
+    };
+    if (!(await isLoggedIn()))
+        return offByDefault;
+    try {
+        const slug = agent?.trim() || (await resolveDefaultSlug());
+        const found = await getAgentByName(slug);
+        if (!found)
+            return offByDefault;
+        const [align, prot] = await Promise.all([
+            getCardSources("alignment", found.id),
+            getCardSources("protection", found.id),
+        ]);
+        const read = (s, layer, field) => {
+            const v = s?.[layer]?.card_json?.[field];
+            return typeof v === "string" && v ? v : undefined;
+        };
+        // A composed card without the field (or none composed yet) is unknown, not
+        // off: the data plane falls back to its own default (observe for integrity),
+        // so the doctor never claims governance is off when it can't see it.
+        const composed = {
+            integrity: read(align, "composed", "integrity_mode") ?? "unknown",
+            protection: read(prot, "composed", "mode") ?? "unknown",
+        };
+        const own = {
+            integrity: read(align, "agent", "integrity_mode"),
+            protection: read(prot, "agent", "mode"),
+        };
+        const text = `governance: ${slug} — ${describeModes(composed)}`;
+        const stricter = (mine, eff) => mine === "off" && eff !== "off" && eff !== "unknown";
+        const overridden = stricter(own.integrity, composed.integrity) || stricter(own.protection, composed.protection);
+        if (overridden) {
+            return {
+                mark: "warn",
+                text,
+                hint: "the agent's own card says off, but a stricter org, team or platform policy keeps it on — it still runs and is billed",
+            };
+        }
+        if (composed.integrity === "off" && composed.protection === "off") {
+            return { mark: "ok", text, hint: OPT_IN_HINT };
+        }
+        if (composed.integrity === "unknown" || composed.protection === "unknown") {
+            return {
+                mark: "info",
+                text,
+                hint: "no composed card yet for at least one feature — it reads once the agent's cards compose (re-run `mnemom agent doctor` in a minute)",
+            };
+        }
+        return {
+            mark: "info",
+            text,
+            hint: "each feature that is on is a model call per turn, billed at cost on top of the agent fee — `mnemom agent setup --no-governance` turns it off",
+        };
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return { ...offByDefault, text: `governance: could not read the agent's cards (${detail})` };
+    }
+}

package/dist/commands/agent-setup.d.ts

@@ -16,6 +16,9 @@
  *     screen_surfaces declared, ready for when it is turned on.
  *   - goal-alignment: nudge — sealed per-conversation via the goal contract
  *     (--goal …), graded and re-anchored by the gateway.
+ * `--governance [integrity,safe-house]` opts a setup in (observe-only, billed at
+ * cost on top of the agent fee); a refresh of an already-claimed agent keeps the
+ * modes its own cards carry unless a --governance / --no-governance flag says otherwise.
  *
  * A launch never runs on an unclaimed agent (operator 2026-10-03): an unclaimed agent lands in
  * the sandbox org and bills nobody. ensureClaimedServedAgent asks the gateway which agent it
@@ -26,6 +29,43 @@
  * reinventing it.
  */
 import { type CodeEntitlement } from "../lib/api.js";
+/** A card's governance mode as the CLI writes it: off, or observe-only. */
+export type GovernanceMode = "off" | "observe";
+/**
+ * The governance features a setup turns on. Each is a model call per turn that
+ * the customer pays for at cost, so both are off unless asked for.
+ */
+export interface GovernanceOptIn {
+    /** AIP integrity analysis (alignment card integrity_mode). */
+    integrity: boolean;
+    /** Safe House screening (protection card mode). */
+    safeHouse: boolean;
+}
+/** The feature names `--governance <list>` accepts (plus `all` / `none`). */
+export declare const GOVERNANCE_FEATURES: readonly ["integrity", "safe-house"];
+/**
+ * Parse the `--governance [features]` / `--no-governance` flag. undefined = not
+ * given (new agents get none; a refresh keeps the agent's current modes),
+ * true = every feature, false = none, a string = a comma-separated list of
+ * `integrity`, `safe-house`, `all` or `none`. Throws on an unknown name.
+ */
+export declare function parseGovernanceFlag(value: boolean | string | undefined): GovernanceOptIn | undefined;
+/**
+ * The modes a setup writes into the two cards: off/observe from the flag, or
+ * whatever an existing agent's own cards already carry (kept as-is on a refresh).
+ */
+export interface CardModes {
+    /** autonomy_mode — verification + policy. No model call, so not billed; kept as-is on a refresh. */
+    autonomy: string;
+    integrity: string;
+    protection: string;
+}
+/** One phrase for the posture line: "integrity off, Safe House off". */
+export declare function describeModes(m: Pick<CardModes, "integrity" | "protection">): string;
+/** The modes for a NEW agent: off unless --governance asks for a feature. */
+export declare function newAgentModes(governance?: GovernanceOptIn): CardModes;
+/** Printed when a setup ran without --governance: how to opt in, and what it costs. */
+export declare const GOVERNANCE_OPT_IN_HINT: string;
 /**
  * The default governed-agent slug for the current customer: `agent-<handle>`,
  * where <handle> is the local-part of their mnemom login email (sanitised), or
@@ -73,6 +113,12 @@ export interface ClaimedAgentOptions {
     orgLabel: string;
     /** true = --setup (re-ask the gateway, refresh the cards); false = --no-setup (no card writes). */
     setup?: boolean;
+    /**
+     * `--governance` / `--no-governance`: the modes the cards get. undefined = a new agent's are
+     * off, and a refresh keeps the agent's current modes. Given on a claimed agent, it also
+     * refreshes the cards (unless --no-setup).
+     */
+    governance?: GovernanceOptIn;
     /** Where the served-agent cache lives (defaults to ~/.mnemom). */
     cacheDir?: string;
 }
@@ -124,9 +170,10 @@ export declare function ensureClaimedServedAgent(opts: ClaimedAgentOptions): Pro
  * (`details.required_scope`). Never the token, never the body.
  */
 export declare function describeApiError(err: unknown): string;
-/** `mnemom agent setup [--agent <slug>]` — the explicit provisioning entry point. */
+/** `mnemom agent setup [--agent <slug>] [--governance …]` — the explicit provisioning entry point. */
 export declare function agentSetupCommand(opts?: {
     agent?: string;
+    governance?: GovernanceOptIn;
 }): Promise<void>;
 /** Thrown when the agent's org has no spendable MU balance. The user-facing
  *  top-up guidance is already printed when this is thrown — callers exit quietly. */
@@ -187,3 +234,5 @@ export declare function resolvePreflightedAccount(): Promise<{
     orgLabel: string;
     entitlement: CodeEntitlement | null;
 }>;
+export declare function buildCodeAlignmentCard(agentId: string, modes?: Pick<CardModes, "autonomy" | "integrity">): Record<string, unknown>;
+export declare function buildCodeProtectionCard(agentId: string, mode?: string): Record<string, unknown>;

package/dist/commands/agent-setup.js

@@ -16,6 +16,9 @@
  *     screen_surfaces declared, ready for when it is turned on.
  *   - goal-alignment: nudge — sealed per-conversation via the goal contract
  *     (--goal …), graded and re-anchored by the gateway.
+ * `--governance [integrity,safe-house]` opts a setup in (observe-only, billed at
+ * cost on top of the agent fee); a refresh of an already-claimed agent keeps the
+ * modes its own cards carry unless a --governance / --no-governance flag says otherwise.
  *
  * A launch never runs on an unclaimed agent (operator 2026-10-03): an unclaimed agent lands in
  * the sandbox org and bills nobody. ensureClaimedServedAgent asks the gateway which agent it
@@ -25,7 +28,7 @@
  * (agents.ts), claimAgent + putAlignmentCard/putProtectionCard (lib/api.ts) — rather than
  * reinventing it.
  */
-import { claimAgent, getAgent, getAgentByName, getMe, getMuBalance, getMyPersonalOrg, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
+import { claimAgent, getAgent, getAgentByName, getCardSources, getMe, getMuBalance, getMyPersonalOrg, MnemomApiError, mintProtectionCapability, putAlignmentCard, putProtectionCard, } from "../lib/api.js";
 import { getAuthInfo, loginWithBrowser, loginWithDeviceFlow, resolveAuth } from "../lib/auth.js";
 import { getActiveOrg } from "../lib/cli-config.js";
 import { getApiUrl, getGatewayUrl, getWebsiteUrl, MNEMOM_DIR } from "../lib/config.js";
@@ -40,6 +43,102 @@ import { birthThroughGateway } from "./wrap.js";
 import { resolveAnthropicKey } from "./agent.js";
 import { assertCodeEnabled, CodeNotEnabledError } from "./agent-invite.js";
 const say = (line = "") => console.error(line);
+/** The feature names `--governance <list>` accepts (plus `all` / `none`). */
+export const GOVERNANCE_FEATURES = ["integrity", "safe-house"];
+/**
+ * Parse the `--governance [features]` / `--no-governance` flag. undefined = not
+ * given (new agents get none; a refresh keeps the agent's current modes),
+ * true = every feature, false = none, a string = a comma-separated list of
+ * `integrity`, `safe-house`, `all` or `none`. Throws on an unknown name.
+ */
+export function parseGovernanceFlag(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "boolean")
+        return { integrity: value, safeHouse: value };
+    const choice = { integrity: false, safeHouse: false };
+    const names = value
+        .split(",")
+        .map((s) => s.trim().toLowerCase())
+        .filter(Boolean);
+    if (names.length === 0)
+        return { integrity: true, safeHouse: true };
+    for (const name of names) {
+        if (name === "all") {
+            choice.integrity = true;
+            choice.safeHouse = true;
+        }
+        else if (name === "none") {
+            // contributes nothing; `none` alone means both off
+        }
+        else if (name === "integrity") {
+            choice.integrity = true;
+        }
+        else if (name === "safe-house") {
+            choice.safeHouse = true;
+        }
+        else {
+            throw new Error(`--governance: unknown feature '${name}' — use ${GOVERNANCE_FEATURES.join(", ")}, all or none (comma-separated).`);
+        }
+    }
+    return choice;
+}
+const modeOf = (on) => (on ? "observe" : "off");
+/** One phrase for the posture line: "integrity off, Safe House off". */
+export function describeModes(m) {
+    return `integrity ${m.integrity}, Safe House ${m.protection}`;
+}
+/** The mode string a raw card carries in `field`, or undefined when absent/not a string. */
+function modeField(card, field) {
+    const v = card?.[field];
+    return typeof v === "string" && v ? v : undefined;
+}
+/**
+ * An existing agent's own (agent-layer) card, to keep its modes on a refresh.
+ * null = it has none. THROWS when the read fails: the caller then leaves the
+ * cards alone rather than guess a mode in either direction.
+ */
+async function existingAgentCard(kind, agentId) {
+    const sources = await getCardSources(kind, agentId);
+    return sources?.agent?.card_json ?? null;
+}
+/** The modes for a NEW agent: off unless --governance asks for a feature. */
+export function newAgentModes(governance) {
+    const integrity = modeOf(governance?.integrity ?? false);
+    return { autonomy: integrity, integrity, protection: modeOf(governance?.safeHouse ?? false) };
+}
+/**
+ * The modes for refreshing an EXISTING agent: an explicit --governance /
+ * --no-governance wins; else it keeps the modes its own cards carry. No agent-layer
+ * card → off (it never had one; new setups are off). A card with no mode field →
+ * observe (the prior CLI always wrote observe). A failed read → null: skip the refresh.
+ */
+async function existingAgentModes(agentId, governance) {
+    if (governance)
+        return newAgentModes(governance);
+    let align;
+    let prot;
+    try {
+        [align, prot] = await Promise.all([
+            existingAgentCard("alignment", agentId),
+            existingAgentCard("protection", agentId),
+        ]);
+    }
+    catch (err) {
+        say(fmt.warn(`mnemom agent: couldn't read ${agentId}'s current cards (${describeApiError(err)}) — leaving them unchanged.`));
+        say(fmt.dim("  Re-run `mnemom agent setup`, or pass --governance / --no-governance to set them."));
+        return null;
+    }
+    const integrity = align ? (modeField(align, "integrity_mode") ?? "observe") : "off";
+    return {
+        autonomy: align ? (modeField(align, "autonomy_mode") ?? "observe") : "off",
+        integrity,
+        protection: prot ? (modeField(prot, "mode") ?? "observe") : "off",
+    };
+}
+/** Printed when a setup ran without --governance: how to opt in, and what it costs. */
+export const GOVERNANCE_OPT_IN_HINT = "  Governance (AIP integrity analysis, Safe House screening) is off by default. Turn it on with " +
+    "`mnemom agent setup --governance` (or --governance integrity / safe-house); it is billed at cost on top of the agent fee.";
 /**
  * The default governed-agent slug for the current customer: `agent-<handle>`,
  * where <handle> is the local-part of their mnemom login email (sanitised), or
@@ -193,11 +292,18 @@ async function confirmClaimed(opts, anchorKey, fp) {
     const slug = opts.slug;
     const agentId = await resolveServedAgent(opts, fp);
     if (await isClaimed(slug, agentId)) {
-        if (opts.setup === true) {
+        if (opts.setup === true || (opts.governance && opts.setup !== false)) {
             // An explicit `mnemom agent setup` / --setup repairs or completes the cards (e.g. a
             // protection card that failed on a prior run before its one-time grant was minted).
             say(fmt.dim(`mnemom agent: '${slug}' is ${agentId}, already claimed — refreshing its cards.`));
-            await publishDefaultCards(agentId);
+            const modes = await existingAgentModes(agentId, opts.governance);
+            if (modes) {
+                if (!opts.governance) {
+                    say(fmt.dim(`  Keeping its current governance (${describeModes(modes)}). New agents default to off; ` +
+                        "`--governance` turns it on, `--no-governance` turns it off."));
+                }
+                await publishDefaultCards(agentId, modes);
+            }
             persistAgentSlug(slug);
         }
         else {
@@ -229,10 +335,14 @@ async function confirmClaimed(opts, anchorKey, fp) {
     }
     say(fmt.success(`mnemom agent: claimed '${slug}' (${agentId}) in ${opts.orgLabel}.`));
     await noteSameNamedAgent(slug, agentId);
-    // Publish the default (off) cards. A card write that can't complete does NOT undo the claim —
-    // the agent is claimed and governed on whatever landed; we warn how to finish it.
-    if (opts.setup !== false)
-        await publishDefaultCards(agentId);
+    // Publish the default cards (off unless --governance). A card write that can't complete does
+    // NOT undo the claim — the agent is claimed and governed on whatever landed; we warn how to
+    // finish it.
+    if (opts.setup !== false) {
+        await publishDefaultCards(agentId, newAgentModes(opts.governance));
+        if (!opts.governance)
+            say(fmt.dim(GOVERNANCE_OPT_IN_HINT));
+    }
     persistAgentSlug(slug);
     return { slug, agentId, claimedNow: true };
 }
@@ -354,9 +464,9 @@ async function tryPublishCard(name, write) {
     }
     return { name, ok: false, error: "unknown error" };
 }
-/** Publish both default (off) cards; never throws — warns on a card that can't be written. */
-async function publishDefaultCards(agentId) {
-    const align = await tryPublishCard("alignment", () => putAlignmentCard(agentId, JSON.stringify(buildCodeAlignmentCard(agentId)), "application/json"));
+/** Publish both default cards at `modes`; never throws — warns on a card that can't be written. */
+async function publishDefaultCards(agentId, modes) {
+    const align = await tryPublishCard("alignment", () => putAlignmentCard(agentId, JSON.stringify(buildCodeAlignmentCard(agentId, modes)), "application/json"));
     // Protection is the "locked door": it needs a one-time cards:write:protection
     // grant that the claim does NOT include (alignment rides a standing cap). Mint
     // it with our human login JWT — the human running `mnemom agent` (which claims
@@ -375,13 +485,13 @@ async function publishDefaultCards(agentId) {
             say(fmt.dim("  That agent is owned by an org other than your active one — `mnemom org use <org>` to switch, or set up under a different --agent."));
         }
     }
-    const prot = await tryPublishCard("protection", () => putProtectionCard(agentId, JSON.stringify(buildCodeProtectionCard(agentId)), "application/json"));
+    const prot = await tryPublishCard("protection", () => putProtectionCard(agentId, JSON.stringify(buildCodeProtectionCard(agentId, modes.protection)), "application/json"));
     if (align.ok && prot.ok) {
-        say(fmt.success("mnemom agent: default posture published (alignment + protection off until you turn them on; goal contracts nudge)."));
+        say(fmt.success(`mnemom agent: cards published (${describeModes(modes)}; goal contracts nudge).`));
         return;
     }
     if (align.ok)
-        say(fmt.success("mnemom agent: alignment card published (off)."));
+        say(fmt.success(`mnemom agent: alignment card published (integrity ${modes.integrity}).`));
     for (const c of [align, prot]) {
         if (c.ok)
             continue;
@@ -392,7 +502,7 @@ async function publishDefaultCards(agentId) {
         say(fmt.dim(`  The agent is claimed and running; finish it later with \`${publishCmd}\`.`));
     }
 }
-/** `mnemom agent setup [--agent <slug>]` — the explicit provisioning entry point. */
+/** `mnemom agent setup [--agent <slug>] [--governance …]` — the explicit provisioning entry point. */
 export async function agentSetupCommand(opts = {}) {
     const gatewayHost = resolveGatewayHost(process.env);
     const cellError = singleCellError({
@@ -427,6 +537,7 @@ export async function agentSetupCommand(opts = {}) {
         orgId: account.orgId,
         orgLabel: account.orgLabel,
         setup: true,
+        governance: opts.governance,
     });
 }
 function persistAgentSlug(slug) {
@@ -603,12 +714,15 @@ export async function resolvePreflightedAccount() {
     return { orgId: active?.org_id ?? entitlement?.org_id ?? "", orgLabel, entitlement };
 }
 // ── The default coding posture (cards off; goal contracts nudge) ─────────────
-function buildCodeAlignmentCard(agentId) {
+export function buildCodeAlignmentCard(agentId, modes = { autonomy: "off", integrity: "off" }) {
     return {
         card_version: "unified/2026-04-26",
         agent_id: agentId,
-        autonomy_mode: "off",
-        integrity_mode: "off",
+        // Integrity off ⇒ the gateway skips the AIP checkpoint and the observer skips
+        // its trace analysis: no model call, no charge. A new agent's autonomy
+        // (verification + policy) follows it; a refresh keeps the agent's own.
+        autonomy_mode: modes.autonomy,
+        integrity_mode: modes.integrity,
         principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
         values: {
             declared: ["transparency", "safety", "honesty", "user_control", "harm_prevention"],
@@ -641,11 +755,11 @@ function buildCodeAlignmentCard(agentId) {
         audit: { retention_days: 30, queryable: false, trace_format: "otel" },
     };
 }
-function buildCodeProtectionCard(agentId) {
+export function buildCodeProtectionCard(agentId, mode = "off") {
     return {
         card_version: "protection/2026-04-26",
         agent_id: agentId,
-        mode: "off",
+        mode,
         thresholds: { warn: 0.6, quarantine: 0.8, block: 0.95 },
         screen_surfaces: {
             incoming: true,

package/dist/commands/agent.d.ts

@@ -29,6 +29,7 @@ import { type MnemomKeyDeps } from "../lib/subscription-login.js";
 import { type SessionRecord } from "../lib/agent-ledger.js";
 import { type ExperimentalId } from "../lib/experimental.js";
 import { type ConsoleKeyDeps } from "../lib/console-key.js";
+import { type GovernanceOptIn } from "./agent-setup.js";
 import { type ContextProfile, type LaunchShape, type SealedContractEnvelope } from "../lib/agent.js";
 export interface AgentOptions {
     goal?: string;
@@ -102,6 +103,11 @@ export interface AgentOptions {
      * default cards, false (`--no-setup`) skips the card writes.
      */
     setup?: boolean;
+    /**
+     * `--governance` / `--no-governance`: the governance modes a provisioning (or
+     * `--setup` refresh) writes. undefined = off for a new agent, kept on a refresh.
+     */
+    governance?: GovernanceOptIn;
     /**
      * Where to source the Anthropic key (from ~/.mnemom/launcher.toml `key_source`).
      * Restricts the default env → store → prompt search: "env" uses env only,

package/dist/commands/agent.js

@@ -402,6 +402,7 @@ export async function agentCommand(scenarioArg, options = {}) {
         orgId: account.orgId,
         orgLabel: account.orgLabel,
         setup: options.setup,
+        governance: options.governance,
     });
     // ── conversation id ── an implicit relaunch continues its earlier conversation (IG5 #1, D1)
     // so the goal the gateway inferred there is still the one it steers by. Resolved here, after

package/dist/index.js

@@ -26,7 +26,7 @@ import { agentCommand } from "./commands/agent.js";
 import { agentConfigCommand } from "./commands/agent-config.js";
 import { agentSlackCommand } from "./commands/agent-slack.js";
 import { agentDoctorCommand } from "./commands/agent-doctor.js";
-import { agentSetupCommand } from "./commands/agent-setup.js";
+import { agentSetupCommand, parseGovernanceFlag } from "./commands/agent-setup.js";
 import { agentInviteCommand, runAgentInvocation } from "./commands/agent-invite.js";
 import { agentFirstRunCommand, offerFirstRunOnLaunch } from "./commands/agent-first-run.js";
 import { applyConfigToEnv, launcherEntries, loadLauncherConfig, withoutDisabledExperimental, } from "./lib/launcher-config.js";
@@ -170,6 +170,8 @@ const agentCmd = program
     .option("--invite <token>", "Redeem a Mnemom Agent invitation (pinv_…): unlocks Mnemom Agent for you + credits your starter µ; launches too when a session name is given")
     .option("--setup", "Re-check the served agent and refresh its default cards before launch")
     .option("--no-setup", "Skip the default-card writes (the agent is still confirmed and claimed)")
+    .option("--governance [features]", "Turn governance ON for the agent's cards: AIP integrity analysis + Safe House screening, observe-only (default: off for new agents). Pick features with a comma list: integrity, safe-house. Billed at cost on top of the agent fee")
+    .option("--no-governance", "Turn governance OFF for the agent's cards (a card refresh otherwise keeps an existing agent's modes)")
     .option("--no-yolo", "Do NOT pass --dangerously-skip-permissions (yolo is on by default)")
     .option("--no-context-hint", "Do NOT seed Claude Code's context-hint feature flag before launch")
     .addOption(new Option("--slack", "EXPERIMENTAL (`mnemom experimental enable slack`): attach the Slack channel — messages addressed to this session arrive in it, and it can reply (see `mnemom agent slack`)").hideHelp(hiddenUnless("slack")))
@@ -299,13 +301,15 @@ const agentCmd = program
             return;
         }
         if (scenario === "doctor") {
-            await agentDoctorCommand({ cli: opts.cli });
+            await agentDoctorCommand({ cli: opts.cli, agent: program.opts().agent ?? cfg.agent });
             return;
         }
+        // Validated up front so a typo fails before any sign-in or provisioning.
+        const governance = parseGovernanceFlag(opts.governance);
         // Sub-verb: `mnemom agent setup` provisions/claims the governed agent and
         // never launches. The agent slug follows the same precedence as a launch.
         if (scenario === "setup") {
-            await agentSetupCommand({ agent: program.opts().agent ?? cfg.agent });
+            await agentSetupCommand({ agent: program.opts().agent ?? cfg.agent, governance });
             return;
         }
         const numToStr = (n) => n === undefined ? undefined : String(n);
@@ -367,6 +371,7 @@ const agentCmd = program
                 : false,
             experimental,
             setup: opts.setup,
+            governance,
             keySource: cfg.keySource,
             passthrough,
             dryRun: opts.dryRun,

package/dist/lib/api.d.ts

@@ -630,6 +630,27 @@ export declare const PROTECTION_CARD_MAX_BYTES: number;
 export declare function putProtectionCard(agentId: string, body: string, contentType?: "text/yaml" | "application/json", opts?: {
     idempotencyKey?: string;
 }): Promise<PublishedCardResponse>;
+/**
+ * The per-layer view of an agent's card (ADR-053 `?include=sources`): the raw
+ * card the agent layer itself carries, next to the composed card every layer
+ * produced. We type the two rows we read; the platform/org/teams rows ride along.
+ */
+export interface CardSources {
+    agent: {
+        card_json: Record<string, unknown> | null;
+        available: boolean;
+    };
+    composed: {
+        card_json: Record<string, unknown> | null;
+        available: boolean;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Fetch an agent's alignment or protection card sources envelope. Returns null
+ * when the agent has no canonical card yet (404).
+ */
+export declare function getCardSources(kind: "alignment" | "protection", agentId: string): Promise<CardSources | null>;
 export interface CardPreviewResult {
     /** true ⇔ the server accepted+composed the card (HTTP 200). */
     valid: boolean;

package/dist/lib/api.js

@@ -841,6 +841,22 @@ export async function putProtectionCard(agentId, body, contentType = "text/yaml"
     }
     return response.json();
 }
+/**
+ * Fetch an agent's alignment or protection card sources envelope. Returns null
+ * when the agent has no canonical card yet (404).
+ */
+export async function getCardSources(kind, agentId) {
+    const url = validateUrl(`${API_BASE}/v1/${kind}/agent/${encodeURIComponent(agentId)}?include=sources`);
+    const response = await mnemomFetch(url, {
+        headers: { Accept: "application/json", ...(await authHeaders()) },
+    });
+    if (!response.ok) {
+        if (response.status === 404)
+            return null;
+        throw await readApiError(response, `Failed to fetch ${kind} card sources`);
+    }
+    return response.json();
+}
 /**
  * Dry-run validate + compose a card body against the server's authoritative
  * pipeline. Returns a structured result — a 422/400 validation failure is an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.11-next.0",
+  "version": "0.17.11-next.1",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {