metergraph-cli 0.2.3 → 0.2.4

package/src/anchored-fs.js

@@ -0,0 +1,163 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+// A process-local directory capability service. The shipped helper owns all
+// descriptors; only its inherited anonymous pipes carry requests and contents.
+// An absent or unverified backend is an error, never a pathname-write fallback.
+const MAX = 2 * 1024 * 1024;
+const base = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../native");
+const errnoNames = new Map(Object.entries(os.constants.errno).map(([name, number]) => [number, name]));
+let service = null;
+let rollbackDepth = 0;
+const aliases = new Map(process.platform === "darwin" ? [["/var", "/private/var"], ["/tmp", "/private/tmp"]] : []);
+function failure(code) { const error = new Error(`Secure filesystem operation failed (${code}).`); error.code = code; return error; }
+function verifiedHelper() {
+  const name = `anchored-fs-${process.platform}-${process.arch}`;
+  let file;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(base, "manifest.json"), "utf8"));
+    file = path.join(base, "bin", name);
+    const bytes = fs.readFileSync(file);
+    if (manifest.schema !== 1 || typeof manifest.artifacts[name] !== "string" ||
+        createHash("sha256").update(bytes).digest("hex") !== manifest.artifacts[name]) throw failure("ENOTSUP");
+  } catch { throw failure("ENOTSUP"); }
+  return file;
+}
+// Test and diagnostic capability discovery verifies the same packaged bytes as
+// start(). It never enables a platform merely because its name is recognised.
+export function hasVerifiedHelper() {
+  try { verifiedHelper(); return true; } catch { return false; }
+}
+function start() {
+  if (service !== null) return service;
+  const file = verifiedHelper();
+  const child = spawn(file, [], { stdio: ["pipe", "pipe", "ignore"], windowsHide: true, env: {} });
+  child.on("error", () => { /* synchronous pipe operations report backend loss */ });
+  const input = child.stdin?._handle;
+  const output = child.stdout?._handle;
+  if (!input || !output || typeof input.setBlocking !== "function" || typeof output.setBlocking !== "function") {
+    child.kill("SIGKILL"); throw failure("ENOTSUP");
+  }
+  input.setBlocking(true); output.setBlocking(true);
+  service = { child, input: input.fd, output: output.fd };
+  child.unref(); child.stdin.unref(); child.stdout.unref();
+  return service;
+}
+function writeAll(fd, bytes) { let offset = 0; while (offset < bytes.length) { const count = fs.writeSync(fd, bytes, offset, bytes.length - offset); if (count === 0) throw failure("EIO"); offset += count; } }
+function readAll(fd, bytes) { let offset = 0; while (offset < bytes.length) { const count = fs.readSync(fd, bytes, offset, bytes.length - offset, null); if (count === 0) throw failure("EIO"); offset += count; } }
+function request(operation, args = [], payload = Buffer.alloc(0)) {
+  const encoded = args.map(value => Buffer.from(String(value)));
+  if (encoded.some(value => value.includes(0))) throw failure("EINVAL");
+  const size = 2 + encoded.reduce((n, value) => n + 4 + value.length, 0) + payload.length;
+  if (size > MAX) throw failure("EFBIG");
+  const body = Buffer.alloc(4 + size); body.writeUInt32BE(size); body[4] = operation; body[5] = args.length;
+  let offset = 6;
+  for (const value of encoded) { body.writeUInt32BE(value.length, offset); offset += 4; value.copy(body, offset); offset += value.length; }
+  payload.copy(body, offset);
+  const pipe = start(); writeAll(pipe.input, body);
+  const header = Buffer.alloc(8); readAll(pipe.output, header);
+  const error = header.readUInt32BE(); const length = header.readUInt32BE(4);
+  if (length > MAX) throw failure("EIO");
+  const result = Buffer.alloc(length); readAll(pipe.output, result);
+  if (error) throw failure(errnoNames.get(error) ?? "EIO");
+  return result;
+}
+function canonical(value) {
+  if (typeof value !== "string" || value.includes("\0")) throw failure("EINVAL");
+  let absolute = path.resolve(value);
+  const choices = [...aliases].sort((a,b) => b[0].length - a[0].length);
+  for (const [alias, target] of choices) if (absolute === alias || absolute.startsWith(`${alias}/`)) { absolute = target + absolute.slice(alias.length); break; }
+  return absolute;
+}
+function descriptor(value) { if (!Number.isSafeInteger(value) || value > -1001) throw failure("EBADF"); return -value - 1001; }
+function statResult(bytes, options) {
+  if (bytes.length !== 88) throw failure("EIO");
+  const keys = ["dev", "ino", "mode", "nlink", "uid", "gid", "size"];
+  const result = {};
+  keys.forEach((key, index) => { const n = bytes.readBigUInt64BE(index*8); result[key] = options?.bigint ? n : Number(n); });
+  for (const [name, index] of [["mtime", 7], ["ctime", 9]]) {
+    const seconds = bytes.readBigInt64BE(index * 8);
+    const nanoseconds = bytes.readBigUInt64BE((index + 1) * 8);
+    if (nanoseconds >= 1000000000n) throw failure("EIO");
+    const ns = seconds * 1000000000n + nanoseconds;
+    result[`${name}Ms`] = options?.bigint ? ns / 1000000n : Number(seconds) * 1000 + Number(nanoseconds) / 1000000;
+    if (options?.bigint) result[`${name}Ns`] = ns;
+    result[name] = new Date(Number(ns / 1000000n));
+  }
+  const mode = Number(result.mode) & 0o170000;
+  return Object.assign(result, { isFile: () => mode === 0o100000, isDirectory: () => mode === 0o040000,
+    isSymbolicLink: () => mode === 0o120000, isFIFO: () => mode === 0o010000,
+    isSocket: () => mode === 0o140000, isBlockDevice: () => mode === 0o060000, isCharacterDevice: () => mode === 0o020000 });
+}
+export function validatePath(value) { request(13, [canonical(value)]); return true; }
+export function withRollback(callback) {
+  if (rollbackDepth++ === 0) request(14, [1]);
+  try { return callback(); } finally { if (--rollbackDepth === 0) request(14, [0]); }
+}
+export function closeAnchoredFs() {
+  if (service !== null) { service.child.stdin.destroy(); service.child.stdout.destroy(); service.child.kill("SIGKILL"); service = null; }
+}
+const anchored = {
+  constants: fs.constants,
+  lstatSync(value, options) { return statResult(request(1, [canonical(value)]), options); },
+  statSync(value, options) { const result = this.lstatSync(value, options); if (result.isSymbolicLink()) throw failure("ELOOP"); return result; },
+  realpathSync(value) {
+    // Root selection is read-only. Pin the resolved identity immediately; every
+    // subsequent operation uses the helper's retained directory descriptors.
+    const absolute = path.resolve(value); const real = fs.realpathSync(absolute);
+    const prior = aliases.get(absolute);
+    if (prior !== undefined && prior !== real) throw failure("ESTALE");
+    // Freeze both the selected spelling and the capability spelling. A later
+    // root resolution cannot rebind an existing capability to another tree.
+    const pinned = aliases.get(real);
+    if (pinned !== undefined && pinned !== real) throw failure("ESTALE");
+    validatePath(real); aliases.set(real, real); aliases.set(absolute, real); return real;
+  },
+  existsSync(value) { try { this.lstatSync(value); return true; } catch (error) { if (["ENOENT", "ENOTDIR"].includes(error.code)) return false; throw error; } },
+  openSync(value, flags, mode = 0o666) {
+    let kind;
+    const extras = (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+    const stripped = typeof flags === "number" ? flags & ~extras : flags;
+    if (flags === "r" || stripped === fs.constants.O_RDONLY) kind = 0;
+    else if (flags === "r+" || stripped === fs.constants.O_RDWR) kind = 1;
+    else if (flags === "wx" || flags === "wx+" || stripped === (fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL)) kind = 2;
+    else throw failure("ENOTSUP");
+    return -1001 - request(2, [canonical(value), kind, mode]).readUInt32BE();
+  },
+  fstatSync(fd, options) { return statResult(request(3, [descriptor(fd)]), options); },
+  readFileSync(value, options) {
+    const own = typeof value !== "number"; const fd = own ? this.openSync(value, "r") : value;
+    try { const bytes = request(4, [descriptor(fd)]); const encoding = typeof options === "string" ? options : options?.encoding; return encoding ? bytes.toString(encoding) : bytes; }
+    finally { if (own) this.closeSync(fd); }
+  },
+  readSync(fd, buffer, offset, length, position) {
+    const bytes = request(16, [descriptor(fd), length, position ?? 0]); bytes.copy(buffer, offset); return bytes.length;
+  },
+  writeFileSync(fd, value, options) {
+    if (typeof fd !== "number") throw failure("ENOTSUP");
+    const encoding = typeof options === "string" ? options : options?.encoding;
+    request(5, [descriptor(fd)], Buffer.isBuffer(value) ? value : Buffer.from(value, encoding));
+  },
+  fchmodSync(fd, mode) { request(6, [descriptor(fd), mode]); },
+  chmodSync(value, mode) { const fd = this.openSync(value, "r"); try { this.fchmodSync(fd, mode); } finally { this.closeSync(fd); } },
+  fsyncSync(fd) { request(7, [descriptor(fd)]); },
+  closeSync(fd) { request(8, [descriptor(fd)]); },
+  mkdirSync(value, options = {}) {
+    const absolute = canonical(value); const mode = typeof options === "number" ? options : options.mode ?? 0o777;
+    try { request(9, [absolute, mode]); }
+    catch (error) {
+      if (!options.recursive) throw error;
+      if (error.code === "ENOENT") { this.mkdirSync(path.dirname(absolute), {recursive:true, mode}); request(9, [absolute, mode]); }
+      else if (error.code !== "EEXIST" || !this.statSync(absolute).isDirectory()) throw error;
+    }
+  },
+  renameSync(from, to) { request(10, [canonical(from), canonical(to)]); },
+  unlinkSync(value) { request(11, [canonical(value)]); },
+  rmdirSync(value) { request(12, [canonical(value)]); },
+  linkSync(from, to) { request(15, [canonical(from), canonical(to)]); },
+};
+export default anchored;

package/src/args.js

@@ -39,13 +39,24 @@ import {
   USAGE_DIMENSIONS,
   USAGE_MAX_FILTER_VALUES,
   USAGE_SORTS,
+  WORKFLOW_PERMISSIONS,
 } from "./constants.js";
 import { parseOrigin } from "./origin.js";
 import { groupedRequest, hasUnsafeText, isCursor, isSafeFilter, readQuery } from "./read-contract.js";
+import { TOOL_ARGS_MAX_BYTES, TOOL_NAME } from "./tools.js";
 
 export const READ_COMMANDS = Object.freeze(["status", "context", "capabilities", "usage", "routes", "traces"]);
-const COMMANDS = new Set(["pricing", "doctor", "help", "skill", "skills", "login", "logout", "setup", "verify", "experiments", ...READ_COMMANDS]);
-const HELP_TOPICS = new Set(["pricing", "doctor", "skill", "skills", "login", "logout", "setup", "verify", "experiments", ...READ_COMMANDS]);
+const COMMANDS = new Set(["pricing", "doctor", "help", "skill", "skills", "login", "logout", "setup", "verify", "experiments", "tools", ...READ_COMMANDS]);
+const HELP_TOPICS = new Set(["agents", "exit-codes", "pricing", "doctor", "skill", "skills", "login", "logout", "setup", "verify", "experiments", "tools", ...READ_COMMANDS]);
+export const TOOLS_ACTIONS = Object.freeze(["list", "call"]);
+// The roles login asks for: Metadata, or Debug, to which --allow-* adds the
+// workflow permissions a workspace owner approves. Replay is never asked for.
+export const LOGIN_ROLES = Object.freeze(["metadata", "debug"]);
+// Each --allow-* switch and the scope it asks for, by the names bin/agent-key
+// and the Keys page use.
+const LOGIN_PERMISSIONS = Object.freeze(
+  WORKFLOW_PERMISSIONS.map(({ field, scope }) => [`--${field.replaceAll("_", "-")}`, scope]),
+);
 export const EXPERIMENT_ACTIONS = Object.freeze(["list", "estimate", "start", "get"]);
 const SKILL_ACTIONS = new Set(["install", "update"]);
 const SKILLS_ACTIONS = new Set(["install", "update", "list"]);
@@ -59,7 +70,7 @@ const OPTIONS = {
   doctor: new Set(["--url", "--timeout-ms"]),
   skill: new Set(["--client", "--runtime", "--project"]),
   skills: new Set(["--client", "--runtime", "--project"]),
-  login: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--timeout-ms"]),
+  login: new Set(["--runtime", "--url", "--workspace", "--role", "--project", "--config-dir", "--timeout-ms"]),
   setup: new Set(["--runtime", "--url", "--workspace", "--project", "--config-dir", "--env-file", "--client", "--timeout-ms", "--deployment", "--agent-token-file", "--repository"]),
   logout: new Set(["--project", "--config-dir"]),
   status: new Set([...READ_BASE, ...READ_KEY]),
@@ -77,6 +88,7 @@ const OPTIONS = {
   experiments: new Set([
     ...READ_BASE, ...READ_KEY, "--workload", "--limit", "--treatment", "--last-n", "--sample-model", "--track", "--id",
   ]),
+  tools: new Set([...READ_BASE, ...READ_KEY, "--name", "--args", "--args-file"]),
 };
 // Which experiments options each action takes, beyond READ_BASE and READ_KEY.
 const EXPERIMENT_OPTIONS = {
@@ -129,10 +141,11 @@ const USAGE_GROUPED = [
 // Options that take no value.
 const FLAGS = {
   pricing: new Set(["--batch"]),
-  login: new Set(["--signup", "--no-browser", "--reconnect"]),
+  login: new Set(["--signup", "--no-browser", "--reconnect", ...LOGIN_PERMISSIONS.map(([flag]) => flag)]),
   setup: new Set(["--no-browser", "--repair", "--signup", "--reconnect", "--skip-skill", "--confirm-prerequisites", "--no-repository"]),
   verify: new Set(["--open", "--no-browser"]),
   usage: new Set(["--today"]),
+  tools: new Set(["--yes"]),
 };
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
@@ -156,13 +169,24 @@ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export function parseArgs(argv) {
   const json = argv.includes("--json");
 
-  if (argv.includes("--help") || argv.includes("-h")) {
-    const topic = argv.find((arg) => HELP_TOPICS.has(arg)) ?? null;
-    return { ok: true, command: "help", topic, json };
+  const helpCommand = argv.find(arg => arg !== "--json") === "help";
+  if (argv.includes("--help") || argv.includes("-h") || helpCommand) {
+    const parts = argv.filter(arg => !["--json", "--help", "-h", "--advanced"].includes(arg));
+    if (parts[0] === "help") parts.shift();
+    const topic = HELP_TOPICS.has(parts[0]) ? parts[0] : null;
+    const actions = { pricing: PRICING_ACTIONS, experiments: EXPERIMENT_ACTIONS,
+      skill: [...SKILL_ACTIONS], skills: [...SKILLS_ACTIONS] };
+    const action = actions[topic]?.includes(parts[1]) ? parts[1] : null;
+    if (helpCommand && (parts.length > (action ? 2 : topic ? 1 : 0))) {
+      return { ok: false, command: "help", json, code: "unknown_help_topic", outcome: "invalid_input",
+        message: 'Unknown help topic. Run "metergraph --help" for commands.' };
+    }
+    return { ok: true, command: "help", topic, ...(action ? { action } : {}), ...(argv.includes("--advanced") ? { advanced: true } : {}), json };
   }
 
   let command = null;
   let action = null;
+  let toolName = null;
   let topic = null;
   let version = false;
   const values = {};
@@ -170,7 +194,7 @@ export function parseArgs(argv) {
 
   const fail = (code, message, outcome = "invalid_input") => ({
     ok: false,
-    command: (command === "skill" || command === "skills" || command === "experiments") && action !== null
+    command: (command === "skill" || command === "skills" || command === "experiments" || command === "tools") && action !== null
       ? `${command} ${action}`
       : command ?? (version ? "version" : null),
     json,
@@ -213,6 +237,14 @@ export function parseArgs(argv) {
       action = arg;
       continue;
     }
+    if (command === "tools" && action === null && TOOLS_ACTIONS.includes(arg)) {
+      action = arg;
+      continue;
+    }
+    if (command === "tools" && action === "call" && toolName === null && !arg.startsWith("-")) {
+      toolName = arg;
+      continue;
+    }
 
     if (READ_COMMANDS.includes(command)) {
       const equals = arg.indexOf("=");
@@ -280,6 +312,9 @@ export function parseArgs(argv) {
         `Unknown experiments subcommand at argument ${position}. Use list, estimate, start or get.`,
       );
     }
+    if (command === "tools" && action === null && !arg.startsWith("-")) {
+      return fail("unknown_subcommand", `Unknown tools subcommand at argument ${position}. Use list or call.`);
+    }
     return fail(
       "unknown_argument",
       `Unrecognized argument at position ${position}. Run "metergraph --help" for usage.`,
@@ -297,6 +332,7 @@ export function parseArgs(argv) {
   if (command === "setup") return parseSetup(values, flags, json, fail);
   if (command === "verify") return parseVerify(values, flags, json, fail);
   if (command === "experiments") return parseExperiments(action, values, json, fail);
+  if (command === "tools") return parseTools(action, toolName, values, flags, json, fail);
   if (READ_COMMANDS.includes(command)) return parseRead(command, values, flags, json, fail);
   if (command === "logout") {
     const paths = parsePaths(values, fail);
@@ -322,16 +358,29 @@ export function parseArgs(argv) {
 
 // --url, --workspace and --agent-token-file, shared by the read commands and
 // experiments: { ok: true, origin, workspace, agentTokenFile } or a failure.
+// --workspace names a workspace by its slug (on its Settings page, and in
+// "metergraph context"), by its name, or by its ID. Returns { workspace,
+// workspaceText }: workspace is an ID, workspaceText a slug or name, which is
+// matched against the workspace the service reports. null for a bad value.
+function workspaceOption(raw) {
+  if (raw === undefined) return { workspace: null, workspaceText: null };
+  if (UUID.test(raw)) return { workspace: raw.toLowerCase(), workspaceText: null };
+  const text = raw.trim();
+  if (text.length === 0 || text.length > MAX_WORKSPACE_TEXT || hasUnsafeText(text)) return null;
+  return { workspace: null, workspaceText: text };
+}
+const MAX_WORKSPACE_TEXT = 200;
+const INVALID_WORKSPACE =
+  "--workspace takes the workspace's slug, shown on its Settings page and by \"metergraph context\", or its name.";
+
 function parseKeyTarget(values, fail) {
   let origin = null;
   if (values["--url"] !== undefined) {
     origin = parseOrigin(values["--url"]);
     if (origin === null) return fail("invalid_url", INVALID_URL);
   }
-  const rawWorkspace = values["--workspace"];
-  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
-    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
-  }
+  const named = workspaceOption(values["--workspace"]);
+  if (named === null) return fail("invalid_workspace", INVALID_WORKSPACE);
   const agentTokenFile = values["--agent-token-file"] ?? null;
   if (agentTokenFile !== null && (agentTokenFile === "" || agentTokenFile.includes("\0"))) {
     return fail("invalid_agent_token_file", "--agent-token-file must name a private absolute file.");
@@ -339,11 +388,61 @@ function parseKeyTarget(values, fail) {
   return {
     ok: true,
     origin,
-    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    ...named,
     agentTokenFile,
   };
 }
 
+// tools list [--name TOOL] | call TOOL [--args JSON | --args-file PATH] [--yes].
+// The credential options are the read commands'. Arguments are checked for
+// shape only; the service validates them against the tool's schema.
+function parseTools(action, toolName, values, flags, json, fail) {
+  if (action === null) {
+    return fail("missing_subcommand", 'tools requires a subcommand: list or call. Run "metergraph help tools" for usage.');
+  }
+  const allowed = action === "list" ? ["--name"] : ["--args", "--args-file"];
+  for (const name of Object.keys(values)) {
+    if (!READ_BASE.includes(name) && !READ_KEY.includes(name) && !allowed.includes(name)) {
+      return fail("unknown_argument", `tools ${action} does not take ${name}. Run "metergraph help tools" for usage.`);
+    }
+  }
+  if (action === "list" && flags.has("--yes")) {
+    return fail("unknown_argument", 'tools list does not take --yes. Run "metergraph help tools" for usage.');
+  }
+  const name = action === "list" ? values["--name"] ?? null : toolName;
+  if (action === "call" && name === null) {
+    return fail("missing_tool", 'tools call needs a tool name, such as metergraph_list_classified_workloads. Run "metergraph tools list" to see them.');
+  }
+  if (name !== null && !TOOL_NAME.test(name)) {
+    return fail("invalid_tool", "A tool name is metergraph_ followed by lower case letters, digits and underscores.");
+  }
+  if (values["--args"] !== undefined && values["--args-file"] !== undefined) {
+    return fail("conflicting_options", "Give --args or --args-file, not both.");
+  }
+  if (values["--args"] !== undefined && Buffer.byteLength(values["--args"]) > TOOL_ARGS_MAX_BYTES) {
+    return fail("args_too_large", "--args is larger than 1 MiB. Use --args-file.");
+  }
+  if (values["--args-file"] !== undefined && (values["--args-file"] === "" || values["--args-file"].includes("\0"))) {
+    return fail("invalid_args_file", "--args-file must name a file.");
+  }
+  const paths = parsePaths(values, fail);
+  if (!paths.ok) return paths;
+  const rawTimeout = values["--timeout-ms"];
+  const timeoutMs = rawTimeout === undefined
+    ? READ_DEFAULT_TIMEOUT_MS
+    : parseTimeout(rawTimeout, READ_MIN_TIMEOUT_MS, READ_MAX_TIMEOUT_MS);
+  if (timeoutMs === null) {
+    return fail("invalid_timeout", `--timeout-ms must be a whole number from ${READ_MIN_TIMEOUT_MS} to ${READ_MAX_TIMEOUT_MS}.`);
+  }
+  const target = parseKeyTarget(values, fail);
+  if (!target.ok) return target;
+  delete target.ok;
+  return {
+    ok: true, command: "tools", action, ...target, project: paths.project, configDir: paths.configDir, timeoutMs, json,
+    tool: { name, args: values["--args"] ?? null, argsFile: values["--args-file"] ?? null, yes: flags.has("--yes") },
+  };
+}
+
 // experiments list | estimate | start | get. estimate and start take the same
 // request, so an agent starts exactly what it priced: the workload, 1 to 3
 // --treatment PROVIDER/MODEL[,label=..][,temperature=..][,max_tokens=..]
@@ -596,9 +695,16 @@ function parseLogin(values, flags, json, fail) {
   }
   const origin = parseUrlOption(values);
   if (origin === null) return fail("invalid_url", INVALID_URL);
-  const rawWorkspace = values["--workspace"];
-  if (rawWorkspace !== undefined && !UUID.test(rawWorkspace)) {
-    return fail("invalid_workspace", "--workspace must be a workspace ID in UUID form.");
+  const named = workspaceOption(values["--workspace"]);
+  if (named === null) return fail("invalid_workspace", INVALID_WORKSPACE);
+  const role = values["--role"] ?? "metadata";
+  if (!LOGIN_ROLES.includes(role)) return fail("invalid_role", "--role must be metadata or debug.");
+  const permissions = LOGIN_PERMISSIONS.filter(([flag]) => flags.has(flag)).map(([, scope]) => scope);
+  if (permissions.length > 0 && role !== "debug") {
+    return fail(
+      "permission_needs_debug",
+      "--allow-evaluation-writes, --allow-evaluation-previews and --allow-analysis-starts need --role debug.",
+    );
   }
   const paths = parsePaths(values, fail);
   if (!paths.ok) return paths;
@@ -618,7 +724,9 @@ function parseLogin(values, flags, json, fail) {
     command: "login",
     runtime,
     origin,
-    workspace: rawWorkspace === undefined ? null : rawWorkspace.toLowerCase(),
+    ...named,
+    role,
+    permissions,
     project: paths.project,
     configDir: paths.configDir,
     timeoutMs,

package/src/auth-binding.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import fs from "node:fs";
+import fs, { withRollback } from "./anchored-fs.js";
 import path from "node:path";
 
 import { Stop, isSlot } from "./auth-store.js";
@@ -8,8 +8,9 @@ import { parseOrigin } from "./origin.js";
 
 // The project binding, .metergraph/project.json, names which origin,
 // workspace and profile a project is signed in to and which credential slot
-// in the user's private store holds the grant. It holds no credential, user
-// name or absolute path, so it is safe to commit. Other files in .metergraph,
+// in the user's private store holds the grant. The private grant also pins the
+// canonical checkout, so copying this file never adopts or revokes that grant.
+// It holds no credential, user name or absolute path. Other files in .metergraph,
 // such as skill receipts, are never touched.
 
 export const BINDING_PATH = ".metergraph/project.json";
@@ -25,7 +26,8 @@ export function resolveProject(project) {
   try {
     const real = fs.realpathSync(path.resolve(project ?? process.cwd()));
     if (fs.statSync(real).isDirectory()) return real;
-  } catch {
+  } catch (error) {
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     // Fall through to the fixed error.
   }
   throw new Stop("invalid_input", "invalid_project");
@@ -44,6 +46,7 @@ export function readBinding(root) {
     return { binding, content };
   } catch (error) {
     if (error instanceof Stop) throw error;
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     throw new Stop("filesystem_error", "read_failed");
   }
 }
@@ -82,12 +85,13 @@ export function writeBinding(root, binding, previous) {
   } catch (error) {
     if (created) {
       try {
-        fs.rmdirSync(dir);
+        withRollback(() => fs.rmdirSync(dir));
       } catch {
         // Not empty. An empty directory is harmless.
       }
     }
     if (error instanceof Stop) throw error;
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     throw new Stop("filesystem_error", "binding_write_failed");
   }
 }
@@ -102,6 +106,7 @@ export function removeBinding(root, previous) {
     });
   } catch (error) {
     if (error instanceof Stop) throw error;
+    if (error.code === "ENOTSUP") throw new Stop("unsupported", "secure_writes_unavailable");
     throw new Stop("filesystem_error", "binding_write_failed");
   }
 }
@@ -118,7 +123,7 @@ function withProjectLock(dir, work) {
     return work();
   } finally {
     try {
-      fs.unlinkSync(lock);
+      withRollback(() => fs.unlinkSync(lock));
     } catch {
       // Reported by the next run as a held lock.
     }
@@ -145,7 +150,7 @@ function replace(dir, content) {
     fs.renameSync(temp, dest);
   } catch (error) {
     try {
-      fs.unlinkSync(temp);
+      withRollback(() => fs.unlinkSync(temp));
     } catch {
       // Already renamed or never created.
     }

package/src/auth-callback.js

@@ -19,6 +19,9 @@ const ALLOWED_PARAMS = new Set(["code", "state", "error", "error_description", "
 // The setup receipt a combined sign-in approval returns next to the code.
 // Accepted only by a wait that asked for it.
 export const SETUP_CODE_PARAM = "ingest_setup_code";
+// The fixed error_description values a consent page sends when the workspace
+// the CLI named matches none, or more than one, of the person's workspaces.
+const HINT_REFUSALS = ["workspace_hint_ambiguous", "workspace_hint_unknown"];
 
 const PAGE_HEADERS = {
   "content-type": "text/html; charset=utf-8",
@@ -39,7 +42,11 @@ const PAGE_HEADERS = {
 //     { kind: "code", code[, setupCode] } setupCode, the ingest_setup_code
 //                                         value, only when wait() was given
 //                                         acceptSetupCode and it was sent
-//     { kind: "denied" }                  the user or server declined
+//     { kind: "denied", hint }            the user or server declined; hint
+//                                         is workspace_hint_ambiguous or
+//                                         workspace_hint_unknown when the
+//                                         consent page refused the workspace
+//                                         the CLI named, else null
 //     { kind: "error", reason }           authorization_error,
 //                                         callback_issuer_mismatch or
 //                                         callback_invalid
@@ -163,8 +170,9 @@ function inspect(request, { host, state, issuer, requireIss, acceptSetupCode })
     if (seen.has("code") || seen.has(SETUP_CODE_PARAM)) {
       return { status: 400, result: { kind: "error", reason: "callback_invalid" } };
     }
+    const description = params.get("error_description");
     return params.get("error") === "access_denied"
-      ? { status: 200, result: { kind: "denied" } }
+      ? { status: 200, result: { kind: "denied", hint: HINT_REFUSALS.includes(description) ? description : null } }
       : { status: 200, result: { kind: "error", reason: "authorization_error" } };
   }
   const code = params.get("code");