@melra/cli 0.3.0-alpha.14 → 0.3.0-alpha.16

package/dist/index.js

@@ -5,23 +5,22 @@ import { access, lstat, mkdir, readFile, stat, writeFile } from "node:fs/promise
 import { constants } from "node:fs";
 import { spawn } from "node:child_process";
 import { basename, dirname, join, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
 import { DatabaseSync } from "node:sqlite";
 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 { assertEnforceable, broadWorkspace, confinedRoot, createMelraRuntime, dataLocationAdvice, narrowWorkspaceAdvice, secretFiles, secretInsideWorkspace, serveHttp, OAuthProvider, clientPrincipal, printable, serveStdio, unconfinedRoot, workspaceHoldsData, workspaceInsideData, } from "@melra/server";
 import { detectBrowserExecutable } from "@melra/browser-runtime";
 import { createSystemComputerAdapter } from "@melra/computer-runtime";
-import { capabilityUsageReader } from "@melra/runtime-core";
+import { capabilityUsageReader, withDefaultEvidence } from "@melra/runtime-core";
 import { SqliteStore } from "@melra/storage-sqlite";
 import { classifyOperation, createDefaultPolicy, evaluatePolicy, loadPolicy, } from "@melra/policy-core";
 import { approverLabel, parseCliEnvironment, serverLaunch, } from "./environment.js";
-import { approvalScreen, printable } from "./approval-screen.js";
+import { approvalConsole, assertConsoleTerminal, confirmInTerminal } from "./approval-console.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 { broadWorkspaceWarning, confirmBroadWorkspace, prompter, renderConformance, renderDoctor, renderInit, renderSetup, setupWizard, } from "./human.js";
 import { isHuman, paint, printJsonOrHuman } from "./output.js";
 import { CLIENTS, clientConfig, clientConfigPath, resolveClient, writeClientConfig, } from "./clients.js";
 /**
@@ -36,8 +35,9 @@ import { CLIENTS, clientConfig, clientConfigPath, resolveClient, writeClientConf
  * 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.
+ * A file that does not load changes nothing here, the mode included: nothing in
+ * an invalid file is trusted to mean what it seems to. `doctor`, `status` and
+ * `tasks` report it, and `serve`, `run` and `approve` refuse to start on it.
  */
 async function settle(env) {
     const path = await existingPolicyPath(env);
@@ -160,7 +160,9 @@ 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 boolean = new Set(["--http", "--json", "--yes", "--deny"]);
+    // Every known flag that takes no value. One missing here had its next
+    // token skipped unchecked, so `--write --dry-run` wrote the config.
+    const boolean = new Set(["--http", "--json", "--yes", "--deny", "--write", "--open"]);
     const valued = new Set(known.filter((flag) => !boolean.has(flag)));
     for (let index = 0; index < args.length; index += 1) {
         const argument_ = args[index];
@@ -352,7 +354,7 @@ async function durableCoreDemo(env) {
     }
 }
 /**
- * Whether `MELRA_SOCKET` names somewhere `serve` can listen, and whether a
+ * Whether `MELRA_SOCKET` names somewhere `serve --socket` 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`.
  */
@@ -458,12 +460,15 @@ async function doctor(env) {
         });
     }
     try {
-        await mkdir(env.dataDirectory, { recursive: true });
+        await mkdir(env.dataDirectory, { recursive: true, mode: 0o700 });
         await access(env.dataDirectory, constants.R_OK | constants.W_OK);
+        // Created private above. One that already existed is left as it is, but
+        // said to be open: the task database inside is private, its directory not.
+        const open = process.platform !== "win32" && ((await stat(env.dataDirectory)).mode & 0o077) !== 0;
         checks.push({
             name: "data-directory",
-            status: "pass",
-            detail: env.dataDirectory,
+            status: open ? "warn" : "pass",
+            detail: open ? `${env.dataDirectory} can be read by other users; run chmod 700 on it` : env.dataDirectory,
         });
     }
     catch {
@@ -474,20 +479,33 @@ async function doctor(env) {
         });
     }
     // 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")) {
+    // workspace.
+    if (checks.every((check) => !["workspace", "data-directory"].includes(check.name) || check.status !== "fail")) {
         try {
-            const inside = await workspaceHoldsData(env.workspaceRoot, env.dataDirectory);
-            checks.push(inside
-                ? {
+            if (await workspaceInsideData(env.workspaceRoot, env.dataDirectory)) {
+                checks.push({
                     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" });
+                    // The server refuses to start this way in every mode.
+                    status: "fail",
+                    detail: `workspace_inside_data_directory: ${env.workspaceRoot} is inside ${env.dataDirectory}, ` +
+                        "where every path is MELRA's own; point MELRA_WORKSPACE at the project",
+                });
+            }
+            else if (!env.unhinged) {
+                // Not in unsafe-local, which reaches every file on the machine and
+                // whose guardrails warning already says so.
+                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`,
+                        // As the server words its refusal.
+                        next: await dataLocationAdvice(env.workspaceRoot, env.dataDirectory, env.policyPath),
+                    }
+                    : { name: "data-location", status: "pass", detail: "outside the workspace" });
+            }
         }
         catch (error) {
             checks.push({
@@ -511,12 +529,21 @@ async function doctor(env) {
         });
     }
     const browser = env.browserExecutablePath ?? (await detectBrowserExecutable());
-    checks.push({
-        name: "browser",
-        status: browser === undefined ? "warn" : "pass",
-        detail: browser ??
-            "Chrome, Chromium, or Edge not found; non-browser capabilities remain available",
-    });
+    checks.push(
+    // An attached browser may be the one the operator browses and approves in.
+    env.browserCdpEndpoint !== undefined
+        ? {
+            name: "browser",
+            status: "warn",
+            detail: `attached over CDP to ${env.browserCdpEndpoint}: any tab open there, signed-in sites included, ` +
+                "is a tab_switch away from the agent; attach to a browser you do not use yourself",
+        }
+        : {
+            name: "browser",
+            status: browser === undefined ? "warn" : "pass",
+            detail: browser ??
+                "Chrome, Chromium, or Edge not found; non-browser capabilities remain available",
+        });
     const computer = await createSystemComputerAdapter().capabilities();
     checks.push({
         name: "computer",
@@ -525,16 +552,28 @@ async function doctor(env) {
             ? `${computer.adapter}: screenshot=${computer.screenshot}, pointer=${computer.pointer}, keyboard=${computer.keyboard}, scroll=${computer.scroll}`
             : computer.limitations.join("; "),
     });
+    let credentials = {};
     try {
         const path = await existingPolicyPath(env);
+        let allowLocalhost;
         // The server's own parser, so a bad `mode` or grant fails here too.
         if (path !== undefined)
-            await loadPolicy(path, env.workspaceRoot);
+            ({ credentials, allowLocalhost } = await loadPolicy(path, env.workspaceRoot));
         checks.push({
             name: "policy",
             status: "pass",
             detail: path ?? "using safe built-in defaults",
         });
+        // Enforced mode keeps loopback closed unless the file opens it, so say so
+        // when it does: the services this machine runs for itself are behind it.
+        if (env.mode === "enforced" && allowLocalhost === true) {
+            checks.push({
+                name: "loopback",
+                status: "warn",
+                detail: `${path} sets allowLocalhost, so HTTP and browser effects can reach services on this machine's loopback`,
+                next: `remove allowLocalhost from ${path} unless a task needs a service on this machine`,
+            });
+        }
     }
     catch (error) {
         checks.push({
@@ -543,6 +582,44 @@ async function doctor(env) {
             detail: error instanceof Error ? error.message : String(error),
         });
     }
+    // Where the browser's and the credential broker's secret files lie, judged as
+    // the server judges them before it starts. Only once the workspace exists:
+    // the check would create it.
+    const secrets = secretFiles(env, credentials);
+    if (secrets.size > 0 && checks.some((check) => check.name === "workspace" && check.status === "pass")) {
+        try {
+            const profile = secrets.get("MELRA_BROWSER_PROFILE");
+            if (profile !== undefined && (await workspaceInsideData(env.workspaceRoot, profile))) {
+                checks.push({
+                    name: "secret-location",
+                    // The server refuses to start this way in every mode.
+                    status: "fail",
+                    detail: `workspace_inside_browser_profile: ${env.workspaceRoot} is inside ${profile}`,
+                    next: "point MELRA_WORKSPACE at the project, outside MELRA_BROWSER_PROFILE",
+                });
+            }
+            else if (!env.unhinged) {
+                // Not in unsafe-local, as for the data directory.
+                const held = await secretInsideWorkspace(env.workspaceRoot, secrets);
+                checks.push(held === undefined
+                    ? { name: "secret-location", status: "pass", detail: "outside the workspace" }
+                    : {
+                        name: "secret-location",
+                        // The server refuses to start this way in enforced mode.
+                        status: env.mode === "enforced" ? "fail" : "warn",
+                        detail: `${held} names ${secrets.get(held)}, inside the workspace, where a recursive read reaches it without naming it`,
+                        next: `move ${secrets.get(held)} out of the workspace`,
+                    });
+            }
+        }
+        catch (error) {
+            checks.push({
+                name: "secret-location",
+                status: "fail",
+                detail: `could not resolve the workspace: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
     if (env.socketPath !== undefined)
         checks.push(await socketCheck(env.socketPath));
     checks.push(isolationCheck(await detectIsolation(), env.mode));
@@ -566,7 +643,7 @@ async function doctor(env) {
     };
 }
 async function init(args, env) {
-    await mkdir(env.dataDirectory, { recursive: true });
+    await mkdir(env.dataDirectory, { recursive: true, mode: 0o700 });
     // 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");
@@ -579,8 +656,10 @@ async function init(args, env) {
         }
         // No `workspaceRoot`: this file is shared by every project's server, and
         // each config `setup` writes names its own workspace in MELRA_WORKSPACE.
+        // In the mode asked for, so `approve` and `console` run from a shell agree
+        // with the server on it; a policy that already exists is the operator's.
         const { workspaceRoot: _shared, ...policy } = createDefaultPolicy(env.workspaceRoot);
-        await writeFile(policyPath, `${JSON.stringify(policy, null, 2)}\n`, { flag: "wx" });
+        await writeFile(policyPath, `${JSON.stringify({ ...policy, mode: env.mode }, null, 2)}\n`, { flag: "wx" });
     }
     const client = resolveClient(argument("--client", args) ?? "generic");
     const label = CLIENTS[client]?.label ?? client;
@@ -590,6 +669,9 @@ async function init(args, env) {
             MELRA_WORKSPACE: env.workspaceRoot,
             MELRA_HOME: env.dataDirectory,
             MELRA_POLICY: policyPath,
+            // The client starts the server with this env, not with our flags: without
+            // it `--mode enforced` would be reported here and a developer server run.
+            ...(env.mode === "enforced" ? { MELRA_MODE: "enforced" } : {}),
         },
     });
     const configPath = clientConfigPath(client, env.workspaceRoot);
@@ -602,6 +684,7 @@ async function init(args, env) {
         return {
             initialized: true,
             client,
+            workspace: env.workspaceRoot,
             policyPath,
             configPath,
             written: true,
@@ -616,6 +699,7 @@ async function init(args, env) {
     return {
         initialized: true,
         client,
+        workspace: env.workspaceRoot,
         policyPath,
         ...(configPath === undefined ? {} : { configPath }),
         config,
@@ -625,22 +709,53 @@ async function init(args, env) {
             : `Add this to ${configPath}, or rerun with --write to merge it there for you.`,
     };
 }
+// A broad workspace (home, a directory holding it, or a filesystem root) hands
+// the agent every project at once, and a fresh terminal starts in home.
+// MELRA_WORKSPACE naming it is a choice already made; otherwise a person at a
+// terminal is asked, defaulting to no, and anything else is refused before a
+// file is written.
+async function workspaceAgreed(env, reader) {
+    const broad = env.workspaceSet === true ? undefined : await broadWorkspace(env.workspaceRoot);
+    if (broad === undefined)
+        return true;
+    const warning = broadWorkspaceWarning(env.workspaceRoot, broad, narrowWorkspaceAdvice(env.dataDirectory, env.policyPath));
+    if (reader === undefined) {
+        throw new Error(`workspace_too_broad: ${warning} (MELRA_WORKSPACE=${env.workspaceRoot} to use it anyway)`);
+    }
+    if (await confirmBroadWorkspace(reader, env.workspaceRoot, warning))
+        return true;
+    process.stdout.write("Nothing was written.\n");
+    return false;
+}
+// Only a person at a terminal on both ends is asked anything. Anything else —
+// a pipe, a test, `--json` — gets the non-interactive behaviour.
+function questions(args) {
+    return isHuman(args) && process.stdin.isTTY ? prompter({ input: process.stdin, output: process.stdout }) : undefined;
+}
 // 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) {
     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;
+    // One reader for the workspace question and the wizard, so answers typed
+    // ahead of the second are not dropped with the first.
+    const reader = questions(args);
+    try {
+        if (!(await workspaceAgreed(env, reader)))
+            return 1;
+        if (argument("--client", args) === undefined && reader !== undefined) {
+            const answer = await setupWizard(reader, 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"] : [])];
         }
-        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"] : [])];
+    }
+    finally {
+        reader?.close();
     }
     const initialized = await init(chosen, env);
     const { report, failed } = await doctor(env);
@@ -679,14 +794,6 @@ 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.
@@ -725,10 +832,8 @@ async function approveCommand(args, env) {
                 });
                 return 3;
             }
-            if (!(await confirmInTerminal(view))) {
-                process.stderr.write("Not approved.\n");
+            if (!(await confirmInTerminal(view)))
                 return 1;
-            }
         }
         const decision = melra.controller.decide(taskId, view.renderDigest, approver);
         if (decision.channel === "in_band") {
@@ -757,7 +862,10 @@ async function inspectTask(args, env) {
     }
 }
 async function policyTest(args, env) {
-    const request = await readTaskRequest(args);
+    // With the evidence the server derives for a mutation that declares none, as
+    // plan does: without it, a file write the server would ask approval for was
+    // previewed as denied for want of evidence.
+    const request = withDefaultEvidence(await readTaskRequest(args));
     // Reports what this process would actually decide, unhinged mode included —
     // a dry run that disagreed with the server it is previewing is worse than
     // none. That is also why the operator's own `policy.json` is loaded rather
@@ -782,6 +890,7 @@ async function policyTest(args, env) {
         output({
             ...evaluatePolicy(taskId, request, policy, capabilityUsageReader(store)),
             classified: { capability, target },
+            requiredEvidence: request.requiredEvidence,
         });
     }
     finally {
@@ -796,10 +905,18 @@ async function policyTest(args, env) {
 function clientsCommand(args, env) {
     const oauth = new OAuthProvider(env.dataDirectory);
     const revoke = argument("--revoke", args);
-    if (revoke !== undefined) {
+    if (args.includes("--revoke")) {
+        // A bare --revoke listed the clients and exited 0, and a mistyped id
+        // reported a revocation that touched nothing.
+        if (revoke === undefined || revoke.trim() === "") {
+            throw new Error("--revoke requires a client id, or all");
+        }
+        if (revoke !== "all" && !oauth.clients().some((client) => client.id === revoke)) {
+            throw new Error(`no such client: ${printable(revoke)}; 'melra clients' lists them`);
+        }
         const dropped = oauth.revoke(revoke === "all" ? undefined : revoke);
         process.stdout.write(`Revoked ${dropped} token${dropped === 1 ? "" : "s"}. ` +
-            `The client must be approved again before it can act.\n`);
+            `${revoke === "all" ? "Every client" : "The client"} must be approved again before it can act.\n`);
         return 0;
     }
     const clients = oauth.clients();
@@ -817,12 +934,14 @@ function clientsCommand(args, env) {
     return 0;
 }
 /**
- * Hands the console URL to whatever opens links here.
+ * Hands the console URL to whatever opens links here, and says whether anything
+ * took it: the helper ran and, if it finished within a few seconds, succeeded.
  *
  * The URL carries the token, so this is the difference between copying a secret
- * out of a terminal and the console simply being open. Failure is silent on
- * purpose: the URL is already on screen, and a server that refused to start
- * because a desktop helper is missing would be worse than one you click into.
+ * out of a terminal and the console simply being open. `serve --open` ignores a
+ * failure on purpose: the URL is already on screen, and a server that refused
+ * to start because a desktop helper is missing would be worse than one you
+ * click into. `melra console` prints no URL, so it has to know.
  */
 function openInBrowser(url) {
     const [command, ...prefix] = process.platform === "darwin"
@@ -834,8 +953,18 @@ function openInBrowser(url) {
         stdio: "ignore",
         detached: true,
     });
-    child.on("error", () => { });
     child.unref();
+    return new Promise((resolveOpened) => {
+        // ponytail: a helper still running after 3s is taken to have handed the URL
+        // on; some xdg-open fallbacks only return when the browser closes.
+        const handedOn = setTimeout(() => resolveOpened(true), 3_000);
+        handedOn.unref();
+        child.once("error", () => resolveOpened(false));
+        child.once("exit", (code) => {
+            clearTimeout(handedOn);
+            resolveOpened(code === 0);
+        });
+    });
 }
 function help() {
     process.stdout.write(`MELRA ${PRODUCT_VERSION}
@@ -845,10 +974,11 @@ Usage:
   melra doctor [--json]
   melra conformance [--url <mcp-url> --token <token>] [--level <1|2|3>]
   melra init [--client <name>] [--write] [--json]
-  melra serve [--http] [--port <port>] [--open]
+  melra serve [--http [--port <port>] [--open]]
   melra serve --socket <path>
   melra run --request <task.json>
   melra approve <task-id> [--yes] [--deny] [--json]
+  melra console
   melra inspect <task-id>
   melra tasks [--limit <n>] [--status <status>] [--json]
   melra watch [--json]
@@ -866,9 +996,23 @@ Usage:
   melra policy test --request <task.json>
   melra version [--json]
 
+'melra console', run by you in a terminal, opens an approval console in your
+browser, on a server of its own with no MCP endpoint, that approves or denies
+as 'melra approve' does. It pairs with the first page to use its code, normally
+the tab it opens. Its one-time pairing code is never printed: it reaches the
+browser on its opener's command line, and reloading or leaving the page ends
+the pairing. Run it with the MELRA_HOME, MELRA_WORKSPACE and mode your agent's
+server uses. Without a terminal or a browser to open, it refuses to start.
+
 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.
+captured, they print JSON (version: the bare number).
+
+The workspace setup and init write into the config is the current directory,
+unless MELRA_WORKSPACE (or a MELRA_POLICY file's workspaceRoot) names one. If
+that is your home directory, a directory holding it, or a filesystem root,
+they ask first in a terminal, and refuse with workspace_too_broad otherwise;
+setting MELRA_WORKSPACE to it skips the question.
 
 Flags:
   --json           Print JSON even in a terminal, and never ask a question.
@@ -891,11 +1035,13 @@ Flags:
   --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).
+  --port <port>    HTTP port, with --http (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.
+                   required. Not on Windows. This flag, not MELRA_SOCKET,
+                   moves 'serve' off stdio.
+  --open           With --http, 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.
@@ -911,11 +1057,12 @@ Environment:
   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_APPROVER   Name 'melra approve' and 'melra console' record 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_SOCKET     Socket path 'doctor' and 'status' check (serve needs --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)
@@ -978,15 +1125,26 @@ async function main() {
                 ...(url === undefined ? {} : { url }),
                 ...(token === undefined ? {} : { token }),
                 ...(level === undefined ? {} : { claim: Number(level) }),
+                // This process's flags, which a server it spawns gets only as env.
+                serverEnv: {
+                    ...(env.mode === "enforced" ? { MELRA_MODE: "enforced" } : {}),
+                    ...(env.unhinged ? { MELRA_UNHINGED: "1" } : {}),
+                },
             });
             printJsonOrHuman(report, renderConformance, args);
             process.exitCode = failed ? 1 : 0;
             return;
         }
-        case "init":
+        case "init": {
             rejectUnknownFlags(args, ["--client", "--write", "--json"]);
+            const reader = questions(args);
+            if (!(await workspaceAgreed(env, reader).finally(() => reader?.close()))) {
+                process.exitCode = 1;
+                return;
+            }
             printJsonOrHuman(await init(args, env), renderInit, args);
             return;
+        }
         case "setup":
             rejectUnknownFlags(args, ["--client", "--write", "--json"]);
             process.exitCode = await setup(args, env);
@@ -996,15 +1154,28 @@ async function main() {
             if (args.includes("--socket") && argument("--socket", args) === undefined) {
                 throw new Error("--socket requires a path");
             }
-            const socketPath = argument("--socket", args) ?? env.socketPath;
+            // Only the flag: an exported MELRA_SOCKET would otherwise move every
+            // stdio client launched from that shell off stdio, to wait forever.
+            const socketPath = argument("--socket", args);
             const http = args.includes("--http");
             const port = argument("--port", args);
             // 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");
+                // The flag, not its value: a --port with nothing after it is still one.
+                (http || args.includes("--port") || args.includes("--open"))) {
+                throw new Error("--socket replaces --http, --port, and --open; pass one transport");
+            }
+            // The same mistake the other way round: without --http, serve speaks
+            // stdio, and a port nobody listens on looks like a server that hangs.
+            if (socketPath === undefined && !http && (args.includes("--port") || args.includes("--open"))) {
+                throw new Error("--port and --open need --http; without it, serve speaks MCP over stdio");
+            }
+            // `--port "$PORT"` with PORT unset is Number(""), which is 0: a random
+            // port on every start, the bug a blank MELRA_HTTP_PORT had.
+            if (args.includes("--port") && (port === undefined || port.trim() === "")) {
+                throw new Error("--port requires a port; leave it out for the default (7457, or MELRA_HTTP_PORT), or pass 0 for any free port");
             }
             const melra = await runtime(env);
             const server = http || socketPath !== undefined ? undefined : await serveStdio(melra);
@@ -1017,14 +1188,6 @@ async function main() {
                     })
                     : 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` +
@@ -1053,7 +1216,7 @@ async function main() {
                         : "") +
                     `Loopback only. Anyone who can read this token can drive this machine.\n`);
                 if (args.includes("--open"))
-                    openInBrowser(endpoint.url);
+                    void openInBrowser(endpoint.url);
             }
             const close = async () => {
                 await server?.close();
@@ -1068,6 +1231,28 @@ async function main() {
             rejectUnknownFlags(args, ["--request"]);
             process.exitCode = await runTask(args, env);
             return;
+        case "console": {
+            rejectUnknownFlags(args, []);
+            const interactive = process.stdin.isTTY === true && process.stderr.isTTY === true;
+            // Before the runtime, which would open, and could create, the database.
+            assertConsoleTerminal(interactive);
+            const melra = await runtime(env);
+            const endpoint = await approvalConsole(env, melra, {
+                interactive,
+                open: openInBrowser,
+                say: (text) => process.stderr.write(text),
+            }).catch(async (error) => {
+                await melra.close();
+                throw error;
+            });
+            const close = async () => {
+                await endpoint.close();
+                await melra.close();
+            };
+            process.once("SIGINT", () => void close().finally(() => process.exit(0)));
+            process.once("SIGTERM", () => void close().finally(() => process.exit(0)));
+            return;
+        }
         case "approve":
             rejectUnknownFlags(args, ["--yes", "--deny", "--json"]);
             process.exitCode = await approveCommand(args, env);
@@ -1079,15 +1264,42 @@ async function main() {
             return;
         case "tasks": {
             rejectUnknownFlags(args, ["--limit", "--status", "--json"]);
+            // A trailing --status, as an unquoted `--status $S` sends with S unset,
+            // listed every status: an unfiltered list that looked filtered.
+            for (const flag of ["--limit", "--status"]) {
+                const value = argument(flag, args);
+                if (args.includes(flag) && (value === undefined || value.startsWith("--"))) {
+                    throw new Error(`${flag} requires a value`);
+                }
+            }
             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);
+            // Approvals are read by the window and mode a server started here would
+            // use; a policy file that does not load leaves the defaults, and says so,
+            // as status does: a server would refuse to start on it.
+            const policyPath = await existingPolicyPath(env);
+            let policy;
+            let policyError;
+            if (policyPath !== undefined) {
+                try {
+                    policy = await loadPolicy(policyPath, env.workspaceRoot);
+                }
+                catch (error) {
+                    policyError = error instanceof Error ? error.message : String(error);
+                }
+            }
             process.exitCode = tasksCommand(env, {
                 limit,
                 json: args.includes("--json"),
                 ...(status === undefined ? {} : { status: TaskStatusSchema.parse(status) }),
+                ...(policyError === undefined ? {} : { policyError }),
+                window: {
+                    mode: env.mode === "enforced" || policy?.mode === "enforced" ? "enforced" : "developer",
+                    ...(policy?.approvalTtlMs === undefined ? {} : { approvalTtlMs: policy.approvalTtlMs }),
+                },
             });
             return;
         }