badgr-cli 1.0.48 → 1.1.0

package/src/commands/sbatch.js

@@ -0,0 +1,232 @@
+/**
+ * badgr sbatch <job.slurm> — run an existing Slurm batch script without
+ * asking HPC users to redesign their workflow.
+ *
+ *   badgr sbatch job.slurm
+ *   badgr sbatch job.slurm --dry-run
+ *   badgr sbatch job.slurm --image myorg/hpc:latest
+ *
+ * Translates the common 20% of #SBATCH directives (cpus-per-task, mem,
+ * gres=gpu:N / gpus, array, time, export, job-name) into the same /run
+ * request shape `badgr batch run` submits — this is another entry point
+ * into the existing execution path, not a new one. Job arrays (--array)
+ * fan out into one deployment per task index, each with
+ * SLURM_ARRAY_TASK_ID set, mirroring how a real Slurm array behaves.
+ */
+import { resolve } from 'path';
+import { requireApiKey } from '../config.js';
+import { loadSlurmScript, envForArrayTask, SlurmParseError } from '../slurm.js';
+import { addReceipt, updateReceipt, generateReceiptId, selectedComputeFromDeployment } from '../store.js';
+import { normalizeTier, callWithFallback } from '../fallback.js';
+import { normalizeGpuType } from '../spec.js';
+import { monitorBatchJob, fmtRuntime } from '../batch.js';
+import { runFanOut, DEFAULT_CONCURRENCY } from '../fanout.js';
+import { callApi } from '../api.js';
+
+const DEFAULT_IMAGE = 'python:3.11-slim';
+const DEFAULT_MAX_RUNTIME_MIN = 60;
+const DEFAULT_MAX_COST = 2;
+
+function parseSbatchArgs(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--image')        { flags.image = args[++i]; continue; }
+    if (args[i] === '--tier')         { flags.tier = args[++i]; continue; }
+    if (args[i] === '--region')       { flags.region = args[++i]; continue; }
+    if (args[i] === '--max-cost')     { flags.maxCost = parseFloat(args[++i]); continue; }
+    if (args[i] === '--max-runtime')  { flags.maxRuntime = parseFloat(args[++i]); continue; }
+    if (args[i] === '--max-concurrency') { flags.maxConcurrency = parseInt(args[++i], 10); continue; }
+    if (args[i] === '--dry-run')      { flags.dryRun = true; continue; }
+    positional.push(args[i]);
+  }
+  return { flags, positional };
+}
+
+/** Translate a parsed Slurm job (or one array task of it) into a /run body. */
+export function buildRunBody(job, { image, tier, region, maxCostUsd, maxRuntimeMinutes, taskId = null, arrayJobId = null }) {
+  const env = envForArrayTask(job.env, taskId, arrayJobId);
+  return {
+    image,
+    command: ['bash', '-lc', job.command],
+    custom_image: image !== DEFAULT_IMAGE,
+    gpu: job.gpuCount > 0 ? (job.gpuType ? normalizeGpuType(job.gpuType) : 'AUTO') : 'NONE',
+    gpu_count: job.gpuCount > 0 ? job.gpuCount : 1,
+    ...(job.gpuCount > 0 ? {} : { no_gpu: true }),
+    ...(job.cpus ? { cpu: job.cpus } : {}),
+    ...(job.memGb ? { memory_gb: job.memGb } : {}),
+    ...(region ? { region: region.toUpperCase() } : {}),
+    tier,
+    env,
+    name: taskId != null ? `${job.name}-${taskId}` : job.name,
+    max_cost_usd: maxCostUsd,
+    max_runtime_seconds: maxRuntimeMinutes * 60,
+  };
+}
+
+function printPlan(job, chalk) {
+  console.log(chalk.bold(`\n📜 Slurm job: ${job.name}\n`));
+  console.log(`  ${chalk.bold('Command:')}      ${job.command.split('\n')[0]}${job.command.includes('\n') ? ' ...' : ''}`);
+  if (job.cpus) console.log(`  ${chalk.bold('CPUs:')}         ${job.cpus}`);
+  if (job.memGb) console.log(`  ${chalk.bold('Memory:')}       ${job.memGb.toFixed(1)} GB`);
+  console.log(`  ${chalk.bold('GPUs:')}         ${job.gpuCount > 0 ? job.gpuCount + (job.gpuType ? ` × ${job.gpuType}` : '') : 'none'}`);
+  if (job.timeMinutes) console.log(`  ${chalk.bold('Time limit:')}   ${job.timeMinutes}min`);
+  if (job.arrayIndices.length) console.log(`  ${chalk.bold('Array:')}        ${job.arrayIndices.length} task(s) [${job.arrayIndices[0]}..${job.arrayIndices[job.arrayIndices.length - 1]}]`);
+  if (Object.keys(job.env).length) console.log(`  ${chalk.bold('Env:')}          ${Object.keys(job.env).join(', ')}`);
+  if (job.ignoredDirectives.length) {
+    console.log(chalk.yellow(`  Ignored directives (no Badgr equivalent): ${job.ignoredDirectives.join(', ')}`));
+  }
+  console.log();
+}
+
+async function submitOne(config, job, opts, chalk, { taskId = null, arrayJobId = null } = {}) {
+  const body = buildRunBody(job, { ...opts, taskId, arrayJobId });
+  const effectiveTier = opts.tier;
+  const dep = await callWithFallback(
+    '/run',
+    { apiKey: config.apiKey, baseUrl: config.baseUrl },
+    () => body,
+    effectiveTier,
+    chalk,
+    { thing: 'Slurm job', cmd: 'badgr sbatch' },
+  );
+  const rcptId = dep.receipt_id || generateReceiptId();
+  addReceipt({
+    receiptId: rcptId,
+    action: 'badgr sbatch',
+    deploymentId: dep.deployment_id,
+    workloadName: body.name,
+    workloadImage: body.image,
+    gpu: dep.gpu_type,
+    providerRoute: dep.provider ?? null,
+    tier: dep.tier ?? null,
+    maxCost: opts.maxCostUsd,
+    maxRuntime: opts.maxRuntimeMinutes,
+    status: dep.status,
+    createdAt: new Date().toISOString(),
+    slurmArrayTaskId: taskId,
+    workloadShape: taskId != null ? 'slurm-array' : 'slurm',
+    computeRequested: { cpu: job.cpus ?? null, memoryGb: job.memGb ?? null, gpuCount: job.gpuCount, gpuType: job.gpuType ?? null },
+    computeSelected: selectedComputeFromDeployment(dep),
+  });
+  return { dep, rcptId };
+}
+
+export async function sbatchCommand(config, args, chalk) {
+  const { flags, positional } = parseSbatchArgs(args);
+  const scriptPath = positional[0];
+  if (!scriptPath) {
+    console.error(chalk.red('\n  Usage: badgr sbatch <job.slurm> [--image <image>] [--dry-run]\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  let job;
+  try {
+    job = loadSlurmScript(resolve(scriptPath));
+  } catch (err) {
+    if (err instanceof SlurmParseError) {
+      console.error(chalk.red(`\n  ✗ ${err.message}\n`));
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+
+  if (flags.maxConcurrency != null && (!Number.isInteger(flags.maxConcurrency) || flags.maxConcurrency < 1)) {
+    console.error(chalk.red(`\n  ✗ --max-concurrency must be a positive integer, got: ${flags.maxConcurrency}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  printPlan(job, chalk);
+
+  const opts = {
+    image: flags.image || DEFAULT_IMAGE,
+    tier: normalizeTier(flags.tier),
+    region: flags.region,
+    maxCostUsd: flags.maxCost ?? DEFAULT_MAX_COST,
+    maxRuntimeMinutes: flags.maxRuntime ?? job.timeMinutes ?? DEFAULT_MAX_RUNTIME_MIN,
+  };
+
+  const isArray = job.arrayIndices.length > 0;
+  const taskIds = isArray ? job.arrayIndices : [null];
+  const concurrency = flags.maxConcurrency ?? DEFAULT_CONCURRENCY;
+
+  if (flags.dryRun) {
+    console.log(chalk.dim(`  Dry run — no GPU provisioned. Would submit ${taskIds.length} job(s) (max ${Math.min(concurrency, taskIds.length)} concurrent) with:`));
+    console.log(chalk.dim(`  image=${opts.image} tier=${opts.tier} max_cost=$${opts.maxCostUsd} max_runtime=${opts.maxRuntimeMinutes}min\n`));
+    return;
+  }
+
+  requireApiKey(config);
+
+  const arrayJobId = isArray ? generateReceiptId() : null;
+
+  if (isArray) {
+    console.log(chalk.dim(`  Submitting ${taskIds.length} array task(s), up to ${Math.min(concurrency, taskIds.length)} at a time...\n`));
+  }
+
+  const { results, allSucceeded, submittedCount, failedSubmitCount } = await runFanOut({
+    tasks: taskIds,
+    concurrency,
+    onSubmitError: (taskId, err) => {
+      if (err.isPaymentRequired) console.error(chalk.yellow(err.message));
+      else console.error(chalk.red(`  ✗ Task ${taskId ?? ''} failed to submit: ${err.message}`));
+    },
+    submitTask: async (taskId) => {
+      process.stdout.write(chalk.dim(taskId != null ? `  Submitting array task ${taskId}...\n` : '  Submitting job...\n'));
+      const { dep, rcptId } = await submitOne(config, job, opts, chalk, { taskId, arrayJobId });
+      console.log(`  ${chalk.bold('Run ID:')} ${chalk.cyan(dep.deployment_id)}${taskId != null ? chalk.dim(` (task ${taskId})`) : ''}`);
+      return { deploymentId: dep.deployment_id, receiptId: rcptId, ratePerHour: dep.cost_per_hour || 0 };
+    },
+    monitorTask: async ({ deploymentId, receiptId, ratePerHour }) => {
+      const result = await monitorBatchJob(config, deploymentId, receiptId, {
+        chalk,
+        maxRuntimeMs: opts.maxRuntimeMinutes * 60 * 1000,
+        maxCost: opts.maxCostUsd,
+        ratePerHour,
+      });
+      let dep2 = null;
+      try {
+        dep2 = await callApi(`/deployments/${deploymentId}`, { apiKey: config.apiKey, baseUrl: config.baseUrl });
+      } catch { /* best-effort */ }
+      updateReceipt(receiptId, {
+        status: dep2?.status ?? result.status,
+        failureReason: dep2?.failure_reason ?? null,
+        teardownOk: dep2?.teardown_ok ?? null,
+        runtimeSeconds: dep2?.runtime_seconds ?? Math.round(result.runtimeMs / 1000),
+        finalCost: dep2?.accrued_cost_usd ?? (ratePerHour * (result.runtimeMs / 3_600_000)),
+      });
+      const status = dep2?.status ?? result.status;
+      return { status, succeeded: ['succeeded', 'completed'].includes(status), runtimeMs: result.runtimeMs };
+    },
+  });
+
+  if (submittedCount === 0) {
+    console.error(chalk.red('\n  ✗ No tasks were submitted\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(chalk.bold(`\n📜 Slurm job summary: ${job.name}\n`));
+  for (const r of results) {
+    const label = r.task != null ? `task ${r.task}` : 'job';
+    if (r.error) {
+      console.log(`  ${chalk.red('✗')} ${label}  ${chalk.dim('never submitted')}`);
+      continue;
+    }
+    const icon = r.succeeded ? chalk.green('✓') : chalk.red('✗');
+    console.log(`  ${icon} ${label}  ${r.deploymentId}  ${r.status}  ${fmtRuntime(r.runtimeMs)}`);
+  }
+  if (failedSubmitCount) console.log(chalk.red(`  ${failedSubmitCount} task(s) never submitted`));
+
+  console.log();
+  if (allSucceeded) {
+    console.log(chalk.green(`  ✓ Slurm job complete (${taskIds.length}/${taskIds.length} task(s) succeeded)\n`));
+  } else {
+    const okCount = results.filter(r => r.succeeded).length;
+    console.error(chalk.red(`  ✗ Slurm job incomplete (${okCount}/${taskIds.length} task(s) succeeded)\n`));
+    process.exitCode = 1;
+  }
+}

package/src/commands/serve.js

@@ -1,4 +1,4 @@
-import { requireApiKey } from '../config.js';
+import { ensureBadgrReady } from '../onboarding.js';
 import { callApi, listDeployments } from '../api.js';
 import { addDeployment, addReceipt, updateReceipt, generateReceiptId } from '../store.js';
 import { normalizeTier, callWithFallback } from '../fallback.js';
@@ -254,7 +254,7 @@ async function findRunningVllmEndpoint(config, modelId) {
  * no model is ever touched in that mode.
  */
 async function serveOpenWebUICommand(config, args, chalk) {
-  requireApiKey(config);
+  config = await ensureBadgrReady(config, chalk);
   const { value: connect, rest: afterConnect } = extractFlag(args, '--connect');
   const { value: model, rest } = extractFlag(afterConnect, '--model');
 
@@ -396,7 +396,7 @@ export async function serveCommand(config, args, chalk) {
     return;
   }
 
-  requireApiKey(config);
+  config = await ensureBadgrReady(config, chalk);
 
   // ── Validate flags early ───────────────────────────────────────────────────
   if (flags.count !== undefined && (!Number.isFinite(flags.count) || flags.count < 1)) {

package/src/commands/status.js

@@ -36,7 +36,15 @@ export async function statusCommand(config, args, chalk) {
     }));
   }
 
-  const running = deployments.filter(d => d.status === 'running' || d.status === 'provisioning');
+  // Filter OUT known-terminal statuses rather than filtering IN a fixed
+  // active list — the backend has more active states than just "running"/
+  // "provisioning" (also "starting", "queued"), and a status this command
+  // doesn't recognize yet must still show as active rather than being
+  // silently hidden (a live run found deployments stuck in "starting" that
+  // this filter used to drop entirely, reporting "Nothing running" while
+  // real billable resources kept running).
+  const TERMINAL_STATUSES = new Set(['completed', 'succeeded', 'success', 'failed', 'stopped']);
+  const running = deployments.filter(d => !TERMINAL_STATUSES.has(d.status));
 
   if (running.length === 0) {
     console.log(chalk.dim('\n  Nothing running.\n'));
@@ -51,9 +59,9 @@ export async function statusCommand(config, args, chalk) {
     const type = d.workload_type === 'endpoint' ? 'endpoint' : 'job';
     const gpu  = d.gpu_type || '—';
     const rate = d.cost_per_hour > 0 ? chalk.yellow(`$${d.cost_per_hour.toFixed(2)}/hr`) : '';
-    const badge = d.status === 'provisioning'
-      ? chalk.yellow('● starting')
-      : chalk.green('● running');
+    const badge = d.status === 'running'
+      ? chalk.green('● running')
+      : chalk.yellow('● starting');
 
     console.log(`  ${badge}  ${chalk.bold(id)}  ${type}  ${gpu}  ${rate}`);
 

package/src/commands/task.js

@@ -0,0 +1,25 @@
+import { launchCommand } from './launch.js';
+
+/**
+ * badgr task "<description>" -- <command>
+ *
+ * The MVP version of "assign a task" — a thin label wrapper over
+ * `badgr launch . -- <command>`. It does not queue, schedule, or track
+ * anything beyond what `badgr launch` already does; the description is
+ * printed for the human and otherwise discarded (the receipt/status page
+ * still key off the deployment ID, same as any other launch).
+ */
+export async function taskCommand(config, args, chalk) {
+  const description = args[0];
+  if (!description || description.startsWith('-')) {
+    console.error(chalk.red('\nUsage: badgr task "<description>" [badgr launch flags...] -- <command>\n'));
+    console.error(chalk.dim('  The description must come first, before any flags.'));
+    console.error(chalk.dim('  Example: badgr task "Run the Chromium tests and tell me what failed" --max-cost 1 -- npm run test:chromium'));
+    console.error(chalk.dim('  Example: badgr task "Fix the failing checkout test" --max-cost 1 -- claude -p "Fix the failing checkout test"\n'));
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(chalk.dim(`  Task: ${description}`));
+  return launchCommand(config, ['.', ...args.slice(1)], chalk);
+}

package/src/commands/test-run.js

@@ -207,8 +207,10 @@ export async function testCommand(config, args, chalk) {
   process.stdout.write(chalk.dim('  Stopping deployment...'));
   let stopped = false;
   try {
-    await terminateDeployment(config, depId);
-    stopped = true;
+    // A 200 response only means deletion was requested, not confirmed —
+    // teardown_ok reflects whether the provider resource is actually gone.
+    const result = await terminateDeployment(config, depId);
+    stopped = result?.teardown_ok === 'ok';
   } catch { /* best-effort */ }
   process.stdout.write('\n');
   step(chalk, stopped, 'Billing stopped');

package/src/credentials.js

@@ -0,0 +1,65 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'fs';
+import { join } from 'path';
+import { CONFIG_DIR } from './config.js';
+
+export const CREDENTIALS_FILE = join(CONFIG_DIR, 'credentials.json');
+
+// Env var each provider's credential is exposed under inside the launch VM.
+export const PROVIDER_ENV_KEYS = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+};
+
+export const KNOWN_PROVIDERS = Object.keys(PROVIDER_ENV_KEYS);
+
+/**
+ * Credential storage for `badgr connect <provider>`. This is a local file
+ * under ~/.badgr with owner-only permissions (chmod 600) — not the
+ * platform's real OS keychain (macOS Keychain / libsecret / Windows
+ * Credential Manager), since that needs a native module this CLI doesn't
+ * depend on yet. Documented as such; do not claim OS-keychain storage.
+ */
+function readStore() {
+  if (!existsSync(CREDENTIALS_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CREDENTIALS_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeStore(store) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  // mode: 0o600 on writeFileSync itself sets permissions atomically at
+  // creation — passing it here (not just the chmodSync below) closes a
+  // brief window where a freshly-created file would otherwise sit at the
+  // default (world-readable) mode until the chmod call caught up.
+  writeFileSync(CREDENTIALS_FILE, JSON.stringify(store, null, 2), { mode: 0o600 });
+  try {
+    chmodSync(CREDENTIALS_FILE, 0o600);
+  } catch {
+    // best-effort — not all filesystems support chmod (e.g. some Windows setups)
+  }
+}
+
+export function getCredential(provider) {
+  return readStore()[provider] ?? null;
+}
+
+export function setCredential(provider, value) {
+  const store = readStore();
+  store[provider] = value;
+  writeStore(store);
+}
+
+export function removeCredential(provider) {
+  const store = readStore();
+  if (!(provider in store)) return false;
+  delete store[provider];
+  writeStore(store);
+  return true;
+}
+
+export function listCredentials() {
+  return Object.keys(readStore());
+}

package/src/fallback.js

@@ -44,9 +44,14 @@ export async function callWithFallback(endpoint, callOpts, buildBody, effectiveT
   const cmd   = labels?.cmd   ?? 'badgr run';
   const allowTier2Fallback = opts.allowTier2Fallback !== false; // default true
 
-  // 130s: backend provisioning runs up to BADGR_PROVISION_TIMEOUT_SECONDS (default 120s).
+  // 220s: comfortably above backend's BADGR_PROVISION_TIMEOUT_SECONDS (default
+  // 200s, itself set above deployment_service.py's 180s routing-search
+  // deadline). Found live: the previous 130s value fired before the server's
+  // own (then-120s) deadline could, so the CLI reported "failed to submit"
+  // for jobs that had actually been created and were already billing —
+  // aborting client-side never cancels the server's in-flight work.
   async function attempt(body) {
-    return callApi(endpoint, { method: 'POST', ...callOpts, body, timeoutMs: 130_000 });
+    return callApi(endpoint, { method: 'POST', ...callOpts, body, timeoutMs: 220_000 });
   }
 
   // Map server error codes → catalog keys and extract context for templates.

package/src/fanout.js

@@ -0,0 +1,70 @@
+/**
+ * Shared fan-out primitive: submit N independent /run tasks — at most
+ * `concurrency` in flight (submitted-but-not-yet-terminal) at once — monitor
+ * each to a terminal state, and roll the results up into one summary.
+ *
+ * "Run the same program many times with different inputs" is structurally
+ * identical whether the N tasks come from a Slurm `#SBATCH --array` range
+ * (see commands/sbatch.js) or a directory of input files (see `badgr batch
+ * run --fan-out`, commands/batch.js) — both funnel through this module so
+ * the submit/monitor/summarize logic, and the concurrency cap that bounds
+ * how much compute a single command can accidentally provision, exist
+ * exactly once.
+ */
+
+const DEFAULT_CONCURRENCY = 5;
+
+/**
+ * @param {Array<any>} tasks - opaque per-task descriptors, passed straight
+ *   through to submitTask/monitorTask/onSubmitError.
+ * @param {(task) => Promise<{deploymentId, receiptId, ratePerHour}>} submitTask
+ *   Submits one task. Rejecting marks it as a submit failure (never monitored).
+ * @param {(submitted: {task, deploymentId, receiptId, ratePerHour}) => Promise<{status, succeeded, runtimeMs}>} monitorTask
+ *   Waits for one submitted task to reach a terminal state.
+ * @param {(task, err) => void} [onSubmitError] - called synchronously as each submit fails.
+ * @param {number} [concurrency] - max tasks with an active deployment (submitted,
+ *   not yet terminal) at once. Defaults to 5 — fan-out must never submit an
+ *   unbounded number of deployments from one command by default.
+ * @returns {Promise<{results: Array, allSucceeded: boolean, submittedCount: number, failedSubmitCount: number}>}
+ *   `results` has one entry per input task, in the original task order, each
+ *   either `{ task, error }` (never submitted) or
+ *   `{ task, deploymentId, receiptId, status, succeeded, runtimeMs }`.
+ */
+export async function runFanOut({ tasks, submitTask, monitorTask, onSubmitError = () => {}, concurrency = DEFAULT_CONCURRENCY }) {
+  const effectiveConcurrency = Math.max(1, concurrency || DEFAULT_CONCURRENCY);
+  const results = new Array(tasks.length);
+  let nextIndex = 0;
+
+  async function worker() {
+    while (nextIndex < tasks.length) {
+      const i = nextIndex++;
+      const task = tasks[i];
+      let submitted;
+      try {
+        submitted = await submitTask(task);
+      } catch (err) {
+        onSubmitError(task, err);
+        results[i] = { task, error: err };
+        continue;
+      }
+      const monitored = await monitorTask({ task, ...submitted });
+      results[i] = { task, ...submitted, ...monitored };
+    }
+  }
+
+  const workerCount = Math.min(effectiveConcurrency, tasks.length);
+  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+
+  const submittedCount = results.filter(r => !r.error).length;
+  const failedSubmitCount = results.filter(r => r.error).length;
+  const allSucceeded = failedSubmitCount === 0 && results.every(r => r.succeeded);
+
+  return {
+    results,
+    allSucceeded,
+    submittedCount,
+    failedSubmitCount,
+  };
+}
+
+export { DEFAULT_CONCURRENCY };

package/src/gpuDoctor/diskInfo.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+function round1(n) {
+  return Math.round(n * 10) / 10;
+}
+
+/**
+ * Read-only disk/cache probe. Never creates or deletes anything.
+ */
+export function detectDisk(fsImpl = fs) {
+  const cachePath = process.env.HF_HOME || process.env.HUGGINGFACE_HUB_CACHE || path.join(os.homedir(), '.cache', 'huggingface');
+  const result = {
+    cachePath,
+    cacheSource: process.env.HF_HOME ? 'HF_HOME' : process.env.HUGGINGFACE_HUB_CACHE ? 'HUGGINGFACE_HUB_CACHE' : 'default (~/.cache/huggingface)',
+    cacheExists: false,
+    writable: false,
+    freeGb: null,
+    totalGb: null,
+  };
+
+  result.cacheExists = fsImpl.existsSync(cachePath);
+  const probePath = result.cacheExists ? cachePath : path.dirname(cachePath);
+
+  try {
+    const stat = fsImpl.statfsSync(probePath);
+    result.freeGb = round1((stat.bavail * stat.bsize) / 1e9);
+    result.totalGb = round1((stat.blocks * stat.bsize) / 1e9);
+  } catch {
+    // statfs unsupported on this platform — leave free/total unknown
+  }
+
+  try {
+    fsImpl.accessSync(fsImpl.existsSync(probePath) ? probePath : os.tmpdir(), fs.constants.W_OK);
+    result.writable = true;
+  } catch {
+    result.writable = false;
+  }
+
+  return result;
+}