@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.321

package/runtime/node_modules/@metro-labs/daemon/src/claude/memory.ts

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { totalmem } from 'node:os';
+import { helperArgv, runningAsMetro } from '../metro-user/privilege.js';
+
+const GIB = 1024 ** 3;
+const RESERVE = 1.5 * GIB;
+const FLOOR = GIB;
+
+export interface ScopeHost {
+  metro: boolean;
+  systemd: boolean;
+  total: number;
+}
+
+const realHost = (): ScopeHost => ({
+  metro: runningAsMetro(),
+  systemd: existsSync('/run/systemd/system'),
+  total: totalmem(),
+});
+
+export function sessionMemoryLimit(total: number): number {
+  const kept = Math.min(Math.floor(total * 0.8), total - RESERVE);
+  return Math.max(FLOOR, Math.floor(kept / (1024 * 1024)) * 1024 * 1024);
+}
+
+export function inSessionScope(command: [string, string[]], host: ScopeHost = realHost()): [string, string[]] {
+  const [file, args] = command;
+  const asAgent = file === 'sudo' && args[0] === '-n' && args[1] === '-u' && args[3] === '--';
+  if (!host.metro || !host.systemd || !asAgent) return command;
+  const limit = sessionMemoryLimit(host.total);
+  return helperArgv(['as-agent-scope', String(limit), String(Math.floor(limit * 0.9)), ...args.slice(4)]);
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/runner-activity.ts

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { parseRunnerActivity, type RunnerActivity } from '@metro-labs/core/runner-activity';
+import { readRange } from '../agent-user/agent-fs.js';
+
+const MAX_BYTES = 65_536;
+
+export function readAgentActivity(home: string): RunnerActivity | null {
+  try {
+    const path = join(home, '.metro', 'agent-status.json');
+    const bytes = readRange(path, 0, MAX_BYTES + 1);
+    if (bytes.length > MAX_BYTES) return null;
+    const raw: unknown = JSON.parse(bytes.toString('utf8'));
+    return parseRunnerActivity(raw);
+  } catch {
+    return null;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/runner-process.ts

@@ -0,0 +1,52 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { RunnerActivity } from '@metro-labs/core/runner-activity';
+import { ApiError } from '@metro-labs/http/api-error';
+import { asAgent } from '../agent-user/user.js';
+import { readAgentActivity } from './runner-activity.js';
+
+function identity(pid: number): { started: string; zombie: boolean } | null {
+  try {
+    const stat = readFileSync(`/proc/${String(pid)}/stat`, 'utf8');
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    return { started: fields[19] ?? '', zombie: fields[0] === 'Z' };
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return isRecord(err) && err.code === 'EPERM';
+  }
+}
+
+export function sdkAlive(activity: RunnerActivity | null): activity is RunnerActivity {
+  if (activity === null) return false;
+  const found = identity(activity.pid);
+  if (found?.zombie === true) return false;
+  if (activity.procStart !== undefined && found !== null && activity.procStart !== found.started) return false;
+  if (activity.procStart === undefined && activity.phase === 'stopped') return false;
+  return pidAlive(activity.pid);
+}
+
+function assertIdentity(activity: RunnerActivity): void {
+  const found = identity(activity.pid);
+  if (activity.pid === process.pid || activity.procStart === undefined || activity.procStart !== found?.started)
+    throw new ApiError('The Agent SDK is still running outside tmux, but its process identity cannot be verified safely. Stop that metro agent process from its terminal.', 503);
+}
+
+export function stopSdkRunner(home: string, cancelActive = false): boolean {
+  const activity = readAgentActivity(home);
+  if (!sdkAlive(activity)) return false;
+  assertIdentity(activity);
+  const signal = cancelActive && activity.cancelSignal === 'SIGUSR2' ? '-USR2' : '-TERM';
+  const run = spawnSync(...asAgent('kill', [signal, String(activity.pid)]), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if ((run.error !== undefined || run.status !== 0) && sdkAlive(activity))
+    throw new ApiError(`The Agent SDK could not be stopped: ${run.error?.message ?? run.stderr.trim()}`, 503);
+  return true;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/session-files.ts

@@ -0,0 +1,75 @@
+import { existsSync, statSync } from '../agent-user/agent-fs.js';
+import { Transform, type Readable } from 'node:stream';
+import { moveHome, receiveHomeFile, removeHome } from '../agent-user/home-fs.js';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { claudeDir, PROJECT_RE, safeName, SESSION_RE } from './files.js';
+
+const SESSION_FILE_MAX = 512 * 1024 * 1024;
+const FILE_MODE = 0o644;
+
+export interface SessionFile {
+  id: string;
+  bytes: number;
+}
+
+const transcriptPath = (project: string, session: string, dir: string): string =>
+  join(dir, 'projects', safeName(project, PROJECT_RE, 'Claude project id'), `${safeName(session, SESSION_RE, 'session id')}.jsonl`);
+
+export function sessionFilePath(project: string, session: string, dir = claudeDir()): string {
+  const path = transcriptPath(project, session, dir);
+  if (!existsSync(path)) throw new ApiError('no such session', 404);
+  if (statSync(path).size > SESSION_FILE_MAX) throw new ApiError(`a session file is at most ${String(SESSION_FILE_MAX)} bytes`, 400);
+  return path;
+}
+
+const HEAD_BYTES = 64 * 1024;
+
+function watched(body: Readable, head: Buffer[]): Transform {
+  let total = 0;
+  let kept = 0;
+  const check = new Transform({
+    transform(chunk: Buffer, _enc, done): void {
+      total += chunk.length;
+      if (total > SESSION_FILE_MAX) {
+        done(new ApiError(`a session file is at most ${String(SESSION_FILE_MAX)} bytes`, 413));
+        return;
+      }
+      if (kept < HEAD_BYTES) {
+        head.push(chunk.subarray(0, HEAD_BYTES - kept));
+        kept += chunk.length;
+      }
+      done(null, chunk);
+    },
+  });
+  return body.pipe(check);
+}
+
+export async function receiveSessionFile(project: string, session: string, body: Readable, dir = claudeDir()): Promise<SessionFile> {
+  const path = transcriptPath(project, session, dir);
+  const tmp = `${path}.metro-upload`;
+  const head: Buffer[] = [];
+  try {
+    await receiveHomeFile(tmp, watched(body, head), FILE_MODE);
+  } catch (err) {
+    removeHome(tmp);
+    throw err;
+  }
+  if (!firstLineIsJson(Buffer.concat(head).toString('utf8'))) {
+    removeHome(tmp);
+    throw new ApiError('a session file is JSON lines, one Claude Code entry per line', 400);
+  }
+  moveHome(tmp, path);
+  return { id: safeName(session, SESSION_RE, 'session id'), bytes: statSync(path).size };
+}
+
+function firstLineIsJson(text: string): boolean {
+  const first = text.split('\n').find((line) => line.trim() !== '');
+  if (first === undefined) return false;
+  try {
+    return isRecord(JSON.parse(first));
+  } catch {
+    return false;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/session.ts

@@ -0,0 +1,294 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { ApiError } from '@metro-labs/http/api-error';
+import type { RunnerActivity } from '@metro-labs/core/runner-activity';
+import { readAgentActivity } from './runner-activity.js';
+import { sdkAlive, stopSdkRunner } from './runner-process.js';
+import { syncAgentView } from '../agent-user/view.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeJson } from '@metro-labs/core/secure-fs';
+import { METRO_VERSION } from '@metro-labs/core/version';
+import { agentsDir, listAgentFiles } from '../agents/files.js';
+import { notReady, primaryRoute, type ModelSetup } from '../gateway/model-config.js';
+import { effectiveSetup } from '../gateway/effective.js';
+import { inSessionScope } from './memory.js';
+import { runningAsRoot } from '../metro-user/privilege.js';
+import { agentUser, agentUserExpected, agentViewDir, asAgent, claudeHome } from '../agent-user/user.js';
+
+function sessionEnv(): Record<string, string> {
+  const user = agentUser();
+  if (user === null) return {};
+  const port = process.env.METRO_WEBHOOK_PORT?.trim() ?? '';
+  return { METRO_AGENTS_DIR: agentViewDir(user), ...(port === '' ? {} : { METRO_WEBHOOK_PORT: port }) };
+}
+
+const SESSION_NAME = 'metro';
+const STATE_FILE = 'claude-session.json';
+const WATCH_MS = 15_000;
+const STRIKE_WINDOW_MS = 60_000;
+const MAX_STRIKES = 5;
+const PAUSE_MS = 30 * 60_000;
+const PREPARE_MS = 16 * 60_000;
+
+export interface SessionDeps {
+  tmux?: string;
+  metro?: string[];
+  home?: string;
+  agents?: string;
+  model?: () => ModelSetup;
+  now?: () => number;
+  version?: string;
+}
+
+export interface SessionStatus {
+  name: string;
+  running: boolean;
+  activity?: RunnerActivity | null;
+  autostart: boolean;
+  blocked: string | null;
+  lastStartedAt: string | null;
+  lastError: string | null;
+}
+
+export interface SessionSnapshot {
+  running: boolean;
+  activity: RunnerActivity | null;
+  lastStartedAt: string | null;
+}
+
+interface Memory {
+  lastStartedAt: number | null;
+  lastError: string | null;
+  strikes: number;
+  pausedUntil: number;
+}
+
+const memory: Memory = { lastStartedAt: null, lastError: null, strikes: 0, pausedUntil: 0 };
+
+const statePath = (agents: string): string => join(agents, STATE_FILE);
+
+function readState(agents: string): Record<string, unknown> {
+  const raw = readJson<unknown>(statePath(agents), null);
+  return isRecord(raw) ? raw : {};
+}
+
+const writeState = (agents: string, patch: Record<string, unknown>): void => {
+  writeJson(statePath(agents), { ...readState(agents), ...patch });
+};
+
+export const autostartEnabled = (agents = agentsDir()): boolean => readState(agents).autostart !== false;
+
+export function setAutostart(enabled: boolean, agents = agentsDir()): void {
+  writeState(agents, { autostart: enabled });
+}
+
+function startedVersion(agents = agentsDir()): string | null {
+  const version = readState(agents).version;
+  return typeof version === 'string' ? version : null;
+}
+
+function tmuxOk(tmux: string, args: string[]): boolean {
+  const run = spawnSync(...asAgent(tmux, args), { stdio: 'ignore' });
+  return run.error === undefined && run.status === 0;
+}
+
+export const sessionRunning = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['has-session', '-t', SESSION_NAME]);
+
+export const tmuxServerUp = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['list-sessions']);
+
+export function metroCli(args: string[], fixed?: string[]): string[] {
+  const bin = process.env.METRO_CLI_BIN?.trim() ?? '';
+  const runtime = agentUser() === null ? process.execPath : 'node';
+  const base = fixed ?? (bin === '' ? ['metro', ...args] : [runtime, bin, ...args]);
+  const env = Object.entries(sessionEnv()).map(([k, v]) => `${k}=${v}`);
+  return env.length === 0 || fixed !== undefined ? base : ['env', ...env, ...base];
+}
+
+const sessionHome = (deps: SessionDeps): string => deps.home ?? claudeHome() ?? homedir();
+
+export function assertSessionStopped(deps: SessionDeps = {}): void {
+  if (sessionLive(deps)) throw new ApiError('The session is running. Let it finish its work, stop it, then change its permissions or prompt and start it again.', 409);
+}
+
+export function prepareRunnerStore(): Promise<void> {
+  const [bin = 'metro', ...args] = metroCli(['agent', '--prepare']);
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn(...asAgent(bin, args), { stdio: ['ignore', 'ignore', 'pipe'], cwd: '/', timeout: PREPARE_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) resolve();
+      else reject(new Error(`metro agent --prepare failed: ${said.trim() || `exit ${String(code)}`}`));
+    });
+  });
+}
+
+const NO_MODEL = "the organization routes this agent to no model yet: choose one on the organization's Models page";
+
+function credentialReady(deps: SessionDeps): string | null {
+  try {
+    const primary = primaryRoute((deps.model ?? (() => effectiveSetup()))());
+    return primary === null ? NO_MODEL : notReady(primary);
+  } catch (err) {
+    return `the model setup is not readable (${errMsg(err)})`;
+  }
+}
+
+const agentUserMissing = (deps: SessionDeps): boolean =>
+  deps.metro === undefined && agentUserExpected() && agentUser() === null;
+
+const ROOT_REFUSED = 'Metro runs as root; reinstall it as the metro user';
+
+export function sessionBlocked(deps: SessionDeps = {}): string | null {
+  if (runningAsRoot()) return ROOT_REFUSED;
+  if (listAgentFiles(deps.agents ?? agentsDir()).length === 0) return 'no agent on this machine yet';
+  return launchBlocked(deps);
+}
+
+function launchBlocked(deps: SessionDeps): string | null {
+  if (agentUserMissing(deps))
+    return 'Claude Code runs as the user agent here, and that user is not ready yet; see the log';
+  if (!tmuxOk(deps.tmux ?? 'tmux', ['-V'])) return 'tmux is not installed on this machine';
+  return credentialReady(deps);
+}
+
+function recordStart(deps: SessionDeps, now: number, run: { error?: Error; status: number | null; stderr: string }): void {
+  memory.lastStartedAt = now;
+  if (run.error !== undefined || run.status !== 0) {
+    memory.lastError = run.error === undefined ? `tmux new-session exited ${String(run.status)}: ${run.stderr.trim()}` : errMsg(run.error);
+    log.warn({ err: memory.lastError }, 'claude-session: tmux could not start');
+    return;
+  }
+  memory.lastError = null;
+  writeState(deps.agents ?? agentsDir(), { version: deps.version ?? METRO_VERSION });
+}
+
+function tmuxLaunch(deps: SessionDeps, tmux: string, args: string[]): [string, string[]] {
+  const launch = asAgent(tmux, args);
+  return deps.tmux === undefined && !tmuxServerUp(tmux) ? inSessionScope(launch) : launch;
+}
+
+export function startSession(deps: SessionDeps = {}): SessionStatus {
+  const status = sessionStatus(deps);
+  if (status.running) return status;
+  if (status.blocked !== null) throw new ApiError(`Cannot start the session: ${status.blocked}`, 409);
+  syncAgentView(undefined, deps.agents);
+  const tmux = deps.tmux ?? 'tmux';
+  const home = sessionHome(deps);
+  const now = (deps.now ?? Date.now)();
+  const [command = 'metro', ...args] = metroCli(['agent'], deps.metro);
+  const tmuxArgs = ['new-session', '-d', '-s', SESSION_NAME, '-c', home, '-x', '200', '-y', '50', command, ...args];
+  const launch = tmuxLaunch(deps, tmux, tmuxArgs);
+  const run = spawnSync(...launch, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd: '/' });
+  recordStart(deps, now, run);
+  if (memory.lastError === null) log.info({ home, command: [command, ...args].join(' ') }, 'claude-session: started the Agent SDK runner in tmux');
+  return sessionStatus(deps);
+}
+
+export function stopSession(deps: SessionDeps = {}, cancelActive = false): SessionStatus {
+  if (!stopSdkRunner(sessionHome(deps), cancelActive))
+    spawnSync(...asAgent(deps.tmux ?? 'tmux', ['kill-session', '-t', SESSION_NAME]), { stdio: 'ignore' });
+  return sessionStatus(deps);
+}
+
+export const runnerAlive = (deps: SessionDeps = {}): boolean => sdkAlive(readAgentActivity(sessionHome(deps)));
+
+export const sessionLive = (deps: SessionDeps = {}): boolean => sessionRunning(deps.tmux ?? 'tmux') || runnerAlive(deps);
+
+export function sessionSnapshot(deps: SessionDeps = {}): SessionSnapshot {
+  const activity = readAgentActivity(sessionHome(deps));
+  return {
+    running: sdkAlive(activity) || sessionRunning(deps.tmux ?? 'tmux'),
+    activity,
+    lastStartedAt: memory.lastStartedAt === null ? null : new Date(memory.lastStartedAt).toISOString(),
+  };
+}
+
+export function sessionStatus(deps: SessionDeps = {}): SessionStatus {
+  return {
+    name: SESSION_NAME,
+    ...sessionSnapshot(deps),
+    autostart: autostartEnabled(deps.agents ?? agentsDir()),
+    blocked: sessionBlocked(deps),
+    lastError: memory.lastError,
+  };
+}
+
+function strike(now: number): boolean {
+  if (memory.lastStartedAt !== null && now - memory.lastStartedAt < STRIKE_WINDOW_MS) memory.strikes += 1;
+  else memory.strikes = 1;
+  if (memory.strikes < MAX_STRIKES) return false;
+  memory.pausedUntil = now + PAUSE_MS;
+  memory.strikes = 0;
+  log.warn({ pauseMinutes: PAUSE_MS / 60_000 }, 'claude-session: the session keeps exiting right after starting; not restarting it for a while');
+  return true;
+}
+
+export type Ensured = 'started' | 'restarted' | 'running' | 'blocked' | 'off' | 'paused';
+
+function holdsBack(deps: SessionDeps, now: number): Ensured | null {
+  if (now < memory.pausedUntil) return 'paused';
+  if (sessionBlocked(deps) !== null) return 'blocked';
+  return strike(now) ? 'paused' : null;
+}
+
+interface Resolved {
+  now: number;
+  agents: string;
+  version: string;
+  tmux: string;
+}
+
+const resolved = (deps: SessionDeps): Resolved => ({
+  now: (deps.now ?? Date.now)(),
+  agents: deps.agents ?? agentsDir(),
+  version: deps.version ?? METRO_VERSION,
+  tmux: deps.tmux ?? 'tmux',
+});
+
+function situation(r: Resolved): 'running' | 'stale' | 'absent' {
+  if (!sessionRunning(r.tmux)) return 'absent';
+  return startedVersion(r.agents) === r.version ? 'running' : 'stale';
+}
+
+export function ensureSession(deps: SessionDeps = {}): Ensured {
+  const r = resolved(deps);
+  if (!autostartEnabled(r.agents)) return 'off';
+  const found = situation(r);
+  if (found === 'running' || (found === 'absent' && sessionLive(deps))) return 'running';
+  const held = holdsBack(deps, r.now);
+  if (held !== null) return held;
+  if (found === 'stale') {
+    log.info({ was: startedVersion(r.agents), now: r.version }, 'claude-session: restarting the session an older metro started, so the new hooks and flags load');
+    stopSession(deps);
+  }
+  startSession(deps);
+  return found === 'stale' ? 'restarted' : 'started';
+}
+
+let watcher: ReturnType<typeof setInterval> | null = null;
+
+export function watchSession(deps: SessionDeps = {}, everyMs = WATCH_MS): void {
+  if (watcher !== null) return;
+  const tick = (): void => {
+    try {
+      const outcome = ensureSession(deps);
+      if (outcome === 'started' || outcome === 'restarted') log.info({ outcome }, 'claude-session: the Agent SDK runner is up');
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'claude-session: check failed');
+    }
+  };
+  watcher = setInterval(tick, everyMs);
+  watcher.unref();
+  setTimeout(tick, 1_000).unref();
+}
+
+export function unwatchSession(): void {
+  if (watcher !== null) clearInterval(watcher);
+  watcher = null;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/settings.ts

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, realpathSync, statSync } from '../agent-user/agent-fs.js';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { claudeDir, listClaudeProjects } from './files.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { writeHomeText } from '../agent-user/home-fs.js';
+
+export const SETTINGS_MAX = 256 * 1024;
+const USER_ID = 'user';
+const LOCAL_SUFFIX = '.local';
+
+type SettingsScope = 'user' | 'project' | 'local';
+
+export interface ClaudeSettingsFile {
+  id: string;
+  scope: SettingsScope;
+  label: string;
+  path: string;
+  exists: boolean;
+  editable: boolean;
+  text: string;
+  modifiedAt: string | null;
+}
+
+const missing = (id: string, scope: SettingsScope, label: string, path: string): ClaudeSettingsFile => ({
+  id,
+  scope,
+  label,
+  path,
+  exists: false,
+  editable: true,
+  text: '',
+  modifiedAt: null,
+});
+
+function entryOf(id: string, scope: SettingsScope, label: string, path: string): ClaudeSettingsFile {
+  if (!existsSync(path)) return missing(id, scope, label, path);
+  const stat = statSync(path);
+  const editable = stat.size <= SETTINGS_MAX;
+  return {
+    id,
+    scope,
+    label,
+    path,
+    exists: true,
+    editable,
+    text: editable ? readFileSync(path, 'utf8') : '',
+    modifiedAt: stat.mtime.toISOString(),
+  };
+}
+
+const PROJECT_FILES: [string, SettingsScope, string][] = [
+  ['', 'project', 'settings.json'],
+  [LOCAL_SUFFIX, 'local', 'settings.local.json'],
+];
+
+function projectEntries(dir: string): ClaudeSettingsFile[] {
+  const out: ClaudeSettingsFile[] = [];
+  for (const project of listClaudeProjects(dir)) {
+    const cwd = project.cwd;
+    if (cwd === null) continue;
+    for (const [suffix, scope, name] of PROJECT_FILES) {
+      const path = join(cwd, '.claude', name);
+      if (existsSync(path)) out.push(entryOf(`${project.id}${suffix}`, scope, cwd, path));
+    }
+  }
+  return out;
+}
+
+const sameFile = (a: string, b: string): boolean => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+};
+
+export function listClaudeSettings(dir = claudeDir()): ClaudeSettingsFile[] {
+  const user = entryOf(USER_ID, 'user', 'This machine', join(dir, 'settings.json'));
+  return [user, ...projectEntries(dir).filter((p) => !sameFile(p.path, user.path))];
+}
+
+function assertSettingsJson(text: string): void {
+  if (text.length > SETTINGS_MAX) throw new ApiError('that is more text than a settings file may hold', 413);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new ApiError(`that is not valid JSON: ${errMsg(err)}`, 400);
+  }
+  if (!isRecord(parsed)) throw new ApiError('Claude Code settings must be a JSON object', 400);
+}
+
+export function writeClaudeSettings(
+  id: string,
+  text: string,
+  seenAt: string | null | undefined,
+  dir = claudeDir(),
+): ClaudeSettingsFile {
+  const target = listClaudeSettings(dir).find((file) => file.id === id);
+  if (target === undefined) throw new ApiError('no such settings file', 404);
+  if (!target.editable) throw new ApiError('that settings file is too large to edit here', 409);
+  assertSettingsJson(text);
+  if (seenAt !== undefined && seenAt !== target.modifiedAt)
+    throw new ApiError('that file changed on disk since you opened it; reload it before saving', 409);
+  writeHomeText(target.path, text, existsSync(target.path) ? statSync(target.path).mode & 0o777 : 0o644);
+  return entryOf(target.id, target.scope, target.label, target.path);
+}