@mnemom/mnemom 0.17.0-next.0 → 0.17.0-next.2

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

@@ -5,12 +5,16 @@
  * If a customer names no agent, `mnemom code` launches under a per-customer
  * governed identity `code-<handle>`. This module makes that identity REAL in
  * their Mnemom org: it births the agent through the gateway, claims it (so the
- * customer owns it), and publishes a sane default coding posture — nudge/nudge:
- *   - alignment card: autonomy_mode + integrity_mode = nudge,
+ * customer owns it), and publishes a sane default coding posture. The CARDS are
+ * observe-only (visibility, no active intervention); the goal contract is what
+ * nudges (re-anchor on drift). Specifically:
+ *   - alignment card: autonomy_mode + integrity_mode = observe,
  *     principal.relationship = delegated_authority, coding bounded/forbidden
  *     actions, escalate-on-irreversible;
- *   - protection card: mode = nudge, thresholds 0.60/0.80/0.95, all four
- *     screen_surfaces on.
+ *   - protection card: mode = observe, thresholds 0.60/0.80/0.95, all four
+ *     screen_surfaces on (screened for observation).
+ *   - goal-alignment: nudge — sealed per-conversation via the goal contract
+ *     (--goal …), graded and re-anchored by the gateway.
  *
  * All account writes are gated: interactive runs show the plan and confirm;
  * non-interactive runs provision only with an explicit `--setup`, and otherwise

package/dist/commands/code-setup.js

@@ -5,12 +5,16 @@
  * If a customer names no agent, `mnemom code` launches under a per-customer
  * governed identity `code-<handle>`. This module makes that identity REAL in
  * their Mnemom org: it births the agent through the gateway, claims it (so the
- * customer owns it), and publishes a sane default coding posture — nudge/nudge:
- *   - alignment card: autonomy_mode + integrity_mode = nudge,
+ * customer owns it), and publishes a sane default coding posture. The CARDS are
+ * observe-only (visibility, no active intervention); the goal contract is what
+ * nudges (re-anchor on drift). Specifically:
+ *   - alignment card: autonomy_mode + integrity_mode = observe,
  *     principal.relationship = delegated_authority, coding bounded/forbidden
  *     actions, escalate-on-irreversible;
- *   - protection card: mode = nudge, thresholds 0.60/0.80/0.95, all four
- *     screen_surfaces on.
+ *   - protection card: mode = observe, thresholds 0.60/0.80/0.95, all four
+ *     screen_surfaces on (screened for observation).
+ *   - goal-alignment: nudge — sealed per-conversation via the goal contract
+ *     (--goal …), graded and re-anchored by the gateway.
  *
  * All account writes are gated: interactive runs show the plan and confirm;
  * non-interactive runs provision only with an explicit `--setup`, and otherwise
@@ -83,21 +87,21 @@ export async function ensureGovernedAgent(opts) {
         say(fmt.section("Set up a governed coding agent"));
         say(fmt.label("  Agent:", slug));
         say(fmt.label("  Org:", orgLabel));
-        say(fmt.label("  Posture:", "nudge / nudge (alignment: autonomy + integrity nudge; protection: all surfaces screened)"));
+        say(fmt.label("  Posture:", "observe (alignment + protection observe-only, all surfaces screened); goal contracts nudge"));
         say(fmt.dim("  Births the agent through the gateway, claims it to your org, and publishes its cards."));
         if (!(await askYesNo("Provision and claim this agent now?", true))) {
             say(fmt.dim("  Skipped — launching under the unclaimed identity. Run `mnemom code setup` anytime."));
             return { slug, provisioned: false };
         }
     }
-    // 5. Birth → claim → publish nudge/nudge cards. (Key never logged.)
+    // 5. Birth → claim → publish observe-only cards. (Key never logged.)
     const gatewayUrl = opts.gatewayHost.replace(/\/+$/, "");
     const agentId = await birthThroughGateway(gatewayUrl, "anthropic", slug, opts.anthropicKey);
     const hashProof = deriveHashProof(opts.anthropicKey, slug);
     await claimAgent(agentId, { hashProof, orgId: org?.org_id });
     await putAlignmentCard(agentId, JSON.stringify(buildCodeAlignmentCard(agentId)), "application/json");
     await putProtectionCard(agentId, JSON.stringify(buildCodeProtectionCard(agentId)), "application/json");
-    say(fmt.success(`mnemom code: provisioned + claimed '${slug}' (${agentId}) in ${orgLabel} — nudge/nudge posture published.`));
+    say(fmt.success(`mnemom code: provisioned + claimed '${slug}' (${agentId}) in ${orgLabel} — observe posture published (goal contracts nudge).`));
     // 6. Remember the slug so future launches skip straight to usable.
     persistAgentSlug(slug);
     return { slug, provisioned: true };
@@ -125,7 +129,7 @@ export async function codeSetupCommand(opts = {}) {
 }
 function warnUnclaimed(slug) {
     say(fmt.warn(`mnemom code: agent '${slug}' is not set up in your org — launching with an UNCLAIMED identity (governance is advisory/fail-open).`));
-    say(fmt.dim("  Provision it (creates + claims the agent, publishes nudge/nudge cards): mnemom code setup"));
+    say(fmt.dim("  Provision it (creates + claims the agent, publishes observe cards): mnemom code setup"));
 }
 function persistAgentSlug(slug) {
     try {
@@ -145,7 +149,7 @@ function persistAgentSlug(slug) {
 export class MuInsufficientError extends Error {
     orgLabel;
     constructor(orgLabel) {
-        super("insufficient MU balance");
+        super("insufficient µ balance");
         this.orgLabel = orgLabel;
         this.name = "MuInsufficientError";
     }
@@ -176,7 +180,7 @@ export async function ensureMnemomSession(opts = {}) {
         return false;
     say(fmt.section("Sign in to Mnemom"));
     say(fmt.dim("  mnemom code runs your coding session governed and under your Mnemom account,"));
-    say(fmt.dim("  so it shows up in your traces and bills to your org's Mnemom Units."));
+    say(fmt.dim("  so it shows up in your traces and draws on your org's µ balance."));
     say(fmt.dim(`  New to Mnemom? You can create a free account in the same flow (or at ${getWebsiteUrl()}/signup).`));
     if (!(await askYesNo("Sign in or create your account now?", true)))
         return false;
@@ -237,21 +241,20 @@ function safeBigInt(v) {
     }
 }
 /**
- * The "you need Mnemom Units" message (no free tier). Voiced like the portal's
+ * The "you need µ" message (no free tier). Voiced like the portal's
  * enforcement-paused banner — safety features can't run without µ — but never
  * says "exhausted" (that assumes a prior balance; a new org may simply have none).
  */
 function printTopUp(orgLabel, balanceMu) {
     say();
-    say(fmt.warn(`No Mnemom Units — ${orgLabel} has a balance of ${balanceMu} µ.`));
-    say(fmt.dim("  mnemom code runs on Mnemom Units (µ), and there's no free tier. Without µ,"));
-    say(fmt.dim("  Mnemom's safety features can't run, so the launch is blocked. Top up to launch"));
-    say(fmt.dim("  a governed session:"));
+    say(fmt.warn(`No µ balance — ${orgLabel} is at ${balanceMu} µ.`));
+    say(fmt.dim("  mnemom code runs on µ, and there's no free tier. Without µ, Mnemom's safety"));
+    say(fmt.dim("  features can't run, so the launch is blocked. Top up to launch a governed session:"));
     say();
     say(`    Top up µ:  ${getWebsiteUrl()}/settings/billing`);
     say(fmt.dim("  If you don't manage billing for this org, ask an admin to top up."));
     say();
-    say(fmt.dim("  Your balance updates the moment a top-up completes — then re-run `mnemom code`."));
+    say(fmt.dim("  Your µ balance updates the moment a top-up completes — then re-run `mnemom code`."));
 }
 /**
  * The shared pre-launch preamble for `mnemom code` (and `mnemom code setup`):
@@ -264,9 +267,9 @@ export async function ensureSessionAndBalance(opts) {
     const interactive = opts.interactive ?? isInteractive();
     const haveSession = await ensureMnemomSession({ interactive });
     if (!haveSession) {
-        throw new Error("mnemom code needs a Mnemom account — it runs your coding session governed and on Mnemom Units.\n" +
+        throw new Error("mnemom code needs a Mnemom account — it runs your coding session governed and on your org's µ balance.\n" +
             "  Sign in:   mnemom login   (or set MNEMOM_API_KEY)\n" +
-            `  New here?  create a free account, then add MUs: ${getWebsiteUrl()}/settings/billing`);
+            `  New here?  create a free account, then top up µ: ${getWebsiteUrl()}/settings/billing`);
     }
     const active = getActiveOrg();
     const orgId = active?.org_id ?? (await getMyPersonalOrg()).org_id;
@@ -274,13 +277,13 @@ export async function ensureSessionAndBalance(opts) {
     await assertMuBalance(orgId, orgLabel);
     return { orgId, orgLabel };
 }
-// ── The default coding posture (nudge/nudge) ────────────────────────────────
+// ── The default coding posture (cards observe-only; goal contracts nudge) ────
 function buildCodeAlignmentCard(agentId) {
     return {
         card_version: "unified/2026-04-26",
         agent_id: agentId,
-        autonomy_mode: "nudge",
-        integrity_mode: "nudge",
+        autonomy_mode: "observe",
+        integrity_mode: "observe",
         principal: { type: "agent", identifier: agentId, relationship: "delegated_authority" },
         values: {
             declared: ["transparency", "safety", "honesty", "user_control", "harm_prevention"],
@@ -317,7 +320,7 @@ function buildCodeProtectionCard(agentId) {
     return {
         card_version: "protection/2026-04-26",
         agent_id: agentId,
-        mode: "nudge",
+        mode: "observe",
         thresholds: { warn: 0.6, quarantine: 0.8, block: 0.95 },
         screen_surfaces: {
             incoming: true,

package/dist/commands/code.d.ts

@@ -100,7 +100,7 @@ export interface ResolvedCli {
  * a non-claude executable is launched through it with a warning.
  */
 export declare function resolveCliBin(cliOpt: string | undefined, env: NodeJS.ProcessEnv): ResolvedCli;
-export declare function commandExists(cmd: string): boolean;
+export declare function promptForCliPath(cliOpt: string | undefined, env: NodeJS.ProcessEnv, origErr: Error | undefined): Promise<ResolvedCli>;
 /**
  * Does the resolved coding-agent CLI advertise the `--remote-control` startup
  * flag (Claude Code >= 2.1.269)? Determined by scanning its `--help`. Best-effort:

package/dist/commands/code.js

@@ -31,6 +31,7 @@ import { tmpdir, homedir } from "node:os";
 import { basename, join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { MNEMOM_DIR } from "../lib/config.js";
+import { configKeySpec, loadCodeConfig, writeCodeConfig } from "../lib/code-config.js";
 import { fmt } from "../lib/format.js";
 import { askInput, askYesNo, isInteractive } from "../lib/prompt.js";
 import { defaultAgentSlug, ensureGovernedAgent, ensureSessionAndBalance, MuInsufficientError, } from "./code-setup.js";
@@ -72,14 +73,25 @@ export async function codeCommand(scenario, options = {}) {
     const cellNote = isProdGateway(env) ? "us-2/prod" : `custom (${gatewayHost})`;
     const yolo = options.yolo !== false; // default ON
     const contextHint = options.contextHint !== false; // default ON
-    // ── which CLI executable (name or full path) ──
-    const cli = resolveCliBin(options.cli, env);
-    // ── default launch shape: prefer Remote-Control-in-terminal (the good default
-    // — one session steerable from this terminal AND claude.ai/the app) when the
-    // machine can do it; otherwise fall back to terminal-only with a clear notice.
-    // An explicit choice (flag / env / config launch=) is always respected. ──
-    if (!shapeExplicit && shape === "terminal") {
-        const rc = checkRcCapability(cli);
+    // ── which CLI executable (name or full path) ── resolve GRACEFULLY: if it's not
+    // found we don't crash with a technical error — we ask for the path at launch.
+    let cli;
+    let cliError;
+    try {
+        cli = resolveCliBin(options.cli, env);
+    }
+    catch (err) {
+        cliError = err instanceof Error ? err : new Error(String(err));
+    }
+    // Default launch shape: prefer Remote-Control-in-terminal (the good default —
+    // one session steerable from this terminal AND claude.ai/the app) when the
+    // machine can do it; otherwise terminal-only with a clear notice. An explicit
+    // choice (flag / env / config launch=) is always respected. Needs a resolved
+    // CLI to test RC capability, so it's applied once the CLI is known.
+    const applyAutoShape = (resolved) => {
+        if (shapeExplicit || shape !== "terminal")
+            return;
+        const rc = checkRcCapability(resolved);
         if (rc.ok) {
             shape = "remote-control";
         }
@@ -87,22 +99,35 @@ export async function codeCommand(scenario, options = {}) {
             say(`mnemom code: launching terminal-only (Remote Control unavailable: ${rc.missing.join("; ")}).`);
             say("mnemom code: once those are in place, `mnemom code <scenario> --remote-control` (or `config set launch remote-control`) gives you a session steerable from claude.ai and the Claude app too.");
         }
-    }
+    };
+    if (cli)
+        applyAutoShape(cli);
     if (options.dryRun) {
-        printPlan({ scenario, shape, agent, conversationId, door, cellNote, envelope, yolo, cli });
+        const planCli = cli ?? {
+            bin: "(not found — pass --cli <path> or `mnemom code config set cli <path>`)",
+            name: basename((options.cli || env.MNEMOM_CODE_CLI || "claude").trim()),
+        };
+        printPlan({ scenario, shape, agent, conversationId, door, cellNote, envelope, yolo, cli: planCli });
         return;
     }
+    // Real launch: make sure we actually have a CLI to run. If we couldn't find it,
+    // ask for the path (a good experience beats a hard technical error). A
+    // non-interactive session still gets the clear, actionable error.
+    if (!cli) {
+        cli = await promptForCliPath(options.cli, env, cliError);
+        applyAutoShape(cli);
+    }
     // ── resolve the Anthropic key (zero 1Password; never logged) ──
     const anthropicKey = await resolveAnthropicKey(env, {
         allowPrompt: true,
         keySource: options.keySource,
     });
-    // ── account + Mnemom Units gate (no free tier) ──────────────────────────────
-    // mnemom code runs governed and on Mnemom Units, so before we seal a contract
-    // or launch we (1) ensure a Mnemom session — offering the try-me-style sign-in
-    // / sign-up when there isn't one — and (2) enforce a positive MU balance on the
-    // org the agent lives in (default: the user's personal org). No MUs ⇒ blocked
-    // with a portal-style top-up message. Skipped only on --dry-run (handled above).
+    // ── account + µ-balance gate (no free tier) ─────────────────────────────────
+    // mnemom code runs governed and on µ, so before we seal a contract or launch we
+    // (1) ensure a Mnemom session — offering the try-me-style sign-in / sign-up when
+    // there isn't one — and (2) enforce a positive µ balance on the org the agent
+    // lives in (default: the user's personal org). No µ ⇒ blocked with a
+    // portal-style top-up message. Skipped only on --dry-run (handled above).
     try {
         await ensureSessionAndBalance({ interactive: isInteractive() });
     }
@@ -295,7 +320,52 @@ export function resolveCliBin(cliOpt, env) {
         (name === "claude" ? " and in the fnm/nvm/asdf node dirs" : "") +
         ".\n  Pass --cli <name|/full/path> or set MNEMOM_CODE_CLI.");
 }
-export function commandExists(cmd) {
+export /**
+ * Recover when the coding-agent CLI can't be found — a good experience beats a
+ * hard technical error. In an interactive session, tell the customer we couldn't
+ * find it and let them paste the full path (offering to save it as their default
+ * so they never retype it). A non-interactive session re-throws the clear,
+ * actionable error rather than hanging on a prompt.
+ */ async function promptForCliPath(cliOpt, env, origErr) {
+    const requested = (cliOpt || env.MNEMOM_CODE_CLI || "claude").trim();
+    if (!isInteractive()) {
+        throw origErr ?? new Error(`mnemom code: coding-agent CLI '${requested}' not found.`);
+    }
+    say(`mnemom code: couldn't find the '${requested}' CLI on your PATH.`);
+    if (requested === "claude") {
+        say("  If Claude Code is installed, paste its full path (find it with: which claude).");
+        say("  Not installed yet? Get it at https://claude.com/claude-code, then re-run.");
+    }
+    else {
+        say("  Paste its full path, or install it and re-run.");
+    }
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const entered = (await askInput("Path to your coding-agent CLI (Enter to cancel):")).trim();
+        if (!entered) {
+            throw new Error("mnemom code: no coding-agent CLI available.\n" +
+                "  Install Claude Code (https://claude.com/claude-code), or pass --cli <path> " +
+                "(or save it: mnemom code config set cli <path>).");
+        }
+        if (!existsSync(entered)) {
+            say(`  '${entered}' doesn't exist — try again.`);
+            continue;
+        }
+        if (await askYesNo("Save this as your default CLI so you don't retype it?", true)) {
+            try {
+                const cfg = loadCodeConfig();
+                configKeySpec("cli").set(cfg, entered);
+                writeCodeConfig(cfg);
+                say("  Saved — future launches will use it.");
+            }
+            catch {
+                // best effort — the launch proceeds with the entered path either way
+            }
+        }
+        return { bin: entered, name: basename(entered) };
+    }
+    throw new Error("mnemom code: couldn't resolve a coding-agent CLI path — pass --cli <path>.");
+}
+function commandExists(cmd) {
     const res = spawnSync("sh", ["-c", `command -v "$1" >/dev/null 2>&1`, "sh", cmd], {
         stdio: "ignore",
     });

package/package.json

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