metergraph-cli 0.2.3 → 0.2.5

package/src/read-contract.js

@@ -1,4 +1,4 @@
-import { normalizeUuid } from "./auth-oauth.js";
+import { credentialAccess, normalizeUuid } from "./auth-oauth.js";
 import {
   AGENT_CONTRACT_VERSION,
   MAX_CURSOR_LENGTH,
@@ -17,7 +17,8 @@ import { traceLink } from "./trace-contract.js";
 // with fixed tokens. notices is a Set that collects fixed notice tokens.
 
 // Every capability name the contract defines. Content, replay and start
-// entries are never available to a Metadata grant.
+// entries are never available to a Metadata grant; a Debug credential with
+// workflow permissions may be offered content and starts.
 export const CAPABILITY_NAMES = Object.freeze([
   "workspace_context",
   "capability_discovery",
@@ -1111,6 +1112,33 @@ export function combinePages(pages) {
   };
 }
 
+const SLUG = /^[a-z0-9][a-z0-9-]{1,62}$/;
+const MAX_WORKSPACE_NAME = 200;
+
+// A workspace document's slug and name, each kept only when it is safe to
+// print (a well-formed slug; a name with no control or bidirectional
+// characters), else null. This is how output names a workspace: never by ID.
+export function workspaceLabel(workspace) {
+  const slug = typeof workspace?.slug === "string" && SLUG.test(workspace.slug) ? workspace.slug : null;
+  const raw = workspace?.name;
+  const name = typeof raw === "string" && raw.trim() !== "" && raw.length <= MAX_WORKSPACE_NAME && !hasUnsafeText(raw)
+    ? raw : null;
+  return { slug, name };
+}
+
+// Whether a workspace document is the one a person named with --workspace.
+// Slugs are unique, names are not, and anyone who owns a workspace chooses
+// its name, including a workspace a person was invited to. So the match is
+// strict, for sign in and for every credential pin: text shaped like a slug
+// matches only the slug, and other text only the exact name, ignoring case.
+export function workspacePinned(workspace, text) {
+  const { slug, name } = workspaceLabel(workspace);
+  const wanted = text.trim().toLowerCase();
+  if (SLUG.test(wanted)) return slug === wanted;
+  return name !== null && name.trim().toLowerCase() === wanted;
+}
+
+
 // GET /v1/agent/workspace, already checked by checkWorkspace during the
 // session. Returns the approved workspace fields only.
 export function workspaceContext(body, ctx, notices) {
@@ -1128,7 +1156,8 @@ export function workspaceContext(body, ctx, notices) {
       throw new Invalid("verification_failed", "content_access_granted");
     }
     const scopes = body.access?.scopes;
-    if (!Array.isArray(scopes) || scopes.length !== 1 || scopes[0] !== METADATA_SCOPE) {
+    const access = credentialAccess(scopes);
+    if (access === null || access !== (ctx.access ?? "metadata")) {
       throw new Invalid("verification_failed", "scope_mismatch");
     }
     return {
@@ -1141,12 +1170,15 @@ export function workspaceContext(body, ctx, notices) {
       },
       retention: { metadata_days: body.retention.metadata_days },
       content: { captured: body.content.captured, included: false },
-      access: { scopes: [METADATA_SCOPE] },
+      access: { scopes: [...scopes].sort() },
     };
   });
 }
 
-function capabilityEntry(entry, reason) {
+// access is the credential's: a Metadata credential is never offered a
+// sensitive capability; a Debug credential may be, and read commands still
+// never use one.
+function capabilityEntry(entry, reason, access = "metadata") {
   if (
     !isObject(entry) ||
     typeof entry.available !== "boolean" ||
@@ -1166,8 +1198,10 @@ function capabilityEntry(entry, reason) {
     entry.privacy_class === "metadata" &&
     entry.required_scope === METADATA_SCOPE;
   // checkCapabilities already refuses this; it is checked again here so a
-  // summary can never show a sensitive capability as available.
-  if (!metadataOnly && entry.available) throw new Invalid("verification_failed", "content_access_granted");
+  // summary can never show a sensitive capability as available to Metadata.
+  if (!metadataOnly && entry.available && access === "metadata") {
+    throw new Invalid("verification_failed", "content_access_granted");
+  }
   return {
     available: entry.available,
     content: entry.content,
@@ -1194,7 +1228,7 @@ export function capabilitySummary(body, ctx, notices) {
     if (!isObject(body.agent)) throw new Invalid("verification_failed", reason);
     const agent = {};
     for (const name of CAPABILITY_NAMES) {
-      agent[name] = Object.hasOwn(body.agent, name) ? capabilityEntry(body.agent[name], reason) : null;
+      agent[name] = Object.hasOwn(body.agent, name) ? capabilityEntry(body.agent[name], reason, ctx.access) : null;
     }
     if (Object.keys(body.agent).some((name) => !CAPABILITY_NAMES.includes(name))) {
       notices.add("unrecognized_capabilities_ignored");

package/src/read-output.js

@@ -1,5 +1,6 @@
+import { WORKFLOW_PERMISSIONS } from "./constants.js";
 import { authMessage } from "./output.js";
-import { PLAIN, fields, headline, paragraph, render, steps, toneFor } from "./style.js";
+import { PLAIN, fields, headline, paragraph, render, steps, toneFor, workspaceShown } from "./style.js";
 
 // Fixed text for read command reasons and notices. Reasons shared with sign
 // in and doctor fall back to their wording. Nothing here contains a value from
@@ -7,18 +8,18 @@ import { PLAIN, fields, headline, paragraph, render, steps, toneFor } from "./st
 
 const READ_MESSAGES = {
   not_signed_in:
-    'This project is not signed in and no Metadata key was given. Run "metergraph login --runtime local" first, ' +
-    "or, where browser sign in cannot finish, give the CLI a coding-agent key with Metadata access in " +
-    "METERGRAPH_AGENT_TOKEN.",
+    'This project is not signed in and no coding-agent key was given. Run "metergraph login --runtime local" first, ' +
+    "or, where browser sign in cannot finish, give the CLI a coding-agent key with the Metadata or Debug role " +
+    "in METERGRAPH_AGENT_TOKEN.",
   agent_key_rejected:
-    "The service refused the Metadata key: it is unknown, expired or revoked. Nothing was read.",
+    "The service refused the coding-agent key: it is unknown, expired or revoked. Nothing was read.",
   agent_key_insufficient_scope:
     "The key is valid but lacks Metadata access to this workspace, for example because it is an ingest key. " +
     "No broader access was requested. Nothing was read.",
   agent_token_malformed:
     "METERGRAPH_AGENT_TOKEN does not hold exactly one key with no label, spaces or extra lines. Its value is not " +
     "shown. Nothing was sent.",
-  agent_token_missing: "No Metadata key was found. Nothing was sent.",
+  agent_token_missing: "No coding-agent key was found. Nothing was sent.",
   metergraph_url_invalid:
     "METERGRAPH_URL is not a bare https origin, or an http origin on localhost. Its value is not shown. Nothing was sent.",
   bound_to_other_origin:
@@ -28,13 +29,14 @@ const READ_MESSAGES = {
     "This project's binding names a non-hosted origin, and a key is never sent to an origin taken only from a " +
     "project file. Set METERGRAPH_URL or pass --url with the same origin to confirm it. Nothing was sent.",
   scope_mismatch:
-    "The credential is not limited to exactly the Metadata scope, so it was not used. The CLI never uses broader access.",
+    "The credential has Replay access or a scope this CLI does not use, so it was not used. Use a credential with " +
+    "the Metadata or Debug role.",
   content_access_granted:
-    "The credential would allow content, replay or provider access, so it was not used. The CLI never uses broader access.",
+    "The service offered content, replay or provider access to a Metadata credential, so it was not used.",
   platform_credential_handoff:
     "--agent-token-file cannot be checked for privacy on this platform. Use METERGRAPH_AGENT_TOKEN instead.",
   capability_unavailable:
-    "The service does not offer this read to the project's Metadata grant. No data was read and no broader access was requested.",
+    "The service does not offer this read to this credential. No data was read and no broader access was requested.",
   exceeds_service_bounds:
     "The requested --days or --limit is larger than the service allows. It was not reduced automatically. No data was read.",
   insufficient_scope: "The service refused this read because the grant lacks a required scope. No broader scope was requested.",
@@ -279,7 +281,7 @@ export function readText(result, message, style = PLAIN) {
     statusRows(data, rows);
     lines.push(...fields(style, rows));
   } else {
-    rows.push(["Workspace", data.workspace?.id ?? null]);
+    rows.push(["Workspace", workspaceShown(data.workspace)]);
     if (result.ok) {
       const body = [];
       resultLines(result.command, data.result, body);
@@ -325,16 +327,30 @@ export function readText(result, message, style = PLAIN) {
       ["Connection guide", handoff ? next.url : null],
     ]));
   }
+  const access = result.command === "status" && result.ok ? data.access : null;
+  const step = access && !allPermissions(access) && access.permissions_offered !== false
+    ? permissionsStep(data.deployment_profile)
+    : null;
+  if (step !== null) lines.push("", ...steps(style, [["", `${PERMISSIONS_NEEDED} ${step}`]]));
   return render(lines);
 }
 
+// The verified workspace by name and slug, and whether it is the bound one.
+function statusWorkspace(workspace) {
+  const shown = workspaceShown(workspace);
+  if (workspace.actual === null) return workspace.intended === null ? "none" : "bound, not verified";
+  const name = shown ?? "verified";
+  if (workspace.match === false) return `${name}, which is not the workspace this project is bound to`;
+  return workspace.match === true ? `${name}, the bound workspace` : name;
+}
+
 function statusRows(data, rows) {
   rows.push(
     ["Configured", data.configured ? "yes" : "no"],
-    ["Credential", { oauth_grant: "saved sign in", agent_key: "Metadata key" }[data.credential] ?? "none"],
+    ["Credential", { oauth_grant: "saved sign in", agent_key: "coding-agent key" }[data.credential] ?? "none"],
     ["Reachable", yesNo(data.reachable)],
     ["Authenticated", data.authenticated ? "yes, verified by the service" : "no"],
-    ["Workspace", `bound ${show(data.workspace.intended)}, verified ${show(data.workspace.actual)}`],
+    ["Workspace", statusWorkspace(data.workspace)],
     ["Deployment profile", `bound ${show(data.deployment_profile)}, reported by the service: ${
       data.deployment_profile_verified === true
         ? "same"
@@ -348,12 +364,49 @@ function statusRows(data, rows) {
     const flag = (name) => yesNo(data.capabilities[name]);
     rows.push(
       ["Metadata reads", `usage ${flag("usage")}, routes ${flag("routes")}, traces ${flag("trace_metadata")}`],
-      ["Content and replay", "not available to this grant"],
+      ["Content", data.content_access
+        ? "available to this credential; the read commands never request it"
+        : "not available to this credential"],
     );
   }
+  if (data.access) rows.push(["Role", ROLE_LABELS[data.access.role] ?? "none"], ["Permissions", permissionsText(data.access)]);
   rows.push(["Application traffic verified", "no"]);
 }
 
+// The role and permission labels the Keys and consent pages use.
+const ROLE_LABELS = { metadata: "Metadata", debug: "Debug" };
+
+const PERMISSIONS_NEEDED =
+  "Writing and testing evaluations and starting analyses need the Debug role with Allow evaluation writes, " +
+  "Allow evaluation previews and Allow analysis starts.";
+
+const allPermissions = (access) =>
+  access.role === "debug" && WORKFLOW_PERMISSIONS.every(({ field }) => access.permissions[field] === true);
+
+function permissionsText(access) {
+  if (access.permissions_offered === false) return "not offered by this deployment";
+  const granted = WORKFLOW_PERMISSIONS.filter(({ field }) => access.permissions[field] === true);
+  return granted.length > 0 ? granted.map(({ label }) => label).join(", ") : "none";
+}
+
+// How a person gives this agent Debug with all three permissions, by
+// deployment. Fixed text: no value from the service is printed.
+export function permissionsStep(profile) {
+  if (profile === "local") {
+    return "From the bundle directory, a workspace owner runs ./bin/agent-key create --role debug " +
+      "--allow-evaluation-writes --allow-evaluation-previews --allow-analysis-starts " +
+      "--write-to ~/.config/metergraph/agent.env, then loads that file in the shell that starts the agent.";
+  }
+  if (profile === "managed") {
+    return 'Run "metergraph login --runtime local --role debug --allow-evaluation-writes ' +
+      '--allow-evaluation-previews --allow-analysis-starts"; a workspace owner approves it in the browser. ' +
+      'Or a workspace owner creates a coding-agent key on the Keys page, choosing "Debug with all three ' +
+      'permissions" under Access, saved as METERGRAPH_AGENT_TOKEN in a private file outside the project. ' +
+      "Do not paste a key into chat.";
+  }
+  return null;
+}
+
 function resultLines(command, report, lines) {
   if (command === "context") {
     const { workspace } = report;

package/src/read.js

@@ -2,12 +2,22 @@ import { agentKeySource, keySession, keyTarget, readAgentKey } from "./agent-key
 import { readBinding, resolveProject } from "./auth-binding.js";
 import { checkDeployment } from "./doctor.js";
 import { sessionFor } from "./auth-session.js";
-import { Stop, openStore, readCredential, resolveConfigDir } from "./auth-store.js";
-import { DEFAULT_ORIGIN, MAX_BODY_BYTES, METADATA_SCOPE, READ_MAX_BYTES, READ_MAX_LIMIT, READ_PATHS } from "./constants.js";
+import { Stop, openStore, readProjectCredential, resolveConfigDir } from "./auth-store.js";
+import {
+  DEFAULT_ORIGIN,
+  MAX_BODY_BYTES,
+  READ_MAX_BYTES,
+  READ_MAX_LIMIT,
+  READ_PATHS,
+  WORKFLOW_DEPLOYMENT_CAPABILITY,
+  WORKFLOW_PERMISSIONS,
+} from "./constants.js";
 import { parseJsonObject } from "./http.js";
 import {
   readQuery,
   groupedRequest,
+  workspaceLabel,
+  workspacePinned,
   READ_ENVIRONMENTS,
   CAPABILITY_NAMES,
   capabilitySummary,
@@ -20,6 +30,7 @@ import {
 import { compareReports, priorWindow, rankReport } from "./usage-aggregates.js";
 import { deadline, failureOf, send, trapSignals } from "./transport.js";
 import { experimentNextAction, experimentRead } from "./experiments.js";
+import { readArguments, toolsNextAction, toolsRead } from "./tools.js";
 import { agentKeyAction, classifyEnvironment, handoffPages } from "./environment.js";
 
 // The read commands: status, context, capabilities, usage, routes and traces.
@@ -61,6 +72,11 @@ export async function runRead(options) {
     healthy: null,
     profileVerified: null,
     authenticated: false,
+    // The credential's access ("metadata" or "debug") and scopes, once verified.
+    access: null,
+    scopes: [],
+    // The verified workspace's slug and name, for output. Never its ID.
+    workspaceLabel: { slug: null, name: null },
     verifiedWorkspace: null,
     capabilities: null,
   };
@@ -82,13 +98,16 @@ export async function runRead(options) {
     if (holdsKnown(data, known)) {
       notices.clear();
       ctx.reason = "credential_in_metadata_response";
+      // The workspace's name or slug may be what echoed the credential.
+      ctx.workspaceLabel = { slug: null, name: null };
       return {
         outcome: "verification_failed",
         reason: "credential_in_metadata_response",
         data: build("verification_failed", null),
+        validateOutput: (text) => !outputHoldsKnown(text, known),
       };
     }
-    return { outcome, reason, data };
+    return { outcome, reason, data, validateOutput: (text) => !outputHoldsKnown(text, known) };
   };
   // A deadline or Ctrl+C reported by a lower layer as a timeout or
   // cancellation is reported here by what actually happened.
@@ -102,6 +121,11 @@ export async function runRead(options) {
   };
 
   try {
+    if (options.command === "tools" && options.action === "call") {
+      const args = readArguments(options.tool);
+      if (!args.ok) return end(args.outcome, args.reason);
+      options = { ...options, toolArguments: args };
+    }
     const root = resolveProject(options.project);
     const configDir = resolveConfigDir(options.configDir);
     const found = readBinding(root);
@@ -116,7 +140,7 @@ export async function runRead(options) {
     if (binding !== null) {
       try {
         store = openStore(configDir, { create: false });
-        const record = store === null ? null : readCredential(store, binding.credential_slot);
+        const record = store === null ? null : readProjectCredential(store, binding.credential_slot, root);
         grantSaved = record !== null;
         originConfirmed = record !== null && record.origin === binding.origin;
       } catch (error) {
@@ -179,18 +203,26 @@ export async function runRead(options) {
     }
 
     const session = useKey
-      ? await keySession({ target, source, env, signal: limit.signal, verifiedProfile })
-      : await sessionFor(binding, store, limit.signal);
+      ? await keySession({ target, source, env, signal: limit.signal, verifiedProfile, access: "read" })
+      : await sessionFor(binding, store, limit.signal, root);
     if (!session.ok) {
       const settled = settle(session);
       return end(settled.outcome, settled.reason);
     }
     ctx.profile = session.session.profile;
+    ctx.access = session.session.access;
+    ctx.scopes = session.session.scopes;
+    known = session.knownCredentials;
+    ctx.workspaceLabel = workspaceLabel(session.documents.workspace?.workspace);
+    // A workspace named by slug or name is checked against the verified one.
+    if (target.workspaceText !== null && !workspacePinned(session.documents.workspace?.workspace, target.workspaceText)) {
+      return end("verification_failed", "workspace_context_mismatch");
+    }
     if (ctx.workspaceId === null) {
       ctx.workspaceId = session.session.workspaceId;
-      notices.add("workspace_not_pinned");
+      if (target.workspaceText === null) notices.add("workspace_not_pinned");
+      else ctx.intendedWorkspace = ctx.workspaceId;
     }
-    known = session.knownCredentials;
     ctx.authenticated = true;
     const { documents } = session;
 
@@ -212,6 +244,15 @@ export async function runRead(options) {
       return end("ok", null, context.value);
     }
     if (options.command === "capabilities") return end("ok", null, capabilities.value);
+    if (options.command === "tools") {
+      const tools = await toolsRead(session.session, options, limit.signal);
+      if (!tools.ok) {
+        if (ctx.credential === "agent_key" && tools.reason === "access_revoked") tools.reason = "agent_key_rejected";
+        const settled = ["refused", "unconfirmed", "action_required"].includes(tools.outcome) ? tools : settle(tools);
+        return end(settled.outcome, settled.reason, tools.report);
+      }
+      return end("ok", null, tools.value);
+    }
     if (options.command === "experiments") {
       const read = await experimentRead(session.session, options, ctx, documents, limit.signal, notices);
       if (!read.ok) {
@@ -351,7 +392,7 @@ export function holdsKnown(value, known) {
 
 const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
-function retryAfterOf(response) {
+export function retryAfterOf(response) {
   const header = response.headers["retry-after"];
   const seconds = typeof header === "string" && RETRY_AFTER.test(header.trim()) ? Number(header.trim()) : null;
   return seconds !== null && seconds <= 86400 ? seconds : null;
@@ -405,16 +446,18 @@ async function fetchRead(session, path, query, signal) {
 function readData(ctx, report, notices, outcome, options, extra = {}) {
   return {
     origin: ctx.origin,
-    workspace: ctx.workspaceId === null ? null : { id: ctx.workspaceId },
+    workspace: ctx.workspaceId === null ? null : { id: ctx.workspaceId, ...ctx.workspaceLabel },
     deployment_profile: ctx.profile,
     environment: ctx.environment.kind,
     credential: ctx.credential,
     authenticated: ctx.authenticated,
-    scopes: ctx.authenticated ? [METADATA_SCOPE] : [],
+    scopes: ctx.authenticated ? ctx.scopes : [],
     result: outcome === "ok" ? report : null,
     retry_after_seconds: outcome === "rate_limited" || report?.retry_after_seconds !== undefined
       ? report?.retry_after_seconds ?? null : null,
     ...(options.command === "experiments" ? { refusal: outcome === "refused" ? report?.refusal ?? null : null } : {}),
+    // A tool's own error document, as the service returned it.
+    ...(options.command === "tools" ? { tool_error: outcome === "refused" ? report?.tool_error ?? null : null } : {}),
     notices: [...notices].sort(),
     next_action: nextAction(outcome, ctx, options, extra),
   };
@@ -446,17 +489,38 @@ function statusData(ctx, notices, outcome, options) {
         ctx.verifiedWorkspace === null || ctx.intendedWorkspace === null
           ? null
           : ctx.verifiedWorkspace === ctx.intendedWorkspace,
+      // The verified workspace's slug and name, which output shows instead
+      // of either ID.
+      ...ctx.workspaceLabel,
     },
-    scopes: ctx.authenticated ? [METADATA_SCOPE] : [],
+    scopes: ctx.authenticated ? ctx.scopes : [],
     capabilities:
       agent === null ? null : Object.fromEntries(CAPABILITY_NAMES.map((name) => [name, agent[name]?.available ?? null])),
-    content_access: false,
+    // Whether this credential may read content through Agent Access. The
+    // read commands never do, whatever it allows.
+    content_access: agent !== null && Object.values(agent).some((entry) => entry?.available === true && entry.content === true),
+    access: accessFor(ctx),
     application_traffic_verified: false,
     notices: [...notices].sort(),
     next_action: nextAction(outcome, ctx, options),
   };
 }
 
+// The credential's role and workflow permissions, by the names the Keys page
+// uses. Either role reads. Writing and testing evaluations and starting
+// analyses need Debug with all three permissions, on a deployment that offers
+// managed evaluations: permissions_offered is false where it does not, and
+// null when the capabilities were not read.
+export function accessFor(ctx) {
+  if (!ctx.authenticated) return null;
+  const deployment = ctx.capabilities?.deployment_capabilities ?? null;
+  return {
+    role: ctx.access,
+    permissions: Object.fromEntries(WORKFLOW_PERMISSIONS.map(({ field, scope }) => [field, ctx.scopes.includes(scope)])),
+    permissions_offered: deployment === null ? null : deployment.includes(WORKFLOW_DEPLOYMENT_CAPABILITY),
+  };
+}
+
 const NARROW =
   "Narrow the read: a shorter --days or --since/--until window, exact --route, --provider or --model filters, " +
   "fewer --group-by dimensions or a lower --limit.";
@@ -474,6 +538,8 @@ function nextAction(outcome, ctx, options, { grouped = false, report = null } =
   if (outcome === "rate_limited") return { kind: "retry_later", message: "Wait, then run the same command again." };
   const experiment = experimentNextAction(outcome, ctx, options, report);
   if (experiment !== undefined) return experiment;
+  const tool = toolsNextAction(ctx, options);
+  if (tool !== undefined) return tool;
   if (reason === "usage_aggregates_unavailable" || (grouped && reason === "endpoint_unavailable")) {
     // Offer the route-by-day read only when this grant actually has it.
     if (capabilities?.agent?.usage?.available !== true) return null;
@@ -527,8 +593,8 @@ function nextAction(outcome, ctx, options, { grouped = false, report = null } =
       kind: "use_metadata_only_key",
       url: handoffPages(origin).keys_url,
       message:
-        "This key grants more than Metadata access, so the CLI does not use it. Ask the person for a " +
-        "coding-agent key limited to Metadata access.",
+        "This key has Replay access or another scope the CLI does not use. Ask the person for a coding-agent " +
+        "key with the Metadata or Debug role, and to replace the secret.",
     };
   }
   if (keyed && reason === "workspace_context_mismatch") {
@@ -575,3 +641,12 @@ function nextAction(outcome, ctx, options, { grouped = false, report = null } =
   }
   return null;
 }
+
+// The final renderer may join independent service fields or insert styling.
+// Check exact emitted bytes and their terminal-visible equivalent.
+export function outputHoldsKnown(text, known) {
+  const visible = (value) => value.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/[\x00-\x1f\x7f-\x9f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "").normalize("NFKC");
+  return holdsKnown(text, known) || known.some((secret) => visible(text).includes(visible(secret)));
+}

package/src/repository-identity.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import fs from "node:fs";
+import fs, { withRollback } from "./anchored-fs.js";
 import path from "node:path";
 
 // Repository identity for the SDKs: `.metergraph/config.json` with
@@ -157,7 +157,7 @@ function writeNewConfig(root, repository) {
     try { fs.writeFileSync(fd, content); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
     fs.linkSync(temp, dest);
   } finally {
-    try { fs.unlinkSync(temp); } catch { /* already gone */ }
+    try { withRollback(() => fs.unlinkSync(temp)); } catch { /* already gone */ }
   }
 }
 

package/src/setup-env-git.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import fs from "node:fs";
+import fs from "./anchored-fs.js";
 import path from "node:path";
 
 import { Stop } from "./auth-store.js";

package/src/setup-env.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import fs from "node:fs";
+import fs, { validatePath, withRollback } from "./anchored-fs.js";
 import path from "node:path";
 
 import { resolveProject } from "./auth-binding.js";
@@ -62,6 +62,8 @@ const PLANS = new WeakMap();
 const HANDLES = new WeakMap();
 
 export const ENV_MESSAGES = Object.freeze({
+  secure_writes_unavailable:
+    "Secure automatic file writes are unavailable on this platform or the bundled filesystem helper failed verification. Nothing was written.",
   invalid_project: "--project must name an existing directory.",
   env_path_invalid:
     "The env file path is not allowed. Use a project-relative path with forward slashes to a file named .env, .env.<name> or <name>.env.",
@@ -193,12 +195,12 @@ export async function rollbackEnv(handle, { signal = null, waitMs = DEFAULT_WAIT
   if (state === undefined) throw new Stop("internal_error", "invalid_plan");
   checkCancel(signal);
   if (state.journal.length > 0) {
-    const lock = await takeLock(state.lockDir, waitMs, signal);
+    const lock = await takeLock(state.lockDir, waitMs, signal, true);
     try {
       checkCancel(signal);
       deferSignals(() => {
         try {
-          undo(state.journal);
+          withRollback(() => undo(state.journal));
         } catch (error) {
           if (error instanceof Stop && error.outcome === "conflict") throw new Stop("conflict", "rollback_conflict");
           throw new Stop("filesystem_error", "rollback_incomplete");
@@ -352,6 +354,8 @@ function apply(state, updates) {
       }
     }
 
+    validatePath(target.dir);
+    if (ignore !== null) validatePath(state.root);
     const receipt = freeze({
       path: target.rel,
       location: target.location,
@@ -363,7 +367,7 @@ function apply(state, updates) {
     return { receipt, journal };
   } catch (error) {
     try {
-      undo(journal);
+      withRollback(() => undo(journal));
     } catch {
       throw new Stop("filesystem_error", "rollback_incomplete");
     }
@@ -575,7 +579,7 @@ function replaceFile(file, content, { before, mode, protect, reasons, changed })
   } catch (error) {
     if (created) {
       try {
-        fs.unlinkSync(temp);
+        withRollback(() => fs.unlinkSync(temp));
       } catch {
         // Reported by the caller's failure; nothing else to do.
       }
@@ -602,7 +606,7 @@ function syncDir(dir) {
 // An exclusive lock file in the project (or, outside a project, in the env
 // file's directory). A held lock is waited on for at most waitMs, then
 // reported; it is never taken over or removed, even if it looks stale.
-async function takeLock(dir, waitMs, signal) {
+async function takeLock(dir, waitMs, signal, rollback = false) {
   const file = path.join(dir, LOCK);
   const wait = Number.isFinite(waitMs) ? Math.min(Math.max(waitMs, 0), MAX_WAIT_MS) : DEFAULT_WAIT_MS;
   const until = Date.now() + wait;
@@ -610,7 +614,7 @@ async function takeLock(dir, waitMs, signal) {
     checkCancel(signal);
     let fd;
     try {
-      fd = fs.openSync(file, "wx", 0o600);
+      fd = rollback ? withRollback(() => fs.openSync(file, "wx", 0o600)) : fs.openSync(file, "wx", 0o600);
     } catch (error) {
       if (error.code !== "EEXIST") throw fixed(error, "env_write_failed");
       if (Date.now() >= until) throw new Stop("conflict", "env_locked");
@@ -629,8 +633,10 @@ async function takeLock(dir, waitMs, signal) {
 // Removes the lock only if it is still the file this process created.
 function dropLock(lock) {
   try {
-    const stat = fs.lstatSync(lock.file);
-    if (IS_WINDOWS || (stat.dev === lock.dev && stat.ino === lock.ino)) fs.unlinkSync(lock.file);
+    withRollback(() => {
+      const stat = fs.lstatSync(lock.file);
+      if (stat.dev === lock.dev && stat.ino === lock.ino) fs.unlinkSync(lock.file);
+    });
   } catch {
     // Reported by the next run as a held lock.
   }
@@ -670,6 +676,7 @@ function deferSignals(work) {
 // error, which can hold a path, is never passed on.
 function fixed(error, reason) {
   if (error instanceof Stop) return error;
+  if (error?.code === "ENOTSUP") return new Stop("unsupported", "secure_writes_unavailable");
   if (DENIED.has(error?.code)) {
     return new Stop("filesystem_error", reason === "env_read_failed" ? "env_read_denied" : "env_write_denied");
   }

package/src/setup-interactive.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline/promises";
 
+import { parseArgs } from "./args.js";
 import { resolveProject } from "./auth-binding.js";
 import { runDoctor } from "./doctor.js";
 import { classifyEnvironment, handoffPages, shellArg } from "./environment.js";
@@ -50,8 +51,18 @@ const WORKSPACE_QUESTIONS = {
   oss: "Workspace ID",
 };
 
-export function canAsk(argv, { stdin, stdout, env = process.env }) {
-  return !argv.includes("--json") && Boolean(stdin?.isTTY) && Boolean(stdout?.isTTY) && !env.CI;
+export function canAsk(argv, { stdin, stdout, stderr = stdout, env = process.env }) {
+  return !argv.includes("--json") && Boolean(stdin?.isTTY) && Boolean(stdout?.isTTY)
+    && Boolean(stderr?.isTTY) && !classifyEnvironment(env).remote;
+}
+
+// Login needs no client or deployment questions. Only supply the local runtime
+// after the rest of the command validates; callers gate this on canAsk.
+export function fillLoginArgv(argv) {
+  const parsed = parseArgs(argv);
+  if (parsed.command !== "login" || parsed.code !== "missing_runtime") return argv;
+  const candidate = [...argv, "--runtime", "local"];
+  return parseArgs(candidate).ok ? candidate : argv;
 }
 
 // Questions on the terminal. ask resolves with the trimmed answer, or null
@@ -145,7 +156,10 @@ export async function fillSetupArgv(argv, {
   }
 
   if (!has("--client") && !has("--skip-skill")) {
-    const client = await choose(ask, say, "Install the Metergraph skill for which coding agent?", CLIENTS, "claude");
+    const client = await choose(ask, say, "Install the Metergraph skill for which coding agent?", CLIENTS, "claude", {
+      ...Object.fromEntries(CLIENTS.map(([value, label]) => [label.toLowerCase(), value])),
+      "skip skill installation": null,
+    });
     if (client === undefined) return null;
     if (client === null) added.push("--skip-skill");
     else added.push("--client", client);
@@ -167,13 +181,14 @@ function valueOf(argv, flag) {
 
 // A numbered menu. Resolves with the chosen value, or undefined on cancel
 // (null is a valid choice: no client).
-async function choose(ask, say, question, options, fallback) {
+async function choose(ask, say, question, options, fallback, aliases = {}) {
   say("", question);
   options.forEach(([, label], index) => say(`  ${index + 1}) ${label}`));
   const fallbackIndex = options.findIndex(([value]) => value === fallback) + 1;
   for (;;) {
     const answer = await ask(`Choose 1-${options.length} [${fallbackIndex}]: `);
     if (answer === null) return undefined;
+    if (Object.hasOwn(aliases, answer.toLowerCase())) return aliases[answer.toLowerCase()];
     const index = answer === "" ? fallbackIndex : Number(answer);
     if (Number.isInteger(index) && index >= 1 && index <= options.length) return options[index - 1][0];
     say(`Enter a number from 1 to ${options.length}.`);