@melra/cli 0.3.0-alpha.10 → 0.3.0-alpha.12

package/dist/index.js

@@ -1,19 +1,28 @@
 #!/usr/bin/env node
 // Copyright 2026 XAGI Labs Private Limited
 // SPDX-License-Identifier: Apache-2.0
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { access, lstat, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
 import { spawn } from "node:child_process";
-import { basename, join, resolve } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { DatabaseSync } from "node:sqlite";
-import { ApprovalResponseSchema, TaskRequestSchema, WorkflowDefinitionSchema, WorkflowInputSchema, PRODUCT_VERSION, principalRef, } from "@melra/protocol";
-import { createMelraRuntime, serveHttp, OAuthProvider, clientPrincipal, serveStdio, unconfinedRoot, } from "@melra/server";
+import { ApprovalResponseSchema, TaskRequestSchema, TaskStatusSchema, WorkflowDefinitionSchema, WorkflowInputSchema, PRODUCT_VERSION, deploymentMode, principalRef, } from "@melra/protocol";
+import { assertEnforceable, createMelraRuntime, serveHttp, OAuthProvider, clientPrincipal, serveStdio, unconfinedRoot, } from "@melra/server";
 import { detectBrowserExecutable } from "@melra/browser-runtime";
 import { createSystemComputerAdapter } from "@melra/computer-runtime";
+import { capabilityUsageReader } from "@melra/runtime-core";
+import { SqliteStore } from "@melra/storage-sqlite";
 import { classifyOperation, createDefaultPolicy, evaluatePolicy, loadPolicy, } from "@melra/policy-core";
 import { parseCliEnvironment, serverLaunch, } from "./environment.js";
 import { runConformance } from "./conformance.js";
+import { statusCommand, tasksCommand, watchCommand } from "./activity.js";
+import { clientStatuses, clientsCheck, detectClients } from "./client-status.js";
+import { RESTART_SAFE_WORKFLOW } from "./demo-workflow.js";
+import { detectIsolation, isolationCheck } from "./isolation.js";
+import { renderConformance, renderDoctor, renderInit, renderSetup, setupWizard, } from "./human.js";
+import { isHuman, paint, printJsonOrHuman } from "./output.js";
+import { CLIENTS, clientConfig, clientConfigPath, resolveClient, writeClientConfig, } from "./clients.js";
 async function existingPolicyPath(env) {
     if (env.policyPath !== undefined)
         return env.policyPath;
@@ -27,7 +36,7 @@ async function existingPolicyPath(env) {
     }
 }
 /**
- * The banner unhinged mode prints before it does anything.
+ * The banner unsafe-local mode prints before it does anything.
  *
  * It goes to stderr, which is where it has to go: in `serve` the stdout stream
  * is the MCP transport and any prose written there corrupts the protocol. stderr
@@ -36,11 +45,11 @@ async function existingPolicyPath(env) {
  * developer who exported the variable in one shell and forgot deserves the
  * reminder on every invocation rather than only at startup.
  */
-function unhingedBanner(root) {
+function unsafeLocalBanner(root) {
     return [
         "",
         "  ############################################################",
-        "  #  MELRA IS RUNNING UNHINGED. NO GUARDRAILS ARE APPLIED.   #",
+        "  #  MELRA IS RUNNING UNSAFE-LOCAL. NO GUARDRAILS APPLY.     #",
         "  ############################################################",
         "",
         "  Disabled for every task this process runs:",
@@ -54,7 +63,7 @@ function unhingedBanner(root) {
         "  OS user can. Receipts are still written, so you will be able to read what",
         "  happened — after it has happened.",
         "",
-        "  Turn it off by unsetting MELRA_UNHINGED and dropping --unhinged.",
+        "  Turn it off by unsetting MELRA_UNHINGED and dropping --unsafe-local.",
         "",
     ].join("\n");
 }
@@ -64,6 +73,7 @@ async function runtime(env) {
         workspaceRoot: env.workspaceRoot,
         dataDirectory: env.dataDirectory,
         unhinged: env.unhinged,
+        mode: env.mode,
         ...(policyPath === undefined ? {} : { policyPath }),
         ...(env.browserExecutablePath === undefined
             ? {}
@@ -98,10 +108,17 @@ function argument(name, args) {
  * a terminal prints nothing and in a pipeline that never closes hangs forever.
  */
 function rejectUnknownFlags(args, known) {
-    const allowed = new Set([...known, "--unhinged"]);
+    // Process-wide rather than per-command: these three describe the process, not
+    // what a command does, so every command accepts them.
+    const allowed = new Set([
+        ...known,
+        "--unsafe-local",
+        "--unhinged",
+        "--mode",
+    ]);
     // A flag's own value can look like a flag (`--input node=--x`), so skip the
     // slot after any known flag that takes one.
-    const valued = new Set(known.filter((flag) => flag !== "--http"));
+    const valued = new Set(known.filter((flag) => flag !== "--http" && flag !== "--json"));
     for (let index = 0; index < args.length; index += 1) {
         const argument_ = args[index];
         if (argument_ === undefined || !argument_.startsWith("--"))
@@ -273,14 +290,13 @@ async function workflowCommand(args, env) {
     }
 }
 async function durableCoreDemo(env) {
-    const examplePath = resolve(import.meta.dirname, "../../../examples/workflows/restart-safe.json");
     const melra = await runtime(env);
     try {
-        const definition = WorkflowDefinitionSchema.parse(JSON.parse(await readFile(examplePath, "utf8")));
+        const definition = WorkflowDefinitionSchema.parse(RESTART_SAFE_WORKFLOW);
         const planned = melra.workflows.plan(definition);
         const advanced = await melra.workflows.advance(planned.id);
         output({
-            examplePath,
+            example: definition.name,
             workflow: advanced.run,
             next: advanced.run.status === "verified_complete"
                 ? "complete"
@@ -292,6 +308,54 @@ async function durableCoreDemo(env) {
         await melra.close();
     }
 }
+/**
+ * Whether `MELRA_SOCKET` names somewhere `serve` can listen, and whether a
+ * socket already there is one only this user can open. The mode is the whole
+ * point of the transport, so a wider one is a `fail`, not a `warn`.
+ */
+async function socketCheck(path) {
+    const name = "socket";
+    if (process.platform === "win32") {
+        return {
+            name,
+            status: "fail",
+            detail: "MELRA_SOCKET is not supported on Windows; use stdio or loopback HTTP",
+        };
+    }
+    try {
+        if (!(await stat(dirname(path))).isDirectory())
+            throw new Error("not a directory");
+    }
+    catch {
+        return { name, status: "fail", detail: `parent directory missing: ${dirname(path)}` };
+    }
+    let stats;
+    try {
+        stats = await lstat(path);
+    }
+    catch {
+        return {
+            name,
+            status: "pass",
+            detail: `${path}: not listening; 'melra serve' creates it mode 0600`,
+        };
+    }
+    if (!stats.isSocket()) {
+        return {
+            name,
+            status: "fail",
+            detail: `${path} exists and is not a socket; 'melra serve' will refuse it`,
+        };
+    }
+    const mode = stats.mode & 0o777;
+    return (mode & 0o077) === 0
+        ? { name, status: "pass", detail: `${path}: socket, mode 0${mode.toString(8)}` }
+        : {
+            name,
+            status: "fail",
+            detail: `${path}: socket, mode 0${mode.toString(8)}; other users can connect`,
+        };
+}
 async function doctor(env) {
     const checks = [];
     const major = Number(process.versions.node.split(".")[0]);
@@ -307,9 +371,21 @@ async function doctor(env) {
         ? {
             name: "guardrails",
             status: "warn",
-            detail: "UNHINGED: no policy, approval, evidence, confinement, or destination check is applied",
+            detail: "UNSAFE-LOCAL: no policy, approval, evidence, confinement, or destination check is applied",
         }
-        : { name: "guardrails", status: "pass", detail: "enforced" });
+        // Not "enforced": the next check uses that word for the deployment mode,
+        // and one JSON blob saying `guardrails: enforced` beside `mode: developer`
+        // reads as a contradiction that is not there.
+        : { name: "guardrails", status: "pass", detail: "all applied" });
+    // Not a `fail` either way. Developer mode is a legitimate choice and the
+    // default; what is not legitimate is a machine that cannot say which one it is.
+    checks.push({
+        name: "mode",
+        status: "pass",
+        detail: env.mode === "enforced"
+            ? "enforced: no unsafe-local, loopback or Unix socket only, no client self-registration"
+            : "developer: MELRA governs what it is asked for; the harness may have another path",
+    });
     try {
         await access(env.workspaceRoot, constants.R_OK | constants.W_OK);
         checks.push({
@@ -386,6 +462,11 @@ async function doctor(env) {
             detail: error instanceof Error ? error.message : String(error),
         });
     }
+    if (env.socketPath !== undefined)
+        checks.push(await socketCheck(env.socketPath));
+    checks.push(isolationCheck(await detectIsolation(), env.mode));
+    const clients = await clientStatuses(env.workspaceRoot);
+    checks.push(clientsCheck(clients));
     const failed = checks.some((check) => check.status === "fail");
     return {
         report: {
@@ -395,7 +476,10 @@ async function doctor(env) {
             // Alongside the `guardrails` check so a script does not have to read a
             // detail string to find out whether this machine has any.
             unhinged: env.unhinged,
+            mode: env.mode,
             checks,
+            // Per client, so a script can find a stale pin without parsing `detail`.
+            clients,
         },
         failed,
     };
@@ -409,33 +493,69 @@ async function init(args, env) {
     catch {
         await writeFile(policyPath, `${JSON.stringify(createDefaultPolicy(env.workspaceRoot), null, 2)}\n`, { flag: "wx" });
     }
-    const client = argument("--client", args) ?? "generic";
-    const config = {
-        mcpServers: {
-            melra: {
-                ...serverLaunch(import.meta.dirname, PRODUCT_VERSION),
-                env: {
-                    MELRA_WORKSPACE: env.workspaceRoot,
-                    MELRA_HOME: env.dataDirectory,
-                    MELRA_POLICY: policyPath,
-                },
-            },
+    const client = resolveClient(argument("--client", args) ?? "generic");
+    const label = CLIENTS[client]?.label ?? client;
+    const config = clientConfig(client, {
+        ...serverLaunch(import.meta.dirname, PRODUCT_VERSION),
+        env: {
+            MELRA_WORKSPACE: env.workspaceRoot,
+            MELRA_HOME: env.dataDirectory,
+            MELRA_POLICY: policyPath,
         },
-    };
+    });
+    const configPath = clientConfigPath(client, env.workspaceRoot);
+    if (args.includes("--write")) {
+        if (configPath === undefined) {
+            throw new Error("--write needs a named --client; see 'melra help' for the list");
+        }
+        const { backup, unchanged } = await writeClientConfig(configPath, config, client);
+        const next = CLIENTS[client]?.next ?? `Restart ${label} to load it.`;
+        return {
+            initialized: true,
+            client,
+            policyPath,
+            configPath,
+            written: true,
+            ...(backup === undefined ? {} : { backup }),
+            ...(unchanged === undefined ? {} : { unchanged }),
+            config,
+            note: unchanged
+                ? `${configPath} already has this melra entry; nothing changed. ${next}`
+                : `Added melra to ${configPath}. ${next}`,
+        };
+    }
     return {
         initialized: true,
         client,
         policyPath,
+        ...(configPath === undefined ? {} : { configPath }),
         config,
-        note: `Add the mcpServers.melra entry to ${client}'s MCP configuration.`,
+        note: configPath === undefined
+            ? "Add the mcpServers.melra entry to your client's MCP configuration, " +
+                "or rerun with --client <name> for that client's own format."
+            : `Add this to ${configPath}, or rerun with --write to merge it there for you.`,
     };
 }
 // One command for the whole local setup: write the policy, emit a working
 // client config, and verify the machine can actually run it.
 async function setup(args, env) {
-    const initialized = await init(args, env);
+    let chosen = args;
+    // Only a person at a terminal on both ends is asked. Anything else — a pipe,
+    // a test, `--json` — gets today's non-interactive generic setup unchanged.
+    if (argument("--client", args) === undefined && isHuman(args) && process.stdin.isTTY) {
+        const answer = await setupWizard({ input: process.stdin, output: process.stdout }, detectClients(env.workspaceRoot));
+        if (answer === undefined) {
+            process.stdout.write("\nCancelled; nothing was written.\n");
+            return 130;
+        }
+        process.stdout.write("\n");
+        // The same arguments the person could have typed, so the wizard cannot
+        // drift from what `--client X --write` does.
+        chosen = ["--client", answer.client, ...(answer.write ? ["--write"] : [])];
+    }
+    const initialized = await init(chosen, env);
     const { report, failed } = await doctor(env);
-    output({ ...initialized, ...report });
+    printJsonOrHuman({ ...initialized, ...report }, () => renderSetup(initialized, report), args);
     return failed ? 1 : 0;
 }
 async function runTask(args, env) {
@@ -494,16 +614,26 @@ async function policyTest(args, env) {
     const policy = {
         ...(await loadPolicy(await existingPolicyPath(env), env.workspaceRoot)),
         unhinged: env.unhinged,
+        mode: env.mode,
     };
     const taskId = "00000000-0000-4000-8000-000000000000";
-    // The decision carries effect, risk, and traits; the classification adds the
-    // capability and target it was made against, so a surprising verdict can be
-    // traced to what MELRA thought the request was touching.
-    const { capability, target } = classifyOperation(request.operation);
-    output({
-        ...evaluatePolicy(taskId, request, policy),
-        classified: { capability, target },
-    });
+    // Metered grants are counted from the same database the server draws them
+    // down in, so a preview cannot report a budget as full when it is spent — and
+    // policy refuses a metered grant outright when nothing can count it.
+    const store = new SqliteStore(join(env.dataDirectory, "melra.sqlite"));
+    try {
+        // The decision carries effect, risk, and traits; the classification adds the
+        // capability and target it was made against, so a surprising verdict can be
+        // traced to what MELRA thought the request was touching.
+        const { capability, target } = classifyOperation(request.operation);
+        output({
+            ...evaluatePolicy(taskId, request, policy, capabilityUsageReader(store)),
+            classified: { capability, target },
+        });
+    }
+    finally {
+        store.close();
+    }
 }
 /**
  * The clients an operator has approved over OAuth, and the way to take that
@@ -558,13 +688,17 @@ function help() {
     process.stdout.write(`MELRA ${PRODUCT_VERSION}
 
 Usage:
-  melra setup [--client <claude|cursor|vscode|codex|generic>]
-  melra doctor
+  melra setup [--client <name>] [--write] [--json]
+  melra doctor [--json]
   melra conformance [--url <mcp-url> --token <token>] [--level <1|2|3>]
-  melra init --client <claude|cursor|vscode|codex|generic>
+  melra init [--client <name>] [--write] [--json]
   melra serve [--http] [--port <port>] [--open]
+  melra serve --socket <path>
   melra run --request <task.json>
   melra inspect <task-id>
+  melra tasks [--limit <n>] [--status <status>] [--json]
+  melra watch [--json]
+  melra status [--json]
   melra workflow plan --definition <workflow.json>
   melra workflow advance <workflow-id> [--approval <id>:<exact-phrase>]
                                        [--input <node-id>=<value>]
@@ -574,28 +708,56 @@ Usage:
   melra demo durable-core
   melra clients [--revoke <client-id|all>]
   melra policy test --request <task.json>
-  melra version
+  melra version [--json]
+
+In a terminal, doctor, setup, init, and version print a readable report, and
+'melra setup' with no --client asks which detected client to set up. Piped or
+captured, they print JSON (version: the bare number), exactly as before.
 
 Flags:
-  --unhinged       Run with no policy and no guardrails. Everything the OS user
+  --json           Print JSON even in a terminal, and never ask a question.
+  --client <name>  Emit the MCP config in this client's own format and say
+                   where it goes: claude-code (or claude), claude-desktop,
+                   cursor, vscode, windsurf, codex, gemini, zed, cline,
+                   opencode, kiro, goose, continue, amp, openclaw, hermes,
+                   copilot, qwen, auggie, warp, junie, droid, kimi, kilo,
+                   lmstudio, or generic (default).
+  --write          With --client, merge the config into that client's file,
+                   keeping everything else and saving the old file as .bak.
+  --unsafe-local   Run with no policy and no guardrails. Everything the OS user
                    can do, any caller can now do. Same as MELRA_UNHINGED=1.
+                   Refused outright when --mode enforced. Was --unhinged, which
+                   still works and warns.
+  --mode <m>       developer (default) or enforced. Enforced is you asserting
+                   the harness has no other path to these systems: MELRA then
+                   refuses --unsafe-local, refuses any bind off loopback, and
+                   admits no self-registering client. Stamped on every receipt.
   --http           Serve MCP over loopback HTTP instead of stdio, alongside a
                    read-only REST API, a workflow event stream, and the console.
                    Prints a bearer token; every request must carry it.
   --port <port>    HTTP port (default: 7457, or MELRA_HTTP_PORT).
+  --socket <path>  Serve what --http serves on a Unix socket created mode 0600,
+                   so only this OS user can connect; the token is still
+                   required. Not on Windows. Same as MELRA_SOCKET.
   --open           Open the console in your browser once it is listening.
   --url <mcp-url>  Endpoint for 'conformance'. Default: spawn 'melra serve'.
   --level <1|2|3>  Conformance level being claimed (default: 3). The run exits
                    non-zero if the endpoint falls short of it.
+  --json           For tasks, watch, and status: JSON (NDJSON for watch) even
+                   in a terminal. Output that is not a terminal is JSON anyway.
+  --limit <n>      How many recent tasks 'tasks' lists (default: 20, max 500).
+  --status <s>     Only tasks in this status, e.g. awaiting_approval.
 
 Environment:
   MELRA_WORKSPACE  Workspace boundary (default: current directory)
   MELRA_HOME       Local database and artifact directory
   MELRA_POLICY     Optional local policy JSON
-  MELRA_UNHINGED   Set to 1 to disable every guardrail (see --unhinged)
+  MELRA_UNHINGED   Set to 1 to disable every guardrail (see --unsafe-local)
+  MELRA_MODE       developer (default) or enforced (see --mode)
   MELRA_HTTP_PORT  Port for 'serve --http' (default: 7457)
   MELRA_HTTP_TOKEN Fixed bearer token for 'serve --http' (default: random)
   MELRA_HTTP_OAUTH Set to 0 so only that token gets in; no client can register
+  MELRA_SOCKET     Unix socket path for 'serve' instead of stdio (see --socket)
   MELRA_BROWSER    Optional Chrome/Chromium/Edge executable
   MELRA_BROWSER_CDP_ENDPOINT       Optional HTTP(S) CDP endpoint
   MELRA_BROWSER_CDP_CONTEXT_INDEX  External context index (-1 is last)
@@ -607,27 +769,41 @@ Environment:
 async function main() {
     const [command = "help", ...args] = process.argv.slice(2);
     const parsed = parseCliEnvironment(process.env);
-    // `--unhinged` is an alias for the variable, not a second setting: one field
-    // carries the answer so no code path can consult the weaker of the two.
-    const env = args.includes("--unhinged")
-        ? { ...parsed, unhinged: true }
-        : parsed;
+    // `--unsafe-local` is an alias for the variable, not a second setting: one
+    // field carries the answer so no code path can consult the weaker of the two.
+    // `--unhinged` was the original name and still works — it undersold what it
+    // does, being a mood rather than a description, so it says so and moves on.
+    const deprecated = args.includes("--unhinged");
+    if (deprecated) {
+        process.stderr.write("melra: --unhinged is deprecated; use --unsafe-local. It is not a mood, " +
+            "it is an opt-out of the entire safety model.\n");
+    }
+    const modeFlag = argument("--mode", args);
+    const env = {
+        ...parsed,
+        unhinged: parsed.unhinged || deprecated || args.includes("--unsafe-local"),
+        ...(modeFlag === undefined ? {} : { mode: deploymentMode(modeFlag) }),
+    };
+    // Before the banner: a process that refuses to start has no guardrails to warn
+    // about, and printing the unsafe-local warning first would read as if it had
+    // taken effect.
+    assertEnforceable(env.mode, env.unhinged);
     // Before the command runs, and for every command including `help` — the mode
     // is a property of the process, so there is no invocation where staying quiet
     // about it is right.
     if (env.unhinged) {
-        process.stderr.write(`${unhingedBanner(unconfinedRoot(env.workspaceRoot))}\n`);
+        process.stderr.write(`${unsafeLocalBanner(unconfinedRoot(env.workspaceRoot))}\n`);
     }
     switch (command) {
         case "doctor": {
-            rejectUnknownFlags(args, []);
+            rejectUnknownFlags(args, ["--json"]);
             const { report, failed } = await doctor(env);
-            output(report);
+            printJsonOrHuman(report, renderDoctor, args);
             process.exitCode = failed ? 1 : 0;
             return;
         }
         case "conformance": {
-            rejectUnknownFlags(args, ["--url", "--token", "--level"]);
+            rejectUnknownFlags(args, ["--url", "--token", "--level", "--json"]);
             const level = argument("--level", args);
             if (level !== undefined && !["1", "2", "3"].includes(level)) {
                 throw new Error("--level must be 1, 2, or 3");
@@ -639,33 +815,63 @@ async function main() {
                 ...(token === undefined ? {} : { token }),
                 ...(level === undefined ? {} : { claim: Number(level) }),
             });
-            output(report);
+            printJsonOrHuman(report, renderConformance, args);
             process.exitCode = failed ? 1 : 0;
             return;
         }
         case "init":
-            rejectUnknownFlags(args, ["--client"]);
-            output(await init(args, env));
+            rejectUnknownFlags(args, ["--client", "--write", "--json"]);
+            printJsonOrHuman(await init(args, env), renderInit, args);
             return;
         case "setup":
-            rejectUnknownFlags(args, ["--client"]);
+            rejectUnknownFlags(args, ["--client", "--write", "--json"]);
             process.exitCode = await setup(args, env);
             return;
         case "serve": {
-            rejectUnknownFlags(args, ["--http", "--port", "--open"]);
-            const melra = await runtime(env);
+            rejectUnknownFlags(args, ["--http", "--port", "--open", "--socket"]);
+            if (args.includes("--socket") && argument("--socket", args) === undefined) {
+                throw new Error("--socket requires a path");
+            }
+            const socketPath = argument("--socket", args) ?? env.socketPath;
             const http = args.includes("--http");
             const port = argument("--port", args);
-            const server = http
-                ? undefined
-                : await serveStdio(melra);
-            const endpoint = http
-                ? await serveHttp({
-                    runtime: melra,
-                    ...(port === undefined ? {} : { port: Number(port) }),
-                })
-                : undefined;
-            if (endpoint !== undefined) {
+            // One transport per process. Quietly preferring one would leave an
+            // operator believing they had the other — and the difference between a
+            // socket only they can open and a port anyone local can is the point.
+            if (socketPath !== undefined &&
+                (http || port !== undefined || args.includes("--open"))) {
+                throw new Error("--socket (or MELRA_SOCKET) replaces --http, --port, and --open; pass one transport");
+            }
+            const melra = await runtime(env);
+            const server = http || socketPath !== undefined ? undefined : await serveStdio(melra);
+            const endpoint = socketPath !== undefined
+                ? await serveHttp({ runtime: melra, socketPath })
+                : http
+                    ? await serveHttp({
+                        runtime: melra,
+                        ...(port === undefined ? {} : { port: Number(port) }),
+                    })
+                    : undefined;
+            if (endpoint?.socketPath !== undefined) {
+                // An exported MELRA_SOCKET also reaches every stdio client spawned from
+                // that shell, which then waits forever for JSON-RPC on stdout. Name the
+                // variable where those clients log stderr, so the hang has a cause.
+                if (argument("--socket", args) === undefined) {
+                    process.stderr.write(`melra: MELRA_SOCKET is set, so 'serve' is on the socket below, not stdio.\n` +
+                        `  An MCP client that started this process will get no reply; unset\n` +
+                        `  MELRA_SOCKET for it, or pass --socket explicitly when you mean it.\n`);
+                }
+                process.stderr.write(`MELRA server listening on Unix socket ${endpoint.socketPath} (mode 0600)\n` +
+                    `  MCP:      ${endpoint.mcpUrl}, connecting to that socket\n` +
+                    `  Token:    ${endpoint.token}\n` +
+                    `  Try:      curl --unix-socket ${endpoint.socketPath} -H 'Authorization: Bearer <token>' http://localhost/api/capabilities\n` +
+                    `Only this OS user can connect; the token is still required on every\n` +
+                    `request. OAuth is off: no browser can reach a socket to approve a client.\n` +
+                    (env.mode === "enforced"
+                        ? `Enforced mode: --unsafe-local is refused. Every receipt says 'enforced'.\n`
+                        : ""));
+            }
+            else if (endpoint !== undefined) {
                 // stdout stays clean for the stdio transport's sake even here, so the
                 // one command an operator has to copy goes where they can read it.
                 process.stderr.write(`MELRA HTTP server listening on http://${endpoint.host}:${endpoint.port}\n` +
@@ -677,6 +883,10 @@ async function main() {
                             `you to approve it in a browser; approved clients are named on every\n` +
                             `receipt. Set MELRA_HTTP_OAUTH=0 to allow only the token above.\n`
                         : `OAuth is off, so the token above is the only way in.\n`) +
+                    (env.mode === "enforced"
+                        ? `Enforced mode: loopback only, no client can register itself, and\n` +
+                            `--unsafe-local is refused. Every receipt says 'enforced'.\n`
+                        : "") +
                     `Loopback only. Anyone who can read this token can drive this machine.\n`);
                 if (args.includes("--open"))
                     openInBrowser(endpoint.url);
@@ -699,13 +909,41 @@ async function main() {
             rejectUnknownFlags(args, []);
             await inspectTask(args, env);
             return;
+        case "tasks": {
+            rejectUnknownFlags(args, ["--limit", "--status", "--json"]);
+            const limit = Number(argument("--limit", args) ?? "20");
+            if (!Number.isInteger(limit) || limit < 1 || limit > 500) {
+                throw new Error("--limit must be a whole number from 1 to 500");
+            }
+            const status = argument("--status", args);
+            process.exitCode = tasksCommand(env, {
+                limit,
+                json: args.includes("--json"),
+                ...(status === undefined ? {} : { status: TaskStatusSchema.parse(status) }),
+            });
+            return;
+        }
+        case "watch":
+            rejectUnknownFlags(args, ["--json"]);
+            process.exitCode = await watchCommand(env, { json: args.includes("--json") });
+            return;
+        case "status": {
+            rejectUnknownFlags(args, ["--json"]);
+            const policyPath = await existingPolicyPath(env);
+            process.exitCode = await statusCommand(env, {
+                json: args.includes("--json"),
+                ...(policyPath === undefined ? {} : { policyPath }),
+            });
+            return;
+        }
         case "workflow":
             rejectUnknownFlags(args, ["--definition", "--approval", "--input"]);
             process.exitCode = await workflowCommand(args, env);
             return;
         case "demo":
             rejectUnknownFlags(args, []);
-            if (args[0] !== "durable-core") {
+            // One demo today, so naming it is optional.
+            if ((args[0] ?? "durable-core") !== "durable-core") {
                 throw new Error("demo supports only 'durable-core'");
             }
             process.exitCode = await durableCoreDemo(env);
@@ -723,7 +961,11 @@ async function main() {
         case "version":
         case "--version":
         case "-v":
-            process.stdout.write(`${PRODUCT_VERSION}\n`);
+            // `--json` keeps the bare version scripts already parse; a JSON object
+            // here would break every `$(melra version)` in the wild.
+            process.stdout.write(isHuman(args)
+                ? `MELRA ${paint.bold(PRODUCT_VERSION)} ${paint.dim(`(Node ${process.version}, ${process.platform}-${process.arch})`)}\n`
+                : `${PRODUCT_VERSION}\n`);
             return;
         case "help":
         case "--help":
@@ -731,7 +973,9 @@ async function main() {
             help();
             return;
         default:
-            throw new Error(`unknown command: ${basename(command)}`);
+            // No inline command list: the switch above is the only truth about what
+            // exists, and a second copy here would rot the first time one is added.
+            throw new Error(`unknown command: ${basename(command)}. Run 'melra --help' for the command list.`);
     }
 }
 /**