@north-light/api 0.3.580 → 0.3.587

package/dist/launcher/limits/policy.d.ts

@@ -0,0 +1,141 @@
+export declare const GIB: number;
+export declare const MIB: number;
+/** The one app with no per-app cap by default (the person's own agent). */
+export declare const UNCAPPED_BY_DEFAULT_APP = "terminal";
+/** Memory kept for crtrd, the launcher and the RAM-backed root filesystem. */
+export declare const RUNTIME_RESERVE_BYTES: number;
+export declare const DEFAULT_APP_MEMORY_BYTES: number;
+export declare const DEFAULT_APP_DISK_BYTES: number;
+export declare const DEFAULT_APP_PIDS = 2048;
+/** Hard ceiling of the project that holds an app's `conversations/` folder. */
+export declare const CONVERSATIONS_DISK_BYTES: number;
+export declare const SANDBOX_ROOT_TMPFS_BYTES: number;
+export declare const SANDBOX_TMP_TMPFS_BYTES: number;
+export declare const CRTRD_OOM_SCORE_ADJ = -900;
+export declare const SANDBOX_OOM_SCORE_ADJ = 300;
+/** Project ids of `conversations/` folders; app uids stay below this. */
+export declare const CONVERSATIONS_PROJECT_OFFSET = 1000000;
+export declare const MIN_MEMORY_BYTES: number;
+export declare const MIN_DISK_BYTES: number;
+/** `'unlimited'` removes the cap for that resource. */
+export type CapValue = number | 'unlimited';
+export interface AppOverride {
+    memory_bytes?: CapValue;
+    disk_bytes?: CapValue;
+}
+export interface LimitSettings {
+    version: 1;
+    apps: Record<string, AppOverride>;
+}
+export interface AppBudget {
+    /** null means no per-app cap (bounded only by the `apps/` parent). */
+    memoryBytes: number | null;
+    diskBytes: number | null;
+    pids: number | null;
+    memorySource: 'default' | 'override';
+    diskSource: 'default' | 'override';
+}
+/** The bare app id (`terminal`) for `app:terminal` or `terminal`. */
+export declare function bareApp(app: string): string;
+export declare function budgetFor(app: string, settings: LimitSettings): AppBudget;
+/** `apps/` memory.max: guest memory less the runtime reserve; a guest smaller than the reserve gives apps half. */
+export declare function appsMemoryMax(totalBytes: number, reserve?: number): number;
+/** An app's cgroup values. `memory.high` is left at `max` on purpose: with it set below `memory.max`, a process whose memory cannot be reclaimed (anonymous pages, no swap) is throttled in the kernel indefinitely instead of being OOM-killed at the cap. `memory.swap.max` is 0 so the cap bounds real memory, not memory plus the host's swap. */
+export interface CgroupValues {
+    memoryMax: string;
+    memoryHigh: 'max';
+    swapMax: string;
+    pidsMax: string;
+}
+export declare function appCgroupValues(budget: AppBudget): CgroupValues;
+export declare function appCgroupPath(root: string, app: string): string;
+export declare function runCgroupPath(root: string, app: string, run: string): string;
+export declare function runGroupName(nodeId: string, nonce: string): string;
+/** Project id of an app's space: the app uid. */
+export declare function appProjectId(uid: number): number;
+export declare function conversationsProjectId(uid: number): number;
+/** ext4 quota block limits are counted in 1 KiB blocks; 0 removes the limit. */
+export declare function quotaBlocks(bytes: number | null): number;
+/** Whether `used` passes `fraction` of `limit`; an uncapped app never does. */
+export declare function passesFraction(used: number, limit: number | null, fraction: number): boolean;
+export declare const APP_QUOTA_CLEANUP_FRACTION = 0.8;
+export declare const DISK_CLEANUP_FRACTION = 0.85;
+export interface MemoryEvents {
+    oomKill: number;
+    oomGroupKill: number;
+}
+export declare function parseMemoryEvents(text: string): MemoryEvents;
+/** Whether the kernel's OOM killer ended any process of the run. */
+export declare function wasOomKilled(events: MemoryEvents): boolean;
+/** The terminal reason a node ends with when its run was OOM-killed. */
+export declare const OUT_OF_MEMORY_REASON: "out_of_memory";
+export declare function exitReasonFor(oomKilled: boolean, ordinary: 'crashed' | 'boot_failed' | 'crash_looped'): 'out_of_memory' | typeof ordinary;
+/** Largest kernel `memory.peak` of any broker run group in its first 20 s (498 MiB measured), rounded up. */
+export declare const BOOT_RESERVATION_BYTES: number;
+/** How long a launched broker still counts as booting; no measured group exceeded 261 MiB after it. */
+export declare const BOOT_WINDOW_MS = 20000;
+/** Growth the app's running nodes can still add: the largest measured (833 MiB), rounded up. */
+export declare const GROWTH_HEADROOM_BYTES: number;
+/** How long an admission holds its boot reservation while the launch it admitted has not reached the launcher. */
+export declare const ADMISSION_TICKET_MS = 30000;
+/** What a broker that started `BOOT_WINDOW_MS` ago or less still has to claim: its reservation less what it holds now, so it is not counted twice. */
+export declare function bootPendingBytes(currentBytes: number): number;
+/** One cgroup level's memory as the launcher measured it. */
+export interface MemoryLevel {
+    /** null means no cap at this level. */
+    max: number | null;
+    current: number;
+    /** Boot reservations not yet visible in `current`. */
+    pending: number;
+    /** A live broker run or an unexpired ticket exists at this level. */
+    hasBroker: boolean;
+}
+export type MemoryAdmissionLevel = 'app' | 'apps';
+export type MemoryAdmission = {
+    verdict: 'admitted';
+} | {
+    verdict: 'denied';
+    level: MemoryAdmissionLevel;
+    free_bytes: number;
+    needed_bytes: number;
+} | {
+    verdict: 'too_small';
+    level: MemoryAdmissionLevel;
+    max_bytes: number;
+    needed_bytes: number;
+};
+/**
+ * Whether one more broker may start. Each capped level must cover the boot reservation, plus the growth headroom
+ * once a broker already runs there: with none, the broker's own boot is the only risk, and waiting would never help.
+ * A cap below the reservation can never admit a broker. `app` is checked before `apps`.
+ */
+export declare function memoryAdmission(levels: {
+    app: MemoryLevel;
+    apps: MemoryLevel;
+}): MemoryAdmission;
+export interface TmpfsSizes {
+    root: number;
+    tmp: number;
+}
+/** `/` holds only mount points; `/tmp` pages are charged to the run's cgroup, so a capped app gets at most a quarter of its memory there. */
+export declare function tmpfsSizes(budget: AppBudget): TmpfsSizes;
+export declare const CACHE_STALE_MS: number;
+export declare const CACHE_PASS_INTERVAL_MS: number;
+/** Whether a cache file has gone untouched (atime and mtime) for three days. */
+export declare function isStale(file: {
+    atimeMs: number;
+    mtimeMs: number;
+}, now: number): boolean;
+export interface AppUsage {
+    app: string;
+    usedBytes: number;
+    limitBytes: number | null;
+}
+export type PurgeMode = 'stale' | 'all';
+/** What the cache pass does for each app: an app past 80 % of its quota, or any app while the disk is past 85 %, loses its whole cache; the rest lose only stale files. */
+export declare function selectCachePurges(apps: readonly AppUsage[], diskUsedFraction: number): Array<{
+    app: string;
+    mode: PurgeMode;
+}>;
+/** At most one pass per hour of awake time; the first call (daemon boot) always runs. */
+export declare function cachePassDue(lastPassAt: number | null, now: number): boolean;

package/dist/launcher/limits/policy.js

@@ -0,0 +1,142 @@
+// Pure arithmetic and path rules for per-app memory and disk limits. Nothing
+// here touches the host: cgroup.ts, quota.ts and manager.ts apply the results.
+export const GIB = 1024 ** 3;
+export const MIB = 1024 ** 2;
+/** The one app with no per-app cap by default (the person's own agent). */
+export const UNCAPPED_BY_DEFAULT_APP = 'terminal';
+/** Memory kept for crtrd, the launcher and the RAM-backed root filesystem. */
+export const RUNTIME_RESERVE_BYTES = 1 * GIB;
+export const DEFAULT_APP_MEMORY_BYTES = 2 * GIB;
+export const DEFAULT_APP_DISK_BYTES = 1 * GIB;
+export const DEFAULT_APP_PIDS = 2048;
+/** Hard ceiling of the project that holds an app's `conversations/` folder. */
+export const CONVERSATIONS_DISK_BYTES = 512 * MIB;
+export const SANDBOX_ROOT_TMPFS_BYTES = 64 * MIB;
+export const SANDBOX_TMP_TMPFS_BYTES = 512 * MIB;
+export const CRTRD_OOM_SCORE_ADJ = -900;
+export const SANDBOX_OOM_SCORE_ADJ = 300;
+/** Project ids of `conversations/` folders; app uids stay below this. */
+export const CONVERSATIONS_PROJECT_OFFSET = 1_000_000;
+export const MIN_MEMORY_BYTES = 64 * MIB;
+export const MIN_DISK_BYTES = 16 * MIB;
+/** The bare app id (`terminal`) for `app:terminal` or `terminal`. */
+export function bareApp(app) {
+    return app.startsWith('app:') ? app.slice(4) : app;
+}
+export function budgetFor(app, settings) {
+    const id = bareApp(app);
+    const override = settings.apps[id] ?? {};
+    const uncapped = id === UNCAPPED_BY_DEFAULT_APP;
+    const resolve = (value, fallback) => {
+        if (value === undefined)
+            return { bytes: uncapped ? null : fallback, source: 'default' };
+        return { bytes: value === 'unlimited' ? null : value, source: 'override' };
+    };
+    const memory = resolve(override.memory_bytes, DEFAULT_APP_MEMORY_BYTES);
+    const disk = resolve(override.disk_bytes, DEFAULT_APP_DISK_BYTES);
+    return {
+        memoryBytes: memory.bytes, diskBytes: disk.bytes,
+        pids: uncapped ? null : DEFAULT_APP_PIDS,
+        memorySource: memory.source, diskSource: disk.source,
+    };
+}
+/** `apps/` memory.max: guest memory less the runtime reserve; a guest smaller than the reserve gives apps half. */
+export function appsMemoryMax(totalBytes, reserve = RUNTIME_RESERVE_BYTES) {
+    if (totalBytes > reserve)
+        return Math.floor(totalBytes - reserve);
+    return Math.max(MIN_MEMORY_BYTES, Math.floor(totalBytes / 2));
+}
+export function appCgroupValues(budget) {
+    return {
+        memoryMax: budget.memoryBytes === null ? 'max' : String(budget.memoryBytes),
+        memoryHigh: 'max',
+        swapMax: budget.memoryBytes === null ? 'max' : '0',
+        pidsMax: budget.pids === null ? 'max' : String(budget.pids),
+    };
+}
+export function appCgroupPath(root, app) { return `${root}/apps/${bareApp(app)}`; }
+export function runCgroupPath(root, app, run) { return `${appCgroupPath(root, app)}/${run}`; }
+const RUN_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+export function runGroupName(nodeId, nonce) {
+    const name = `${nodeId}.${nonce}`;
+    if (!RUN_NAME.test(name))
+        throw new Error(`invalid run group name: ${name}`);
+    return name;
+}
+/** Project id of an app's space: the app uid. */
+export function appProjectId(uid) { return uid; }
+export function conversationsProjectId(uid) { return uid + CONVERSATIONS_PROJECT_OFFSET; }
+/** ext4 quota block limits are counted in 1 KiB blocks; 0 removes the limit. */
+export function quotaBlocks(bytes) { return bytes === null ? 0 : Math.ceil(bytes / 1024); }
+/** Whether `used` passes `fraction` of `limit`; an uncapped app never does. */
+export function passesFraction(used, limit, fraction) {
+    return limit !== null && limit > 0 && used > limit * fraction;
+}
+export const APP_QUOTA_CLEANUP_FRACTION = 0.8;
+export const DISK_CLEANUP_FRACTION = 0.85;
+export function parseMemoryEvents(text) {
+    const read = (key) => {
+        const m = new RegExp(`^${key}\\s+(\\d+)\\s*$`, 'm').exec(text);
+        return m ? Number(m[1]) : 0;
+    };
+    return { oomKill: read('oom_kill'), oomGroupKill: read('oom_group_kill') };
+}
+/** Whether the kernel's OOM killer ended any process of the run. */
+export function wasOomKilled(events) { return events.oomKill > 0 || events.oomGroupKill > 0; }
+/** The terminal reason a node ends with when its run was OOM-killed. */
+export const OUT_OF_MEMORY_REASON = 'out_of_memory';
+export function exitReasonFor(oomKilled, ordinary) {
+    return oomKilled ? OUT_OF_MEMORY_REASON : ordinary;
+}
+// Broker memory admission
+/** Largest kernel `memory.peak` of any broker run group in its first 20 s (498 MiB measured), rounded up. */
+export const BOOT_RESERVATION_BYTES = 512 * MIB;
+/** How long a launched broker still counts as booting; no measured group exceeded 261 MiB after it. */
+export const BOOT_WINDOW_MS = 20_000;
+/** Growth the app's running nodes can still add: the largest measured (833 MiB), rounded up. */
+export const GROWTH_HEADROOM_BYTES = 850 * MIB;
+/** How long an admission holds its boot reservation while the launch it admitted has not reached the launcher. */
+export const ADMISSION_TICKET_MS = 30_000;
+/** What a broker that started `BOOT_WINDOW_MS` ago or less still has to claim: its reservation less what it holds now, so it is not counted twice. */
+export function bootPendingBytes(currentBytes) { return Math.max(0, BOOT_RESERVATION_BYTES - currentBytes); }
+/**
+ * Whether one more broker may start. Each capped level must cover the boot reservation, plus the growth headroom
+ * once a broker already runs there: with none, the broker's own boot is the only risk, and waiting would never help.
+ * A cap below the reservation can never admit a broker. `app` is checked before `apps`.
+ */
+export function memoryAdmission(levels) {
+    const applicable = ['app', 'apps'].flatMap(level => (levels[level].max === null ? [] : [{ level, ...levels[level], max: levels[level].max }]));
+    const small = applicable.find(l => l.max < BOOT_RESERVATION_BYTES);
+    if (small)
+        return { verdict: 'too_small', level: small.level, max_bytes: small.max, needed_bytes: BOOT_RESERVATION_BYTES };
+    for (const l of applicable) {
+        const needed = BOOT_RESERVATION_BYTES + (l.hasBroker ? GROWTH_HEADROOM_BYTES : 0);
+        const free = l.max - l.current - l.pending;
+        if (free < needed)
+            return { verdict: 'denied', level: l.level, free_bytes: free, needed_bytes: needed };
+    }
+    return { verdict: 'admitted' };
+}
+/** `/` holds only mount points; `/tmp` pages are charged to the run's cgroup, so a capped app gets at most a quarter of its memory there. */
+export function tmpfsSizes(budget) {
+    const ceiling = budget.memoryBytes === null ? 1 * GIB : Math.max(64 * MIB, Math.min(SANDBOX_TMP_TMPFS_BYTES, Math.floor(budget.memoryBytes / 4)));
+    return { root: SANDBOX_ROOT_TMPFS_BYTES, tmp: ceiling };
+}
+// Cache purge
+export const CACHE_STALE_MS = 3 * 24 * 60 * 60_000;
+export const CACHE_PASS_INTERVAL_MS = 60 * 60_000;
+/** Whether a cache file has gone untouched (atime and mtime) for three days. */
+export function isStale(file, now) {
+    return now - Math.max(file.atimeMs, file.mtimeMs) >= CACHE_STALE_MS;
+}
+/** What the cache pass does for each app: an app past 80 % of its quota, or any app while the disk is past 85 %, loses its whole cache; the rest lose only stale files. */
+export function selectCachePurges(apps, diskUsedFraction) {
+    const diskFull = diskUsedFraction > DISK_CLEANUP_FRACTION;
+    return apps.map(({ app, usedBytes, limitBytes }) => ({
+        app, mode: diskFull || passesFraction(usedBytes, limitBytes, APP_QUOTA_CLEANUP_FRACTION) ? 'all' : 'stale',
+    }));
+}
+/** At most one pass per hour of awake time; the first call (daemon boot) always runs. */
+export function cachePassDue(lastPassAt, now) {
+    return lastPassAt === null || now - lastPassAt >= CACHE_PASS_INTERVAL_MS;
+}

package/dist/launcher/limits/settings.d.ts

@@ -0,0 +1,19 @@
+import { type CapValue, type LimitSettings } from './policy.js';
+export declare const SETTINGS_FILE = "limits.json";
+export declare function emptySettings(): LimitSettings;
+export declare function settingsPath(runtimeRoot: string): string;
+/** Keep only well-formed entries; a damaged file never blocks the launcher. */
+export declare function normalizeSettings(raw: unknown): LimitSettings;
+export declare function readSettings(runtimeRoot: string): LimitSettings;
+export declare function writeSettings(runtimeRoot: string, settings: LimitSettings): void;
+export declare class LimitInputError extends Error {
+}
+/** Merge a change into `settings` (pure). `undefined` leaves a field alone. */
+export declare function applyChange(settings: LimitSettings, app: string, change: {
+    memory_bytes?: CapValue;
+    disk_bytes?: CapValue;
+}): LimitSettings;
+/** Drop the named override fields (pure); an app left with none disappears. */
+export declare function removeOverride(settings: LimitSettings, app: string, fields: Array<'memory' | 'disk'>): LimitSettings;
+/** `2GiB`, `512MiB`, `1073741824` or `unlimited`. */
+export declare function parseSize(text: string): CapValue;

package/dist/launcher/limits/settings.js

@@ -0,0 +1,94 @@
+// Person-set per-app caps. The file lives in the runtime's own directory, which
+// no sandbox mounts; the daemon writes it and the launcher reads it.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { bareApp, MIN_DISK_BYTES, MIN_MEMORY_BYTES } from './policy.js';
+export const SETTINGS_FILE = 'limits.json';
+const APP_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+export function emptySettings() { return { version: 1, apps: {} }; }
+export function settingsPath(runtimeRoot) { return join(runtimeRoot, SETTINGS_FILE); }
+function capValue(value, minimum) {
+    if (value === 'unlimited')
+        return 'unlimited';
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum)
+        return value;
+    return undefined;
+}
+/** Keep only well-formed entries; a damaged file never blocks the launcher. */
+export function normalizeSettings(raw) {
+    const out = emptySettings();
+    const apps = raw?.apps;
+    if (apps === null || typeof apps !== 'object')
+        return out;
+    for (const [id, entry] of Object.entries(apps)) {
+        if (!APP_ID.test(id) || entry === null || typeof entry !== 'object')
+            continue;
+        const memory = capValue(entry.memory_bytes, MIN_MEMORY_BYTES);
+        const disk = capValue(entry.disk_bytes, MIN_DISK_BYTES);
+        if (memory === undefined && disk === undefined)
+            continue;
+        out.apps[id] = { ...(memory === undefined ? {} : { memory_bytes: memory }), ...(disk === undefined ? {} : { disk_bytes: disk }) };
+    }
+    return out;
+}
+export function readSettings(runtimeRoot) {
+    try {
+        return normalizeSettings(JSON.parse(readFileSync(settingsPath(runtimeRoot), 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return emptySettings();
+        return emptySettings();
+    }
+}
+export function writeSettings(runtimeRoot, settings) {
+    const path = settingsPath(runtimeRoot);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temp, path);
+}
+export class LimitInputError extends Error {
+}
+/** Merge a change into `settings` (pure). `undefined` leaves a field alone. */
+export function applyChange(settings, app, change) {
+    const id = bareApp(app);
+    if (!APP_ID.test(id))
+        throw new LimitInputError(`invalid app id: ${app}`);
+    const memory = change.memory_bytes === undefined ? undefined : capValue(change.memory_bytes, MIN_MEMORY_BYTES);
+    const disk = change.disk_bytes === undefined ? undefined : capValue(change.disk_bytes, MIN_DISK_BYTES);
+    if (change.memory_bytes !== undefined && memory === undefined)
+        throw new LimitInputError(`memory must be 'unlimited' or at least ${MIN_MEMORY_BYTES} bytes`);
+    if (change.disk_bytes !== undefined && disk === undefined)
+        throw new LimitInputError(`disk must be 'unlimited' or at least ${MIN_DISK_BYTES} bytes`);
+    const next = { version: 1, apps: { ...settings.apps } };
+    const merged = { ...(next.apps[id] ?? {}), ...(memory === undefined ? {} : { memory_bytes: memory }), ...(disk === undefined ? {} : { disk_bytes: disk }) };
+    next.apps[id] = merged;
+    return next;
+}
+/** Drop the named override fields (pure); an app left with none disappears. */
+export function removeOverride(settings, app, fields) {
+    const id = bareApp(app);
+    const next = { version: 1, apps: { ...settings.apps } };
+    const entry = { ...(next.apps[id] ?? {}) };
+    if (fields.includes('memory'))
+        delete entry.memory_bytes;
+    if (fields.includes('disk'))
+        delete entry.disk_bytes;
+    if (entry.memory_bytes === undefined && entry.disk_bytes === undefined)
+        delete next.apps[id];
+    else
+        next.apps[id] = entry;
+    return next;
+}
+const UNITS = { b: 1, kib: 1024, mib: 1024 ** 2, gib: 1024 ** 3, tib: 1024 ** 4, k: 1024, m: 1024 ** 2, g: 1024 ** 3, t: 1024 ** 4 };
+/** `2GiB`, `512MiB`, `1073741824` or `unlimited`. */
+export function parseSize(text) {
+    const value = text.trim().toLowerCase();
+    if (value === 'unlimited')
+        return 'unlimited';
+    const m = /^(\d+(?:\.\d+)?)\s*(b|kib|mib|gib|tib|k|m|g|t)?$/.exec(value);
+    if (!m)
+        throw new LimitInputError(`unrecognized size: ${text}`);
+    return Math.floor(Number(m[1]) * UNITS[m[2] ?? 'b']);
+}

package/dist/launcher/spec.d.ts

@@ -0,0 +1,181 @@
+import type { MemoryAdmission } from './limits/policy.js';
+export declare const APP_UID_MIN = 200000;
+export declare const APP_UID_MAX = 299999;
+export declare const LAUNCHER_SOCKET = "/run/crtr/launcher.sock";
+export interface LaunchSpec {
+    nodeId: string;
+    uid: number;
+    mounts: Array<{
+        source: string;
+        writable: boolean;
+    }>;
+    cwd: string;
+    /** Isolated runs receive a private network namespace. Omitted means shared network. */
+    network?: 'none';
+    env: Record<string, string>;
+    command: string[];
+    log: string;
+    /** Non-broker processes return bounded output and exit status through wait. */
+    capture?: {
+        stdoutBytes: number;
+        stderrBytes: number;
+        stderrTail?: boolean;
+        stdin?: string;
+    };
+    pluginRoot?: string;
+    /** The launch is a node's broker engine. Only the daemon's broker host sets it; the launcher counts such runs for memory admission. */
+    broker?: true;
+    token?: never;
+}
+export type LauncherRequest = {
+    operation: 'launch';
+    spec: LaunchSpec;
+} | {
+    operation: 'stop';
+    pid: number;
+    signal?: 'SIGTERM' | 'SIGKILL';
+    nodeId?: string;
+} | {
+    operation: 'wait';
+    pid: number;
+} | {
+    operation: 'user.create';
+    app: string;
+    uid: number;
+} | {
+    operation: 'user.delete';
+    uid: number;
+} | {
+    operation: 'users.sync';
+    users: Array<{
+        app: string;
+        uid: number;
+    }>;
+} | {
+    operation: 'daemon.handover';
+}
+/** Re-read the person's limit overrides for one app and write its memory cap and disk quota now. */
+ | {
+    operation: 'limits.apply';
+    app: string;
+} | {
+    operation: 'limits.show';
+}
+/** Whether one more broker of this app fits in its memory now; an admit holds the boot reservation until the node's broker launch. */
+ | {
+    operation: 'memory.admit';
+    app: string;
+    nodeId: string;
+}
+/** Bytes the data volume holds, per app and for the person's files and the runtime directory (a directory walk, cached briefly). */
+ | {
+    operation: 'disk.usage';
+}
+/** One cache pass over every app (stale files; whole cache for an app past 80 % of its quota or a disk past 85 %). */
+ | {
+    operation: 'cache.purge';
+}
+/** How the sandbox with this first-process pid ended: whether the kernel OOM-killed its run, and the code and signal its first process exited with. */
+ | {
+    operation: 'exit.status';
+    pid: number;
+}
+/** Every live sandbox with the mounts it was launched with (runtime spec §15, R26 sweep). */
+ | {
+    operation: 'list';
+};
+/** A diagnostic the launcher has no event log for; the daemon emits it when the reply arrives. */
+export interface LimitEvent {
+    level: 'info' | 'warn';
+    event: string;
+    nodeId?: string;
+    fields?: Record<string, unknown>;
+}
+export interface LimitsReport {
+    memory: {
+        available: boolean;
+        reason: string | null;
+    };
+    disk: {
+        available: boolean;
+        reason: string | null;
+    };
+    apps: Array<{
+        app: string;
+        uid: number;
+        /** null means no cap */
+        memory_bytes: number | null;
+        disk_bytes: number | null;
+        memory_source: 'default' | 'override';
+        disk_source: 'default' | 'override';
+        disk_used_bytes: number | null;
+    }>;
+}
+export type MemoryAdmitReply = MemoryAdmission;
+export interface DiskUsageReport {
+    /** The data volume the apps live on, from statfs. */
+    total_bytes: number;
+    used_bytes: number;
+    /** Bytes under each registered app's folder, largest first; null where the walk failed. */
+    apps: Array<{
+        app: string;
+        bytes: number | null;
+    }>;
+    user_bytes: number | null;
+    runtime_bytes: number | null;
+    /** When the walk ran, in epoch milliseconds. */
+    measured_at: number;
+}
+export interface CachePurged {
+    app: string;
+    mode: 'stale' | 'all';
+    files: number;
+    bytes: number;
+}
+export interface SandboxRecord {
+    pid: number;
+    uid: number;
+    nodeId: string;
+    mounts: LaunchSpec['mounts'];
+}
+export interface CapturedExit {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+    stdoutSha256: string;
+    /** The kernel OOM-killed this run's cgroup. */
+    oomKilled?: boolean;
+}
+export type LauncherReply = ({
+    pid: number;
+} | {
+    sandboxes: SandboxRecord[];
+} | {
+    result: CapturedExit;
+} | {
+    uid: number;
+} | {
+    ok: true;
+} | MemoryAdmitReply | {
+    limits: LimitsReport;
+} | {
+    disk: DiskUsageReport;
+} | {
+    purged: CachePurged[];
+} | {
+    oomKilled: boolean;
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}) & {
+    events?: LimitEvent[];
+} | {
+    refusal: LauncherRefusal;
+};
+export type LauncherRefusal = 'invalid_spec' | 'invalid_uid' | 'runtime_source' | 'run_source' | 'writable_source' | 'symlink_source' | 'source_missing' | 'source_type' | 'log_refused' | 'launch_failed';
+export declare class LaunchRefused extends Error {
+    readonly refusal: LauncherRefusal;
+    constructor(refusal: LauncherRefusal, message: string);
+}

package/dist/launcher/spec.js

@@ -0,0 +1,10 @@
+export const APP_UID_MIN = 200000;
+export const APP_UID_MAX = 299999;
+export const LAUNCHER_SOCKET = '/run/crtr/launcher.sock';
+export class LaunchRefused extends Error {
+    refusal;
+    constructor(refusal, message) {
+        super(message);
+        this.refusal = refusal;
+    }
+}

package/dist/migrations/004-canvas-documents/apply.d.ts

@@ -0,0 +1,8 @@
+import type { ImportPlan, ImportReport } from './plan.js';
+import type { CanvasDb } from '../../core/canvas/db.js';
+/** The canvas_meta key whose presence means this home's legacy stores were imported. */
+export declare const IMPORT_DONE_KEY = "canvas-import";
+export declare const IMPORT_ID = "004-canvas-documents";
+export declare function readImportRecord(db: CanvasDb): Promise<ImportReport | null>;
+/** Run inside the caller's write transaction; each revision's text is stored in it. Throws on any divergence from the plan. */
+export declare function applyPlan(db: CanvasDb, plan: ImportPlan): Promise<void>;