@north-light/api 0.3.579 → 0.3.587

package/dist/core/spaces/mounts.js

@@ -0,0 +1,126 @@
+import { lstatSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { appSpace, appsRoot, runtimeRoot, socketDir, userFilesRoot } from '../layout.js';
+import { nodeAgentDir, nodeRunDir } from '../canvas/paths.js';
+import { uidForApp } from './users.js';
+import { permissionsForRun } from './permissions.js';
+/** The mounts a run's grant adds beyond its own app space (other apps' files
+ *  and nodes, and the person's files). */
+export function grantedMounts(permissions) {
+    const mounts = [];
+    for (const file of permissions.otherFiles) {
+        const root = file.holder === 'user' ? userFilesRoot() : appSpace(file.holder).files;
+        mounts.push({ source: file.path === '.' ? root : join(root, file.path), writable: file.writable });
+    }
+    for (const app of permissions.otherNodes)
+        mounts.push({ source: appSpace(app).nodes, writable: false });
+    return mounts;
+}
+function beneath(parent, path) {
+    const rel = relative(parent, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}
+/** Whether a launched mount came from a grant: it lies under the person's files
+ *  or under another app's space. Own-space and system mounts never do. */
+export function isGrantedSource(app, source) {
+    return beneath(userFilesRoot(), source) || (beneath(appsRoot(), source) && !beneath(appSpace(app).root, source));
+}
+/** A launched mount the current permissions still give: the same or a broader
+ *  granted directory, writable if the mount is. */
+export function mountAllowed(mount, allowed) {
+    return allowed.some((a) => beneath(a.source, mount.source) && (a.writable || !mount.writable));
+}
+/** Whether a spec compiled earlier is still within the node's current
+ *  permissions. A launch whose grant generation moved while the launcher was
+ *  starting it checks this before registering the sandbox (runtime spec §15). */
+export async function launchStillGranted(node, spec) {
+    try {
+        const allowed = grantedMounts(await permissionsForRun(node.app, node.sub, node.grantId, node.scopes));
+        return spec.mounts.every((mount) => !isGrantedSource(node.app, mount.source) || mountAllowed(mount, allowed));
+    }
+    catch {
+        return false;
+    }
+}
+export async function compileLaunch(node) {
+    const own = appSpace(node.app);
+    const permissions = await permissionsForRun(node.app, node.sub, node.grantId, node.scopes);
+    if (node.isolated && node.withoutNode && node.folder === undefined)
+        throw new Error('isolated launch requires a node');
+    const nodeFolder = node.folder ?? (node.isolated ? nodeAgentDir(node.nodeId, node.app) : undefined);
+    if (nodeFolder && node.cwd !== undefined && !beneath(nodeFolder, node.cwd)) {
+        throw new Error('isolated cwd must be inside the node folder');
+    }
+    const mounts = new Map();
+    const add = (source, writable, optional = false, granted = false) => {
+        if (optional) {
+            try {
+                lstatSync(source);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                if (granted)
+                    node.auditMissing(source);
+                return;
+            }
+        }
+        mounts.set(source, writable || (mounts.get(source) ?? false));
+    };
+    for (const source of ['/usr', '/bin', '/lib', '/lib64', '/opt/crouter', '/etc/passwd', '/etc/group', '/etc/resolv.conf', '/etc/hosts', '/etc/ssl', '/etc/ca-certificates']) {
+        add(source, false, true);
+    }
+    if (!node.withoutNode)
+        add(nodeAgentDir(node.nodeId, node.app), true);
+    if (node.folder !== undefined)
+        add(node.folder, true);
+    if (node.cron?.anchorDir !== undefined)
+        add(node.cron.anchorDir, true);
+    // An isolated node's home is `nodes/<id>/home`, inside its own (already mounted)
+    // agent folder; it never shares the app's home with another run (Silas, 2026-09-30).
+    if (!node.isolated)
+        add(own.home, true);
+    if (!node.isolated)
+        add(own.files, true);
+    // Package caches: purgeable, so an isolated run (which has no shared home) still gets one.
+    add(own.cache, true, true);
+    if (!node.withoutNode || node.cron !== undefined)
+        add(nodeRunDir(node.nodeId), true);
+    if (node.cron === undefined) {
+        add(join(socketDir(), 'api.sock'), true);
+    }
+    // `/apps/<A>/nodes` is never mounted: it holds every run's node folders, isolated
+    // runs' included, so a shell could read them past the daemon's run confinement
+    // (Silas, 2026-09-30). Another node's folder is reached through `/v1/files`.
+    for (const mount of grantedMounts(permissions))
+        add(mount.source, mount.writable, true, true);
+    if (node.pluginRoot !== undefined) {
+        const within = (base) => node.pluginRoot === base ||
+            (relative(base, node.pluginRoot) !== '..' && !relative(base, node.pluginRoot).startsWith(`..${sep}`));
+        const pluginDir = join(runtimeRoot(), 'plugins');
+        // Project hooks need no extra mount: their repo must already be visible
+        // through this app's permissions. Installed code alone gets a new mount.
+        if ([...mounts].some(([source]) => within(source))) {
+            if (mounts.get(node.pluginRoot) === true)
+                throw new Error('hook root cannot also be writable');
+            add(node.pluginRoot, false);
+        }
+        else if (within(pluginDir) && node.pluginRoot !== pluginDir)
+            add(node.pluginRoot, false);
+        else if (within('/opt/crouter'))
+            add(node.pluginRoot, false);
+        else
+            throw new Error('hook root is not readable with this app’s mounts');
+    }
+    const cwd = node.cwd ?? nodeFolder ?? own.files;
+    const ordered = [...mounts].sort(([a], [b]) => a.split(sep).length - b.split(sep).length || a.localeCompare(b));
+    const log = join(runtimeRoot(), 'nodes', node.nodeId, 'job', 'broker.log');
+    const macIpc = process.platform !== 'linux' ? [nodeRunDir(node.nodeId), join(socketDir(), 'api.sock')] : [];
+    if (ordered.some(([source]) => source !== node.pluginRoot && !macIpc.includes(source) &&
+        (source === runtimeRoot() || (!relative(runtimeRoot(), source).startsWith('..') && !relative(runtimeRoot(), source).startsWith(sep))))) {
+        throw new Error('runtime records cannot be mounted');
+    }
+    return { nodeId: node.nodeId, uid: await uidForApp(node.app), mounts: ordered.map(([source, writable]) => ({ source, writable })),
+        cwd, env: node.env, command: node.command, log,
+        ...(node.isolated ? { network: 'none' } : {}) };
+}

package/dist/core/spaces/permissions.d.ts

@@ -0,0 +1,19 @@
+import { type ActiveGrant } from '../grants/mirror.js';
+export interface RunPermissions {
+    app: string;
+    ownNodes: boolean;
+    otherFiles: Array<{
+        holder: string;
+        path: string;
+        writable: boolean;
+    }>;
+    otherNodes: string[];
+}
+/** Only the active mirror and the launched scope list determine a run's mounts. */
+export declare function permissionsForRun(app: string, sub: string, grantId: string | null, launched: string[] | null): Promise<RunPermissions>;
+/** The same computation over a given grant record, e.g. the mirror before a sync replaced it. */
+export declare function permissionsForGrant(app: string, sub: string, grant: ActiveGrant | null, launched: string[] | null): RunPermissions;
+/** A project is available only through an actual file mount, never a symlink or an ancestor of it. */
+export declare function readableProject(repository: string, roots: readonly string[]): boolean;
+export declare function readableProjectForScopes(repository: string, app: string, resolved: readonly string[], launched: readonly string[] | null): boolean;
+export { fileRoot, type FileCaller } from './file-root.js';

package/dist/core/spaces/permissions.js

@@ -0,0 +1,77 @@
+import { parseScope } from '@north-light/identity';
+import { coveredByAny } from '../../shared/env.js';
+import { activeGrant, grantFor } from '../grants/mirror.js';
+import { appSpace, userFilesRoot } from '../layout.js';
+import { contains } from './file-root.js';
+import { join, resolve } from 'node:path';
+import { lstatSync, realpathSync } from 'node:fs';
+/** Only the active mirror and the launched scope list determine a run's mounts. */
+export async function permissionsForRun(app, sub, grantId, launched) {
+    return permissionsForGrant(app, sub, grantId ? await activeGrant(grantId) : await grantFor(app, sub), launched);
+}
+/** The same computation over a given grant record, e.g. the mirror before a sync replaced it. */
+export function permissionsForGrant(app, sub, grant, launched) {
+    if (!grant || grant.grantee !== app || grant.sub !== sub)
+        throw new Error(`no active grant for ${app}`);
+    if (launched !== null && !Array.isArray(launched))
+        throw new Error('invalid launched scopes');
+    const otherFiles = [];
+    const otherNodes = [];
+    let ownNodes = launched === null;
+    const scopes = launched ?? grant.resolved;
+    for (const scope of scopes) {
+        if (typeof scope !== 'string')
+            throw new Error('invalid launched scope');
+        parseScope(scope);
+        const own = scope === `crtr:memory:read:${app}` || scope === `crtr:memory:rw:${app}` ||
+            scope.startsWith(`crtr:memory:read:${app}:`) || scope.startsWith(`crtr:memory:rw:${app}:`);
+        if (launched !== null && !own && !coveredByAny(grant.resolved, scope))
+            throw new Error(`launched scope not in grant: ${scope}`);
+        const files = /^crtr:files:(read|rw):(user|app:[A-Za-z0-9_-]{1,64}):(.+)$/.exec(scope);
+        if (files) {
+            const [, access, holder, path] = files;
+            if (holder === app)
+                throw new Error(`own-app files cannot narrow a run: ${scope}`);
+            otherFiles.push({ holder: holder, path: path, writable: access === 'rw' });
+        }
+        const objects = /^crtr:objects:read:(app:[A-Za-z0-9_-]{1,64})$/.exec(scope);
+        if (objects && objects[1] !== app)
+            otherNodes.push(objects[1]);
+    }
+    return { app, ownNodes, otherFiles, otherNodes };
+}
+/** A project is available only through an actual file mount, never a symlink or an ancestor of it. */
+export function readableProject(repository, roots) {
+    const repo = resolve(repository);
+    for (const root of roots) {
+        const mount = resolve(root);
+        if (!contains(mount, repo))
+            continue;
+        try {
+            if (realpathSync(repo) !== repo || realpathSync(mount) !== mount)
+                continue;
+            let path = repo;
+            while (contains(mount, path)) {
+                if (lstatSync(path).isSymbolicLink())
+                    break;
+                if (path === mount)
+                    return true;
+                path = resolve(path, '..');
+            }
+        }
+        catch { /* An absent mount cannot grant access. */ }
+    }
+    return false;
+}
+export function readableProjectForScopes(repository, app, resolved, launched) {
+    const roots = [appSpace(app).files];
+    for (const scope of launched ?? resolved) {
+        if (launched !== null && !coveredByAny(resolved, scope))
+            continue;
+        const match = /^crtr:files:(?:read|rw):(user|app:[A-Za-z0-9_-]{1,64}):(.+)$/.exec(scope);
+        if (match)
+            roots.push(join(match[1] === 'user' ? userFilesRoot() : appSpace(match[1]).files, match[2] === '.' ? '' : match[2]));
+    }
+    return readableProject(repository, roots);
+}
+export { fileRoot } from './file-root.js';

package/dist/core/spaces/process.d.ts

@@ -0,0 +1,61 @@
+import { type CapturedExit } from '../../launcher/spec.js';
+/** The launcher's node id for one cron execution; its run folder is `nodeRunDir(<this>)`. */
+export declare function cronLaunchId(executionId: string): string;
+export interface AppProcess {
+    pid: number;
+    completion: Promise<CapturedExit>;
+    stop(signal?: 'SIGTERM' | 'SIGKILL'): Promise<void>;
+}
+export interface AppProcessOptions {
+    nodeId?: string;
+    /** For node-backed work the persisted node setting always takes precedence. */
+    isolated?: boolean;
+    app?: string;
+    /** The grant a process without a node runs under (an app cron's stored principal). Absent, it runs under the app's whole current grant. */
+    principal?: {
+        sub: string;
+        grantId: string | null;
+        scopes: string[] | null;
+    };
+    /** A cron execution: launch id `cron-<executionId>`, no node, and no `api.sock` — its only API path is
+     *  its own execution folder's `cli.sock`. `anchorDir` is an anchored cron's anchor agent folder (rw). Needs `principal`. */
+    cron?: {
+        executionId: string;
+        anchorDir?: string;
+    };
+    /** The folder an isolated process without a node runs in (an isolated cron's own folder). */
+    folder?: string;
+    command: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdin?: string;
+    stdoutBytes?: number;
+    stderrBytes?: number;
+    stderrTail?: boolean;
+    pluginRoot?: string;
+    /** A file-backed job writes its own log and needs no launcher output capture. */
+    capture?: boolean;
+}
+/** The same mount compiler and launcher request used by broker launches. A node
+ * keeps its launched scope list; a process without a node uses the app's whole
+ * current grant. Linux never falls back to direct execution when configured
+ * with a launcher whose socket is missing. */
+export declare function appProcessSandboxed(): boolean;
+/** Whether app processes start through the root launcher (a sandbox with a fixed mount list). */
+export declare function appProcessesSandboxed(): boolean;
+/** Test seam: treat app processes as sandboxed (or not) without a launcher socket. */
+export declare function __setAppProcessesSandboxedForTest(value: boolean | undefined): void;
+/** Whether `cwd` lies inside a directory mount the launcher would give a process of
+ *  `app`. This is the launcher's own `cwd is not mounted` rule applied to the mounts
+ *  `compileLaunch` produces, so a caller can refuse a directory at arm time instead of
+ *  at every run. `nodeId` is the node the process runs for, when it has one. */
+export declare function cwdIsMounted(app: string, cwd: string, nodeId?: string, isolated?: boolean, folder?: string, principal?: {
+    sub: string;
+    grantId: string | null;
+    scopes: string[] | null;
+}): Promise<boolean>;
+export declare function stopAppProcess(pid: number, signal?: 'SIGTERM' | 'SIGKILL', nodeId?: string): Promise<void>;
+/** A node-backed isolated process always starts in its own agent folder.
+ * Callers validate explicitly requested cwd separately (e.g. hook execution). */
+export declare function appProcessCwd(nodeId: string, app: string, cwd: string, isolated: boolean, folder?: string): string;
+export declare function launchAppProcess(options: AppProcessOptions): Promise<AppProcess>;

package/dist/core/spaces/process.js

@@ -0,0 +1,172 @@
+import { existsSync } from 'node:fs';
+import { assertGranteeRunsHere } from '../runtime/unsandboxed.js';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { getNode } from '../canvas/canvas.js';
+import { nodeAgentDir, nodeHome, nodeRunDir } from '../canvas/paths.js';
+import { appSpace } from '../layout.js';
+import { activeGrant, activeGrantForApp, grantFor, grantsGeneration } from '../grants/mirror.js';
+import { emitEvent } from '../events/emit.js';
+import { ensureAppSpace } from './space.js';
+import { compileLaunch, launchStillGranted } from './mounts.js';
+import { pinSandboxRuntimeHome } from './runtime-home.js';
+import { sandboxCacheEnv } from './cache-env.js';
+import { launcherRequest } from '../../launcher/client.js';
+import { LAUNCHER_SOCKET } from '../../launcher/spec.js';
+import { isCloudRole, personId } from '../canvas/person.js';
+/** The launcher's node id for one cron execution; its run folder is `nodeRunDir(<this>)`. */
+export function cronLaunchId(executionId) { return `cron-${executionId}`; }
+/** The same mount compiler and launcher request used by broker launches. A node
+ * keeps its launched scope list; a process without a node uses the app's whole
+ * current grant. Linux never falls back to direct execution when configured
+ * with a launcher whose socket is missing. */
+export function appProcessSandboxed() {
+    if (process.platform !== 'linux')
+        return false;
+    if (existsSync(LAUNCHER_SOCKET))
+        return true;
+    throw new Error('root launcher socket is unavailable; refusing an unsandboxed app process');
+}
+/** Whether app processes start through the root launcher (a sandbox with a fixed mount list). */
+export function appProcessesSandboxed() {
+    return sandboxedForTest ?? (process.platform === 'linux' && existsSync(LAUNCHER_SOCKET));
+}
+let sandboxedForTest;
+/** Test seam: treat app processes as sandboxed (or not) without a launcher socket. */
+export function __setAppProcessesSandboxedForTest(value) { sandboxedForTest = value; }
+/** Whether `cwd` lies inside a directory mount the launcher would give a process of
+ *  `app`. This is the launcher's own `cwd is not mounted` rule applied to the mounts
+ *  `compileLaunch` produces, so a caller can refuse a directory at arm time instead of
+ *  at every run. `nodeId` is the node the process runs for, when it has one. */
+export async function cwdIsMounted(app, cwd, nodeId, isolated = false, folder, principal) {
+    const row = nodeId === undefined ? null : await getNode(nodeId);
+    // A stored principal decides the grant and scopes even for an anchored run (see launchAppProcess).
+    const grant = principal !== undefined ? (principal.grantId ? await activeGrant(principal.grantId) : await grantFor(app, principal.sub))
+        : row ? null : await activeGrantForApp(app);
+    if (principal !== undefined ? !grant : !row && !grant)
+        throw new Error(`no active grant for ${app}`);
+    const spec = await compileLaunch({ nodeId: nodeId ?? `proc-cwd-check`, app,
+        ...(principal !== undefined
+            ? { sub: principal.sub, grantId: grant?.id ?? null, scopes: principal.scopes }
+            : { sub: row ? row.sub ?? personId() : grant.sub, grantId: row ? row.grant_id ?? null : grant.id, scopes: row?.scopes ?? null }),
+        command: ['true'], env: {},
+        ...(nodeId === undefined ? { withoutNode: true } : {}),
+        ...(folder === undefined ? {} : { folder }),
+        isolated: row?.isolated === true || isolated,
+        auditMissing: () => { } });
+    return spec.mounts.some(({ source }) => cwd === source || cwd.startsWith(source === '/' ? '/' : `${source}/`));
+}
+export async function stopAppProcess(pid, signal = 'SIGKILL', nodeId) {
+    const stopped = await launcherRequest({ operation: 'stop', pid, signal, ...(nodeId === undefined ? {} : { nodeId }) });
+    if (!('ok' in stopped))
+        throw new Error('launcher did not stop process');
+}
+/** A node-backed isolated process always starts in its own agent folder.
+ * Callers validate explicitly requested cwd separately (e.g. hook execution). */
+export function appProcessCwd(nodeId, app, cwd, isolated, folder) {
+    return isolated ? folder ?? nodeAgentDir(nodeId, app) : cwd;
+}
+export async function launchAppProcess(options) {
+    // A cloud role runs no app process on its own host: a node's processes run in its Blaxel sandbox.
+    if (isCloudRole())
+        throw new Error('a cloud role launches no app process; the node runs in its sandbox');
+    if (options.cron !== undefined && (options.nodeId !== undefined || options.principal === undefined))
+        throw new Error('a cron launch has a stored principal and no node');
+    const row = options.nodeId === undefined ? null : await getNode(options.nodeId);
+    if (options.nodeId !== undefined && !row)
+        throw new Error(`missing node ${options.nodeId}`);
+    const app = row?.grantee ?? options.app ?? 'app:terminal';
+    assertGranteeRunsHere(app);
+    if (options.app !== undefined && options.app !== app)
+        throw new Error('app does not match node');
+    // The grant is checked before the app space exists: a launch for an app being
+    // removed must not recreate its directories and OS user.
+    const stored = options.principal;
+    // A stored principal decides the grant, sub and scopes even when an anchor node is
+    // given: the anchor supplies only its cwd, context dir and home, never authority.
+    let grant = null;
+    if (stored !== undefined) {
+        grant = stored.grantId ? await activeGrant(stored.grantId) : await grantFor(app, stored.sub);
+        if (!grant || grant.grantee !== app || grant.sub !== stored.sub)
+            throw new Error(`no active grant for ${app}`);
+    }
+    else if (row) {
+        if (app !== 'app:terminal' && !(row.grant_id ? await activeGrant(row.grant_id) : await grantFor(app, row.sub ?? personId()))) {
+            throw new Error(`no active grant for ${app}`);
+        }
+    }
+    else {
+        grant = await activeGrantForApp(app);
+        if (!grant)
+            throw new Error(`no active grant for ${app}`);
+    }
+    await ensureAppSpace(app);
+    const nodeId = options.cron === undefined ? options.nodeId ?? `proc-${randomUUID()}` : cronLaunchId(options.cron.executionId);
+    const isolated = row?.isolated === true || options.isolated === true;
+    if (isolated && !row && options.folder === undefined)
+        throw new Error('isolated process requires a live node');
+    const own = appSpace(app);
+    const cwd = appProcessCwd(nodeId, app, options.cwd, isolated, options.folder);
+    const home = row ? nodeHome(nodeId, app, isolated) : isolated && options.folder !== undefined ? join(options.folder, 'home') : own.home;
+    const env = pinSandboxRuntimeHome(Object.fromEntries(Object.entries({ ...options.env,
+        ...(process.platform === 'linux' ? sandboxCacheEnv(app) : {}),
+        HOME: home,
+        PI_CODING_AGENT_DIR: join(home, '.pi', 'agent'),
+        PWD: cwd,
+        ...(options.nodeId === undefined && options.cron === undefined ? {} : { CRTR_API_SOCKET: join(nodeRunDir(nodeId), 'cli.sock') }),
+    }).filter((entry) => entry[1] !== undefined)));
+    const launchNode = stored !== undefined
+        ? { nodeId, app, sub: stored.sub, grantId: grant?.id ?? null, scopes: stored.scopes }
+        : { nodeId, app, sub: row ? row.sub ?? personId() : grant.sub, grantId: row ? row.grant_id ?? null : grant.id, scopes: row?.scopes ?? null };
+    const compile = async () => {
+        const spec = await compileLaunch({ ...launchNode, command: options.command, env,
+            ...(options.nodeId === undefined ? { withoutNode: true } : {}),
+            isolated, cwd,
+            ...(options.folder === undefined ? {} : { folder: options.folder }),
+            ...(options.cron === undefined ? {} : { cron: options.cron.anchorDir === undefined ? {} : { anchorDir: options.cron.anchorDir } }),
+            ...(options.pluginRoot === undefined ? {} : { pluginRoot: options.pluginRoot }),
+            auditMissing: source => emitEvent({ level: 'warn', event: 'process.mount.missing', ...(options.nodeId === undefined ? {} : { node_id: options.nodeId }), fields: { source } }),
+        });
+        if (options.pluginRoot !== undefined)
+            spec.pluginRoot = options.pluginRoot;
+        if (options.capture === false) {
+            if (options.nodeId === undefined || options.stdin !== undefined)
+                throw new Error('uncaptured process requires a node and no stdin');
+        }
+        else {
+            spec.capture = { stdoutBytes: options.stdoutBytes ?? 256 * 1024, stderrBytes: options.stderrBytes ?? 256 * 1024,
+                ...(options.stderrTail ? { stderrTail: true } : {}),
+                ...(options.stdin === undefined ? {} : { stdin: options.stdin }) };
+        }
+        return spec;
+    };
+    let launched;
+    for (let attempt = 0; attempt < 2 && launched === undefined; attempt++) {
+        const generation = await grantsGeneration();
+        const spec = await compile();
+        const reply = await launcherRequest({ operation: 'launch', spec });
+        if (!('pid' in reply))
+            throw new Error('launcher did not return a process id');
+        // A sync that committed during this launch may have revoked a mount the spec holds.
+        if (await grantsGeneration() === generation || await launchStillGranted(launchNode, spec)) {
+            launched = reply.pid;
+            break;
+        }
+        emitEvent({ level: 'info', event: 'process.launch.regranted', ...(options.nodeId === undefined ? {} : { node_id: options.nodeId }), fields: { pid: reply.pid } });
+        await stopAppProcess(reply.pid, 'SIGKILL').catch(() => undefined);
+    }
+    if (launched === undefined)
+        throw new Error('grant changed during every launch attempt');
+    const pid = launched;
+    return {
+        pid,
+        get completion() {
+            return launcherRequest({ operation: 'wait', pid }).then(result => {
+                if (!('result' in result))
+                    throw new Error('launcher did not return process completion');
+                return result.result;
+            });
+        },
+        stop: (signal = 'SIGKILL') => stopAppProcess(pid, signal, options.cron === undefined ? options.nodeId : nodeId),
+    };
+}

package/dist/core/spaces/runtime-home.d.ts

@@ -0,0 +1,5 @@
+export declare const SANDBOX_RUNTIME_HOME = "/opt/crouter/runtime";
+/** Pin the generation selector even if an app/profile supplied its own value. */
+export declare function pinSandboxRuntimeHome<T extends NodeJS.ProcessEnv>(env: T): T & {
+    CRTR_RUNTIME_HOME: string;
+};

package/dist/core/spaces/runtime-home.js

@@ -0,0 +1,8 @@
+// Installed code is part of the sandbox's read-only system mounts, not the
+// app's writable HOME. Keep this independent of CRTR_HOME and of any app or
+// profile environment value: those name data/configuration spaces, not code.
+export const SANDBOX_RUNTIME_HOME = '/opt/crouter/runtime';
+/** Pin the generation selector even if an app/profile supplied its own value. */
+export function pinSandboxRuntimeHome(env) {
+    return { ...env, CRTR_RUNTIME_HOME: SANDBOX_RUNTIME_HOME };
+}

package/dist/core/spaces/space.d.ts

@@ -0,0 +1,9 @@
+/** App sandboxes bind the person's files through crtr-data group access. */
+export declare function ensureUserFiles(): void;
+/** On macOS no launcher or crtr-data group exists; directories stay owned by the Mac user. A cloud role has no per-app OS user
+ *  or directory to prepare: a node's files live in its sandbox and in rows, so it answers the process's own ids and touches nothing. */
+export declare function ensureAppSpace(app: string): Promise<{
+    uid: number;
+    gid: number;
+    root: string;
+}>;

package/dist/core/spaces/space.js

@@ -0,0 +1,58 @@
+import { chownSync, chmodSync, existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
+import { appSpace, appsRoot, userFilesRoot } from '../layout.js';
+import { launcherRequest } from '../../launcher/client.js';
+import { LAUNCHER_SOCKET } from '../../launcher/spec.js';
+import { allocateAppUser, uidForApp } from './users.js';
+import { isCloudRole } from '../canvas/person-state.js';
+function dataGroup() {
+    const group = readFileSync('/etc/group', 'utf8').split('\n').find(line => line.startsWith('crtr-data:'));
+    if (!group)
+        throw new Error('crtr-data group is required on sandboxed Linux');
+    const gid = Number(group.split(':')[2]);
+    if (!Number.isInteger(gid))
+        throw new Error('invalid crtr-data group id');
+    return gid;
+}
+/** App sandboxes bind the person's files through crtr-data group access. */
+export function ensureUserFiles() {
+    const path = userFilesRoot();
+    const gid = dataGroup();
+    mkdirSync(path, { recursive: true, mode: 0o2770 });
+    const stat = statSync(path);
+    const mode = stat.mode & 0o7777;
+    if (!stat.isDirectory() || stat.gid !== gid || mode !== 0o2770) {
+        if (!stat.isDirectory() || stat.uid !== process.getuid()) {
+            throw new Error(`${path} has owner ${stat.uid}, group ${stat.gid}, mode ${mode.toString(8).padStart(4, '0')}; requires an crtr-data (${gid}) directory with mode 2770; only its owner can repair it`);
+        }
+        if (stat.gid !== gid)
+            chownSync(path, stat.uid, gid);
+        if (mode !== 0o2770)
+            chmodSync(path, 0o2770);
+    }
+}
+/** On macOS no launcher or crtr-data group exists; directories stay owned by the Mac user. A cloud role has no per-app OS user
+ *  or directory to prepare: a node's files live in its sandbox and in rows, so it answers the process's own ids and touches nothing. */
+export async function ensureAppSpace(app) {
+    const space = appSpace(app);
+    if (isCloudRole())
+        return { uid: process.getuid(), gid: process.getgid(), root: space.root };
+    const launcher = process.platform === 'linux' && existsSync(LAUNCHER_SOCKET);
+    if (!launcher) {
+        if (process.platform === 'linux')
+            throw new Error('app space requires the root launcher on Linux');
+        for (const path of [space.root, space.profiles, space.conversations, space.nodes, space.files, space.home, space.cache])
+            mkdirSync(path, { recursive: true });
+        return { uid: await uidForApp(app), gid: process.getgid(), root: space.root };
+    }
+    const gid = dataGroup();
+    const user = await allocateAppUser(app);
+    const reply = await launcherRequest({ operation: 'user.create', app: space.root.slice(appsRoot().length + 1), uid: user.uid });
+    if (!('uid' in reply) || reply.uid !== user.uid)
+        throw new Error(`launcher did not create OS user for ${app}`);
+    for (const path of [space.root, space.profiles, space.conversations, space.nodes, space.files, space.home, space.cache]) {
+        mkdirSync(path, { recursive: true, mode: 0o2770 });
+        chownSync(path, process.getuid(), gid);
+        chmodSync(path, 0o2770);
+    }
+    return { uid: user.uid, gid, root: space.root };
+}

package/dist/core/spaces/stop.d.ts

@@ -0,0 +1,24 @@
+import { type CanvasDb } from '../canvas/db.js';
+import type { ObjectRow } from '../graph/types.js';
+import { type TeardownResult } from '../runtime/host.js';
+/** End the job object of a backgrounded command as killed. A command that was never backgrounded
+ *  has no job object; that answers false. Daemon-only: opens canvas.db. */
+export declare function killBashJobObject(jobId: string, killedBy: (db: CanvasDb) => Promise<ObjectRow | null>, reason?: string): Promise<boolean>;
+/** Record a backgrounded command as its node's job object (id = job id); an existing job
+ *  object is returned as is. The one path for both the broker's record call and the
+ *  daemon adopting a job the broker backgrounded while exiting. Daemon-only. */
+export declare function recordBashJobObject(nodeId: string, jobId: string, spec: {
+    command: string;
+    purpose?: string | null;
+    deadlineAtMs?: number | null;
+}): Promise<ObjectRow>;
+type StopOptions = {
+    excludePid?: number;
+    startAfter?: Promise<unknown>;
+    after?: () => Promise<void>;
+    deleting?: boolean;
+    holdRecovery?: boolean;
+};
+/** Stop the broker first so it cannot start another job during the job scan. */
+export declare function stopNodeSandboxes(nodeId: string, reason: string, options?: StopOptions): Promise<TeardownResult>;
+export {};