@meetless/mla 0.1.4

package/dist/lib/auth-breaker.js

@@ -0,0 +1,161 @@
+"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.AUTH_BREAKER_PATH = void 0;
+exports.fingerprintToken = fingerprintToken;
+exports.tripAuthBreaker = tripAuthBreaker;
+exports.consultAuthBreaker = consultAuthBreaker;
+exports.clearAuthBreaker = clearAuthBreaker;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const config_1 = require("./config");
+// Dead-auth circuit breaker (incident: a dead `mla login` self-DoSing control).
+//
+// THE PROBLEM. When a user-token session's refresh token is genuinely dead
+// (expired ~30d idle, revoked, or rotated out from under a stale process), every
+// hook-driven `mla` call (heartbeat, steer-sync, flush, _internal refresh) does
+// the same dance: authenticated control call -> 401 -> refresh -> 401 -> surface
+// "login expired". With the editor firing those hooks on every tool use across
+// several long-lived `mla mcp` workers, that became a tight validate+refresh
+// storm against control (measured ~6-8 req/sec on constant hashed keys), i.e. a
+// self-inflicted DoS that no server-side rate limit can cure (the server can only
+// cheapen each rejection, not stop the client from asking).
+//
+// THE CURE. The FIRST process to have its refresh token REJECTED writes a small
+// sentinel here, keyed to a one-way fingerprint of that exact refresh token.
+// Every later user-token control call consults it first (consultAuthBreaker) and
+// fails fast WITHOUT touching control. The flood collapses from "forever" to a
+// bounded burst (one validate+refresh per process until the shared sentinel lands,
+// then silence).
+//
+// WHY FINGERPRINT-KEYED (self-healing). The sentinel records sha256(refreshToken)
+// .slice(0,16), NOT a bare "auth is dead" flag. consult re-reads the ON-DISK
+// config (not the caller's possibly-stale in-memory cfg) and only stays open while
+// the on-disk refresh token still matches the fingerprint. The instant the token
+// changes (an `mla login` writes a fresh pair) the fingerprint no longer matches,
+// consult clears the sentinel and lets the call through. That is what lets a
+// re-login heal the long-lived `mla mcp` workers LIVE: the worker bound its cfg
+// object once at boot, but consult reads disk, sees the new token, and reopens the
+// gate without a restart. Comparing the in-memory token instead would wedge the
+// worker forever (it would never observe the re-login).
+//
+// WHY THIS LEAKS NOTHING. The fingerprint is a one-way sha256 slice; it cannot be
+// reversed to a token, and the file lives right next to cli-config.json (which
+// holds the actual tokens, mode 0600) anyway.
+// Sibling of CFG_PATH (config.ts), so it shares the config's home and is wiped by
+// the same `rm -rf ~/.meetless` an operator already uses to reset.
+exports.AUTH_BREAKER_PATH = `${config_1.HOME}/auth-dead.json`;
+// One-way, non-reversible. Same construction as control's hashToken prefix and
+// http.ts's rate-limit keys, so the value is recognizable in logs without
+// exposing token material.
+function fingerprintToken(token) {
+    return crypto.createHash("sha256").update(token).digest("hex").slice(0, 16);
+}
+// Trip the breaker for a specific refresh token that control just REJECTED. Only
+// http.ts's refreshUserToken calls this, and only on a true "unauthorized"
+// (401/410) outcome, never on a transient/throttled one, so the gate can never
+// close on a mere rate-limit burst. Best-effort: a write failure just means the
+// next process re-attempts the dance and trips it then.
+function tripAuthBreaker(refreshToken, reason) {
+    const sentinel = {
+        refreshFingerprint: fingerprintToken(refreshToken),
+        deadSince: new Date().toISOString(),
+        reason,
+    };
+    try {
+        // Write-then-rename so a concurrent reader never sees a torn file (5 workers
+        // + N hooks share this path).
+        const tmp = `${exports.AUTH_BREAKER_PATH}.tmp.${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify(sentinel) + "\n", { mode: 0o600 });
+        fs.renameSync(tmp, exports.AUTH_BREAKER_PATH);
+    }
+    catch {
+        // Best-effort sentinel; never let a breaker write break the caller.
+    }
+}
+// Returns true iff the breaker is OPEN: a prior refresh was rejected AND the
+// on-disk refresh token still matches that rejection's fingerprint. Fails OPEN
+// (returns true) for nothing: every uncertain path fails CLOSED (returns false,
+// let the call proceed) so a bug here can never wedge a healthy session. Clears a
+// stale sentinel as a side effect when the on-disk credential has moved on.
+function consultAuthBreaker() {
+    let raw;
+    try {
+        raw = fs.readFileSync(exports.AUTH_BREAKER_PATH, "utf8");
+    }
+    catch {
+        return false; // No sentinel (the common, healthy case) -> proceed.
+    }
+    let sentinel;
+    try {
+        sentinel = JSON.parse(raw);
+    }
+    catch {
+        return false; // Torn/garbage read (concurrent writer) -> proceed, don't block.
+    }
+    if (!sentinel || typeof sentinel.refreshFingerprint !== "string") {
+        return false;
+    }
+    // Compare against the ON-DISK token, not the caller's in-memory cfg, so a
+    // re-login that rotated the token on disk reopens the gate for live workers.
+    let cfg;
+    try {
+        cfg = (0, config_1.readConfig)();
+    }
+    catch {
+        return false; // Config unreadable -> fail open, never block on our own read.
+    }
+    if (cfg.auth.mode !== "user-token") {
+        // Logged out / downgraded to shared-key: the dead user-token is irrelevant.
+        clearAuthBreaker();
+        return false;
+    }
+    if (fingerprintToken(cfg.auth.refreshToken) === sentinel.refreshFingerprint) {
+        return true; // Same dead token still on disk -> gate stays shut.
+    }
+    // The on-disk token changed (a re-login happened): the sentinel is stale.
+    clearAuthBreaker();
+    return false;
+}
+// Clear the breaker. Called on a successful login/refresh and on the stale-token
+// path above. Idempotent and best-effort.
+function clearAuthBreaker() {
+    try {
+        fs.unlinkSync(exports.AUTH_BREAKER_PATH);
+    }
+    catch {
+        // Already gone (never tripped, or another process cleared it first).
+    }
+}

package/dist/lib/auto-index.js

@@ -0,0 +1,112 @@
+"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.selectIndexTargets = selectIndexTargets;
+exports.buildKbAddArgv = buildKbAddArgv;
+// tools/meetless-agent/src/lib/auto-index.ts
+// Pure selection + argv construction for the Zone 2 auto-index loop. Given the
+// reduced Active Review records for a session, pick the produced docs to index
+// into the owner's Personal KB and build the `mla kb add` argv for each. No I/O;
+// the command layer (internal-auto-index.ts) owns the store read, the on-disk
+// existence check, and the (fail-soft) add invocation.
+// See notes/20260605-mla-auto-index-loop-implementation-plan.md.
+const path = __importStar(require("path"));
+const observability_1 = require("./observability");
+// One target per (repoRootHash, canonicalPath). Only produced_doc records that
+// carry a repoRoot are eligible: tagged_reference docs are user-named, not
+// agent-produced, and a record without a repoRoot predates Phase A and cannot be
+// resolved on disk. reduceActiveMemory yields records most-recent-last, so a later
+// record overwrites an earlier one for the same key -> latest content wins.
+function selectIndexTargets(records) {
+    const latest = new Map();
+    for (const r of records) {
+        if (r.kind !== "produced_doc")
+            continue;
+        if (!r.repoRoot || r.repoRoot.length === 0)
+            continue;
+        latest.set(`${r.repoRootHash}|${r.canonicalPath}`, r);
+    }
+    return Array.from(latest.values()).map((r) => ({
+        absPath: path.join(r.repoRoot, r.canonicalPath),
+        workspaceId: r.workspaceId,
+        canonicalPath: r.canonicalPath,
+        contentHash: r.contentHash,
+    }));
+}
+// The Zone 2 personal-KB add contract: agent_distilled provenance (ADVISORY echo
+// under the two-axis model; the server derives recorded trust from the capture
+// path), workspace pinned from the record (NOT marker-resolved, since the detached
+// run has cwd=$HOME), and --queue so the add returns after the revision commits
+// without blocking on the async GRAPH_EXTRACT job.
+//
+// NO --posture: commit e7f20756 removed the --posture contract from `mla kb add`
+// (every notes ingest is born reviewOutcome=PENDING; LIVE/SHADOW posture is dead).
+// `mla kb add` now REJECTS --posture as an unknown flag, so emitting it here made
+// every auto-index ingest fail ("Unknown flag: --posture") -- session files were
+// recorded but never ingested or mined for relationships. Keep this argv in lockstep
+// with kb_add.ts's VALUE_FLAGS/BOOLEAN_FLAGS.
+//
+// --reingest-if-active makes this an add-or-UPDATE. Without it, a doc the agent
+// produced once is ACTIVE in the KB, and every later edit re-runs `kb add` over an
+// ACTIVE identity, which the kb add route hard-refuses ("use mla kb reingest"). The
+// loop swallows that exit-2 as a failure, so a re-edited doc silently never accrues
+// a second revision. With the flag, a changed body reingests in place (new revision)
+// and a frontmatter-only change patches; an unchanged doc still no-ops.
+function buildKbAddArgv(t, sessionId) {
+    const argv = [
+        t.absPath,
+        "--mode",
+        "file",
+        "--provenance",
+        "agent_distilled",
+        "--workspace",
+        t.workspaceId,
+        "--queue",
+        "--reingest-if-active",
+    ];
+    // Channel B (sync ingest): carry THIS session's raw Claude UUID through to the
+    // intel ingest route as `--agent-session <uuid>` (it rides the kb add HTTP body)
+    // so the workspace-authoritative sink composes the Langfuse session exactly once
+    // (INV-COMPOSE-ONCE). The value is canonicalized here (trim, uuid-shape, lowercase)
+    // but NEVER composed; an absent or malformed session simply omits the flag and the
+    // ingest still runs (intel falls back to its own grouping). No env var is read: the
+    // detached auto-index process has a bare environment, so the session arrives
+    // explicitly on its `--session` wire.
+    const agentSession = (0, observability_1.canonicalizeSessionId)(sessionId ?? null);
+    if (agentSession) {
+        argv.push("--agent-session", agentSession);
+    }
+    return argv;
+}

package/dist/lib/classifier.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * File-path risk classifier.
+ *
+ * Maps a repository file path to a coarse risk category so an automated code
+ * reviewer can state deterministic pre-prompt facts ("this change touches
+ * auth", "this is a schema migration") before the LLM reasons about the diff.
+ *
+ * This is a generic, config-driven utility: it ships a DEFAULT_RULES ruleset
+ * built from COMMON repository conventions (a Prisma schema, a `migrations/`
+ * dir, an `auth`/`authz` dir, `webhooks`/`integrations`, a `prompts/` dir of
+ * YAML, an `outbox`/`handlers` dir, NestJS-style `*.controller.ts` / `*.dto.ts`
+ * or an `api/` dir, shell scripts and a `tools/` dir, docs). None of the rules
+ * encode any one repo's internal service map; point `classify` at your own
+ * ruleset (or extend DEFAULT_RULES) to fit a differently-structured codebase.
+ *
+ * Ordering is load-bearing. First match wins. Narrow rules come before broad
+ * rules (e.g. `*.controller.ts` before a bare `api/` dir).
+ *
+ * The ruleset is pinned by a VERSIONED fixture (`fixtures/risk-classifier.fixture.json`,
+ * `version: 1`) and a drift test (`test/lib/classifier.spec.ts`): every fixture
+ * case must classify to its declared category, the fixture's declared taxonomy
+ * must equal ALL_CATEGORIES, and every non-`unknown` category must be exercised.
+ * Adding or changing a rule therefore forces a matching fixture update (and, on
+ * a taxonomy change, a version bump).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RULES = exports.ALL_CATEGORIES = void 0;
+exports.classify = classify;
+exports.classifyMany = classifyMany;
+// Runtime list of every category. The drift test asserts the fixture's declared
+// taxonomy equals this set, so the type and the fixture cannot drift apart.
+exports.ALL_CATEGORIES = [
+    "schema_or_migration",
+    "auth_or_permission",
+    "external_integration",
+    "llm_prompt",
+    "outbox_or_handler",
+    "api_contract",
+    "cli_or_tooling",
+    "docs",
+    "unknown",
+];
+const _categoryCompletenessCheck = true;
+void _categoryCompletenessCheck;
+// Generic default ruleset. Patterns are prefix-agnostic ((^|\/) anchors a path
+// segment whether it is at the repo root or nested), so the same rule matches
+// `auth/x.ts`, `src/auth/x.ts`, and `packages/api/src/auth/x.ts`.
+exports.DEFAULT_RULES = [
+    { pattern: /(^|\/)prisma\/schema\.prisma$/, category: "schema_or_migration" },
+    { pattern: /(^|\/)migrations?\//, category: "schema_or_migration" },
+    { pattern: /(^|\/)(auth|authz)\//, category: "auth_or_permission" },
+    { pattern: /(^|\/)(webhooks?|integrations?)\//, category: "external_integration" },
+    { pattern: /(^|\/)prompts\/.*\.ya?ml$/, category: "llm_prompt" },
+    { pattern: /(^|\/)(outbox|handlers?)\//, category: "outbox_or_handler" },
+    { pattern: /\.(controller|dto)\.ts$/, category: "api_contract" },
+    { pattern: /(^|\/)api\//, category: "api_contract" },
+    { pattern: /(^|\/)tools\//, category: "cli_or_tooling" },
+    { pattern: /\.sh$/, category: "cli_or_tooling" },
+    { pattern: /(^|\/)docs\//, category: "docs" },
+    { pattern: /\.md$/, category: "docs" },
+];
+function normalize(path) {
+    let p = path.replace(/\\/g, "/");
+    while (p.startsWith("./") || p.startsWith(".\\")) {
+        p = p.slice(2);
+    }
+    while (p.startsWith("/")) {
+        p = p.slice(1);
+    }
+    return p;
+}
+function classify(path, rules = exports.DEFAULT_RULES) {
+    if (!path)
+        return "unknown";
+    const normalized = normalize(path);
+    for (const rule of rules) {
+        if (rule.pattern.test(normalized))
+            return rule.category;
+    }
+    return "unknown";
+}
+function classifyMany(paths, rules = exports.DEFAULT_RULES) {
+    const out = {};
+    for (const p of paths)
+        out[p] = classify(p, rules);
+    return out;
+}

package/dist/lib/config.js

@@ -0,0 +1,298 @@
+"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.SESSION_GATE_DIR = exports.HOOKS_DIR = exports.QUEUE_DIR = exports.CFG_PATH = exports.HOME = exports.DEFAULT_CONSOLE_URL = exports.DEFAULT_INTEL_URL = exports.DEFAULT_CONTROL_URL = void 0;
+exports.getConsoleUrl = getConsoleUrl;
+exports.telemetryDisabled = telemetryDisabled;
+exports.readConfig = readConfig;
+exports.loadWorkspaceConfig = loadWorkspaceConfig;
+exports.readKbConfig = readKbConfig;
+exports.writeConfig = writeConfig;
+exports.configExists = configExists;
+exports.readUpdateConfig = readUpdateConfig;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const workspace_1 = require("./workspace");
+// Hosted prod defaults. A freshly-installed `mla` reaches the Meetless
+// production backend out of the box with zero flags. Override to staging or
+// local with the MEETLESS_BACKEND_URL / MEETLESS_INTEL_URL / MEETLESS_CONSOLE_URL
+// env vars (or the matching cli-config.json fields), which always win over these.
+exports.DEFAULT_CONTROL_URL = "https://control.meetless.ai";
+exports.DEFAULT_INTEL_URL = "https://intel.meetless.ai";
+exports.DEFAULT_CONSOLE_URL = "https://app.meetless.ai";
+// Strip trailing slash so callers can always concatenate `${base}/relationships/<id>`
+// without producing a `//` in the URL.
+function getConsoleUrl(cfg) {
+    const raw = process.env.MEETLESS_CONSOLE_URL || cfg.consoleUrl || exports.DEFAULT_CONSOLE_URL;
+    return raw.replace(/\/+$/, "");
+}
+exports.HOME = process.env.MEETLESS_HOME || path.join(os.homedir(), ".meetless");
+exports.CFG_PATH = path.join(exports.HOME, "cli-config.json");
+exports.QUEUE_DIR = path.join(exports.HOME, "queue");
+exports.HOOKS_DIR = path.join(exports.HOME, "hooks");
+// Per-session OFF sentinels (`<sid>.off`) written by `mla mute` (removed by
+// `mla unmute`) and read by meetless_session_disabled in common.sh. This is the
+// per-session capture lifecycle, distinct from the `.meetless.json` workspace
+// binding that `mla activate` / `mla deactivate` manage. Must match
+// SESSION_GATE_DIR in common.sh.
+exports.SESSION_GATE_DIR = path.join(exports.HOME, "session-gate");
+// The master telemetry kill switch. The single source of truth for "no telemetry
+// of any kind leaves (or, for the local deadletter, is even recorded on) this
+// machine." It lives here in low-level config (not in observability.ts) so the
+// trace plane, the analytics-consent gate, the debug command, AND the
+// failure-telemetry deadletter can all share it without an import cycle.
+// observability.ts re-exports it for back-compat. MEETLESS_TELEMETRY in
+// {off,0,false,no} hard-disables; a truthy MEETLESS_NO_TELEMETRY does the same.
+// An unset MEETLESS_TELEMETRY is NOT disabled here: per-plane opt-IN (analytics
+// forwarding) is enforced at the forwarding sites, not by this hard switch.
+function telemetryDisabled(env = process.env) {
+    const t = (env.MEETLESS_TELEMETRY || "").trim().toLowerCase();
+    if (t === "off" || t === "0" || t === "false" || t === "no")
+        return true;
+    const no = (env.MEETLESS_NO_TELEMETRY || "").trim().toLowerCase();
+    if (no && no !== "0" && no !== "false" && no !== "no")
+        return true;
+    return false;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+// Normalize the optional on-disk `update` object into a UpdateConfig, or
+// undefined when absent/empty so OnDiskConfig omits it (no defaults written to
+// disk). autoApply is strictly boolean-true to opt in; anything else stays
+// nag-only. channel falls back to "stable". Returns undefined when neither field
+// is meaningfully set, so a bare `{}` does not get persisted back.
+function normalizeUpdate(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const o = value;
+    const channel = asString(o.channel);
+    const autoApply = o.autoApply === true;
+    if (!autoApply && !channel)
+        return undefined;
+    return { autoApply, channel: channel ?? "stable" };
+}
+// Normalize a parsed user-token-shaped object (either `auth: {mode:'user-token'}`
+// or a legacy expanded top-level) into the CliAuth user-token variant. Throws if
+// the access token is absent: a user-token config with no bearer is corrupt and
+// must fail loud, not silently degrade.
+function normalizeUserToken(src) {
+    const accessToken = asString(src.accessToken);
+    if (!accessToken) {
+        throw new Error(`cli-config.json at ${exports.CFG_PATH} has auth.mode 'user-token' but no access token. ` +
+            "The login is corrupt. Run `mla logout` then `mla login`, or " +
+            "`mla init --control-token <T>` to fall back to shared-key.");
+    }
+    const user = src.user ?? {};
+    return {
+        mode: "user-token",
+        accessToken,
+        refreshToken: asString(src.refreshToken) ?? "",
+        accessExpiresAt: asString(src.accessExpiresAt) ?? "",
+        refreshExpiresAt: asString(src.refreshExpiresAt) ?? "",
+        sessionId: asString(src.sessionId) ?? "",
+        user: {
+            id: asString(user.id) ?? "",
+            displayName: asString(user.displayName) ?? "",
+            email: typeof user.email === "string" ? user.email : null,
+            role: asString(user.role) ?? "",
+        },
+    };
+}
+// The §6.4 compat shim: collapse the three accepted on-disk shapes into one
+// CliAuth. (1) new nested `auth`; (2) legacy shared-key (top-level controlToken,
+// no refresh); (3) legacy expanded user-token (top-level controlToken + refresh
+// + authMode==='user-token'); absent everything => 'none'.
+function normalizeAuthFromDisk(cfg) {
+    // (1) New nested shape wins when present and well-formed.
+    if (cfg.auth !== null && typeof cfg.auth === "object") {
+        const a = cfg.auth;
+        if (a.mode === "none")
+            return { mode: "none" };
+        if (a.mode === "shared-key") {
+            const accessToken = asString(a.accessToken);
+            if (accessToken)
+                return { mode: "shared-key", accessToken };
+            // shared-key with no token is meaningless; treat as logged out.
+            return { mode: "none" };
+        }
+        if (a.mode === "user-token") {
+            return normalizeUserToken(a);
+        }
+        // Unknown mode: fail loud rather than guess a credential path.
+        throw new Error(`cli-config.json at ${exports.CFG_PATH} has an unrecognized auth.mode. ` +
+            "Run `mla logout` then `mla login`, or `mla init --control-token <T>`.");
+    }
+    // (2)/(3) Legacy top-level controlToken.
+    const legacyToken = asString(cfg.controlToken);
+    if (legacyToken) {
+        if (asString(cfg.refreshToken) && cfg.authMode === "user-token") {
+            return normalizeUserToken({ ...cfg, accessToken: legacyToken });
+        }
+        return { mode: "shared-key", accessToken: legacyToken };
+    }
+    // Nothing on disk => terminal logged-out state.
+    return { mode: "none" };
+}
+function readConfig() {
+    if (!fs.existsSync(exports.CFG_PATH)) {
+        throw new Error(`cli-config.json not found at ${exports.CFG_PATH}. Run 'mla init' first.`);
+    }
+    const raw = fs.readFileSync(exports.CFG_PATH, "utf8");
+    const cfg = JSON.parse(raw);
+    // Non-credential env aliases select WHICH control plane, not WHO you are, so
+    // they are honored in every auth mode (CI / containers). MEETLESS_INTEL_ROOT
+    // is handled separately in the intel-root resolver.
+    const controlUrl = process.env.MEETLESS_BACKEND_URL || cfg.controlUrl || exports.DEFAULT_CONTROL_URL;
+    const intelUrl = process.env.MEETLESS_INTEL_URL || cfg.intelUrl || exports.DEFAULT_INTEL_URL;
+    const diskAuth = normalizeAuthFromDisk(cfg);
+    // §0.01 clause 4 / Finding H: under an on-disk user-token, MEETLESS_CONTROL_TOKEN
+    // is REJECTED loudly, never silently honored. Falling back to shared-key here
+    // would mis-attribute the operator's audited actions to INTERNAL_API_KEY.
+    const envSharedKey = process.env.MEETLESS_CONTROL_TOKEN;
+    let auth;
+    if (diskAuth.mode === "user-token" && envSharedKey) {
+        throw new Error(`MEETLESS_CONTROL_TOKEN is set but you are logged in as ${diskAuth.user.displayName}.\n` +
+            "Unset it (`unset MEETLESS_CONTROL_TOKEN`) or run `mla logout` first.");
+    }
+    else if (envSharedKey) {
+        // Env-driven shared key overrides a shared-key / none on-disk state (the
+        // documented CI / container path). It never silently overrides user-token
+        // (handled above).
+        auth = { mode: "shared-key", accessToken: envSharedKey };
+    }
+    else {
+        auth = diskAuth;
+    }
+    // workspaceId is intentionally NOT resolved here (folder = workspace, T1.1);
+    // loadWorkspaceConfig / readKbConfig add it from the `.meetless.json` marker.
+    // controlUrl/intelUrl always resolve (hosted prod default is the final
+    // fallback above), so there is no missing-config branch to guard here.
+    // actorUserId: pinned to auth.user.id under user-token (P3, so the actor
+    // header and session identity can never disagree); otherwise the preserved
+    // top-level value (migrated across the rewrite, Finding G).
+    const actorUserId = auth.mode === "user-token" ? auth.user.id : asString(cfg.actorUserId);
+    // Derived controlToken: the bearer for shared-key / user-token; empty for
+    // 'none' (a none-mode request fails fast at the http layer, §6.5).
+    const controlToken = auth.mode === "none" ? "" : auth.accessToken;
+    return {
+        controlUrl,
+        controlToken,
+        intelUrl,
+        mlaPath: cfg.mlaPath || "",
+        intelRoot: cfg.intelRoot,
+        consoleUrl: cfg.consoleUrl,
+        actorUserId,
+        update: normalizeUpdate(cfg.update),
+        auth,
+    };
+}
+// Load the machine config AND resolve the active workspace from the nearest
+// `.meetless.json` marker (folder = workspace, T1.1). This is the single entry
+// point every workspace-scoped command uses instead of readConfig(): it threads
+// the marker-resolved id onto cfg.workspaceId so existing `cfg.workspaceId`
+// call sites keep working, now sourced from the marker rather than cli-config.
+//
+// `override` is the admin `--workspace <id>` escape hatch (KB ops against
+// another workspace): when provided and non-empty it short-circuits marker
+// resolution, so the command never throws NotActivatedError just because the
+// operator is acting cross-workspace from an unbound directory. When absent,
+// resolveWorkspaceId() walks up from cwd and throws a clean "not activated"
+// error if no marker is found.
+function loadWorkspaceConfig(override) {
+    const cfg = readConfig();
+    const workspaceId = (override || "").trim() || (0, workspace_1.resolveWorkspaceId)();
+    return { ...cfg, workspaceId };
+}
+// KB curation loader: resolves the workspace from the marker (via
+// loadWorkspaceConfig, honoring the optional `--workspace` admin override) AND
+// enforces an actorUserId. `workspaceId` is therefore marker-sourced just like
+// every other workspace-scoped command; cli-config is never consulted for it.
+function readKbConfig(override) {
+    const cfg = loadWorkspaceConfig(override);
+    const actor = (cfg.actorUserId || "").trim();
+    if (!actor) {
+        throw new Error(`cli-config.json is missing required field 'actorUserId'. ` +
+            `KB curation commands stamp this onto every outbox event so the ` +
+            `audit trail records who acted. Re-run 'mla init --actor <id>' ` +
+            `or edit ${exports.CFG_PATH} directly to add it.`);
+    }
+    return { ...cfg, actorUserId: actor };
+}
+function writeConfig(cfg) {
+    fs.mkdirSync(exports.HOME, { recursive: true });
+    fs.mkdirSync(exports.QUEUE_DIR, { recursive: true });
+    fs.mkdirSync(exports.HOOKS_DIR, { recursive: true });
+    // P3: under a user session the actor is the authenticated user, full stop, so
+    // it can never drift from auth.user.id even if a caller passed a stale value.
+    const actorUserId = cfg.auth.mode === "user-token" ? cfg.auth.user.id : cfg.actorUserId;
+    // Serialize ONLY the canonical fields. `controlToken` is intentionally dropped:
+    // it is a read-time projection of auth.accessToken, persisting it would create
+    // two sources of truth that can silently diverge on the next login/refresh.
+    const onDisk = {
+        controlUrl: cfg.controlUrl,
+        ...(cfg.intelUrl ? { intelUrl: cfg.intelUrl } : {}),
+        ...(cfg.workspaceId ? { workspaceId: cfg.workspaceId } : {}),
+        mlaPath: cfg.mlaPath,
+        ...(cfg.intelRoot ? { intelRoot: cfg.intelRoot } : {}),
+        ...(cfg.consoleUrl ? { consoleUrl: cfg.consoleUrl } : {}),
+        ...(actorUserId ? { actorUserId } : {}),
+        ...(cfg.update ? { update: cfg.update } : {}),
+        auth: cfg.auth,
+    };
+    fs.writeFileSync(exports.CFG_PATH, JSON.stringify(onDisk, null, 2) + "\n", { mode: 0o600 });
+}
+function configExists() {
+    return fs.existsSync(exports.CFG_PATH);
+}
+// Throw-free reader for the self-upgrade hot path. The upgrade machinery (the
+// apply-on-launch promote step and `mla upgrade`) can run BEFORE `mla init`
+// exists, so it must never throw the "run mla init first" error readConfig
+// raises on a missing file. Returns nag-only defaults (autoApply false, channel
+// "stable") on a missing/corrupt/empty config and only enables autoApply when
+// the on-disk `update.autoApply` is exactly true.
+function readUpdateConfig() {
+    const fallback = { autoApply: false, channel: "stable" };
+    try {
+        if (!fs.existsSync(exports.CFG_PATH))
+            return fallback;
+        const raw = JSON.parse(fs.readFileSync(exports.CFG_PATH, "utf8"));
+        return normalizeUpdate(raw.update) ?? fallback;
+    }
+    catch {
+        return fallback;
+    }
+}