@superjackfruitlabs/salaam 0.0.3 → 0.0.5

package/dist/src/hooks.js

@@ -0,0 +1,351 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { ServiceError } from './protocol.js';
+/** Hooks for a person's own desk sessions (Phase 4b, operator 2026-10-31), in the Claude Code
+ * format: `{"hooks": {"PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command",
+ * "command": "...", "timeout": 30}]}]}}`. Yours live in `~/.config/salaam/hooks.json`; a
+ * repository's `.salaam/hooks.json` is ignored until you trust that exact file, and any change to it
+ * needs trusting again. A hook can block a tool call or a prompt; it can never approve anything. */
+export const HOOK_EVENTS = [
+    'PreToolUse',
+    'PostToolUse',
+    'UserPromptSubmit',
+    'Stop',
+    'Notification',
+];
+const MAX_FILE = 64 * 1024;
+const MAX_COMMAND = 4096;
+const MAX_HANDLERS = 16;
+const MAX_CONTEXT = 8192;
+const DEFAULT_TIMEOUT = 60;
+const MAX_TIMEOUT = 600;
+const BLOCKING = new Set(['PreToolUse', 'UserPromptSubmit']);
+const TOOL_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
+export function defaultUserHooksFile(env = process.env) {
+    return (env.SALAAM_HOOKS_FILE ||
+        join(env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config'), 'salaam', 'hooks.json'));
+}
+const sha = (data) => 'sha256:' + createHash('sha256').update(data).digest('hex');
+export function parseHooks(text) {
+    const problems = [];
+    const config = {};
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        return { config, problems: ['not valid JSON: ' + error.message] };
+    }
+    const events = raw?.hooks;
+    if (!events || typeof events !== 'object' || Array.isArray(events))
+        return { config, problems: ['expected {"hooks": {...}}'] };
+    let handlers = 0;
+    for (const [event, groups] of Object.entries(events)) {
+        if (!HOOK_EVENTS.includes(event)) {
+            problems.push(`${event}: not supported; Salaam runs ${HOOK_EVENTS.join(', ')}`);
+            continue;
+        }
+        if (!Array.isArray(groups)) {
+            problems.push(`${event}: expected a list of matcher groups`);
+            continue;
+        }
+        for (const group of groups) {
+            const g = group;
+            if (g?.matcher !== undefined && typeof g.matcher !== 'string') {
+                problems.push(`${event}: matcher must be a string`);
+                continue;
+            }
+            if (typeof g.matcher === 'string' && !validMatcher(g.matcher)) {
+                problems.push(`${event}: matcher ${JSON.stringify(g.matcher)} is not a valid pattern`);
+                continue;
+            }
+            if (!Array.isArray(g.hooks)) {
+                problems.push(`${event}: a group needs a hooks list`);
+                continue;
+            }
+            const kept = [];
+            for (const h of g.hooks) {
+                const hook = h;
+                if (hook?.type !== 'command') {
+                    problems.push(`${event}: hook type ${JSON.stringify(hook?.type)} is not supported (command only)`);
+                    continue;
+                }
+                if (typeof hook.command !== 'string' || !hook.command.trim()) {
+                    problems.push(`${event}: a command hook needs a command`);
+                    continue;
+                }
+                if (Buffer.byteLength(hook.command) > MAX_COMMAND) {
+                    problems.push(`${event}: a hook command is longer than 4 KiB`);
+                    continue;
+                }
+                if (hook.timeout !== undefined &&
+                    (typeof hook.timeout !== 'number' || !(hook.timeout > 0) || hook.timeout > MAX_TIMEOUT)) {
+                    problems.push(`${event}: timeout must be 1–${MAX_TIMEOUT} seconds`);
+                    continue;
+                }
+                if (++handlers > MAX_HANDLERS * HOOK_EVENTS.length) {
+                    problems.push('too many hooks; the rest are ignored');
+                    break;
+                }
+                kept.push({
+                    command: hook.command,
+                    ...(hook.timeout !== undefined ? { timeout: hook.timeout } : {}),
+                });
+            }
+            if (kept.length)
+                (config[event] ??= []).push({
+                    ...(g.matcher !== undefined ? { matcher: g.matcher } : {}),
+                    hooks: kept.slice(0, MAX_HANDLERS),
+                });
+        }
+    }
+    return { config, problems };
+}
+function validMatcher(m) {
+    if (m === '' || m === '*' || /^[A-Za-z0-9_|,-]+$/.test(m))
+        return true;
+    try {
+        new RegExp(m);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Claude Code's rule: empty or `*` matches everything, plain names (letters, digits, `_`, `-`,
+ * separated by `|` or `,`) are exact, anything else is a regular expression. `names` holds the
+ * Salaam tool name and its Claude Code alias (`Bash`, `Edit`, …). */
+export function matchesTool(matcher, names) {
+    if (matcher === undefined || matcher === '' || matcher === '*')
+        return true;
+    if (/^[A-Za-z0-9_|,-]+$/.test(matcher)) {
+        const wanted = matcher.split(/[|,]/);
+        return names.some((n) => wanted.includes(n));
+    }
+    const re = new RegExp('^(?:' + matcher + ')$');
+    return names.some((n) => re.test(n));
+}
+export class Hooks {
+    store;
+    run;
+    userFile;
+    constructor(store, run, userFile = defaultUserHooksFile()) {
+        this.store = store;
+        this.run = run;
+        this.userFile = userFile;
+        store.db.exec('CREATE TABLE IF NOT EXISTS hook_trust(root TEXT NOT NULL,path TEXT NOT NULL,digest TEXT NOT NULL,trusted_at TEXT NOT NULL,PRIMARY KEY(root,path))');
+    }
+    repoFile(session) {
+        return join(this.store.session(session).cwd, '.salaam', 'hooks.json');
+    }
+    /** Your hooks and this workspace's, read afresh, each with its trust state. */
+    sources(session) {
+        const root = this.store.session(session).cwd;
+        const out = [];
+        for (const [scope, path] of [
+            ['user', this.userFile],
+            ['repo', this.repoFile(session)],
+        ]) {
+            if (!existsSync(path) && !isLink(path))
+                continue;
+            const problems = [];
+            let digest = null;
+            let config = {};
+            try {
+                const real = realpathSync(path);
+                if (scope === 'repo' && !inside(realpathSync(root), real))
+                    throw new Error('resolves outside the repository; ignored');
+                if (lstatSync(real).size > MAX_FILE)
+                    throw new Error('larger than 64 KiB; ignored');
+                const bytes = readFileSync(real);
+                digest = sha(bytes);
+                const parsed = parseHooks(bytes.toString('utf8'));
+                config = parsed.config;
+                problems.push(...parsed.problems);
+            }
+            catch (error) {
+                problems.push(error.message);
+                digest = null;
+            }
+            const trusted = scope === 'user'
+                ? digest !== null
+                : digest !== null && this.trustedDigest(root, path) === digest;
+            out.push({ scope, path, digest, trusted, config, problems });
+        }
+        return out;
+    }
+    trustedDigest(root, path) {
+        const row = this.store.db
+            .prepare('SELECT digest FROM hook_trust WHERE root=? AND path=?')
+            .get(root, path);
+        return row?.digest;
+    }
+    /** Trust this workspace's hooks file as reviewed: `digest` must be the content shown to you. */
+    trust(session, digest) {
+        const source = this.sources(session).find((s) => s.scope === 'repo');
+        if (!source || !source.digest)
+            throw new ServiceError('hooks_missing', 'This workspace has no readable .salaam/hooks.json', 404);
+        if (source.digest !== digest)
+            throw new ServiceError('hooks_changed', 'The hooks file changed since you reviewed it; review it again', 409);
+        const root = this.store.session(session).cwd;
+        this.store.transaction(() => {
+            this.store.db
+                .prepare('INSERT INTO hook_trust VALUES (?,?,?,?) ON CONFLICT(root,path) DO UPDATE SET digest=excluded.digest,trusted_at=excluded.trusted_at')
+                .run(root, source.path, digest, new Date().toISOString());
+            this.store.event(session, 'hooks.trusted', { path: source.path, digest });
+        });
+        return { ...source, trusted: true };
+    }
+    revoke(session) {
+        const root = this.store.session(session).cwd;
+        const path = this.repoFile(session);
+        this.store.transaction(() => {
+            this.store.db.prepare('DELETE FROM hook_trust WHERE root=? AND path=?').run(root, path);
+            this.store.event(session, 'hooks.revoked', { path });
+        });
+    }
+    /** Run every trusted hook for `event`. Blocking events stop at the first block. */
+    async fire(session, event, payload, names) {
+        const notices = [];
+        const context = [];
+        const cwd = this.store.session(session).cwd;
+        const input = JSON.stringify({ session_id: session, cwd, hook_event_name: event, ...payload });
+        for (const source of this.sources(session)) {
+            if (!source.trusted)
+                continue;
+            for (const group of source.config[event] ?? []) {
+                if (TOOL_EVENTS.has(event) && !matchesTool(group.matcher, names))
+                    continue;
+                for (const handler of group.hooks) {
+                    const started = Date.now();
+                    const r = await this.run(session, handler.command, input, (handler.timeout ?? DEFAULT_TIMEOUT) * 1000);
+                    const decision = parseDecision(r.stdout);
+                    let blocked;
+                    if (BLOCKING.has(event) && !r.refused && !r.timedOut) {
+                        if (r.code === 2)
+                            blocked = r.stderr.trim() || `Blocked by a ${event} hook`;
+                        else if (r.code === 0 && decision.block)
+                            blocked = decision.reason || `Blocked by a ${event} hook`;
+                    }
+                    if (r.refused)
+                        notices.push(`${event} hook refused: ${r.refused}`);
+                    else if (r.timedOut)
+                        notices.push(`${event} hook timed out: ${short(handler.command)}`);
+                    else if (r.code !== 0 && r.code !== 2)
+                        notices.push(`${event} hook failed (exit ${r.code}): ${short(handler.command)}`);
+                    if (event === 'UserPromptSubmit' && r.code === 0 && !blocked) {
+                        const extra = decision.context ?? (decision.json ? '' : r.stdout.trim());
+                        if (extra)
+                            context.push(extra);
+                    }
+                    this.store.transaction(() => this.store.event(session, 'hook.run', {
+                        event,
+                        scope: source.scope,
+                        path: source.path,
+                        file_digest: source.digest,
+                        command_digest: sha(handler.command),
+                        exit_code: r.code,
+                        timed_out: r.timedOut,
+                        refused: !!r.refused,
+                        blocked: !!blocked,
+                        ...(decision.ignored ? { ignored_decision: decision.ignored } : {}),
+                        duration_ms: Date.now() - started,
+                        stdout_digest: sha(r.stdout),
+                        stderr_digest: sha(r.stderr),
+                        output_bytes: Buffer.byteLength(r.stdout) + Buffer.byteLength(r.stderr),
+                        truncated: r.truncated,
+                    }));
+                    if (blocked)
+                        return { blocked, notices };
+                }
+            }
+        }
+        const joined = context.join('\n\n');
+        return {
+            notices,
+            ...(joined ? { context: truncate(joined, MAX_CONTEXT) } : {}),
+        };
+    }
+}
+/** A JSON object on stdout, read the Claude Code way. "allow" and "ask" are recorded as ignored:
+ * Salaam's own approval flow decides those. */
+function parseDecision(stdout) {
+    const text = stdout.trim();
+    if (!text.startsWith('{'))
+        return { json: false };
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { json: false };
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return { json: false };
+    const specific = (value.hookSpecificOutput ?? {});
+    const decision = specific.permissionDecision;
+    const reason = typeof specific.permissionDecisionReason === 'string'
+        ? specific.permissionDecisionReason
+        : typeof value.reason === 'string'
+            ? value.reason
+            : undefined;
+    const context = typeof specific.additionalContext === 'string' ? specific.additionalContext : undefined;
+    if (decision === 'deny' || value.decision === 'block')
+        return { json: true, block: true, ...(reason ? { reason } : {}) };
+    return {
+        json: true,
+        ...(context ? { context } : {}),
+        ...(typeof decision === 'string' ? { ignored: decision } : {}),
+        ...(value.decision === 'approve' ? { ignored: 'approve' } : {}),
+    };
+}
+function inside(root, path) {
+    const r = relative(root, path);
+    return !r.startsWith('..') && !r.startsWith(sep);
+}
+function isLink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function short(command) {
+    const line = command.split('\n')[0];
+    return line.length > 60 ? line.slice(0, 57) + '…' : line;
+}
+function truncate(text, max) {
+    const buf = Buffer.from(text);
+    return buf.length <= max
+        ? text
+        : buf.subarray(0, max).toString('utf8') + '\n[hook output truncated]';
+}
+/** What `/hooks` shows, and what you review before trusting a workspace file: every command. */
+export function describeHooks(sources) {
+    if (!sources.length)
+        return "No hooks. Add your own in ~/.config/salaam/hooks.json, or a workspace's in .salaam/hooks.json (it runs only once you trust it with /hooks trust).";
+    return sources
+        .map((s) => {
+        const state = s.scope === 'user'
+            ? 'yours, runs'
+            : s.trusted
+                ? 'workspace, trusted (this exact content)'
+                : s.digest
+                    ? 'workspace, NOT trusted, does not run (/hooks trust to review)'
+                    : 'workspace, unreadable';
+        const lines = [`${s.path}  [${state}]`];
+        for (const event of HOOK_EVENTS)
+            for (const g of s.config[event] ?? [])
+                for (const h of g.hooks)
+                    lines.push(`  ${event}${g.matcher ? ` (${g.matcher})` : ''}: ${h.command}${h.timeout ? `  [${h.timeout}s]` : ''}`);
+        for (const p of s.problems)
+            lines.push(`  ! ${p}`);
+        if (s.digest)
+            lines.push(`  ${s.digest}`);
+        return lines.join('\n');
+    })
+        .join('\n\n');
+}

package/dist/src/host-bind.js

@@ -0,0 +1,111 @@
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, writeFileSync, existsSync, } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, resolve } from 'node:path';
+import { planHost } from './host.js';
+import { canonical, digest } from './protocol.js';
+import { stationHash, stationRuntimeFingerprint, stationWorkspaceIdentity, } from './station-config.js';
+const userName = /^[a-z_][a-z0-9_-]{0,31}$/;
+function pin(path) {
+    const real = realpathSync(path);
+    return { path: real, sha256: stationHash(readFileSync(real)) };
+}
+/** Write a private file only when its content changes; report whether it did. */
+function put(path, value) {
+    const text = JSON.stringify(value, null, 2) + '\n';
+    if (existsSync(path) && readFileSync(path, 'utf8') === text)
+        return false;
+    const tmp = path + '.tmp', fd = openSync(tmp, 'w', 0o600);
+    try {
+        writeFileSync(fd, text);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+    return true;
+}
+/** Bind one AgentPod station to a launcher-profile strict work host. Root on Linux.
+ * Every output is derived from the inputs; nothing is edited by hand. */
+export async function bindHost(input) {
+    if (process.platform !== 'linux' || process.getuid?.() !== 0)
+        throw Error('host bind runs as root on Linux');
+    const workspace = input.workspace;
+    if (!isAbsolute(workspace) || realpathSync(workspace) !== workspace)
+        throw Error('Use the canonical absolute workspace path');
+    const key = 'salaam:' + createHash('sha256').update(workspace).digest('hex').slice(0, 16);
+    if (input.station_key !== key)
+        throw Error('Station key does not name this workspace (expected ' + key + ')');
+    if (!userName.test(input.tools_user))
+        throw Error('tools user must be a user name');
+    try {
+        execFileSync('/usr/bin/getent', ['passwd', input.tools_user], { stdio: 'ignore' });
+    }
+    catch {
+        throw Error('tools user does not exist');
+    }
+    if (input.tools_user === 'root')
+        throw Error('tools user must not be root');
+    const id = key.slice('salaam:'.length), roots = input.roots ?? { config: '/etc/salaam/stations', state: '/var/lib/salaam/stations' }, dir = resolve(input.dir ?? join(roots.config, id)), state = resolve(input.state ?? join(roots.state, id, 'state'));
+    mkdirSync(dir, { recursive: true, mode: 0o755 });
+    // Ancestors of state stay traversable so the operator group can reach operator.sock;
+    // state itself is the daemon's (0700, or 0710 for the operator group once served).
+    mkdirSync(join(state, '..'), { recursive: true, mode: 0o755 });
+    chmodSync(join(state, '..'), 0o755);
+    const pinsPath = join(dir, 'agentpod-pins.json'), stationPath = join(dir, 'station-config.json'), configPath = join(dir, 'host-config.json'), manifestPath = join(dir, 'host.json');
+    let changed = put(pinsPath, {
+        version: 1,
+        organization_id: input.organization_id,
+        node_id: input.node_id,
+        station_key: key,
+        workspace,
+    });
+    const runtime = realpathSync(input.runtime_root);
+    changed =
+        put(stationPath, {
+            version: 1,
+            kind: 'linux-systemd-station-v1',
+            workspace,
+            workspace_identity: stationWorkspaceIdentity(workspace),
+            files: pin(input.files),
+            systemd_run: pin(input.systemd_run ?? '/usr/bin/systemd-run'),
+            systemctl: pin(input.systemctl ?? '/usr/bin/systemctl'),
+            runtime_root: runtime,
+            runtime_fingerprint: stationRuntimeFingerprint(runtime),
+            runtime_image_digest: input.runtime_image_digest,
+            tools_user: input.tools_user,
+        }) || changed;
+    const config = {
+        mode: 'agentpod',
+        state,
+        agentpod_config: pinsPath,
+        station_config: stationPath,
+        strict_work_version: 1,
+        ...(input.operator_group ? { operator_group: input.operator_group } : {}),
+        ...(input.provider ? { provider: input.provider } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.mcp_config ? { operator_mcp_config: realpathSync(input.mcp_config) } : {}),
+        ...(input.persona ? { persona_config: realpathSync(input.persona) } : {}),
+        ...(input.managed_mcp_config ? { mcp_config: realpathSync(input.managed_mcp_config) } : {}),
+    };
+    changed = put(configPath, config) || changed;
+    const manifest = await planHost(config);
+    const before = existsSync(manifestPath)
+        ? canonical(JSON.parse(readFileSync(manifestPath, 'utf8')))
+        : null;
+    if (before !== canonical(manifest)) {
+        put(manifestPath, manifest);
+        changed = true;
+    }
+    return {
+        version: 1,
+        station_key: key,
+        dir,
+        state,
+        manifest: manifestPath,
+        manifest_digest: digest(manifest),
+        unit: 'salaam-host@' + id + '.service',
+        changed,
+    };
+}

package/dist/src/host-breaker.js

@@ -0,0 +1,88 @@
+/**
+ * A circuit breaker for agent fetches (operator MCP calls whose arguments carry a `url`). After
+ * repeated consecutive failures to one host within a session, calls to that host are paused for a
+ * short while: the agent gets a tool error saying so and can do something else, and the run's
+ * activity gets one line. Nothing fails the run, and a paused call is never made, so it records no
+ * operator MCP call. One success to the host closes the breaker again.
+ */
+export const BREAKER_FAILURES = 3;
+export const BREAKER_PAUSE_MS = 60_000;
+export function fetchHost(args) {
+    const url = args?.url;
+    if (typeof url !== 'string')
+        return null;
+    try {
+        const host = new URL(url).hostname.toLowerCase();
+        return host || null;
+    }
+    catch {
+        return null;
+    }
+}
+export class HostBreaker {
+    now;
+    hosts = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    key(session, host) {
+        return session + '\u0000' + host;
+    }
+    /** Milliseconds this host stays paused for the session, 0 when calls may go ahead. */
+    paused(session, host) {
+        const h = this.hosts.get(this.key(session, host));
+        return h ? Math.max(0, h.until - this.now()) : 0;
+    }
+    /** Records a call's outcome; true when this failure just opened the breaker. */
+    record(session, host, ok) {
+        const key = this.key(session, host);
+        if (ok) {
+            this.hosts.delete(key);
+            return false;
+        }
+        const h = this.hosts.get(key) ?? { failures: 0, until: 0 };
+        h.failures++;
+        this.hosts.set(key, h);
+        if (h.failures < BREAKER_FAILURES)
+            return false;
+        h.failures = 0;
+        h.until = this.now() + BREAKER_PAUSE_MS;
+        return true;
+    }
+    forget(session) {
+        for (const key of this.hosts.keys())
+            if (key.startsWith(session + '\u0000'))
+                this.hosts.delete(key);
+    }
+}
+/**
+ * One operator MCP call through the breaker. A paused host returns a tool error without calling;
+ * a thrown failure or a tool error counts against the host; the call that opens the breaker
+ * records `fetch.host_paused` for the run's activity. The call's own result or error is unchanged.
+ */
+export async function callThroughBreaker(breaker, session, args, event, call) {
+    const host = fetchHost(args);
+    if (!host)
+        return call();
+    const wait = breaker.paused(session, host);
+    if (wait)
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Requests to ${host} are paused for ${Math.ceil(wait / 1000)}s after repeated failures; try another source or retry later.`,
+                },
+            ],
+            is_error: true,
+        };
+    let ok = false;
+    try {
+        const result = await call();
+        ok = !result.is_error;
+        return result;
+    }
+    finally {
+        if (breaker.record(session, host, ok))
+            event({ host, failures: BREAKER_FAILURES, pause_ms: BREAKER_PAUSE_MS });
+    }
+}

package/dist/src/host-start.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, execFile } from 'node:child_process';
 import { constants, openSync, closeSync, fstatSync, mkdirSync, realpathSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { readHost, hostMcp, hostToolkit } from './host.js';
@@ -118,3 +118,43 @@ export async function startHost(path) {
         release();
     }
 }
+const launcherUnit = /^salaam-host@[a-f0-9]{16}\.service$/;
+/** Launcher profile: an unprivileged operator asks systemd to start a root-owned,
+ * provisioned unit. It names only the unit; root reads its own reviewed manifest. */
+export async function startHostUnit(unit, state, options = {}) {
+    if (!launcherUnit.test(unit))
+        throw Error('Unit must be salaam-host@<16 hex>.service');
+    if (realpathSync(state) !== state)
+        throw Error('Use the canonical state path');
+    const socket = join(state, 'operator.sock'), deadline = Date.now() + (options.timeoutMs ?? 20000);
+    const ready = async () => {
+        let h;
+        try {
+            h = await call(socket, '/v1/health', undefined, undefined, 2000);
+        }
+        catch {
+            return null;
+        }
+        if (!h.host_receipt || h.host_receipt.manifest_digest !== h.host_manifest_digest)
+            throw new ServiceError('host_mismatch', 'Running daemon reports no reviewed host receipt');
+        if (h.host_receipt.state !== state)
+            throw new ServiceError('host_mismatch', 'Running daemon serves another state directory');
+        if (h.host_supervisor_connected !== true || h.service !== 'healthy')
+            return null;
+        if (h.job_execution?.control_error ||
+            h.job_execution?.schedule_control_error ||
+            h.job_execution?.inbox_control_error)
+            throw Error('Reviewed host controls are not ready');
+        return h.host_receipt;
+    };
+    let receipt = await ready();
+    if (receipt)
+        return receipt;
+    await new Promise((done, fail) => execFile(options.systemctl ?? '/usr/bin/systemctl', ['start', '--no-ask-password', unit], { env: { PATH: '/usr/bin:/bin', LANG: 'C.UTF-8' }, timeout: 20000 }, (error) => error ? fail(Error('systemd refused to start ' + unit + '; inspect its journal')) : done()));
+    while (!(receipt = await ready())) {
+        if (Date.now() >= deadline)
+            throw Error('Host unit did not become ready; inspect its journal');
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    return receipt;
+}