@mnemom/mnemom 0.17.15 → 0.17.16

package/README.md

@@ -67,10 +67,41 @@ header. In implicit mode the goal lags your steering by one request: a response
 message carries `x-mnemom-goal-steer: queued` and the revision the agent acted under;
 the next request reads the new revision (`x-mnemom-goal-revision`).
 
+A sealed contract takes no in-session steering: nothing said inside the session (a lead's
+direction included) changes what the judge measures against — a lead's direction must
+already be a requirement in the seal. `--lead-directed` seals the standard line for a
+lead-directed agent (e.g. an orchestrating agent that ships the work it was given), so its
+own-branch pushes and draft/ready PR
+creation are read against the contract instead of flagged as an unrequested effect:
+
+```
+mnemom agent --goal "ship the lane's cards" --lead-directed
+```
+
+Requires `--goal`; appends the line at most once, however many times the flag (or the same
+requirement text given verbatim via `--requirement`) appears. It does not permit merging.
+
 Make one mode the standing default with `mnemom agent config set goal_mode implicit`
 (or `off`); `--goal` still seals for that launch and `--no-implicit` turns it off for one
 launch. A sealed contract needs a per-launch statement, so it cannot be the default.
 
+#### Watching a session: `mnemom agent show [ref] --follow`
+
+`mnemom agent show` prints a session's latest state — the sealed contract, the current
+verdict, guardrails, and (under `--json`) the last 50 judge verdicts. Add `--follow` to
+keep the command running and print each new verdict as it lands, instead of re-running
+`show` yourself:
+
+```bash
+mnemom agent show --follow           # watch the newest session
+mnemom agent show my-task --follow --json   # one JSON object per new verdict (NDJSON)
+```
+
+It polls every 3 seconds by default; override with `--follow-interval <seconds>` for one
+run, or `MNEMOM_AGENT_FOLLOW_INTERVAL=<seconds>` for every run in a shell. It prints each
+verdict once — never a repeat on a later poll — and stops on Ctrl-C, or once the session
+is no longer available.
+
 #### Orchestrated launches: `MNEMOM_AGENT_PREFLIGHTED=1`
 
 An orchestrator (the ADW fleet) that already checked sign-in and the µ balance before

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

@@ -53,8 +53,22 @@ export declare function assertCodeEnabled(orgId: string, orgLabel: string): Prom
 export type EnsureSession = (opts: {
     interactive?: boolean;
 }) => Promise<boolean>;
-/** Map an accept failure to the sentence the customer needs. Null = not ours to explain. */
-export declare function explainAcceptError(err: unknown): string | null;
+/** The accept route's 403 codes (mnemom-api `product-invite-accept.ts`). */
+export declare const INVITE_ACCOUNT_MISMATCH = "invite_account_mismatch";
+export declare const INVITE_EMAIL_MISMATCH = "invite_email_mismatch";
+/** The account's email must be confirmed first. The accept route redeems for a matching
+ *  unconfirmed email today, but the code (and the api's general `email_not_verified`) is
+ *  still voiced as what it is, never as "a different account". */
+export declare const INVITE_EMAIL_UNVERIFIED = "invite_email_unverified";
+export declare const EMAIL_NOT_VERIFIED = "email_not_verified";
+/**
+ * Map an accept failure to the sentence the customer needs. Null = not ours to explain.
+ * `signedInAs` (the account's email, when known) is named in the 403 sentences so the
+ * customer can see which account the CLI is using.
+ */
+export declare function explainAcceptError(err: unknown, signedInAs?: string | null): string | null;
+/** The signed-in account's email, or null when it can't be read (never throws). */
+export type SignedInEmail = () => Promise<string | null>;
 /** Print the outcome of a successful accept. */
 export declare function printAccepted(res: AcceptProductInviteResult): void;
 /**
@@ -65,6 +79,7 @@ export declare function printAccepted(res: AcceptProductInviteResult): void;
 export declare function agentInviteCommand(token: string | undefined, opts?: {
     interactive?: boolean;
     ensureSession?: EnsureSession;
+    signedInEmail?: SignedInEmail;
 }): Promise<AcceptProductInviteResult>;
 export interface AgentInvocation {
     /** The positional `[scenario]` (may be a reserved sub-verb such as "invite"). */

package/dist/commands/agent-invite.js

@@ -19,7 +19,7 @@
  * All narration goes to stderr (the `mnemom agent` convention — stdout is for
  * the dry-run plan only). Copy says "µ", never "MU".
  */
-import { acceptProductInvite, CODE_NOT_ENABLED, getCodeEntitlement, MnemomApiError, } from "../lib/api.js";
+import { acceptProductInvite, CODE_NOT_ENABLED, getCodeEntitlement, getMe, MnemomApiError, } from "../lib/api.js";
 import { fmt } from "../lib/format.js";
 import { isInteractive } from "../lib/prompt.js";
 const say = (line = "") => console.error(line);
@@ -123,8 +123,38 @@ async function defaultEnsureSession(opts) {
     const { ensureMnemomSession } = await import("./agent-setup.js");
     return ensureMnemomSession(opts);
 }
-/** Map an accept failure to the sentence the customer needs. Null = not ours to explain. */
-export function explainAcceptError(err) {
+/** The accept route's 403 codes (mnemom-api `product-invite-accept.ts`). */
+export const INVITE_ACCOUNT_MISMATCH = "invite_account_mismatch";
+export const INVITE_EMAIL_MISMATCH = "invite_email_mismatch";
+/** The account's email must be confirmed first. The accept route redeems for a matching
+ *  unconfirmed email today, but the code (and the api's general `email_not_verified`) is
+ *  still voiced as what it is, never as "a different account". */
+export const INVITE_EMAIL_UNVERIFIED = "invite_email_unverified";
+export const EMAIL_NOT_VERIFIED = "email_not_verified";
+/** ` (email)` for the signed-in account, or "" when it could not be read. */
+function signedInLabel(signedInAs) {
+    return signedInAs ? ` (${sanitizeTerminalText(signedInAs)})` : "";
+}
+/** A 403 from the accept route: which one it is decides what the customer can do. */
+function explainForbidden(err, signedInAs) {
+    const who = signedInLabel(signedInAs);
+    switch (err.code) {
+        case INVITE_EMAIL_UNVERIFIED:
+        case EMAIL_NOT_VERIFIED:
+            return `Your Mnemom account email${who} isn't confirmed yet. Open the confirmation email Mnemom sent to that address, then run the same command again.`;
+        case INVITE_EMAIL_MISMATCH:
+        case INVITE_ACCOUNT_MISMATCH:
+            return `This invitation was sent to a different email than the account you're signed in with${who}. Sign in with the address it was sent to (mnemom logout, then mnemom login), then run the same command again.`;
+        default:
+            return `The invitation couldn't be redeemed for the account you're signed in with${who}: ${sanitizeTerminalText(err.message)}`;
+    }
+}
+/**
+ * Map an accept failure to the sentence the customer needs. Null = not ours to explain.
+ * `signedInAs` (the account's email, when known) is named in the 403 sentences so the
+ * customer can see which account the CLI is using.
+ */
+export function explainAcceptError(err, signedInAs) {
     if (!(err instanceof MnemomApiError))
         return null;
     switch (err.effectiveStatus) {
@@ -133,13 +163,25 @@ export function explainAcceptError(err) {
         case 410:
             return "This invitation has expired or was revoked — ask your Mnemom contact for a new one.";
         case 403:
-            return "This invitation was issued to a different account — sign in with the email it was sent to (mnemom logout, then mnemom login).";
+            return explainForbidden(err, signedInAs);
         case 409:
             return "The invitation changed while redeeming — run the command again.";
         default:
             return null;
     }
 }
+async function defaultSignedInEmail() {
+    try {
+        return (await getMe()).email ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The email to name in an accept error — looked up only for a 403, where it matters. */
+async function signedInFor(err, lookup) {
+    return err instanceof MnemomApiError && err.effectiveStatus === 403 ? lookup() : null;
+}
 /** Print the outcome of a successful accept. */
 export function printAccepted(res) {
     if (res.already_accepted) {
@@ -180,7 +222,8 @@ export async function agentInviteCommand(token, opts = {}) {
         result = await acceptProductInvite(trimmed);
     }
     catch (err) {
-        const explained = explainAcceptError(err);
+        const signedInAs = await signedInFor(err, opts.signedInEmail ?? defaultSignedInEmail);
+        const explained = explainAcceptError(err, signedInAs);
         if (explained)
             throw new Error(`mnemom agent --invite: ${explained}`, { cause: err });
         throw err;

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

@@ -14,7 +14,7 @@
  * only the server's hash is shown, labelled "sealed hash".
  */
 import { type GoalMode, type SessionRecord } from "../lib/agent-ledger.js";
-import { type AgentSessionResponse } from "../lib/api.js";
+import { type AgentSessionResponse, type AgentSessionVerdictTrailEntry } from "../lib/api.js";
 import { type GoalShowResponse } from "../lib/goal-api.js";
 export interface SessionCommandDeps {
     /** The ledger, newest first. */
@@ -33,6 +33,20 @@ export interface SessionCommandDeps {
     cellGateway?: () => string;
     out: (line: string) => void;
     err: (line: string) => void;
+    /**
+     * `--follow`: sleep for `ms` between polls. Injected so tests can drive the loop without a
+     * real timer. Defaults to a real `setTimeout` — deliberately NOT unref'd: `--follow` is a
+     * foreground watch loop invoked explicitly by the user, and an unref'd timer does not keep
+     * Node's event loop alive, so the process would exit right after the one-shot snapshot
+     * instead of polling (reproduced standalone: a loop of unref'd-timer sleeps prints zero
+     * iterations because nothing else is pending).
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * `--follow`: register a one-shot SIGINT handler, returning an unregister function. Injected so
+     * tests can simulate Ctrl-C without sending a real signal. Defaults to `process.once("SIGINT")`.
+     */
+    onSigint?: (handler: () => void) => () => void;
 }
 /** The production wiring (index.ts). Lazy so a test that mocks lib/api without
  *  this export can still import index.ts. */
@@ -82,6 +96,41 @@ export declare function formatSessionsTable(rows: SessionRecord[], opts: {
 }): string[];
 /** `turns 3/10 (crossed)` — value against its ceiling (none ⇒ just the value). */
 export declare function gauge(label: string, value: number, ceiling: number | null, fired: boolean | undefined): string;
+/**
+ * One verdict-trail entry, human-readable — shared by the one-shot trail section in
+ * `buildShowView` and by `--follow`'s streamed lines, so the two never drift apart.
+ */
+export declare function formatTrailEntry(e: AgentSessionVerdictTrailEntry): string;
+/**
+ * The verdict trail is a bounded 50-entry ring: once it wraps, new entries at one end push
+ * old ones out, so an array index does not name the same verdict across two polls. The stable
+ * identity is the (request id, turn) pair the gateway recorded it under — `request_id` is
+ * null-able (the judge can run without one), joined with a separator that can't collide with a
+ * turn number.
+ */
+export declare function verdictTrailKey(e: Pick<AgentSessionVerdictTrailEntry, "request_id" | "turn">): string;
+/**
+ * Best-effort "has this session ended" check for `--follow`'s exit condition. No field is locked
+ * in on the wire yet: MNE-8149 adds an `expired` seal state on the gateway's row, and a later
+ * mnemom-api card is expected to carry it through to this response — so this reads defensively,
+ * off either the top-level response or the `sealed` block, and returns null (never throws) when
+ * neither carries a recognized value, which is every server today.
+ */
+export declare function sessionEndedState(remote: AgentSessionResponse): "expired" | "ended" | null;
+/** Default and floor for `--follow`'s poll interval. */
+export declare const DEFAULT_FOLLOW_INTERVAL_MS = 3000;
+export declare const MIN_FOLLOW_INTERVAL_MS = 500;
+/** Seconds; consulted only when `--follow-interval` was not passed. */
+export declare const FOLLOW_INTERVAL_ENV_VAR = "MNEMOM_AGENT_FOLLOW_INTERVAL";
+/** Resolve the poll interval: explicit opt > env override (seconds) > default, floored. */
+export declare function resolveFollowIntervalMs(opts: {
+    followIntervalMs?: number;
+}): number;
+export declare function followVerdictTrail(record: SessionRecord, agentId: string, deps: SessionCommandDeps, opts: {
+    json?: boolean;
+    intervalMs: number;
+    seenKeys: Set<string>;
+}): Promise<void>;
 /**
  * The human view for `mnemom agent show`: the local record, then the live
  * gateway state (or a dim "live state unavailable (<reason>)" line when
@@ -101,6 +150,8 @@ export interface ShowJson {
         verdict: AgentSessionResponse["verdict"];
         turn: AgentSessionResponse["turn"];
         guardrails: AgentSessionResponse["guardrails"];
+        /** R10 (MNE-8200): oldest first (the gateway's own wire order), unlike the human view. */
+        verdict_trail: AgentSessionResponse["verdict_trail"];
     } | {
         source: "gateway";
         available: false;
@@ -116,6 +167,10 @@ export interface AgentSessionsOptions {
 export declare function agentSessionsCommand(opts: AgentSessionsOptions, deps: SessionCommandDeps): Promise<void>;
 export interface AgentShowOptions {
     json?: boolean;
+    /** Keep watching after the snapshot and print each new verdict as it lands. */
+    follow?: boolean;
+    /** `--follow`'s poll interval, in ms. Undefined ⇒ {@link resolveFollowIntervalMs}'s default/env. */
+    followIntervalMs?: number;
 }
 /** Why the live read could not happen, from the thrown error. */
 export declare function unavailableReason(err: unknown): string;

package/dist/commands/agent-sessions.js

@@ -16,7 +16,7 @@
 import { readSessionRecords } from "../lib/agent-ledger.js";
 import { getGatewayUrl, MNEMOM_DIR } from "../lib/config.js";
 import { resumeCommand, sameOrigin } from "../lib/agent.js";
-import { getAgentSession, MnemomApiError } from "../lib/api.js";
+import { getAgentSession, MnemomApiError, } from "../lib/api.js";
 import { fmt, formatRelativeAge } from "../lib/format.js";
 import { goalControlFetch } from "../lib/goal-api.js";
 /** The production wiring (index.ts). Lazy so a test that mocks lib/api without
@@ -35,6 +35,15 @@ export const liveSessionDeps = {
     cellGateway: () => getGatewayUrl(),
     out: (line) => console.log(line),
     err: (line) => console.error(line),
+    // NOT unref'd: see SessionCommandDeps.sleep's doc comment above — this timer must keep the
+    // process alive, or --follow exits right after the one-shot snapshot instead of polling.
+    sleep: (ms) => new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    }),
+    onSigint: (handler) => {
+        process.once("SIGINT", handler);
+        return () => process.removeListener("SIGINT", handler);
+    },
 };
 export const NO_SESSIONS_MESSAGE = "No sessions yet — run `mnemom agent` to start one.";
 export const DEFAULT_SESSIONS_LIMIT = 20;
@@ -162,6 +171,130 @@ export function gauge(label, value, ceiling, fired) {
     const ratio = ceiling === null ? String(value) : `${value}/${ceiling}`;
     return `${label} ${ratio}${fired ? " (crossed)" : ""}`;
 }
+/**
+ * One verdict-trail entry, human-readable — shared by the one-shot trail section in
+ * `buildShowView` and by `--follow`'s streamed lines, so the two never drift apart.
+ */
+export function formatTrailEntry(e) {
+    const fence = e.fence_breach === null ? "" : e.fence_breach ? " [fence breach]" : "";
+    return `turn ${e.turn} ${e.verdict.toUpperCase()} — ${e.reason}${fence} (${e.at})`;
+}
+/**
+ * The verdict trail is a bounded 50-entry ring: once it wraps, new entries at one end push
+ * old ones out, so an array index does not name the same verdict across two polls. The stable
+ * identity is the (request id, turn) pair the gateway recorded it under — `request_id` is
+ * null-able (the judge can run without one), joined with a separator that can't collide with a
+ * turn number.
+ */
+export function verdictTrailKey(e) {
+    return `${e.request_id ?? ""}#${e.turn}`;
+}
+/**
+ * Best-effort "has this session ended" check for `--follow`'s exit condition. No field is locked
+ * in on the wire yet: MNE-8149 adds an `expired` seal state on the gateway's row, and a later
+ * mnemom-api card is expected to carry it through to this response — so this reads defensively,
+ * off either the top-level response or the `sealed` block, and returns null (never throws) when
+ * neither carries a recognized value, which is every server today.
+ */
+export function sessionEndedState(remote) {
+    const as = (v) => v === "expired" || v === "ended" ? v : null;
+    const top = as(remote.state);
+    if (top)
+        return top;
+    if (remote.sealed) {
+        return as(remote.sealed.state);
+    }
+    return null;
+}
+/** Default and floor for `--follow`'s poll interval. */
+export const DEFAULT_FOLLOW_INTERVAL_MS = 3000;
+export const MIN_FOLLOW_INTERVAL_MS = 500;
+/** Seconds; consulted only when `--follow-interval` was not passed. */
+export const FOLLOW_INTERVAL_ENV_VAR = "MNEMOM_AGENT_FOLLOW_INTERVAL";
+/** Resolve the poll interval: explicit opt > env override (seconds) > default, floored. */
+export function resolveFollowIntervalMs(opts) {
+    if (opts.followIntervalMs !== undefined) {
+        return Math.max(MIN_FOLLOW_INTERVAL_MS, opts.followIntervalMs);
+    }
+    const envSeconds = Number(process.env[FOLLOW_INTERVAL_ENV_VAR]);
+    if (Number.isFinite(envSeconds) && envSeconds > 0) {
+        return Math.max(MIN_FOLLOW_INTERVAL_MS, envSeconds * 1000);
+    }
+    return DEFAULT_FOLLOW_INTERVAL_MS;
+}
+/**
+ * `--follow`: after the one-shot snapshot, keep polling the same live read-back
+ * (`deps.fetchSession`, the same `/internal/goal/session` route `show` already uses) and print
+ * each newly-landed verdict-trail entry once — a `tail -f` over the gateway's 50-entry ring.
+ * `opts.seenKeys` seeds the baseline (every entry already visible in the one-shot print); only
+ * entries whose {@link verdictTrailKey} is not yet in that set are printed, so a poll never
+ * repeats a verdict the ring-wrap could otherwise make look "new" by index.
+ *
+ * Exits (resolves) on SIGINT, or once {@link sessionEndedState} reads `"expired"`/`"ended"`, or
+ * once the gateway reports the session gone (`MnemomApiError` with `code === "agent_not_found"`).
+ * An auth failure (401/403 — an expired or revoked key) is NOT transient: it prints a clear
+ * error via `deps.err` and exits (`process.exitCode = 1`) rather than retrying forever. Any other
+ * fetch failure — including the documented `gateway_unavailable` — is treated as transient: the
+ * loop backs off and retries, and after {@link FOLLOW_FAILURE_WARNING_THRESHOLD} consecutive
+ * failures prints exactly one dim warning line to stderr (not one per failure) so a persistently
+ * broken poll isn't silent, then keeps retrying; a single success resets the counter.
+ */
+const FOLLOW_FAILURE_WARNING_THRESHOLD = 5;
+function isAuthError(e) {
+    return e instanceof MnemomApiError && (e.effectiveStatus === 401 || e.effectiveStatus === 403);
+}
+export async function followVerdictTrail(record, agentId, deps, opts) {
+    // NOT unref'd (see SessionCommandDeps.sleep's doc comment) — this is the foreground poll
+    // delay for --follow, and it must keep the process alive between polls.
+    const sleep = deps.sleep ??
+        ((ms) => new Promise((resolve) => {
+            setTimeout(resolve, ms);
+        }));
+    const seen = opts.seenKeys;
+    let stopped = false;
+    let consecutiveFailures = 0;
+    const unregister = deps.onSigint?.(() => {
+        stopped = true;
+    });
+    try {
+        while (!stopped) {
+            await sleep(opts.intervalMs);
+            if (stopped)
+                break;
+            let remote;
+            try {
+                remote = await deps.fetchSession(record.conversation_id, agentId, record.org_id);
+            }
+            catch (e) {
+                if (e instanceof MnemomApiError && e.code === "agent_not_found")
+                    return;
+                if (isAuthError(e)) {
+                    deps.err(`Error: the gateway rejected the credential (${e.effectiveStatus}) — this key may be expired or revoked: ${e.message}`);
+                    process.exitCode = 1;
+                    return;
+                }
+                consecutiveFailures += 1;
+                if (consecutiveFailures === FOLLOW_FAILURE_WARNING_THRESHOLD) {
+                    deps.err(fmt.dim(`--follow: ${consecutiveFailures} consecutive polls have failed; still retrying…`));
+                }
+                continue; // transient (gateway_unavailable or anything else) — back off and retry
+            }
+            consecutiveFailures = 0;
+            for (const entry of remote.verdict_trail ?? []) {
+                const key = verdictTrailKey(entry);
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                deps.out(opts.json ? JSON.stringify(entry) : formatTrailEntry(entry));
+            }
+            if (sessionEndedState(remote))
+                return;
+        }
+    }
+    finally {
+        unregister?.();
+    }
+}
 /**
  * The human view for `mnemom agent show`: the local record, then the live
  * gateway state (or a dim "live state unavailable (<reason>)" line when
@@ -223,6 +356,15 @@ export function buildShowView(local, remote, reason) {
     else {
         L.push(fmt.label("verdict:        ", fmt.dim("none yet")));
     }
+    // R10 (MNE-8200): the last up-to-50 judged verdicts. The gateway returns them oldest first;
+    // shown here newest first (most recent verdict closest to the cursor) — the reverse of the
+    // wire order, so don't reuse `remote.verdict_trail`'s index as the turn number.
+    if (remote.verdict_trail && remote.verdict_trail.length > 0) {
+        L.push(fmt.label("verdict trail:  ", `last ${remote.verdict_trail.length} (newest first)`));
+        for (const e of [...remote.verdict_trail].reverse()) {
+            L.push(fmt.label("  ", formatTrailEntry(e)));
+        }
+    }
     if (remote.guardrails) {
         const { ceilings, state } = remote.guardrails;
         if (state) {
@@ -257,6 +399,7 @@ export function buildShowJson(local, remote, reason) {
                 verdict: remote.verdict,
                 turn: remote.turn,
                 guardrails: remote.guardrails,
+                verdict_trail: remote.verdict_trail,
             }
             : { source: "gateway", available: false, reason: reason ?? "unknown" },
     };
@@ -300,6 +443,22 @@ export function liveGoalLine(body) {
     const cut = statement.slice(0, LIVE_GOAL_STATEMENT_MAX - 1).trimEnd();
     return `${rev} — "${cut}…" (full: mnemom agent goal show)`;
 }
+/**
+ * Can this session's live state (and hence `--follow`) ever be read? Two cases never resolve
+ * regardless of retries — no agent id was recorded at launch, or the session ran on a different
+ * cell than this CLI is pointed at — so they're resolved once, up front, as a named reason rather
+ * than inside the fetch's catch (where a genuinely transient failure also lands).
+ */
+function resolveFollowTarget(record, cell) {
+    if (record.agent_id === null)
+        return { reason: "agent id was not resolved at launch" };
+    if (cell !== undefined && !sameOrigin(record.gateway_host, cell)) {
+        return {
+            reason: `this session ran on ${record.gateway_host}, not this CLI's cell (${cell}) — point the CLI at that cell to read it`,
+        };
+    }
+    return { agentId: record.agent_id };
+}
 /** `mnemom agent show [ref] [--json]` */
 export async function agentShowCommand(ref, opts, deps) {
     const records = deps.readRecords();
@@ -325,18 +484,16 @@ export async function agentShowCommand(ref, opts, deps) {
         return;
     }
     const { record, others } = resolved;
+    const cell = deps.cellGateway?.();
+    const target = resolveFollowTarget(record, cell);
     let remote = null;
     let reason;
-    const cell = deps.cellGateway?.();
-    if (record.agent_id === null) {
-        reason = "agent id was not resolved at launch";
-    }
-    else if (cell !== undefined && !sameOrigin(record.gateway_host, cell)) {
-        reason = `this session ran on ${record.gateway_host}, not this CLI's cell (${cell}) — point the CLI at that cell to read it`;
+    if ("reason" in target) {
+        reason = target.reason;
     }
     else {
         try {
-            remote = await deps.fetchSession(record.conversation_id, record.agent_id, record.org_id);
+            remote = await deps.fetchSession(record.conversation_id, target.agentId, record.org_id);
         }
         catch (e) {
             reason = unavailableReason(e);
@@ -344,27 +501,40 @@ export async function agentShowCommand(ref, opts, deps) {
     }
     if (opts.json) {
         deps.out(JSON.stringify(buildShowJson(record, remote, reason), null, 2));
-        return;
     }
-    for (const line of buildShowView(record, remote, reason))
-        deps.out(line);
-    if (deps.fetchGoal && resolveGoalMode(record, remote) === "implicit") {
-        // Best effort: any failure (no key, gateway without the route, agent not found) is one dim line.
-        let line;
-        try {
-            line = liveGoalLine(await deps.fetchGoal(record));
+    else {
+        for (const line of buildShowView(record, remote, reason))
+            deps.out(line);
+        if (deps.fetchGoal && resolveGoalMode(record, remote) === "implicit") {
+            // Best effort: any failure (no key, gateway without the route, agent not found) is one dim line.
+            let line;
+            try {
+                line = liveGoalLine(await deps.fetchGoal(record));
+            }
+            catch {
+                line = fmt.dim("(live goal unavailable)");
+            }
+            deps.out(fmt.label("live goal:      ", line));
         }
-        catch {
-            line = fmt.dim("(live goal unavailable)");
+        if (others.length > 0) {
+            deps.out("");
+            deps.out(fmt.dim(`  ${others.length} older session(s) share this name — \`mnemom agent show <conv-id prefix>\` picks one:`));
+            for (const o of others) {
+                deps.out(fmt.dim(`    ${o.conversation_id.slice(0, 8)}  ${formatRelativeAge(o.started_at)}`));
+            }
         }
-        deps.out(fmt.label("live goal:      ", line));
-    }
-    if (others.length > 0) {
         deps.out("");
-        deps.out(fmt.dim(`  ${others.length} older session(s) share this name — \`mnemom agent show <conv-id prefix>\` picks one:`));
-        for (const o of others) {
-            deps.out(fmt.dim(`    ${o.conversation_id.slice(0, 8)}  ${formatRelativeAge(o.started_at)}`));
-        }
     }
-    deps.out("");
+    if (!opts.follow)
+        return;
+    if ("reason" in target) {
+        deps.err(fmt.dim(`--follow: ${target.reason} — nothing to watch.`));
+        return;
+    }
+    const seenKeys = new Set((remote?.verdict_trail ?? []).map(verdictTrailKey));
+    await followVerdictTrail(record, target.agentId, deps, {
+        json: opts.json,
+        intervalMs: resolveFollowIntervalMs(opts),
+        seenKeys,
+    });
 }

package/dist/commands/agent.d.ts

@@ -40,12 +40,16 @@ export interface AgentOptions {
     budget?: string;
     maxTurns?: string;
     stall?: string;
+    /** `--mode nudge|enforce` (MNE-8199): see `ContractFlags.mode` (lib/agent.ts). */
+    mode?: string;
     /**
      * `--implicit`: goal alignment with no sealed contract — the gateway infers the
      * goal from the user's messages and revises it as they steer; the ceilings above
      * ride on the `x-mnemom-goal-mode` header. Exclusive with the contract flags.
      */
     implicit?: boolean;
+    /** `--lead-directed`: see `ContractFlags.leadDirected` (lib/agent.ts, MNE-8152). */
+    leadDirected?: boolean;
     /** x-mnemom-agent value (defaults to "code-agent"). */
     agent?: string;
     conversationId?: string;
@@ -251,6 +255,8 @@ export interface ResolvedCli {
     /** The basename, e.g. "claude" — selects the launch adapter. */
     name: string;
 }
+/** The CLI asked for — `--cli`, else MNEMOM_AGENT_CLI, else "claude" — before any lookup. */
+export declare function requestedCli(cliOpt: string | undefined, env: NodeJS.ProcessEnv): string;
 /**
  * Resolve which coding-agent CLI to launch. `--cli` (or MNEMOM_AGENT_CLI) is a
  * name or a full path; default "claude". A value with a path separator is used