@ours.network/fleet 0.10.2 → 0.10.4

package/README.md

@@ -128,6 +128,72 @@ ours-fleet spawn Coder --harness codex --model gpt-5.4 \
 # wake owner separately in fleet.yaml with monitor.mode: fleet|native.
 ```
 
+## Local web console
+
+The interactive console is packaged with `@ours.network/fleet` and runs only on
+IPv4 loopback:
+
+```sh
+npm run build
+ours-fleet web
+# choose a free port for an isolated test:
+ours-fleet web serve --port 0 --no-open
+```
+
+The normal `ours-fleet web` command installs or updates an owner-level native
+service, starts it on stable `127.0.0.1:49271`, and opens/re-pairs the browser.
+Linux uses a systemd user unit and macOS uses a LaunchAgent; both restart after
+process failures and send logs to the native supervisor. Service management is
+explicit through `ours-fleet web install|start|stop|restart|status|uninstall`.
+Use `ours-fleet web serve` for a foreground development process. Linux login
+persistence requires linger; the installer reports when it is missing but
+never enables it or requests root privileges.
+
+The normal command opens a one-time five-minute fragment directly in the local
+browser; it does not print a reusable secret. If the browser needs pairing
+again while the server is running, use `ours-fleet web open`. The fragment is
+exchanged once and removed from history. A paired browser receives a rotating,
+30-day `HttpOnly; SameSite=Strict` device credential and can return after a
+session idle timeout or server restart. Use **Sign out** to revoke the current
+browser, or `ours-fleet web revoke-all` to revoke every trusted browser and
+active web session.
+
+Only a domain-separated SHA-256 device-secret hash and bounded timestamps are
+stored in the owner-private fleet state directory (`0700` directory, `0600`
+atomic file). The re-pair and revoke controls use an owner-private Unix socket;
+local processes running as the same OS user are therefore inside the trust
+boundary. Keep the console local: it has no `--host`, proxy, TLS, or
+remote-access mode.
+
+The console is installable as a standalone PWA. Its service worker caches only
+the data-free offline page and successful content-hashed JavaScript/CSS assets.
+HTML stays network-first and no API, authentication, bootstrap, device,
+WebSocket, terminal, event, audit, log, session, query-bearing, or error response
+is cached. When the local daemon is unavailable, the PWA shows an explicit
+offline shell and no stale fleet state.
+
+The console provides evidence-separated inventory and status, ACP activity and
+permission controls, redacted logs, typed text send, confirmed lifecycle
+actions, transactional permanent/temporary creation, and a shared tmux browser
+terminal. Identity is fixed to the role name. Creation uses the current
+authenticated identity existence check and reports verified, missing, or
+unknown evidence; a newly launched harness follows its generated first-boot
+instructions to choose or create and bind the identity. The console never
+claims that the host created an identity and never deletes one.
+`node-pty` is optional: if its native module cannot load, ACP and all
+non-terminal features remain available and tmux Terminal is disabled with a
+diagnostic.
+
+Security boundaries:
+
+- exact runtime `Host` and `Origin`, CSRF, one-time WebSocket tickets, and
+  loopback binding are enforced server-side;
+- cwd values must resolve beneath configured local roots;
+- terminal bytes are intentionally unredacted and are never copied into audit
+  records; normal logs are bounded and redacted;
+- tests use temporary fleet homes, fake supervisors/identity providers, and
+  isolated tmux sockets—never active role state.
+
 Permanent spawns are written to `~/fleet.d/<Name>.yaml` — your hand-written
 `~/fleet.yaml` is **never** machine-edited. `ours-fleet rm <Name>` unspawns.
 

package/dist/application/capabilities.d.ts

@@ -0,0 +1,6 @@
+import type { RoleRecord, RoleCapabilities, RoleStatus } from './types.js';
+export interface CapabilityContext {
+    terminalPtyAvailable?: boolean;
+    controlProtocolVersion?: number;
+}
+export declare function roleCapabilities(role: RoleRecord, status: RoleStatus, context?: CapabilityContext): RoleCapabilities;

package/dist/application/capabilities.js

@@ -0,0 +1,37 @@
+export function roleCapabilities(role, status, context = {}) {
+    const backend = role.configuredBackend ?? (role.detectedBackend === 'acp' || role.detectedBackend === 'tmux' ? role.detectedBackend : undefined);
+    const online = status.session.reachability === 'online';
+    const acp = backend === 'acp';
+    const tmux = backend === 'tmux';
+    const protocolVersion = context.controlProtocolVersion ?? 1;
+    const inactive = status.overall === 'offline'
+        || (!online && status.supervisor.liveness === 'stopped');
+    const terminalAvailable = tmux && online && context.terminalPtyAvailable === true;
+    const terminalReason = terminalAvailable ? undefined
+        : !tmux ? 'wrong_backend'
+            : !online ? 'offline'
+                : 'pty_unavailable';
+    return {
+        protocolVersion,
+        inventory: true,
+        status: true,
+        output: {
+            recent: acp || tmux, stream: (acp && protocolVersion >= 2) || terminalAvailable,
+            structured: acp, replayCursor: acp && protocolVersion >= 2,
+        },
+        input: { text: online && (acp || tmux), rawKeys: terminalAvailable, interrupt: online && acp, steering: false },
+        permissions: { observe: acp, respond: acp && online },
+        terminal: {
+            available: terminalAvailable, reason: terminalReason,
+            multiViewer: terminalAvailable, writerLease: terminalAvailable,
+        },
+        lifecycle: {
+            start: role.lifetime === 'permanent' && status.supervisor.liveness !== 'running',
+            stop: role.lifetime === 'permanent' && !inactive && status.supervisor.liveness !== 'stopped',
+            restartResume: role.lifetime === 'permanent' && !inactive,
+            restartFresh: role.lifetime === 'permanent' && !inactive,
+            remove: false,
+        },
+        logs: { tail: true, follow: status.supervisor.backend !== 'none', cursor: status.supervisor.backend !== 'none' },
+    };
+}

package/dist/application/errors.d.ts

@@ -0,0 +1,31 @@
+export type FleetErrorCode = 'role_not_found' | 'capability_unavailable' | 'invalid_request' | 'offline' | 'control_unavailable' | 'timeout' | 'rejected' | 'backend_failure' | 'conflict' | 'stale_state' | 'prerequisite_unavailable' | 'idempotency_conflict' | 'rollback_incomplete' | 'launched_unconfirmed' | 'unauthorized' | 'forbidden' | 'rate_limited' | 'incompatible_version' | 'internal';
+export interface FleetErrorShape {
+    code: FleetErrorCode;
+    message: string;
+    provesOffline: boolean;
+    retryable: boolean;
+    requestId: string;
+    details?: Record<string, string | number | boolean>;
+}
+export declare class FleetError extends Error implements FleetErrorShape {
+    readonly code: FleetErrorCode;
+    readonly options: {
+        provesOffline?: boolean;
+        retryable?: boolean;
+        requestId?: string;
+        details?: Record<string, string | number | boolean>;
+    };
+    readonly requestId: string;
+    constructor(code: FleetErrorCode, message: string, options?: {
+        provesOffline?: boolean;
+        retryable?: boolean;
+        requestId?: string;
+        details?: Record<string, string | number | boolean>;
+    });
+    get provesOffline(): boolean;
+    get retryable(): boolean;
+    get details(): Record<string, string | number | boolean> | undefined;
+    toJSON(): FleetErrorShape;
+}
+export declare function safeLine(input: string, max?: number): string;
+export declare function normalizeError(error: unknown, requestId?: string): FleetError;

package/dist/application/errors.js

@@ -0,0 +1,51 @@
+import { randomUUID } from 'node:crypto';
+import { SessionControlError } from '../session/types.js';
+import { CreationConflictError } from '../creation.js';
+const CONTROL_CODES = {
+    offline: 'offline',
+    'control-unavailable': 'control_unavailable',
+    timeout: 'timeout',
+    rejected: 'rejected',
+    backend: 'backend_failure',
+};
+export class FleetError extends Error {
+    code;
+    options;
+    requestId;
+    constructor(code, message, options = {}) {
+        super(safeLine(message));
+        this.code = code;
+        this.options = options;
+        this.name = 'FleetError';
+        this.requestId = options.requestId ?? randomUUID();
+    }
+    get provesOffline() { return this.options.provesOffline ?? this.code === 'offline'; }
+    get retryable() {
+        return this.options.retryable
+            ?? ['timeout', 'control_unavailable', 'backend_failure', 'launched_unconfirmed'].includes(this.code);
+    }
+    get details() { return this.options.details; }
+    toJSON() {
+        return {
+            code: this.code, message: this.message, provesOffline: this.provesOffline,
+            retryable: this.retryable, requestId: this.requestId, details: this.details,
+        };
+    }
+}
+export function safeLine(input, max = 512) {
+    return input.replace(/[\0-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+export function normalizeError(error, requestId) {
+    if (error instanceof FleetError)
+        return error;
+    if (error instanceof CreationConflictError)
+        return new FleetError('conflict', error.message, { requestId, retryable: true });
+    if (error instanceof SessionControlError) {
+        const code = CONTROL_CODES[error.kind];
+        return new FleetError(code, error.message, {
+            requestId, provesOffline: error.kind === 'offline',
+            retryable: error.kind === 'timeout' || error.kind === 'control-unavailable' || error.kind === 'backend',
+        });
+    }
+    return new FleetError('internal', error instanceof Error ? error.message : String(error), { requestId });
+}

package/dist/application/fleet-query-service.d.ts

@@ -0,0 +1,31 @@
+import type { SupervisorBackend } from '../supervisor/types.js';
+import { controlRequest } from '../session/control.js';
+import { Tmux } from '../tmux.js';
+import { type CapabilityContext } from './capabilities.js';
+import { RoleRepository } from './role-repository.js';
+import type { RoleCapabilities, RoleRecord, RoleStatus } from './types.js';
+export interface FleetQueryOptions {
+    repository: RoleRepository;
+    supervisor: SupervisorBackend;
+    tmux?: Tmux;
+    control?: typeof controlRequest;
+    capabilityContext?: CapabilityContext;
+}
+export declare class FleetQueryService {
+    private readonly options;
+    private readonly tmux;
+    private readonly control;
+    constructor(options: FleetQueryOptions);
+    list(): Promise<Array<{
+        role: RoleRecord;
+        status: RoleStatus;
+        capabilities: RoleCapabilities;
+    }>>;
+    detail(id: string): Promise<{
+        role: RoleRecord;
+        status: RoleStatus;
+        capabilities: RoleCapabilities;
+    }>;
+    status(role: RoleRecord): Promise<RoleStatus>;
+    private session;
+}

package/dist/application/fleet-query-service.js

@@ -0,0 +1,180 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { controlRequest } from '../session/control.js';
+import { SessionControlError } from '../session/types.js';
+import { readExitRecord, readRestartLedger } from '../runner.js';
+import { Tmux } from '../tmux.js';
+import { roleCapabilities } from './capabilities.js';
+import { FleetError } from './errors.js';
+const clean = (value, max = 512) => value.replace(/[\0-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '').trim().slice(0, max);
+function boundedText(path, max = 16 * 1024) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > max)
+            return undefined;
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function readMonitor(dir, now = Date.now()) {
+    const owner = clean(boundedText(join(dir, '.monitor-owner'), 64) ?? '');
+    const raw = clean(boundedText(join(dir, '.monitor-status')) ?? '');
+    const statAt = (() => {
+        try {
+            return lstatSync(join(dir, '.monitor-status')).mtime.toISOString();
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const lower = raw.toLowerCase();
+    const health = /fail|error/.test(lower) ? 'failed'
+        : /degrad|api error/.test(lower) ? 'degraded'
+            : raw ? 'armed' : 'unknown';
+    const stale = statAt ? now - Date.parse(statAt) > 60_000 : true;
+    return {
+        mode: owner === 'fleet' || owner === 'native' ? owner : 'unknown',
+        health, updatedAt: statAt, detail: raw || undefined, stale,
+    };
+}
+function readIsolation(dir) {
+    const text = boundedText(join(dir, '.isolation-degraded'));
+    return text ? { degraded: true, detail: clean(text) } : { degraded: false };
+}
+function sessionOverall(supervisor, session, restart, monitor, isolation, problems) {
+    if (restart.circuit === 'open' || monitor.health === 'failed' || monitor.health === 'degraded'
+        || isolation.degraded || problems.some(problem => problem.severity === 'error')
+        || session.readiness === 'failed')
+        return 'attention';
+    // A reachable ACP/tmux session is the user's live interaction surface. Its
+    // evidence remains authoritative even when a service manager no longer owns
+    // the process (for example, a detached ACP session with an inactive unit).
+    if (session.reachability === 'online'
+        && (session.readiness === 'running' || session.readiness === 'awaiting_permission'))
+        return 'busy';
+    if (session.reachability === 'online' && session.readiness === 'idle')
+        return 'ready';
+    if (session.reachability === 'offline'
+        && (session.evidence === 'authoritative' || supervisor.liveness === 'stopped'))
+        return 'offline';
+    return 'unknown';
+}
+export class FleetQueryService {
+    options;
+    tmux;
+    control;
+    constructor(options) {
+        this.options = options;
+        this.tmux = options.tmux ?? new Tmux();
+        this.control = options.control ?? controlRequest;
+    }
+    async list() {
+        const roles = await this.options.repository.list();
+        return Promise.all(roles.map(async (role) => {
+            const status = await this.status(role);
+            return { role, status, capabilities: roleCapabilities(role, status, this.options.capabilityContext) };
+        }));
+    }
+    async detail(id) {
+        const role = await this.options.repository.get(id);
+        if (!role)
+            throw new FleetError('role_not_found', `no such role '${id}'`, { provesOffline: false });
+        const status = await this.status(role);
+        return { role, status, capabilities: roleCapabilities(role, status, this.options.capabilityContext) };
+    }
+    async status(role) {
+        const observedAt = new Date().toISOString();
+        const live = await this.options.supervisor.liveness(role.id)
+            .catch(error => ({ state: 'unknown', detail: error.message }));
+        const dir = this.options.repository.stateDir(role);
+        const restart = dir ? readRestartLedger(dir) : {
+            circuit: 'closed', consecutiveImmediateFailures: 0, nextDelayMs: 0,
+            lastReason: '', openedAt: undefined,
+        };
+        const monitor = dir ? readMonitor(dir) : {
+            mode: 'unknown', health: 'unknown', stale: true,
+        };
+        const isolation = dir ? readIsolation(dir) : { degraded: false };
+        const lastExit = dir ? readExitRecord(join(dir, '.exit-status')) ?? undefined : undefined;
+        const session = await this.session(role, dir, live.state);
+        const problems = [...role.problems];
+        if (live.state === 'running' && session.reachability !== 'online')
+            problems.push({
+                code: 'supervisor_session_disagreement', severity: 'warning',
+                detail: 'supervisor is live but the session is not reachable',
+            });
+        if (role.lifetime === 'permanent' && live.state === 'stopped'
+            && session.reachability === 'online')
+            problems.push({
+                code: 'session_supervisor_disagreement', severity: 'warning',
+                detail: 'session is live while its permanent supervisor service is inactive',
+            });
+        const supervisor = {
+            backend: this.options.supervisor.id, liveness: live.state,
+            nativeState: live.detail.split(/\s/)[0], detail: clean(live.detail),
+        };
+        return {
+            roleId: role.id, observedAt,
+            overall: sessionOverall(supervisor, session, restart, monitor, isolation, problems),
+            supervisor, session,
+            restart: {
+                circuit: restart.circuit,
+                consecutiveImmediateFailures: restart.consecutiveImmediateFailures,
+                nextDelayMs: restart.nextDelayMs,
+                lastReason: restart.lastReason || undefined,
+                openedAt: restart.openedAt,
+            },
+            monitor, lastExit, isolation, problems,
+        };
+    }
+    async session(role, dir, supervisor) {
+        const intended = role.configuredBackend;
+        if (intended === 'acp' && dir) {
+            try {
+                const response = await this.control(dir, { command: 'snapshot' }, 2_000);
+                if (!response.ok)
+                    throw new SessionControlError(response.kind ?? 'backend', response.error ?? 'snapshot failed');
+                const snapshot = response.result;
+                return {
+                    backend: 'acp', reachability: snapshot.alive ? 'online' : 'offline',
+                    readiness: snapshot.readiness, evidence: 'authoritative',
+                    sessionId: snapshot.sessionId, lastError: snapshot.lastError,
+                    pendingPermissionId: snapshot.pendingPermissionId,
+                };
+            }
+            catch (error) {
+                const failure = error instanceof SessionControlError ? error.kind : 'backend';
+                const offline = failure === 'offline';
+                return {
+                    backend: 'acp',
+                    reachability: offline ? 'offline'
+                        : failure === 'control-unavailable' ? 'unavailable' : 'unknown',
+                    readiness: offline ? 'failed' : 'unknown',
+                    evidence: 'authoritative', lastError: clean(error.message),
+                };
+            }
+        }
+        if (intended === 'tmux' || role.detectedBackend === 'tmux') {
+            try {
+                const has = await this.tmux.has(role.id);
+                return {
+                    backend: 'tmux', reachability: has ? 'online' : supervisor === 'stopped' ? 'offline' : 'unknown',
+                    readiness: has ? 'idle' : supervisor === 'running' ? 'starting' : 'failed',
+                    evidence: 'inferred',
+                };
+            }
+            catch (error) {
+                return {
+                    backend: 'tmux', reachability: 'unknown', readiness: 'unknown',
+                    evidence: 'inferred', lastError: clean(error.message),
+                };
+            }
+        }
+        return {
+            backend: 'unknown', reachability: supervisor === 'stopped' ? 'offline' : 'unknown',
+            readiness: supervisor === 'stopped' ? 'failed' : 'unknown', evidence: 'inferred',
+        };
+    }
+}

package/dist/application/log-service.d.ts

@@ -0,0 +1,28 @@
+import type { Exec } from '../exec.js';
+import type { SupervisorBackend } from '../supervisor/types.js';
+import type { LogPage, LogRecord } from './types.js';
+export declare function redactLogLine(input: string, patterns?: RegExp[]): {
+    text: string;
+    redactionApplied: boolean;
+};
+export interface RoleLogSource {
+    tail(limit: number, cursor?: string): Promise<LogPage>;
+}
+/**
+ * Presentation-only compaction for noisy historical monitor transport hiccups.
+ * Exact reason and adjacency are part of the key: a different or intervening
+ * record always starts a new run. Source journal/file records are untouched.
+ */
+export declare function compactMonitorStreamHiccups(records: LogRecord[]): LogRecord[];
+export declare class StructuredLogService {
+    private readonly backend;
+    private readonly exec;
+    private readonly cursorKey;
+    constructor(backend: SupervisorBackend, exec?: Exec);
+    source(roleId: string): RoleLogSource;
+    private tail;
+    private cursor;
+    private validCursor;
+}
+/** Bounded launchd file reader used by tests and diagnostics. */
+export declare function readKnownRoleLog(roleId: string, limit?: number): LogPage;

package/dist/application/log-service.js

@@ -0,0 +1,146 @@
+import { lstatSync, readFileSync } from 'node:fs';
+import { createHmac, randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { realExec } from '../exec.js';
+import { logsRoot } from '../paths.js';
+import { unitFor } from '../supervisor/systemd.js';
+import { ROLE_NAME_RE } from '../config.js';
+import { FleetError } from './errors.js';
+const STANDARD_REDACTIONS = [
+    /\b(authorization\s*:\s*(?:bearer|basic)\s+)[^\s]+/gi,
+    /\b((?:api[_-]?key|token|secret|password)\s*[=:]\s*)[^\s,;]+/gi,
+    /-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]*?-----END [A-Z ]+PRIVATE KEY-----/g,
+    /\bours_[A-Za-z0-9_-]{16,}\b/g,
+];
+export function redactLogLine(input, patterns = []) {
+    let text = input.replace(/[\0-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '').slice(0, 16 * 1024);
+    const before = text;
+    for (const pattern of [...STANDARD_REDACTIONS, ...patterns.slice(0, 20)])
+        text = text.replace(pattern, (_match, prefix) => `${prefix ?? ''}[REDACTED]`);
+    return { text, redactionApplied: text !== before };
+}
+const MONITOR_STREAM_HICCUP = /^monitor degraded:\s*stream hiccup\s*\((.+)\)\s*$/;
+/**
+ * Presentation-only compaction for noisy historical monitor transport hiccups.
+ * Exact reason and adjacency are part of the key: a different or intervening
+ * record always starts a new run. Source journal/file records are untouched.
+ */
+export function compactMonitorStreamHiccups(records) {
+    const result = [];
+    for (let index = 0; index < records.length;) {
+        const first = records[index];
+        const match = MONITOR_STREAM_HICCUP.exec(first.text);
+        if (!match) {
+            result.push(first);
+            index++;
+            continue;
+        }
+        const reason = match[1];
+        let end = index + 1;
+        while (end < records.length) {
+            const candidate = MONITOR_STREAM_HICCUP.exec(records[end].text);
+            if (!candidate || candidate[1] !== reason)
+                break;
+            end++;
+        }
+        if (end - index === 1) {
+            result.push(first);
+        }
+        else {
+            const last = records[end - 1];
+            result.push({
+                at: first.at,
+                text: 'monitor degraded: stream hiccup',
+                cursor: last.cursor,
+                redactionApplied: records.slice(index, end).some(record => record.redactionApplied),
+                compacted: {
+                    kind: 'monitor_stream_hiccup', reason, count: end - index,
+                    firstAt: first.at, lastAt: last.at,
+                },
+            });
+        }
+        index = end;
+    }
+    return result;
+}
+export class StructuredLogService {
+    backend;
+    exec;
+    cursorKey = randomBytes(32);
+    constructor(backend, exec = realExec) {
+        this.backend = backend;
+        this.exec = exec;
+    }
+    source(roleId) {
+        if (!ROLE_NAME_RE.test(roleId))
+            throw new FleetError('invalid_request', 'invalid role id');
+        return { tail: (limit, cursor) => this.tail(roleId, limit, cursor) };
+    }
+    async tail(roleId, requested, cursor) {
+        const limit = Math.min(Math.max(requested, 1), 1_000);
+        const args = this.backend.id === 'systemd'
+            ? {
+                cmd: 'journalctl',
+                args: ['--user', '-u', unitFor(roleId), '-o', 'json', '--no-pager', '-n', String(limit)],
+            }
+            : this.backend.logsArgs(roleId, false);
+        if (!['journalctl', 'tail', 'tmux'].includes(args.cmd))
+            throw new FleetError('capability_unavailable', 'log backend is unsupported');
+        const result = await this.exec(args.cmd, args.args);
+        if (result.code !== 0)
+            throw new FleetError('backend_failure', `log query failed with exit ${result.code}`);
+        const lines = result.stdout.split(/\r?\n/).filter(Boolean).slice(-limit);
+        const parsed = lines.map((line, index) => {
+            let text = line;
+            let at;
+            if (this.backend.id === 'systemd') {
+                try {
+                    const json = JSON.parse(line);
+                    text = typeof json.MESSAGE === 'string' ? json.MESSAGE : line;
+                    if (typeof json.__REALTIME_TIMESTAMP === 'string') {
+                        const micros = Number(json.__REALTIME_TIMESTAMP);
+                        if (Number.isFinite(micros))
+                            at = new Date(micros / 1000).toISOString();
+                    }
+                }
+                catch { /* preserve the bounded raw line */ }
+            }
+            const redacted = redactLogLine(text);
+            return {
+                at, ...redacted,
+                cursor: this.cursor(`${roleId}:${index}:${line.length}`),
+            };
+        });
+        const records = compactMonitorStreamHiccups(parsed);
+        return {
+            records, nextCursor: records.at(-1)?.cursor,
+            truncated: lines.length >= limit || Boolean(cursor && !this.validCursor(cursor)),
+        };
+    }
+    cursor(value) {
+        const body = Buffer.from(value).toString('base64url');
+        const tag = createHmac('sha256', this.cursorKey).update(body).digest('base64url').slice(0, 16);
+        return `${body}.${tag}`;
+    }
+    validCursor(cursor) {
+        const [body, tag] = cursor.split('.');
+        return Boolean(body && tag && this.cursor(Buffer.from(body, 'base64url').toString()).split('.')[1] === tag);
+    }
+}
+/** Bounded launchd file reader used by tests and diagnostics. */
+export function readKnownRoleLog(roleId, limit = 200) {
+    if (!ROLE_NAME_RE.test(roleId))
+        throw new FleetError('invalid_request', 'invalid role id');
+    const path = join(logsRoot(), `${roleId}.log`);
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 8 * 1024 * 1024)
+            throw new Error('unsafe or oversized log file');
+        const records = readFileSync(path, 'utf8').split(/\r?\n/).filter(Boolean).slice(-limit)
+            .map(line => ({ ...redactLogLine(line) }));
+        return { records, truncated: stat.size > 512 * 1024 };
+    }
+    catch (error) {
+        throw new FleetError('backend_failure', `could not read role log: ${error.message}`);
+    }
+}

package/dist/application/role-command-service.d.ts

@@ -0,0 +1,37 @@
+import { type OpsDeps } from '../ops.js';
+import { FleetError } from './errors.js';
+import { RoleRepository } from './role-repository.js';
+import type { RoleStatus } from './types.js';
+export type LifecycleAction = 'start' | 'stop' | 'restart_resume' | 'restart_fresh';
+export interface CommandReceipt {
+    actionId: string;
+    roleId: string;
+    action: LifecycleAction;
+    acceptedAt: string;
+    completedAt?: string;
+    state: 'accepted' | 'running' | 'succeeded' | 'failed' | 'uncertain';
+    error?: ReturnType<FleetError['toJSON']>;
+    postcondition?: Pick<RoleStatus, 'overall' | 'observedAt'>;
+}
+export interface RoleCommandOptions {
+    repository: RoleRepository;
+    ops: OpsDeps;
+    configPath?: string;
+    status(roleId: string): Promise<RoleStatus>;
+    onProgress?: (receipt: CommandReceipt) => void;
+}
+export declare class RoleCommandService {
+    private readonly options;
+    private readonly receipts;
+    private readonly locks;
+    constructor(options: RoleCommandOptions);
+    execute(input: {
+        roleId: string;
+        action: LifecycleAction;
+        actionId?: string;
+        confirmation?: string;
+    }): Promise<CommandReceipt>;
+    get(actionId: string): CommandReceipt | undefined;
+    private run;
+    private serial;
+}