@melra/cli 0.3.0-alpha.11 → 0.3.0-alpha.13

package/dist/index.js

@@ -1,27 +1,73 @@
 #!/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, deploymentMode, principalRef, } from "@melra/protocol";
-import { assertEnforceable, createMelraRuntime, serveHttp, OAuthProvider, clientPrincipal, serveStdio, unconfinedRoot, } from "@melra/server";
+import { ApprovalResponseSchema, TaskRequestSchema, TaskStatusSchema, WorkflowDefinitionSchema, WorkflowInputSchema, PRODUCT_VERSION, deploymentMode, principalRef, } from "@melra/protocol";
+import { assertEnforceable, confinedRoot, createMelraRuntime, serveHttp, OAuthProvider, clientPrincipal, serveStdio, unconfinedRoot, workspaceHoldsData, } 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 { approverLabel, parseCliEnvironment, serverLaunch, } from "./environment.js";
+import { approvalScreen, printable } from "./approval-screen.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";
+/**
+ * Fold in what the policy file says, so every command describes the server it
+ * would actually start: `unhinged` if either asks for it, and the stricter
+ * `mode`, exactly as the server combines them.
+ *
+ * The workspace is MELRA_WORKSPACE when it is set, which every config `setup`
+ * writes does, and the working directory otherwise. A file the operator names
+ * in MELRA_POLICY may pin it when MELRA_WORKSPACE is not set; any policy file
+ * may narrow it to a directory inside, never move it outside. Older `setup`
+ * runs wrote their own workspace into the shared ~/.melra/policy.json, and a
+ * server for any later project was then confined to the first one instead.
+ *
+ * A file that does not parse changes nothing here; `doctor` reports it and the
+ * server refuses to start on it.
+ */
+async function settle(env) {
+    const path = await existingPolicyPath(env);
+    if (path === undefined)
+        return env;
+    let file;
+    try {
+        file = await loadPolicy(path, env.workspaceRoot);
+    }
+    catch {
+        return env;
+    }
+    const shared = resolve(path) === resolve(env.dataDirectory, "policy.json");
+    return {
+        ...env,
+        workspaceRoot: env.workspaceSet !== true && !shared
+            ? file.workspaceRoot
+            : confinedRoot(env.workspaceRoot, file.workspaceRoot),
+        unhinged: env.unhinged || file.unhinged,
+        mode: env.mode === "enforced" || file.mode === "enforced" ? "enforced" : "developer",
+    };
+}
 async function existingPolicyPath(env) {
     if (env.policyPath !== undefined)
         return env.policyPath;
     const candidate = join(env.dataDirectory, "policy.json");
     try {
-        await access(candidate, constants.R_OK);
+        // Exists, not readable: an unreadable file has to fail loudly, not be
+        // skipped for the built-in defaults along with its enforced mode.
+        await access(candidate, constants.F_OK);
         return candidate;
     }
     catch {
@@ -89,7 +135,10 @@ async function runtime(env) {
     });
 }
 function output(value) {
-    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    // JSON.stringify escapes C0 controls but leaves C1, DEL and the invisible
+    // and reordering characters raw, and much of what is printed came from an
+    // agent. Spelled out, it is still valid JSON for the same values.
+    process.stdout.write(`${printable(JSON.stringify(value, null, 2), true)}\n`);
 }
 function argument(name, args) {
     const index = args.indexOf(name);
@@ -111,7 +160,8 @@ function rejectUnknownFlags(args, known) {
     ]);
     // 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 boolean = new Set(["--http", "--json", "--yes", "--deny"]);
+    const valued = new Set(known.filter((flag) => !boolean.has(flag)));
     for (let index = 0; index < args.length; index += 1) {
         const argument_ = args[index];
         if (argument_ === undefined || !argument_.startsWith("--"))
@@ -283,14 +333,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"
@@ -302,6 +351,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]);
@@ -319,17 +416,33 @@ async function doctor(env) {
             status: "warn",
             detail: "UNSAFE-LOCAL: no policy, approval, evidence, confinement, or destination check is applied",
         }
-        : { name: "guardrails", status: "pass", detail: "enforced" });
-    // 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.
+        // 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" });
+    // Neither mode is a `fail` on its own. Developer mode is a legitimate choice and the
+    // default; what is not legitimate is a machine that cannot say which one it is,
+    // or one asking for enforced mode and unsafe-local at once, which a policy file
+    // can do past the flag check and which the server then refuses to start.
+    let refusal;
+    try {
+        assertEnforceable(env.mode, env.unhinged);
+    }
+    catch (error) {
+        refusal = error instanceof Error ? error.message : String(error);
+    }
     checks.push({
         name: "mode",
-        status: "pass",
-        detail: env.mode === "enforced"
-            ? "enforced: no unsafe-local, loopback only, no client self-registration"
-            : "developer: MELRA governs what it is asked for; the harness may have another path",
+        status: refusal === undefined ? "pass" : "fail",
+        detail: refusal ??
+            (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 {
+        // A file passes access() too, and the runtime then fails to start on it.
+        if (!(await stat(env.workspaceRoot)).isDirectory())
+            throw new Error("not a directory");
         await access(env.workspaceRoot, constants.R_OK | constants.W_OK);
         checks.push({
             name: "workspace",
@@ -360,6 +473,30 @@ async function doctor(env) {
             detail: env.dataDirectory,
         });
     }
+    // Only once both exist as directories: the check would create a missing
+    // workspace. Not in unsafe-local, which reaches every file on the machine and
+    // whose guardrails warning already says so.
+    if (!env.unhinged &&
+        checks.every((check) => !["workspace", "data-directory"].includes(check.name) || check.status === "pass")) {
+        try {
+            const inside = await workspaceHoldsData(env.workspaceRoot, env.dataDirectory);
+            checks.push(inside
+                ? {
+                    name: "data-location",
+                    // The server refuses to start this way in enforced mode.
+                    status: env.mode === "enforced" ? "fail" : "warn",
+                    detail: `${env.dataDirectory} is inside the workspace, where a recursive read reaches payload.key without naming it`,
+                }
+                : { name: "data-location", status: "pass", detail: "outside the workspace" });
+        }
+        catch (error) {
+            checks.push({
+                name: "data-location",
+                status: "fail",
+                detail: `could not resolve the workspace: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
     try {
         const database = new DatabaseSync(":memory:");
         database.exec("CREATE TABLE readiness(value TEXT)");
@@ -390,8 +527,9 @@ async function doctor(env) {
     });
     try {
         const path = await existingPolicyPath(env);
+        // The server's own parser, so a bad `mode` or grant fails here too.
         if (path !== undefined)
-            JSON.parse(await readFile(path, "utf8"));
+            await loadPolicy(path, env.workspaceRoot);
         checks.push({
             name: "policy",
             status: "pass",
@@ -405,6 +543,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: {
@@ -416,46 +559,92 @@ async function doctor(env) {
             unhinged: env.unhinged,
             mode: env.mode,
             checks,
+            // Per client, so a script can find a stale pin without parsing `detail`.
+            clients,
         },
         failed,
     };
 }
 async function init(args, env) {
     await mkdir(env.dataDirectory, { recursive: true });
-    const policyPath = join(env.dataDirectory, "policy.json");
+    // The operator's MELRA_POLICY when there is one: writing the default path
+    // into the client config instead quietly swapped their policy for ours.
+    const policyPath = env.policyPath ?? join(env.dataDirectory, "policy.json");
     try {
         await access(policyPath, constants.F_OK);
     }
     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,
-                },
-            },
+        if (env.policyPath !== undefined) {
+            throw new Error(`MELRA_POLICY names ${policyPath}, which does not exist`);
+        }
+        // No `workspaceRoot`: this file is shared by every project's server, and
+        // each config `setup` writes names its own workspace in MELRA_WORKSPACE.
+        const { workspaceRoot: _shared, ...policy } = createDefaultPolicy(env.workspaceRoot);
+        await writeFile(policyPath, `${JSON.stringify(policy, null, 2)}\n`, { flag: "wx" });
+    }
+    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) {
@@ -471,13 +660,14 @@ async function runTask(args, env) {
                 output({ task, next: "rerun interactively to approve this scoped action" });
                 return 3;
             }
-            const prompt = createInterface({ input: process.stdin, output: process.stderr });
-            const phrase = await prompt.question(`Type the exact approval phrase '${task.approval.phrase}' to continue: `);
-            prompt.close();
-            const execution = await melra.controller.execute(task.id, {
-                approvalId: task.approval.approvalId,
-                phrase,
-            });
+            // Shown the effect and asked, rather than made to retype a phrase that
+            // proves only that someone typed it.
+            const approver = approverLabel(env);
+            const view = melra.controller.approvalView(task.id);
+            if (!(await confirmInTerminal(view)))
+                return 1;
+            melra.controller.decide(task.id, view.renderDigest, approver);
+            const execution = await melra.controller.execute(task.id);
             output(execution);
             return execution.task.status === "verified_success" ? 0 : 2;
         }
@@ -489,6 +679,68 @@ async function runTask(args, env) {
         await melra.close();
     }
 }
+/** The effect as an approver needs to see it, on stderr, then y/N. */
+async function confirmInTerminal(view) {
+    process.stderr.write(approvalScreen(view));
+    const prompt = createInterface({ input: process.stdin, output: process.stderr });
+    const answer = (await prompt.question("Approve this effect? [y/N] ")).trim().toLowerCase();
+    prompt.close();
+    return answer === "y" || answer === "yes";
+}
+/**
+ * Records an approval for a task another process planned, without running it:
+ * the agent that planned it runs it, and the decision lets it.
+ */
+async function approveCommand(args, env) {
+    // `--mode` is the one flag here that takes a value.
+    const given = args.find((value, index) => !value.startsWith("--") && args[index - 1] !== "--mode");
+    if (given === undefined)
+        throw new Error("approve requires a task ID");
+    const approver = approverLabel(env);
+    const melra = await runtime(env);
+    try {
+        // `melra tasks` shows the first eight characters, so a prefix naming one
+        // waiting task is enough.
+        const waiting = melra.store
+            .listTasks(500, "awaiting_approval")
+            .filter((task) => task.id.startsWith(given));
+        if (given.length < 36 && waiting.length > 1)
+            throw new Error(`task_id_ambiguous:${given}`);
+        const taskId = given.length < 36 && waiting.length === 1 ? waiting[0].id : given;
+        const view = melra.controller.approvalView(taskId);
+        if (args.includes("--deny")) {
+            melra.controller.cancel(taskId);
+            // Read back: another process may have started it in the meantime.
+            const task = melra.controller.status(taskId);
+            output({ task });
+            return task.status === "cancelled" ? 0 : 1;
+        }
+        if (!args.includes("--yes")) {
+            if (!process.stdin.isTTY || args.includes("--json")) {
+                output({
+                    taskId,
+                    renderDigest: view.renderDigest,
+                    contract: view.contract,
+                    next: "rerun with --yes to approve, or in a terminal to be asked",
+                });
+                return 3;
+            }
+            if (!(await confirmInTerminal(view))) {
+                process.stderr.write("Not approved.\n");
+                return 1;
+            }
+        }
+        const decision = melra.controller.decide(taskId, view.renderDigest, approver);
+        if (decision.channel === "in_band") {
+            process.stderr.write("Recorded in band: this process is in developer mode. Set \"mode\": \"enforced\" in the policy file (or MELRA_MODE=enforced) for the server and for this command. An enforced server will not run on this decision: a workflow plans the step again once the challenge expires; a single task needs --deny and planning again.\n");
+        }
+        output({ decision });
+        return 0;
+    }
+    finally {
+        await melra.close();
+    }
+}
 async function inspectTask(args, env) {
     const taskId = args[0];
     if (taskId === undefined)
@@ -513,6 +765,7 @@ async function policyTest(args, env) {
     // answer for a policy nobody is running.
     const policy = {
         ...(await loadPolicy(await existingPolicyPath(env), env.workspaceRoot)),
+        workspaceRoot: env.workspaceRoot,
         unhinged: env.unhinged,
         mode: env.mode,
     };
@@ -556,7 +809,7 @@ function clientsCommand(args, env) {
     }
     for (const client of clients) {
         process.stdout.write(`${client.approvedAt === undefined ? "pending " : "approved"}  ` +
-            `${client.id}  ${client.name}\n` +
+            `${client.id}  ${printable(client.name)}\n` +
             `          ${principalRef(clientPrincipal(client))}\n`);
     }
     process.stdout.write(`\nRevoke one with 'melra clients --revoke <client-id>', or all of them\n` +
@@ -588,25 +841,45 @@ 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 approve <task-id> [--yes] [--deny] [--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>]
+                                       (--approval: developer mode; enforced:
+                                       melra approve <task-id>, then advance)
   melra workflow inspect <workflow-id>
   melra workflow cancel <workflow-id>
   melra workflow pause|resume|suspend <workflow-id>
   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:
+  --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
@@ -619,20 +892,30 @@ Flags:
                    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_WORKSPACE  Workspace boundary (default: a MELRA_POLICY file's
+                   workspaceRoot, else the 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 --unsafe-local)
   MELRA_MODE       developer (default) or enforced (see --mode)
+  MELRA_APPROVER   Name 'melra approve' records as the approver (default: operator)
   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)
@@ -654,15 +937,21 @@ async function main() {
             "it is an opt-out of the entire safety model.\n");
     }
     const modeFlag = argument("--mode", args);
-    const env = {
+    const requested = {
         ...parsed,
         unhinged: parsed.unhinged || deprecated || args.includes("--unsafe-local"),
-        ...(modeFlag === undefined ? {} : { mode: deploymentMode(modeFlag) }),
+        // The strictest of the flag and the variable, as for the policy file below:
+        // `--mode developer` does not undo MELRA_MODE=enforced.
+        ...(modeFlag === undefined || deploymentMode(modeFlag) === "developer"
+            ? {}
+            : { mode: "enforced" }),
     };
     // 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);
+    // taken effect. On the flags and variables only: a policy file that asks for
+    // both is the server's to refuse, naming the file, and `doctor` still runs.
+    assertEnforceable(requested.mode, requested.unhinged);
+    const env = await settle(requested);
     // 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.
@@ -671,14 +960,14 @@ async function main() {
     }
     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");
@@ -690,33 +979,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` +
@@ -725,8 +1044,8 @@ async function main() {
                     `  Token:    ${endpoint.token}\n` +
                     (endpoint.oauth
                         ? `A client that cannot be given the token can register itself and ask\n` +
-                            `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`
+                            `you to approve it in a browser, with the token above; approved clients\n` +
+                            `are named on every receipt. Set MELRA_HTTP_OAUTH=0 to allow only the token.\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` +
@@ -749,18 +1068,50 @@ async function main() {
             rejectUnknownFlags(args, ["--request"]);
             process.exitCode = await runTask(args, env);
             return;
+        case "approve":
+            rejectUnknownFlags(args, ["--yes", "--deny", "--json"]);
+            process.exitCode = await approveCommand(args, env);
+            return;
         case "inspect":
         case "export":
             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);
@@ -778,7 +1129,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":