@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/agent-fs.ts

@@ -0,0 +1,246 @@
+import { spawn, spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import { resolve, sep } from 'node:path';
+import type { Readable } from 'node:stream';
+import { runningAsMetro } from '../metro-user/privilege.js';
+import { agentUser, asUser, type AgentUser } from './user.js';
+
+export interface AgentStat {
+  size: number;
+  mtime: Date;
+  mtimeMs: number;
+  mode: number;
+  isFile: () => boolean;
+  isDirectory: () => boolean;
+  isSymbolicLink: () => boolean;
+}
+
+export interface AgentDirent {
+  name: string;
+  isFile: () => boolean;
+  isDirectory: () => boolean;
+  isSymbolicLink: () => boolean;
+}
+
+const MAX_OUTPUT = 256 * 1024 * 1024;
+
+const codeOf = (err: unknown): unknown => (err as { code?: unknown } | null)?.code;
+
+const refused = (err: unknown): boolean => {
+  const code = codeOf(err);
+  return (code === 'EACCES' || code === 'EPERM') && runningAsMetro();
+};
+
+const realHome = new Map<string, string>();
+
+function homeOf(user: AgentUser): string {
+  let real = realHome.get(user.home);
+  if (real === undefined) {
+    try {
+      real = fs.realpathSync(user.home);
+    } catch {
+      real = resolve(user.home);
+    }
+    realHome.set(user.home, real);
+  }
+  return real;
+}
+
+const within = (home: string, path: string): boolean => path === home || path.startsWith(`${home}${sep}`);
+
+function realOf(path: string, fd: number | undefined): string | null {
+  if (fd !== undefined) return fs.readlinkSync(`/proc/self/fd/${String(fd)}`);
+  try {
+    return fs.realpathSync(path);
+  } catch (err) {
+    if (codeOf(err) === 'ENOENT' || codeOf(err) === 'ENOTDIR') return null;
+    throw err;
+  }
+}
+
+export function escapesHome(path: string, user: AgentUser, fd?: number): boolean {
+  const home = homeOf(user);
+  const asked = resolve(path);
+  if (!within(resolve(user.home), asked) && !within(home, asked)) return false;
+  const real = realOf(path, fd);
+  return real !== null && !within(home, real);
+}
+
+const confinedUser = (): AgentUser | null => (runningAsMetro() ? agentUser() : null);
+
+function outside(path: string): Error {
+  const err = new Error(`${path} leads out of the agent's home, so metro reads it as the agent`) as Error & { code: string };
+  err.code = 'EACCES';
+  return err;
+}
+
+function guardPath(path: string, fd?: number): void {
+  const user = confinedUser();
+  if (user !== null && escapesHome(path, user, fd)) throw outside(path);
+}
+
+function openGuarded(path: string): number {
+  const fd = fs.openSync(path, 'r');
+  try {
+    guardPath(path, fd);
+    return fd;
+  } catch (err) {
+    fs.closeSync(fd);
+    throw err;
+  }
+}
+
+function asAgentSh(script: string, args: string[], failure = 'ENOENT'): Buffer {
+  const [file, argv] = asUser(agentUser(), 'sh', ['-c', script, 'metro', ...args]);
+  const run = spawnSync(file, argv, { maxBuffer: MAX_OUTPUT, stdio: ['ignore', 'pipe', 'pipe'] });
+  if (run.error !== undefined) throw run.error;
+  if (run.status !== 0) {
+    const err = new Error(run.stderr.toString('utf8').trim() || `no such file or directory, ${args[0] ?? ''}`) as Error & { code: string };
+    err.code = run.status === 66 ? 'ENOENT' : failure;
+    throw err;
+  }
+  return run.stdout;
+}
+
+function viaAgent<T>(native: () => T, fallback: () => T): T {
+  try {
+    return native();
+  } catch (err) {
+    if (!refused(err)) throw err;
+    return fallback();
+  }
+}
+
+export function existsSync(path: string): boolean {
+  try {
+    guardPath(path);
+    fs.accessSync(path, fs.constants.F_OK);
+    return true;
+  } catch (err) {
+    if (!refused(err)) return false;
+    try {
+      asAgentSh('test -e "$1"', [path]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+const kindTests = (kind: string): Pick<AgentStat, 'isFile' | 'isDirectory' | 'isSymbolicLink'> => ({
+  isFile: () => kind === 'f',
+  isDirectory: () => kind === 'd',
+  isSymbolicLink: () => kind === 'l',
+});
+
+function agentStat(path: string, follow: boolean): AgentStat {
+  const out = asAgentSh(`stat ${follow ? '-L ' : ''}-c "%s %Y %f %F" -- "$1"`, [path]).toString('utf8').trim();
+  const [size = '0', mtime = '0', mode = '0', ...type] = out.split(' ');
+  const kind = type.join(' ') === 'directory' ? 'd' : type.join(' ') === 'symbolic link' ? 'l' : 'f';
+  const ms = Number(mtime) * 1000;
+  return { size: Number(size), mtime: new Date(ms), mtimeMs: ms, mode: parseInt(mode, 16), ...kindTests(kind) };
+}
+
+export const statSync = (path: string): AgentStat =>
+  viaAgent(
+    () => {
+      guardPath(path);
+      return fs.statSync(path);
+    },
+    () => agentStat(path, true),
+  );
+
+export const realpathSync = (path: string): string =>
+  viaAgent(
+    () => {
+      guardPath(path);
+      return fs.realpathSync(path);
+    },
+    () => asAgentSh('realpath -e -- "$1"', [path]).toString('utf8').trim(),
+  );
+
+export function readFileSync(path: string, encoding: 'utf8'): string {
+  return viaAgent(
+    () => {
+      const fd = openGuarded(path);
+      try {
+        return fs.readFileSync(fd, encoding);
+      } finally {
+        fs.closeSync(fd);
+      }
+    },
+    () => asAgentSh('if test -x "${1%/*}" && ! test -e "$1" && ! test -L "$1"; then exit 66; fi; cat -- "$1"', [path], 'EIO').toString('utf8'),
+  );
+}
+
+export function readRange(path: string, start: number, length: number): Buffer {
+  return viaAgent(
+    () => {
+      const fd = openGuarded(path);
+      try {
+        const buffer = Buffer.alloc(length);
+        return buffer.subarray(0, fs.readSync(fd, buffer, 0, length, start));
+      } finally {
+        fs.closeSync(fd);
+      }
+    },
+    () => asAgentSh('tail -c +"$2" -- "$1" | head -c "$3"', [path, String(start + 1), String(length)]),
+  );
+}
+
+export function readdirNames(path: string): string[] {
+  return readdirEntries(path).map((e) => e.name);
+}
+
+export function readdirEntries(path: string): AgentDirent[] {
+  return viaAgent(
+    () => {
+      guardPath(path);
+      return fs.readdirSync(path, { withFileTypes: true });
+    },
+    () =>
+      asAgentSh('find -H "$1" -mindepth 1 -maxdepth 1 -printf "%y\\t%f\\0"', [path])
+        .toString('utf8')
+        .split('\0')
+        .filter((line) => line.includes('\t'))
+        .map((line) => {
+          const at = line.indexOf('\t');
+          return { name: line.slice(at + 1), ...kindTests(line.slice(0, at)) };
+        }),
+  );
+}
+
+export function createReadStream(path: string): Readable {
+  try {
+    return fs.createReadStream(path, { fd: openGuarded(path) });
+  } catch (err) {
+    if (!refused(err)) return fs.createReadStream(path);
+    const [file, argv] = asUser(agentUser(), 'cat', ['--', path]);
+    const child = spawn(file, argv, { stdio: ['ignore', 'pipe', 'ignore'] });
+    return child.stdout;
+  }
+}
+
+export function readAsAgent(path: string, maxBytes: number): Buffer | null {
+  if (!runningAsMetro() || agentUser() === null) {
+    try {
+      const st = fs.statSync(path);
+      if (!st.isFile()) return null;
+      const start = Math.max(0, st.size - maxBytes);
+      const fd = fs.openSync(path, 'r');
+      try {
+        const buffer = Buffer.alloc(st.size - start);
+        return buffer.subarray(0, fs.readSync(fd, buffer, 0, buffer.length, start));
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch {
+      return null;
+    }
+  }
+  try {
+    return asAgentSh('[ -f "$1" ] && tail -c "$2" -- "$1"', [path, String(maxBytes)]);
+  } catch {
+    return null;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/crontab.ts

@@ -0,0 +1,44 @@
+import type { Runner } from './schedules.js';
+import type { AgentUser } from './user.js';
+
+const NO_CRONTAB = /no crontab for/i;
+
+const indexesOf = (lines: string[], marker: string): number[] => lines.flatMap((l, i) => (l === marker ? [i] : []));
+
+function outsideBlock(lines: string[], begin: string, end: string): string[] {
+  const starts = indexesOf(lines, begin);
+  const stops = indexesOf(lines, end);
+  const [start = -1] = starts;
+  const [stop = -1] = stops;
+  if (starts.length !== 1 || stops.length !== 1 || stop < start) return lines;
+  return [...lines.slice(0, start), ...lines.slice(stop + 1)];
+}
+
+export function withBlock(lines: string[], begin: string, end: string, block: string[], at: 'top' | 'end', owned: (line: string) => boolean = () => false): string[] {
+  const kept = outsideBlock(lines, begin, end).filter((l) => l !== '' && l !== begin && l !== end && !owned(l));
+  if (block.length === 0) return kept;
+  const wrapped = [begin, ...block, end];
+  return at === 'top' ? [...wrapped, ...kept] : [...kept, ...wrapped];
+}
+
+const failure = (what: string, user: AgentUser, out: { status: number | null; stderr?: string }): Error =>
+  new Error(`could not ${what} the crontab of ${user.name}: ${(out.stderr ?? '').trim() || `exit ${String(out.status)}`}`);
+
+export function readCrontab(user: AgentUser, runner: Runner): string[] {
+  const out = runner.run('crontab', ['-l', '-u', user.name]);
+  if (out.status === 0) return out.stdout.split('\n');
+  if (out.status === 1 && NO_CRONTAB.test(out.stderr ?? '')) return [];
+  throw failure('read', user, out);
+}
+
+export function writeCrontab(user: AgentUser, runner: Runner, lines: string[], next: string[]): boolean {
+  if (next.join('\n') === lines.filter((l) => l !== '').join('\n')) return false;
+  const out = runner.run('crontab', ['-u', user.name, '-'], next.length === 0 ? '' : `${next.join('\n')}\n`);
+  if (out.status !== 0) throw failure('write', user, out);
+  return true;
+}
+
+export function editCrontab(user: AgentUser, runner: Runner, change: (lines: string[]) => string[]): boolean {
+  const lines = readCrontab(user, runner);
+  return writeCrontab(user, runner, lines, change(lines));
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/files-api.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { sessionRoute } from '@metro-labs/http/api-http';
+import { readAgentPath } from './files.js';
+import { agentUser } from './user.js';
+
+const PATH = '/api/files';
+
+const queryPath = (req: IncomingMessage): string => new URLSearchParams((req.url ?? '').split('?')[1] ?? '').get('path') ?? '';
+
+export function handleFilesRequest(req: IncomingMessage, res: ServerResponse): boolean {
+  return sessionRoute(req, res, { methods: { [PATH]: ['GET'] }, admin: true, label: 'files-api' }, () => Promise.resolve(readAgentPath(agentUser(), queryPath(req))));
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/files.ts

@@ -0,0 +1,89 @@
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { asUser, type AgentUser } from './user.js';
+
+type EntryKind = 'folder' | 'file' | 'other';
+
+interface FileEntry {
+  name: string;
+  kind: EntryKind;
+  bytes: number;
+  modifiedAt: string;
+}
+
+export type FilesAnswer =
+  | { root: string; path: string; kind: 'folder'; entries: FileEntry[]; more: boolean }
+  | { root: string; path: string; kind: 'file'; bytes: number; modifiedAt: string; text: string | null; truncated: boolean };
+
+const MAX_ENTRIES = 2000;
+const PREVIEW_BYTES = 256 * 1024;
+const SNIFF_BYTES = 8192;
+
+const SCRIPT = [
+  'if [ -d "$1" ]; then',
+  '  printf "D\\0"; find -H "$1" -mindepth 1 -maxdepth 1 -printf "%y\\0%s\\0%T@\\0%f\\0"',
+  'elif [ -f "$1" ]; then',
+  '  printf "F\\0"; stat -L -c "%s %Y" -- "$1" | tr "\\n" "\\0"; head -c "$2" -- "$1"',
+  'else',
+  '  echo "no such file or folder" >&2; exit 2',
+  'fi',
+].join('\n');
+
+export function segmentsOf(path: string): string[] {
+  const parts = path.split('/').filter((part) => part !== '');
+  if (parts.some((part) => part === '.' || part === '..' || part.includes('\0')))
+    throw new ApiError('that path is not inside the home folder', 400);
+  return parts;
+}
+
+const stamp = (seconds: number): string => (Number.isFinite(seconds) && seconds > 0 ? new Date(seconds * 1000).toISOString() : '');
+
+const kindOf = (letter: string): EntryKind => (letter === 'd' ? 'folder' : letter === 'f' ? 'file' : 'other');
+
+const byKindThenName = (a: FileEntry, b: FileEntry): number =>
+  a.kind === 'folder' && b.kind !== 'folder' ? -1 : b.kind === 'folder' && a.kind !== 'folder' ? 1 : a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: 'base' });
+
+function preview(bytes: Buffer, size: number): { text: string | null; truncated: boolean } {
+  const binary = bytes.subarray(0, SNIFF_BYTES).includes(0);
+  return { text: binary ? null : bytes.subarray(0, PREVIEW_BYTES).toString('utf8'), truncated: size > PREVIEW_BYTES };
+}
+
+function folderAnswer(root: string, path: string, entries: FileEntry[]): FilesAnswer {
+  const sorted = entries.sort(byKindThenName);
+  return { root, path, kind: 'folder', entries: sorted.slice(0, MAX_ENTRIES), more: sorted.length > MAX_ENTRIES };
+}
+
+function parseListing(out: Buffer): FileEntry[] {
+  const fields = out.toString('utf8').split('\0');
+  const entries: FileEntry[] = [];
+  for (let at = 0; at + 3 < fields.length; at += 4)
+    entries.push({ kind: kindOf(fields[at] ?? ''), bytes: Number(fields[at + 1]), modifiedAt: stamp(Number(fields[at + 2])), name: fields[at + 3] ?? '' });
+  return entries;
+}
+
+function parseFile(root: string, path: string, out: Buffer): FilesAnswer {
+  const end = out.indexOf(0);
+  const [size = '0', mtime = '0'] = out.subarray(0, end).toString('utf8').trim().split(' ');
+  const bytes = Number(size);
+  return { root, path, kind: 'file', bytes, modifiedAt: stamp(Number(mtime)), ...preview(out.subarray(end + 1), bytes) };
+}
+
+function readAsAgent(user: AgentUser, path: string): FilesAnswer {
+  const target = join(user.home, ...segmentsOf(path));
+  const [file, argv] = asUser(user, 'sh', ['-c', SCRIPT, 'metro', target, String(PREVIEW_BYTES + 1)]);
+  const run = spawnSync(file, argv, { stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 64 * 1024 * 1024, timeout: 20_000 });
+  if (run.error !== undefined) throw new ApiError(`could not read that path: ${run.error.message}`, 500);
+  if (run.status !== 0) throw new ApiError(run.stderr.toString('utf8').trim() || 'the agent cannot read that path', 404);
+  return answerOf(user.home, path, run.stdout);
+}
+
+export function answerOf(root: string, path: string, out: Buffer): FilesAnswer {
+  const body = out.subarray(2);
+  return out.subarray(0, 1).toString() === 'D' ? folderAnswer(root, path, parseListing(body)) : parseFile(root, path, body);
+}
+
+export function readAgentPath(user: AgentUser | null, path: string): FilesAnswer {
+  if (user === null) throw new ApiError('Claude Code does not run as its own user on this machine, so there is no agent folder to show', 409);
+  return readAsAgent(user, path);
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/home-fs.ts

@@ -0,0 +1,113 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createWriteStream, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { writeAtomic } from '@metro-labs/core/secure-fs';
+import { agentUser, asUser, type AgentUser } from './user.js';
+
+const WRITE = [
+  'set -e',
+  'mkdir -p -- "$(dirname -- "$1")"',
+  'tmp=$(mktemp -- "$1.metro-XXXXXX")',
+  'trap \'rm -f -- "$tmp"\' EXIT',
+  'cat > "$tmp"',
+  'chmod -- "$2" "$tmp"',
+  'if [ -n "$3" ]; then touch -d "@$3" -- "$tmp"; fi',
+  'mv -f -- "$tmp" "$1"',
+  'trap - EXIT',
+].join('\n');
+
+const octal = (mode: number): string => mode.toString(8);
+const epoch = (mtime: Date | undefined): string => (mtime === undefined ? '' : String(Math.floor(mtime.getTime() / 1000)));
+
+function runAs(user: AgentUser, script: string, args: string[], input?: string): void {
+  const [file, argv] = asUser(user, 'sh', ['-c', script, 'metro', ...args]);
+  const run = spawnSync(file, argv, { input, encoding: 'utf8', stdio: ['pipe', 'ignore', 'pipe'] });
+  if (run.error !== undefined) throw run.error;
+  if (run.status !== 0) throw new Error(`as ${user.name}: ${run.stderr.trim() || `exit ${String(run.status)}`}`);
+}
+
+export function writeHomeText(path: string, text: string, mode = 0o644, mtime?: Date, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, WRITE, [path, octal(mode), epoch(mtime)], text);
+    return;
+  }
+  writeAtomic(path, text, mode);
+  if (mtime !== undefined) utimesSync(path, mtime, mtime);
+}
+
+export function writeHomeInPlace(path: string, text: string, mode = 0o644, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, 'mkdir -p -- "$(dirname -- "$1")"; cat > "$1"; chmod -- "$2" "$1"', [path, octal(mode)], text);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text, { mode });
+}
+
+function filesUnder(root: string, rel = ''): string[] {
+  return readdirSync(join(root, rel), { withFileTypes: true }).flatMap((entry) => {
+    const inner = rel === '' ? entry.name : `${rel}/${entry.name}`;
+    if (entry.isDirectory()) return filesUnder(root, inner);
+    return entry.isFile() ? [inner] : [];
+  });
+}
+
+export function copyIntoHome(from: string, to: string, user = agentUser()): number {
+  removeHome(to, true, user);
+  const files = filesUnder(from);
+  for (const rel of files) {
+    const source = join(from, rel);
+    writeHomeText(join(to, rel), readFileSync(source, 'utf8'), statSync(source).mode & 0o777, undefined, user);
+  }
+  return files.length;
+}
+
+export function removeHome(path: string, recursive = false, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, recursive ? 'rm -rf -- "$1"' : 'rm -f -- "$1"', [path]);
+    return;
+  }
+  rmSync(path, { recursive, force: true });
+}
+
+export function moveHome(from: string, to: string, user = agentUser()): void {
+  if (user !== null) {
+    runAs(user, 'mv -f -- "$1" "$2"', [from, to]);
+    return;
+  }
+  renameSync(from, to);
+}
+
+async function receiveAs(user: AgentUser, path: string, source: Readable, mode: number): Promise<void> {
+  const [file, argv] = asUser(user, 'sh', ['-c', WRITE, 'metro', path, octal(mode), '']);
+  const child = spawn(file, argv, { stdio: ['pipe', 'ignore', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', (chunk: Buffer) => {
+    stderr += chunk.toString('utf8');
+  });
+  const closed = new Promise<number | null>((resolve, reject) => {
+    child.on('error', reject);
+    child.on('close', resolve);
+  });
+  await pipeline(source, child.stdin);
+  const status = await closed;
+  if (status !== 0) throw new Error(`as ${user.name}: ${stderr.trim() || `exit ${String(status)}`}`);
+}
+
+export async function receiveHomeFile(path: string, source: Readable, mode = 0o600, user = agentUser()): Promise<void> {
+  if (user !== null) {
+    await receiveAs(user, path, source, mode);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.metro-${String(process.pid)}.part`;
+  try {
+    await pipeline(source, createWriteStream(tmp, { mode }));
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/job-env.ts

@@ -0,0 +1,39 @@
+import { join } from 'node:path';
+import { log } from '@metro-labs/core/log';
+import { editCrontab, withBlock } from './crontab.js';
+import { writeHomeText } from './home-fs.js';
+import { listSchedules, realRunner, showProps, type Runner } from './schedules.js';
+import type { AgentUser } from './user.js';
+import { removeDropIn, writeDropIn } from './unit-files.js';
+
+const DROP_IN = '11-metro-vault.conf';
+const BEGIN = '# metro vault: begin';
+const END = '# metro vault: end';
+
+const jobEnvFile = (user: AgentUser): string => join(user.home, '.metro', 'vault.env');
+
+export function withCronEnv(lines: string[], env: Record<string, string>): string[] {
+  return withBlock(lines, BEGIN, END, Object.entries(env).map(([k, v]) => `${k}=${v}`), 'top');
+}
+
+function setTimerEnv(user: AgentUser, on: boolean, runner: Runner): void {
+  let changed = false;
+  for (const job of listSchedules(user, runner)) {
+    if (job.kind !== 'timer' || job.runsAs !== user.name) continue;
+    const unit = job.id.slice('timer:'.length);
+    const service = showProps(runner, unit, ['Unit']).Unit ?? unit.replace(/\.timer$/, '.service');
+    if (on) {
+      writeDropIn(service, DROP_IN, `[Service]\nEnvironmentFile=-${jobEnvFile(user)}\n`);
+      changed = true;
+    } else if (removeDropIn(service, DROP_IN)) changed = true;
+  }
+  if (changed) runner.run('systemctl', ['daemon-reload']);
+}
+
+export function exportJobEnv(user: AgentUser, env: Record<string, string>, runner: Runner = realRunner): void {
+  const on = Object.keys(env).length > 0;
+  writeHomeText(jobEnvFile(user), Object.entries(env).map(([k, v]) => `${k}=${v}\n`).join(''), 0o644);
+  editCrontab(user, runner, (lines) => withCronEnv(lines, env));
+  setTimerEnv(user, on, runner);
+  log.info({ on, keys: Object.keys(env).length }, "vault: the agent's scheduled jobs use the vault settings");
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/metro-home.ts

@@ -0,0 +1,42 @@
+import { chmodSync, lstatSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+
+const CLI_PREFIX = '.npm-global';
+const OPEN_BITS = 0o077;
+
+function entryHolding(home: string, path: string): string | null {
+  const rel = relative(home, path);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return null;
+  return rel.split(sep)[0] ?? null;
+}
+
+function sharedEntries(home: string, env: NodeJS.ProcessEnv = process.env): Set<string> {
+  const cli = env.METRO_CLI_BIN?.trim() ?? '';
+  const holding = cli === '' ? null : entryHolding(home, cli);
+  return new Set(holding === null ? [CLI_PREFIX] : [CLI_PREFIX, holding]);
+}
+
+function closeEntry(path: string): boolean {
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || (stat.mode & OPEN_BITS) === 0) return false;
+  chmodSync(path, stat.mode & 0o700);
+  return true;
+}
+
+export function closeMetroHome(home = homedir(), env: NodeJS.ProcessEnv = process.env): string[] {
+  chmodSync(home, 0o711);
+  const shared = sharedEntries(home, env);
+  const closed: string[] = [];
+  for (const name of readdirSync(home)) {
+    if (shared.has(name)) continue;
+    try {
+      if (closeEntry(join(home, name))) closed.push(name);
+    } catch (err) {
+      log.warn({ entry: name, err: errMsg(err) }, 'agent-user: could not close an entry of the metro home');
+    }
+  }
+  if (closed.length > 0) log.info({ closed }, 'agent-user: closed entries of the metro home so the agent user cannot read them');
+  return closed;
+}

package/runtime/node_modules/@metro-labs/daemon/src/agent-user/provision.ts

@@ -0,0 +1,81 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from './agent-fs.js';
+import { join } from 'node:path';
+import { chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { errMsg, log } from '@metro-labs/core/log';
+import { copyIntoHome } from './home-fs.js';
+import { AGENT_NAME, agentMarketplaceDir, agentUser, agentUserExpected, asUser, claudeBin, forgetAgentUser, type AgentUser } from './user.js';
+import { watchAgentView } from './view.js';
+import { closeMetroHome } from './metro-home.js';
+import { mustHelper } from '../metro-user/privilege.js';
+import { stagedPluginVersion } from '../claude/plugin-install.js';
+
+const INSTALL_MS = 10 * 60_000;
+const INSTALLER = 'curl -fsSL https://claude.ai/install.sh | bash';
+
+export type Provisioned = 'off' | 'failed' | 'ready';
+
+function run(file: string, args: string[]): void {
+  const done = spawnSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (done.error !== undefined) throw done.error;
+  if (done.status !== 0) throw new Error(`${file} ${args.join(' ')}: ${done.stderr.trim() || `exit ${String(done.status)}`}`);
+}
+
+function openMetroHome(): void {
+  closeMetroHome();
+  chmodSync(join(homedir(), '.metro'), 0o700);
+}
+
+function ensureUser(): AgentUser | null {
+  mustHelper(['ensure-agent']);
+  openMetroHome();
+  forgetAgentUser();
+  const user = agentUser();
+  if (user !== null) run(...asUser(user, 'chmod', ['711', user.home]));
+  return user;
+}
+
+function installClaude(user: AgentUser): Promise<void> {
+  if (existsSync(claudeBin(user))) return Promise.resolve();
+  const [file, args] = asUser(user, 'bash', ['-c', INSTALLER]);
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, { stdio: ['ignore', 'ignore', 'pipe'], cwd: '/', timeout: INSTALL_MS });
+    let said = '';
+    child.stderr.on('data', (chunk: Buffer) => {
+      said = `${said}${chunk.toString('utf8')}`.slice(-2000);
+    });
+    child.on('error', reject);
+    child.on('close', (code) => {
+      if (code === 0 && existsSync(claudeBin(user))) {
+        log.info({ user: user.name }, 'agent-user: installed Claude Code for the agent user');
+        resolve();
+      } else reject(new Error(`the Claude Code installer failed: ${said.trim() || `exit ${String(code)}`}`));
+    });
+  });
+}
+
+function copyMarketplace(user: AgentUser, env: NodeJS.ProcessEnv): void {
+  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
+  const from = join(store, 'marketplace');
+  if (store === '' || !existsSync(join(from, '.claude-plugin', 'marketplace.json'))) return;
+  const to = agentMarketplaceDir(user);
+  if (stagedPluginVersion(from) !== null && stagedPluginVersion(from) === stagedPluginVersion(to)) return;
+  const files = copyIntoHome(from, to, user);
+  log.info({ files, version: stagedPluginVersion(from) }, 'agent-user: copied the metro plugin where the agent user can load it');
+}
+
+export async function provisionAgentUser(env: NodeJS.ProcessEnv = process.env): Promise<Provisioned> {
+  if (!agentUserExpected()) return 'off';
+  try {
+    const user = ensureUser();
+    if (user === null) throw new Error(`the user ${AGENT_NAME} could not be found after creating it`);
+    await installClaude(user);
+    copyMarketplace(user, env);
+    watchAgentView();
+    return 'ready';
+  } catch (err) {
+    log.error({ user: AGENT_NAME, err: errMsg(err) }, 'agent-user: could not prepare the agent user; the Claude session stays stopped');
+    return 'failed';
+  }
+}