@mnemom/mnemom 0.17.16-next.0 → 0.17.17-next.0

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;

package/dist/commands/agent.js

@@ -176,7 +176,9 @@ export async function agentCommand(scenarioArg, options = {}) {
         budget: options.budget,
         maxTurns: options.maxTurns,
         stall: options.stall,
+        mode: options.mode,
         implicit: options.implicit,
+        leadDirected: options.leadDirected,
     });
     // ── implicit goal mode (no contract; the gateway infers the goal from the user's
     // messages) — the guardrail ceilings ride on the mode header instead ──

package/dist/index.js

@@ -150,7 +150,12 @@ const agentCmd = program
     .option("--budget <usd>", "Guardrail: spend ceiling in USD (positive number)")
     .option("--max-turns <n>", "Guardrail: turn ceiling (positive integer)")
     .option("--stall <n>", "Guardrail: consecutive no-write turns (positive integer)")
-    .addOption(new Option("--implicit", "EXPERIMENTAL (`mnemom experimental enable implicit`): implicit goal alignment — the gateway infers the goal from your messages and revises it as you steer (the default while the feature is on; not combinable with --goal/--requirement/--allow/--forbid/--goal-id; the guardrail ceilings still apply)").hideHelp(hiddenUnless("implicit")))
+    .option("--mode <nudge|enforce>", "Sealed contract mode (MNE-8199; default nudge). Under enforce, a crossed turn/budget/time " +
+    "ceiling REFUSES the next request on this conversation until the owner raises it via a " +
+    "contract update — under nudge the ceiling only nudges, unchanged. Requires --goal.")
+    .option("--lead-directed", "Seal the standard lead-directed requirement: own-branch push and draft/ready PR creation, " +
+    "from a git worktree, on the lead's direction — not merging. Requires --goal; idempotent.")
+    .addOption(new Option("--implicit", "EXPERIMENTAL (`mnemom experimental enable implicit`): implicit goal alignment — the gateway infers the goal from your messages and revises it as you steer (the default while the feature is on; not combinable with --goal/--requirement/--allow/--forbid/--goal-id/--mode/--lead-directed; the guardrail ceilings still apply)").hideHelp(hiddenUnless("implicit")))
     .option("--no-implicit", "Turn implicit goal alignment OFF for this launch (overrides launcher.toml goal_mode = implicit)")
     .option("--conversation-id <id>", "x-mnemom-conversation-id (default: auto-generated)")
     .option("--cli <name|path>", "Coding-agent CLI to launch: a name or full path (default: claude)")
@@ -345,9 +350,11 @@ const agentCmd = program
             forbid: opts.forbid,
             goalId: opts.goalId,
             implicit,
+            leadDirected: opts.leadDirected,
             budget: opts.budget ?? (contractIntended ? numToStr(cfg.guardrails?.budgetUsd) : undefined),
             maxTurns: opts.maxTurns ?? (contractIntended ? numToStr(cfg.guardrails?.maxTurns) : undefined),
             stall: opts.stall ?? (contractIntended ? numToStr(cfg.guardrails?.stallTurns) : undefined),
+            mode: opts.mode,
             agent: parentOpts.agent ?? cfg.agent,
             conversationId: opts.conversationId,
             cli: opts.cli,
@@ -878,9 +885,21 @@ agentCmd
     .description("Show one session — the local launch record merged with the gateway's live goal state (sealed contract, latest verdict, guardrails). " +
     "`ref` is a session name (newest match wins) or a unique conversation-id prefix; omitted = the newest session")
     .option("--json", "Output the merged view as JSON (each section tagged with its source)")
+    .option("--follow", "After the snapshot, keep watching and print each new verdict as it lands (Ctrl-C to stop)")
+    .option("--follow-interval <seconds>", "Poll interval for --follow, in seconds (default 3; also settable via MNEMOM_AGENT_FOLLOW_INTERVAL)")
     .action(async (ref, opts) => {
     try {
-        await agentShowCommand(ref, { json: opts.json }, liveSessionDeps);
+        let followIntervalMs;
+        if (opts.followInterval !== undefined) {
+            const seconds = Number(opts.followInterval);
+            if (!Number.isFinite(seconds) || seconds <= 0) {
+                console.error("Error: --follow-interval must be a positive number of seconds.");
+                process.exit(1);
+                return;
+            }
+            followIntervalMs = seconds * 1000;
+        }
+        await agentShowCommand(ref, { json: opts.json, follow: opts.follow, followIntervalMs }, liveSessionDeps);
     }
     catch (error) {
         console.error("Error:", error instanceof Error ? error.message : error);

package/dist/lib/agent.d.ts

@@ -39,6 +39,15 @@ export interface SealedContract {
     max_turns?: number;
     budget_usd?: number;
     stall_turns?: number;
+    /**
+     * `nudge` | `enforce` (MNE-8199, design D9/R9): under `enforce` a crossed turn/budget/time
+     * ceiling refuses the gateway's NEXT request on this conversation rather than only
+     * nudging. ALWAYS present once a contract is sealed (never omitted) — the gateway's
+     * `parseContractHeader` defaults an absent/invalid value to `"nudge"` unconditionally
+     * before hashing, so the CLI must set it here too (defaulting to `"nudge"`) or the sha
+     * printed here would disagree with the one the gateway seals (the MNE-7649 class of bug).
+     */
+    mode?: "nudge" | "enforce";
 }
 /** The raw contract/guardrail flags as commander hands them to the command. */
 export interface ContractFlags {
@@ -50,6 +59,8 @@ export interface ContractFlags {
     maxTurns?: string | number;
     budget?: string | number;
     stall?: string | number;
+    /** `--mode nudge|enforce` (MNE-8199) — validated and defaulted in `assembleContract`. */
+    mode?: string;
     /**
      * `--implicit`: goal alignment WITHOUT a sealed contract. No `x-mnemom-contract`
      * is sent; the gateway infers the goal from the user's own messages (revision 1
@@ -58,7 +69,26 @@ export interface ContractFlags {
      * of inside a contract. Cannot be combined with the sealed-contract flags.
      */
     implicit?: boolean;
+    /**
+     * `--lead-directed`: append `LEAD_DIRECTED_REQUIREMENT` to the sealed contract's
+     * `requirements` (MNE-8152, design `mnemom-agent-wave` D4). A lead-directed agent
+     * (e.g. an ADW lane lead) legitimately pushes its own branches and opens draft/ready
+     * PRs; under the sealed framing the judge reads only `goal`/`requirements`/fences, so
+     * without this line a push/PR step is flagged `violation` ("an effect of this step is
+     * not allowed by the requirements"). The mechanism is a requirement line, not a judge
+     * input — sealed mode takes no in-session steering, so the lead's direction must
+     * already be IN the seal. Idempotent: appended at most once, whether the flag is
+     * given once or the requirement text is already present (e.g. supplied verbatim via
+     * `--requirement`).
+     */
+    leadDirected?: boolean;
 }
+/**
+ * The standard requirement line `--lead-directed` seals: own-branch push and draft/ready
+ * PR creation, from a git worktree, on the lead's direction — merging is explicitly out.
+ * A single constant so every launch that opts in seals byte-identical wording (MNE-8152).
+ */
+export declare const LEAD_DIRECTED_REQUIREMENT: string;
 /** The three launch shapes the command supports (see commands/code.ts). */
 export type LaunchShape = "terminal" | "remote-control" | "server";
 /**

package/dist/lib/agent.js

@@ -25,6 +25,13 @@ import { join } from "node:path";
 import { getGatewayUrl } from "./config.js";
 /** The us-2/prod gateway host. The default door — never any other cell silently. */
 export const PROD_GATEWAY_HOST = "https://gateway.mnemom.ai";
+/**
+ * The standard requirement line `--lead-directed` seals: own-branch push and draft/ready
+ * PR creation, from a git worktree, on the lead's direction — merging is explicitly out.
+ * A single constant so every launch that opts in seals byte-identical wording (MNE-8152).
+ */
+export const LEAD_DIRECTED_REQUIREMENT = "On the lead's direction, this session may push its own branches and open draft or " +
+    "ready pull requests, from a git worktree, never the primary checkout; it may not merge them.";
 /**
  * Resolve the gateway HOST (scheme + host, no path). An explicit, non-empty
  * `MNEMOM_AGENT_GATEWAY` wins verbatim; otherwise the gateway of the cell the rest
@@ -381,7 +388,9 @@ export function contractFlagsPresent(flags) {
         hasText(flags.goalId) ||
         flags.maxTurns !== undefined ||
         flags.budget !== undefined ||
-        flags.stall !== undefined);
+        flags.stall !== undefined ||
+        hasText(flags.mode) ||
+        flags.leadDirected === true);
 }
 function hasText(v) {
     return typeof v === "string" && v.trim().length > 0;
@@ -413,11 +422,18 @@ export function assembleContract(flags) {
     const statement = (flags.goal ?? "").trim();
     if (!statement) {
         throw new Error("--goal is required when any contract flag " +
-            "(--requirement/--allow/--forbid/--goal-id/--budget/--max-turns/--stall) is given.");
+            "(--requirement/--allow/--forbid/--goal-id/--budget/--max-turns/--stall/--mode/--lead-directed) is given.");
+    }
+    const requirements = cleanList(flags.requirement);
+    // Idempotent: append the standard line only when it is not already present, whether
+    // because `--lead-directed` was given more than once or because the exact wording
+    // was already supplied verbatim via `--requirement`.
+    if (flags.leadDirected === true && !requirements.includes(LEAD_DIRECTED_REQUIREMENT)) {
+        requirements.push(LEAD_DIRECTED_REQUIREMENT);
     }
     const contract = {
         statement,
-        requirements: cleanList(flags.requirement),
+        requirements,
         allowed_paths: cleanList(flags.allow),
         forbidden_paths: cleanList(flags.forbid),
     };
@@ -442,6 +458,19 @@ export function assembleContract(flags) {
         }
         contract.stall_turns = Number(flags.stall);
     }
+    // MNE-8199: set only for the non-default "enforce" — the gateway's own canonicalHash
+    // folds `mode` into the hash the same way (see its doc comment): a contract that never
+    // named `--mode` must keep hashing identically to the byte-identical contract sealed
+    // before the field existed, or every live conversation logs `goal_contract_ignored_change`
+    // on deploy. Setting a defaulted "nudge" here unconditionally would instead make the SHA
+    // this prints disagree with the one the gateway actually seals for the exact same launch —
+    // the MNE-7649 class of bug, just reintroduced from the client side.
+    const rawMode = (flags.mode ?? "").trim();
+    if (rawMode && rawMode !== "nudge" && rawMode !== "enforce") {
+        throw new Error(`--mode must be "nudge" or "enforce" (got '${flags.mode}').`);
+    }
+    if (rawMode === "enforce")
+        contract.mode = "enforce";
     const canonical = canonicalJson(contract);
     return {
         contract,
@@ -756,7 +785,7 @@ export function applyGatewayHintHeaders(childEnv) {
     }
     return childEnv;
 }
-const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id";
+const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id/--mode/--lead-directed";
 /**
  * `--implicit` and a sealed contract are mutually exclusive: on the gateway a
  * sealed `x-mnemom-contract` always wins and would silently switch implicit mode
@@ -768,7 +797,9 @@ function assertImplicitCompatible(flags) {
         (flags.requirement?.length ?? 0) > 0 ||
         (flags.allow?.length ?? 0) > 0 ||
         (flags.forbid?.length ?? 0) > 0 ||
-        hasText(flags.goalId);
+        hasText(flags.goalId) ||
+        hasText(flags.mode) ||
+        flags.leadDirected === true;
     if (sealed) {
         throw new Error(`--implicit cannot be combined with ${SEALED_ONLY_FLAGS}: a sealed contract always wins on ` +
             "the gateway and would silently switch implicit mode off. Drop --implicit to seal a " +

package/dist/lib/api.d.ts

@@ -1289,6 +1289,22 @@ export interface AgentSessionGuardrails {
         };
     } | null;
 }
+/**
+ * One entry of the gateway's verdict trail (R10, MNE-8200) — up to the last 50 judged turns,
+ * oldest first (same order the gateway stores and returns them in). `request_id` is the request
+ * that produced this verdict, or null when the judge ran without one. `fence_breach` is `true`/
+ * `false` for a conclusive mechanical allowed/forbidden-paths check, `null` when the contract has
+ * no fences or the verdict predates the check. This shape is also what MNE-8234 mirrors — keep
+ * the field name and member shape stable.
+ */
+export interface AgentSessionVerdictTrailEntry {
+    request_id: string | null;
+    turn: number;
+    verdict: "aligned" | "drifting" | "violation";
+    reason: string;
+    fence_breach: boolean | null;
+    at: string;
+}
 /** `GET /v1/agent/sessions/{conversationId}` 200 body. Nulls mean "nothing stored" — absence is data. */
 export interface AgentSessionResponse {
     conversation_id: string;
@@ -1301,6 +1317,8 @@ export interface AgentSessionResponse {
     verdict: AgentSessionVerdict | null;
     turn: number | null;
     guardrails: AgentSessionGuardrails | null;
+    /** Absent on an older server (back-compat) — never shown then, never an empty-array assumption. */
+    verdict_trail?: AgentSessionVerdictTrailEntry[];
 }
 /**
  * The live goal state of one `mnemom agent` session, read through mnemom-api

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.16-next.0",
+  "version": "0.17.17-next.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "js-yaml": "^4.3.2",
-    "smol-toml": "^1.8.0"
+    "smol-toml": "^1.9.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",