@meetless/mla 0.1.4

package/dist/commands/internal-finalize.js

@@ -0,0 +1,221 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseArgs = parseArgs;
+exports.triggerSessionFinalize = triggerSessionFinalize;
+exports.runInternalFinalize = runInternalFinalize;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("../lib/config");
+const workspace_1 = require("../lib/workspace");
+const http_1 = require("../lib/http");
+const git_1 = require("../lib/git");
+// `mla _internal finalize-session <sessionId>` (§5.2 + Correction 6)
+//
+// Invoked by flush.sh after it drains a session and observes a
+// finalize_requested event. CLI is responsible for git evidence capture
+// because hooks must NOT shell out to git (slow + sandbox unpredictability).
+//
+// Wire: POST /internal/v1/agent-runs/by-session/<sid>/finalize
+//   body: { workspaceId, gitEvidence }   (Correction 6: no finalMessage)
+//
+// Git is opportunistic corroboration, NOT the source of truth (Decision 7,
+// note 20260528 §11). The source of truth for what a session changed is the
+// coding agent's own text report (captured by stop.sh into
+// session_stopped.finalMessage -> agentClaimsRaw). Meetless is a coordination
+// layer, not a git forensics tool; we do not reconstruct "what changed" from
+// disk state. Git evidence is captured ONLY as supplementary "actuals" when the
+// session cwd resolves to a single repo.
+//
+// We prefer $MEETLESS_REPO_PATH (set by flush.sh from the session_started
+// repoPath sidecar) over process.cwd(). When that path is a real repo,
+// captureGitEvidence returns the actuals (branch, last commit, changed files,
+// diff stat). When it is a non-repo (e.g. a parent folder holding many child
+// repos, or a scratch dir), captureGitEvidence returns an empty shell with the
+// reason in `errors[]` (`{topLevel: "", errors: ["toplevel:fatal: not a git
+// repository"], ...}`). Either way we POST finalize: the worker degrades
+// gracefully on empty git, and `errors[]` keeps the absence visible rather than
+// silently dropped (preserving Epoch 33's anti-silent-loss intent without the
+// hard block).
+//
+// Why no block: a non-repo cwd is a legitimate, supported setup, not a wrong-cwd
+// retry to fix. The earlier guard (Epoch 33) refused to POST on empty topLevel
+// and re-spooled finalize_requested, which re-spooled FOREVER in a multi-repo
+// parent and wedged the whole review loop. Git absence is now just absence.
+// Strict argv parsing for `mla _internal finalize-session` (Wedge v6
+// Epoch 53). The internal subcommand is fired by flush.sh on every
+// drained session's finalize_requested event:
+//
+//   "$MLA_PATH" _internal finalize-session "$SESSION_ID"
+//
+// flush.sh always passes exactly one positional. The CLI's old guard
+// was `argv.length < 1` which masked three silent drops if the hook
+// is ever invoked with anything other than that exact shape:
+//
+//   1. `mla _internal finalize-session sid extra` silently dropped
+//      "extra". An accidental flush.sh refactor that appended a
+//      second positional would silently target one sessionId but
+//      look like it accepted two.
+//
+//   2. `mla _internal finalize-session --foo` bound sessionId="--foo"
+//      and the server then 404'd opaquely. A flush.sh template bug
+//      that emitted a flag in the SESSION_ID slot (e.g. shell glob
+//      expansion gone wrong) would silently 404.
+//
+//   3. Zero positionals returned exit 2 with the usage line, which
+//      is correct -- but the same path is preserved here through
+//      the throw + catch convention so it stays symmetric with the
+//      other strict parsers.
+//
+// Strict rules below:
+//   - Exactly one positional (sessionId). Zero or two+ throw.
+//   - Zero flags supported. Any `--`-prefixed or `-`-prefixed token
+//     throws.
+function parseArgs(argv) {
+    let sessionId;
+    for (const a of argv) {
+        if (a.startsWith("--") || a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. \`mla _internal finalize-session\` takes no flags, only <sessionId>.`);
+        }
+        if (sessionId !== undefined) {
+            throw new Error(`Unexpected extra positional argument: ${a}. \`mla _internal finalize-session\` takes exactly one sessionId.`);
+        }
+        sessionId = a;
+    }
+    if (sessionId === undefined) {
+        throw new Error("usage: mla _internal finalize-session <sessionId>");
+    }
+    return { sessionId };
+}
+// The finalize core, extracted so it can be fired by more than the Stop hook.
+//
+// Two callers share it:
+//   1. `mla _internal finalize-session` (this file's runInternalFinalize),
+//      driven by flush.sh on the Stop hook's finalize_requested event.
+//   2. `mla review` (Phase 7 / PATCH 5 / INV-M6,
+//      notes/20260604-mla-mission-and-review-packet-rethink.md), which fires
+//      this on demand so a review snapshot is produced WITHOUT waiting for a
+//      Stop signal that, in practice, never cleanly arrives. The Stop-hook
+//      finalize is now one trigger among several, not the sole producer.
+//
+// Captures git evidence (opportunistic corroboration, never the source of truth)
+// and POSTs the finalize. Returns both the evidence and the resolved repoPath so
+// the caller can tailor its own logging. Idempotent on runId server-side, so it
+// is safe to re-fire on every `mla review` (the rolling-snapshot model). Carries
+// no mission (PR1) and tolerates branch = null (INV-M1): a detached-HEAD / non-
+// repo checkout yields an empty branch and the finalize still proceeds.
+async function triggerSessionFinalize(sessionId, cfg) {
+    // Repo resolution ladder, mirroring flush.sh so both finalize callers agree:
+    //   1. $MEETLESS_REPO_PATH  -- the Stop-hook path: flush.sh exports it from the
+    //      <sid>.repoPath sidecar before invoking `mla _internal finalize-session`.
+    //   2. <sid>.repoPath sidecar -- the on-demand `mla review` path (Phase 7 /
+    //      INV-M6) has no flush.sh wrapper to set the env var, so it reads the
+    //      sidecar directly. Without this rung, on-demand finalize captured git
+    //      evidence from whatever directory the human happened to type `mla review`
+    //      in, and the rolling-snapshot finalize OVERWROTE the run with wrong-repo
+    //      (or empty) evidence. Since Phase 7 assumes a clean Stop never arrives,
+    //      that on-demand capture may be the only git evidence the run ever gets.
+    //   3. process.cwd() -- legacy fallback for a session with no sidecar (started
+    //      before session-start.sh wrote one), preserving the original behavior.
+    const envRepoPath = process.env.MEETLESS_REPO_PATH;
+    let repoPath;
+    if (envRepoPath && envRepoPath.length > 0) {
+        repoPath = envRepoPath;
+    }
+    else {
+        let sidecarRepoPath = null;
+        try {
+            const raw = fs.readFileSync(path.join(config_1.QUEUE_DIR, `${sessionId}.repoPath`), "utf8").trim();
+            sidecarRepoPath = raw.length > 0 ? raw : null;
+        }
+        catch {
+            sidecarRepoPath = null;
+        }
+        repoPath = sidecarRepoPath ?? process.cwd();
+    }
+    // Folder = workspace (T1.1): the run belongs to the workspace bound to the
+    // SESSION REPO, resolved from the nearest `.meetless.json` marker walking up
+    // from repoPath -- NOT from process.cwd(). The Stop-hook path runs this via
+    // flush.sh, which is nohup-spawned and whose cwd is usually $HOME, so cwd is
+    // not the repo; repoPath (env -> sidecar -> cwd ladder above) is. Both finalize
+    // callers therefore agree on the workspace the same way they agree on git
+    // evidence: through the one resolved repo path. An unactivated repo (no marker)
+    // throws NotActivatedError here -- finalize cannot name a workspace to the
+    // server, so it correctly does not POST a half-bound run.
+    const workspaceId = (0, workspace_1.resolveWorkspaceId)(repoPath);
+    // Read the session-start git baseline sidecar (written by session-start.sh).
+    // Subtracting it makes captureGitEvidence attribute only session-touched
+    // changes, not ambient dirty state the tree carried before the agent ran.
+    // Absent sidecar (older session, or session-start hook never ran) => null =>
+    // original whole-tree behavior, so this is fully backward-compatible.
+    const baselinePath = path.join(config_1.QUEUE_DIR, `${sessionId}.gitBaseline`);
+    let baseline = null;
+    try {
+        baseline = fs.readFileSync(baselinePath, "utf8");
+    }
+    catch {
+        baseline = null;
+    }
+    const git = (0, git_1.captureGitEvidence)(repoPath, baseline);
+    await (0, http_1.post)(cfg, `/internal/v1/agent-runs/by-session/${encodeURIComponent(sessionId)}/finalize`, {
+        workspaceId,
+        gitEvidence: git,
+    }, 15000);
+    return { git, repoPath, workspaceId };
+}
+async function runInternalFinalize(argv) {
+    let sessionId;
+    try {
+        ({ sessionId } = parseArgs(argv));
+    }
+    catch (e) {
+        console.error(e.message);
+        return 2;
+    }
+    // Folder = workspace (T1.1): credentials only here. The run's workspaceId is
+    // resolved INSIDE triggerSessionFinalize from the `.meetless.json` marker
+    // at/above the resolved session repo path (NOT process.cwd()), because flush.sh
+    // is nohup-spawned and runs this from $HOME -- cwd is not the repo.
+    const cfg = (0, config_1.readConfig)();
+    const { git, repoPath } = await triggerSessionFinalize(sessionId, cfg);
+    if (!git.topLevel) {
+        console.log(`Finalize accepted for session ${sessionId} (no git corroboration: ${repoPath} is not a single repo; ` +
+            `agent report remains the source of truth).`);
+    }
+    else {
+        console.log(`Finalize accepted for session ${sessionId}.`);
+    }
+    return 0;
+}

package/dist/commands/internal-pretool-observe.js

@@ -0,0 +1,225 @@
+"use strict";
+// `mla _internal pretool-observe` (A1: make the R1 notes-location pilot live). The managed
+// pre-tool-use.sh hook pipes its raw PreToolUse stdin into this subcommand and forwards whatever it
+// writes on stdout back to Claude Code as the hook response.
+//
+// In R0 this subcommand was decision-free by construction (a constant `{}`). A1 wires it to the
+// version-backed enforce seam (`evaluateAndEnforceNotesVersion`): it now emits a real deny on the wire
+// when, and ONLY when, a human-attested LIVE version is VIOLATED and the deny is admitted by the
+// deny-admission gates (P0.58 sole input authority, P0.63 attested path root). Everything else is the
+// empty pass-through. Two invariants are load-bearing:
+//
+//   1. The decision is COMPUTED from the rule evaluation, never reflected from the input. A payload that
+//      smuggles a `hookSpecificOutput.permissionDecision` cannot survive into stdout: the only deny this
+//      command can emit is the one the seam returns against the one human-attested LIVE version, with a
+//      reason the seam builds (`buildDenyReason`), never the attacker's string.
+//
+//   2. The hook can never block on infrastructure. A PreToolUse exit 2 (or a thrown error, or a missing
+//      `mla`) would block the tool; we must never do that. Every failure path -- unreadable stdin,
+//      malformed payload, store open failure, a throwing dependency -- fails OPEN to the exit-0
+//      pass-through. The decision travels in the JSON body, never the exit code.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRETOOL_PASS_THROUGH = void 0;
+exports.renderPreToolUseResponse = renderPreToolUseResponse;
+exports.renderConflictWarning = renderConflictWarning;
+exports.runInternalPretoolObserve = runInternalPretoolObserve;
+const os_1 = require("os");
+const active_conflict_cache_1 = require("../lib/active-conflict-cache");
+const ce0_store_1 = require("../lib/rules/ce0-store");
+const enforce_notes_version_1 = require("../lib/rules/enforce-notes-version");
+const observe_adapter_1 = require("../lib/rules/observe-adapter");
+const runtime_scope_1 = require("../lib/rules/runtime-scope");
+const live_input_authority_1 = require("../lib/rules/live-input-authority");
+const cache_1 = require("../lib/scanner/cache");
+const workspace_1 = require("../lib/workspace");
+// The empty pass-through response: exit-0, carries no `hookSpecificOutput`, hence grants nothing and
+// decides nothing (the documented Claude Code no-decision body).
+exports.PRETOOL_PASS_THROUGH = {};
+/**
+ * Pure. Map the enforce seam's internal response to the Claude Code PreToolUse wire shape. A deny
+ * becomes the documented `hookSpecificOutput` deny body; everything else is the empty pass-through.
+ * Exit code is ALWAYS 0: the decision rides the body, never the exit code (an exit 2 would block).
+ */
+function renderPreToolUseResponse(seam) {
+    if ("permissionDecision" in seam && seam.permissionDecision === "deny") {
+        return {
+            stdout: JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: "PreToolUse",
+                    permissionDecision: "deny",
+                    permissionDecisionReason: seam.reason,
+                },
+            }),
+            exitCode: 0,
+        };
+    }
+    return { stdout: JSON.stringify(exports.PRETOOL_PASS_THROUGH), exitCode: 0 };
+}
+/**
+ * Pure. Build the SOFT cross-session conflict warning (G8 / D1 §11.3, CRITICAL-5)
+ * for the session's open conflicts. It carries NO `permissionDecision`, so the tool
+ * is PERMITTED: Claude Code falls through to its normal permission flow. The body
+ * splits the two audiences the way Claude Code routes them:
+ *   - `systemMessage` is shown to the human operator (a one-line "heads up, an open
+ *     conflict touches this work, resolve it in /inbox").
+ *   - `hookSpecificOutput.additionalContext` is fed to the agent so it can pause the
+ *     conflicting line of work on its own.
+ * The hard default-deny is DEFERRED (§0.1): a fail-closed gate on a possibly-stale
+ * snapshot would brick coding sessions, so this surface only ever warns. The mode is
+ * named in the agent context purely for transparency; it never gates the wire shape
+ * here (both soft and hard render the same warning until the deny path is built).
+ */
+function renderConflictWarning(conflicts, mode) {
+    const first = conflicts[0];
+    const extra = conflicts.length - 1;
+    const more = extra > 0 ? ` (and ${extra} more open on this session)` : "";
+    const systemMessage = `Meetless: a pending cross-session conflict touches this work. ` +
+        `${first.reason} Case ${first.caseId}${more}. ` +
+        `Resolve it in /inbox before relying on this change.`;
+    const additionalContext = `Meetless D1 early warning (gate: ${mode}). ${conflicts.length} open ` +
+        `cross-session conflict(s) on this session. ${first.reason} ` +
+        `Case ${first.caseId} opened ${first.openedAt}${more}. ` +
+        `This is advisory and the tool is permitted; pause this line of work and ` +
+        `check /inbox for the human decision before continuing.`;
+    return {
+        stdout: JSON.stringify({
+            systemMessage,
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                additionalContext,
+            },
+        }),
+        exitCode: 0,
+    };
+}
+function readStdinReal() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (c) => chunks.push(c));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", reject);
+    });
+}
+const defaultDeps = {
+    readStdin: readStdinReal,
+    writeOut: (s) => process.stdout.write(s),
+};
+/**
+ * Compute the PreToolUse decision for one raw stdin payload by running the enforce seam against the
+ * active scope's LIVE attested version. Fails OPEN to the pass-through on ANY error (store open failure,
+ * a throwing dependency, a seam fault) so the hook can never block a tool on infrastructure. The store
+ * is opened here and closed in `finally` unless the caller injected one (then the caller owns its
+ * lifecycle).
+ */
+async function computePretoolDecision(raw, deps) {
+    const ownsStore = deps.store === undefined;
+    let store;
+    try {
+        store = deps.store ?? (0, ce0_store_1.openCe0Store)((0, ce0_store_1.defaultCe0StorePath)());
+        const scope = (deps.resolveScope ?? defaultResolveScope)();
+        const clock = (deps.clock ?? defaultClock)();
+        const resolveInputAuthority = deps.resolveInputAuthority ?? live_input_authority_1.resolveLiveInputAuthority;
+        const directives = (deps.resolveDirectives ?? defaultResolveDirectives)();
+        const { response } = await (0, enforce_notes_version_1.evaluateEnforceOrObserveNotesRule)(store, {
+            rawStdin: raw,
+            runtimeProjectRoot: scope.runtimeProjectRoot,
+            runtimeScopeId: scope.runtimeScopeId,
+            createdAt: clock.createdAt,
+            now: clock.now,
+            classifyRuntime: deps.classifyRuntime,
+            resolveInputAuthority,
+            directives,
+        });
+        // The notes-version governance deny is a HARD, human-attested block and takes
+        // precedence: never soften a real deny into a warning. Only when the notes path
+        // passes through do we layer the SOFT cross-session conflict warning (which can
+        // only ever advise, never deny).
+        if ("permissionDecision" in response && response.permissionDecision === "deny") {
+            return renderPreToolUseResponse(response);
+        }
+        return computeConflictWarning(raw, deps);
+    }
+    catch {
+        // No failure may escalate into a blocking hook decision.
+        return renderPreToolUseResponse(exports.PRETOOL_PASS_THROUGH);
+    }
+    finally {
+        if (ownsStore && store) {
+            try {
+                (0, ce0_store_1.closeCe0Store)(store);
+            }
+            catch {
+                // Closing the store must never affect the (already computed) decision.
+            }
+        }
+    }
+}
+/**
+ * The SOFT cross-session conflict warning layer. Runs only after the notes path
+ * passes through (a notes deny already returned). Parses the session id from the raw
+ * stdin, reads the session's zero-network open-conflict snapshot, and warns when one
+ * is open. Fails OPEN to the pass-through on a missing session id, an empty or stale
+ * snapshot, or ANY error: the warning is advisory, so silence is always the safe
+ * direction. Synchronous (the snapshot read is a local file read, no network).
+ *
+ * The matcher pins this hook to Write|Edit, so the warning fires immediately before a
+ * file mutation, the highest-value moment to interrupt work built on a contested
+ * assumption. The turn-level open-time steer (§11.1) is the complementary channel that
+ * reaches the agent regardless of which tool runs; this decision function is itself
+ * tool-agnostic, so broadening the matcher later needs no change here.
+ */
+function computeConflictWarning(raw, deps) {
+    try {
+        const sessionId = (0, observe_adapter_1.parsePreToolUseInput)(raw)?.session_id;
+        if (!sessionId)
+            return renderPreToolUseResponse(exports.PRETOOL_PASS_THROUGH);
+        const readConflicts = deps.readConflicts ?? ((sid) => (0, active_conflict_cache_1.readActiveConflicts)(sid));
+        const conflicts = readConflicts(sessionId);
+        if (conflicts.length === 0)
+            return renderPreToolUseResponse(exports.PRETOOL_PASS_THROUGH);
+        const mode = (deps.resolveGateMode ?? active_conflict_cache_1.resolveConflictGateMode)();
+        return renderConflictWarning(conflicts, mode);
+    }
+    catch {
+        // The conflict warning is advisory; any fault degrades to no warning, never a block.
+        return renderPreToolUseResponse(exports.PRETOOL_PASS_THROUGH);
+    }
+}
+function defaultResolveScope() {
+    const root = (0, runtime_scope_1.resolveActiveRuntimeScopeId)();
+    return { runtimeScopeId: root, runtimeProjectRoot: root };
+}
+function defaultClock() {
+    const now = Date.now();
+    return { now, createdAt: new Date(now).toISOString() };
+}
+/** Read the active workspace's scanned directives from the scan cache (the source of the pilot rule
+ * for the R0 observe substrate). Fails OPEN to none on any error or a missing cache: an unreadable
+ * scan cache must degrade to "no rule observed", never block the hook. */
+function defaultResolveDirectives() {
+    try {
+        const workspaceId = (0, workspace_1.resolveWorkspaceIdWithEnv)();
+        if (!workspaceId)
+            return [];
+        const cache = (0, cache_1.readScanCache)((0, os_1.homedir)(), workspaceId);
+        return cache?.directives ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+// IO shell. Reads stdin best-effort (a read failure still yields the pass-through body so the hook never
+// blocks a tool), computes the decision, writes stdout, returns the exit code (always 0). Takes no argv.
+async function runInternalPretoolObserve(_argv, deps = defaultDeps) {
+    let raw = "";
+    try {
+        raw = await deps.readStdin();
+    }
+    catch {
+        // A stdin read error must never escalate into a blocking hook decision.
+        raw = "";
+    }
+    const out = await computePretoolDecision(raw, deps);
+    deps.writeOut(out.stdout);
+    return out.exitCode;
+}

package/dist/commands/internal-refresh.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRefreshArgs = parseRefreshArgs;
+exports.runInternalRefresh = runInternalRefresh;
+const config_1 = require("../lib/config");
+const http_1 = require("../lib/http");
+// `mla _internal refresh [--quiet] [--if-expiring-within <secs>]` (Part 3, T2).
+//
+// A thin policy wrapper over the existing concurrency-safe `refreshUserToken`
+// (lib/http.ts). It reimplements NOTHING: it reads the config, guards the mode,
+// optionally short-circuits on a comfortably-fresh token, then calls
+// refreshUserToken and maps its RefreshOutcome to a sysexits process exit code
+// the bash hooks branch on with a clean `case "$rc"`.
+//
+// Wire contract (the 75/77/64 numbers are hardcoded in common.sh; keep in sync):
+//   refreshed -> 0   token rotated, adopted from a concurrent winner, or the
+//                    `--if-expiring-within` gate found it comfortably fresh.
+//   busy      -> 75  EX_TEMPFAIL: sidecar lock contended past cap, or transient
+//                    outage. Session untouched; the hook keeps events queued.
+//   expired   -> 77  EX_NOPERM: the refresh token itself is dead server-side.
+//                    The hook surfaces enrichment_unauthorized + "run `mla login`".
+//   wrong mode-> 64  EX_USAGE: shared-key / none / unreadable config / bad args.
+//                    Refresh is meaningless; the hook surfaces a mode message.
+//
+// SECURITY: this command NEVER prints a token. It prints at most a one-line
+// status to stdout (suppressed by --quiet) and a one-line error to stderr.
+const EX_OK = 0;
+const EX_USAGE = 64; // EX_USAGE: wrong mode, unreadable config, or bad args.
+const EX_TEMPFAIL = 75; // EX_TEMPFAIL: busy/transient; retry later.
+const EX_NOPERM = 77; // EX_NOPERM: refresh token dead; re-login required.
+const VALUE_FLAGS = new Set(["--if-expiring-within"]);
+const BOOLEAN_FLAGS = new Set(["--quiet"]);
+// Strict argv parsing, mirroring `mla login`'s VALUE_FLAGS/BOOLEAN_FLAGS shape.
+// `mla _internal refresh` takes no positionals. Throws on any unknown flag,
+// stray positional, missing value, or non-integer --if-expiring-within.
+function parseRefreshArgs(argv) {
+    const out = { quiet: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (VALUE_FLAGS.has(a)) {
+            const v = argv[i + 1];
+            if (v === undefined || v.startsWith("--") || v.startsWith("-")) {
+                throw new Error(`Missing value for ${a}`);
+            }
+            if (a === "--if-expiring-within") {
+                const secs = Number(v);
+                if (!Number.isInteger(secs) || secs < 0) {
+                    throw new Error(`Invalid --if-expiring-within value "${v}": expected a non-negative integer (seconds).`);
+                }
+                out.ifExpiringWithinSecs = secs;
+            }
+            i += 1;
+            continue;
+        }
+        if (BOOLEAN_FLAGS.has(a)) {
+            if (a === "--quiet")
+                out.quiet = true;
+            continue;
+        }
+        if (a.startsWith("--") || a.startsWith("-")) {
+            throw new Error(`Unknown flag: ${a}. Supported flags: ${[...VALUE_FLAGS, ...BOOLEAN_FLAGS].sort().join(", ")}`);
+        }
+        throw new Error(`Unexpected positional argument: ${a}. \`mla _internal refresh\` takes no positionals.`);
+    }
+    return out;
+}
+async function runInternalRefresh(argv, deps = {}) {
+    const refresh = deps.refresh ?? http_1.refreshUserToken;
+    const now = deps.now ?? (() => Date.now());
+    let flags;
+    try {
+        flags = parseRefreshArgs(argv);
+    }
+    catch (e) {
+        console.error(e.message);
+        return EX_USAGE;
+    }
+    // Read config. readConfig throws loudly on a missing/corrupt config or the
+    // Gate-4 env conflict (user-token on disk + MEETLESS_CONTROL_TOKEN). Any of
+    // these means we cannot name a refreshable user session: surface and bail 64.
+    let cfg;
+    try {
+        cfg = (0, config_1.readConfig)();
+    }
+    catch (e) {
+        console.error(e.message);
+        return EX_USAGE;
+    }
+    // Mode guard BEFORE refreshUserToken so we can distinguish "wrong mode" (64)
+    // from "dead refresh token" (77). shared-key and none have no refresh token.
+    if (cfg.auth.mode !== "user-token") {
+        if (cfg.auth.mode === "shared-key") {
+            console.error("This is a shared-key session (no refresh token to rotate). " +
+                "Re-key with `mla init --control-token <T>` if it is invalid.");
+        }
+        else {
+            console.error("Not logged in. Run `mla login` first.");
+        }
+        return EX_USAGE;
+    }
+    // Proactive gate (Part 3 §A): if --if-expiring-within is set and the access
+    // token has MORE than that much runway, no-op with no network call. An
+    // unparseable expiry parses to NaN; we treat that as "cannot prove fresh" and
+    // fall through to a real refresh rather than trust a broken timestamp (same
+    // NaN-safe philosophy as `mla login`).
+    if (flags.ifExpiringWithinSecs !== undefined) {
+        const remainingMs = Date.parse(cfg.auth.accessExpiresAt) - now();
+        const thresholdMs = flags.ifExpiringWithinSecs * 1000;
+        if (!Number.isNaN(remainingMs) && remainingMs > thresholdMs) {
+            if (!flags.quiet) {
+                console.log("Access token still fresh; no refresh needed.");
+            }
+            return EX_OK;
+        }
+    }
+    const outcome = await refresh(cfg);
+    switch (outcome) {
+        case "refreshed":
+            if (!flags.quiet)
+                console.log("Access token refreshed.");
+            return EX_OK;
+        case "busy":
+            console.error("Refresh busy (lock contended or transient outage); will retry later.");
+            return EX_TEMPFAIL;
+        case "expired":
+            console.error("Session expired server-side. Run `mla login`.");
+            return EX_NOPERM;
+        default: {
+            // Exhaustiveness guard: a new RefreshOutcome must be mapped explicitly
+            // rather than silently treated as success.
+            const _never = outcome;
+            console.error(`Unexpected refresh outcome: ${String(_never)}`);
+            return EX_TEMPFAIL;
+        }
+    }
+}