@addai/node 0.30.13 → 0.30.15

package/dist/entitybox/model-mcp-proxy.d.ts

@@ -0,0 +1,3 @@
+/** Public, credential-free stdio shim placed inside the isolated model's own
+ * workspace. It talks only to that container's loopback broker endpoint. */
+export declare function entityboxModelMcpProxySource(endpoint: string): string;

package/dist/entitybox/model-mcp-proxy.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entityboxModelMcpProxySource = entityboxModelMcpProxySource;
+/** Public, credential-free stdio shim placed inside the isolated model's own
+ * workspace. It talks only to that container's loopback broker endpoint. */
+function entityboxModelMcpProxySource(endpoint) {
+    if (!/^http:\/\/127\.0\.0\.1:[0-9]{1,5}\/entitybox\/mcp$/.test(endpoint))
+        throw new Error('Invalid isolated MCP endpoint');
+    return '(' + proxyMain.toString() + ')(' + JSON.stringify(endpoint) + ');\n';
+}
+// Keep this function self-contained: its compiled source runs in a separate
+// Node process without imports, credentials or references to the outer bundle.
+function proxyMain(endpoint) {
+    const http = require('node:http');
+    let input = '', queued = 0, serial = Promise.resolve();
+    const requests = new Set();
+    const fail = () => { process.stderr.write('The required desktop connection ended.\n'); process.exit(70); };
+    const exchange = (message) => new Promise((resolve, reject) => {
+        const body = JSON.stringify(message);
+        const req = http.request(endpoint, { method: 'POST', headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) } }, res => {
+            const chunks = [];
+            let bytes = 0;
+            res.on('data', (chunk) => { bytes += chunk.length; if (bytes > 32 * 1024 * 1024) {
+                req.destroy();
+                reject(Error());
+            }
+            else
+                chunks.push(chunk); });
+            res.on('error', reject);
+            res.on('end', () => {
+                try {
+                    if (res.statusCode !== 200)
+                        throw Error();
+                    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                    if (message.id === undefined ? value !== null : (!value || value.jsonrpc !== '2.0' || value.id !== message.id || !value.result))
+                        throw Error();
+                    resolve(value);
+                }
+                catch {
+                    reject(Error());
+                }
+            });
+        });
+        requests.add(req);
+        req.on('close', () => requests.delete(req));
+        req.on('error', reject);
+        req.setTimeout(130000, () => { req.destroy(); reject(Error()); });
+        req.end(body);
+    });
+    const consume = async (message) => {
+        const value = await exchange(message);
+        if (value !== null)
+            await new Promise((resolve, reject) => process.stdout.write(JSON.stringify(value) + '\n', error => error ? reject(error) : resolve()));
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+        try {
+            input += chunk;
+            if (Buffer.byteLength(input) > 512 * 1024)
+                throw Error();
+            let end;
+            while ((end = input.indexOf('\n')) >= 0) {
+                const message = JSON.parse(input.slice(0, end));
+                input = input.slice(end + 1);
+                if (!message || message.jsonrpc !== '2.0' || typeof message.method !== 'string' || ++queued > 8)
+                    throw Error();
+                // MCP cancellation is urgent even while an earlier tool response is
+                // pending. The host broker fences the whole external-action task.
+                if (message.method === 'notifications/cancelled')
+                    void consume(message).then(() => queued--).catch(fail);
+                else {
+                    serial = serial.then(() => consume(message)).then(() => { queued--; });
+                    serial.catch(fail);
+                }
+            }
+        }
+        catch {
+            fail();
+        }
+    });
+    process.stdin.on('end', () => { for (const req of requests)
+        req.destroy(); process.exit(0); });
+    process.stdin.on('error', fail);
+    process.stdout.on('error', fail);
+}

package/dist/entitybox-application-boundary.d.ts

@@ -0,0 +1,59 @@
+import { type EntityboxExecutionLease } from './entitybox-execution-lease';
+import type { EntityboxMcpScope } from './entitybox-mcp-contract';
+/** One application's persistent process namespace, separate from the native
+ * display and from a task's short-lived model/command namespace. This accepts
+ * only newly provisioned, labeled capacity; it never discovers or adopts an
+ * ordinary desktop. Registration and crash recovery belong to the adapter. */
+export interface EntityboxApplicationBinding {
+    capacityId: string;
+    desktopId: string;
+    runtimeId: string;
+    containerId: string;
+    imageId: string;
+    startedAt: string;
+}
+export interface EntityboxApplicationQuiescence {
+    capacityId: string;
+    containerId: string;
+    attemptId: string;
+    state: 'paused' | 'stopped';
+    observedAt: string;
+}
+export type EntityboxApplicationDocker = (args: string[]) => Promise<string>;
+export declare function entityboxApplicationVolumes(binding: EntityboxApplicationBinding): {
+    socket: string;
+    profile: string;
+    work: string;
+};
+export declare function entityboxApplicationLabels(binding: EntityboxApplicationBinding): {
+    'ai.add.entitybox.application.version': string;
+    'ai.add.entitybox.application.capacity': string;
+    'ai.add.entitybox.application.desktop': string;
+    'ai.add.entitybox.application.runtime': string;
+};
+/** Inspect all mounts as well as immutable identities. A Docker success code,
+ * a matching container name, or a stopped model is never sufficient proof. */
+export declare function inspectEntityboxApplication(binding: EntityboxApplicationBinding, scope: EntityboxMcpScope, docker: EntityboxApplicationDocker): Promise<'running' | 'paused' | 'stopped'>;
+/** One-use owner for an already paused application. It resumes only after a
+ * fresh native lease check, and freezes the entire namespace when fenced.
+ * A successful pause is final for this object: a late callback from an old
+ * task cannot pause a replacement owner. The adapter must keep the SQL
+ * reservation until this proof AND task/MCP stop proof both succeed.
+ *
+ * This is not a daemon-crash watchdog or a human-control grant. A durable
+ * capacity owner and independent watchdog are required before registration
+ * in the production request pump. */
+export declare class EntityboxApplicationBoundary {
+    private readonly lease;
+    readonly binding: Readonly<EntityboxApplicationBinding>;
+    private readonly docker;
+    private used;
+    private startup;
+    private quiescing?;
+    private proven?;
+    private abort;
+    private constructor();
+    static attach(lease: EntityboxExecutionLease, binding: EntityboxApplicationBinding, docker: EntityboxApplicationDocker): Promise<EntityboxApplicationBoundary>;
+    resume(): Promise<void>;
+    pauseAndVerify(): Promise<EntityboxApplicationQuiescence>;
+}

package/dist/entitybox-application-boundary.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxApplicationBoundary = void 0;
+exports.entityboxApplicationVolumes = entityboxApplicationVolumes;
+exports.entityboxApplicationLabels = entityboxApplicationLabels;
+exports.inspectEntityboxApplication = inspectEntityboxApplication;
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const uuid = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+const failure = () => new entitybox_execution_lease_1.EntityboxExecutionError('The dedicated application boundary could not be verified');
+function entityboxApplicationVolumes(binding) {
+    if (!uuid.test(binding?.capacityId))
+        throw failure();
+    return { socket: 'entitybox-display-' + binding.capacityId, profile: 'entitybox-app-profile-' + binding.capacityId, work: 'entitybox-app-work-' + binding.capacityId };
+}
+function entityboxApplicationLabels(binding) {
+    return { 'ai.add.entitybox.application.version': '1', 'ai.add.entitybox.application.capacity': binding.capacityId, 'ai.add.entitybox.application.desktop': binding.desktopId, 'ai.add.entitybox.application.runtime': binding.runtimeId };
+}
+function labelMatch(actual, expected) { return !!actual && Object.entries(expected).every(([k, v]) => actual[k] === v); }
+function validBinding(binding, scope) {
+    if (!binding || !uuid.test(binding.capacityId) || !uuid.test(binding.desktopId) || !uuid.test(binding.runtimeId)
+        || binding.desktopId !== scope.desktopId || binding.runtimeId !== scope.runtimeId || !/^[0-9a-f]{64}$/.test(binding.containerId)
+        || !/^sha256:[0-9a-f]{64}$/.test(binding.imageId) || typeof binding.startedAt !== 'string' || binding.startedAt.length > 80
+        || !Number.isFinite(Date.parse(binding.startedAt)))
+        throw failure();
+}
+/** Inspect all mounts as well as immutable identities. A Docker success code,
+ * a matching container name, or a stopped model is never sufficient proof. */
+async function inspectEntityboxApplication(binding, scope, docker) {
+    validBinding(binding, scope);
+    const volumes = entityboxApplicationVolumes(binding), labels = entityboxApplicationLabels(binding);
+    const inspected = await Promise.all([docker(['container', 'inspect', binding.containerId]), docker(['volume', 'inspect', volumes.socket, volumes.profile, volumes.work])]);
+    let c, rows;
+    try {
+        const containers = JSON.parse(inspected[0]);
+        rows = JSON.parse(inspected[1]);
+        if (!Array.isArray(containers) || containers.length !== 1 || !Array.isArray(rows) || rows.length !== 3)
+            throw Error();
+        c = containers[0];
+    }
+    catch {
+        throw failure();
+    }
+    const h = c?.HostConfig, security = (h?.SecurityOpt ?? []);
+    if (c?.Id !== binding.containerId || c.Image !== binding.imageId || c.State?.StartedAt !== binding.startedAt || !labelMatch(c.Config?.Labels, labels)
+        || c.Config?.User !== '10001:10001' || !h?.ReadonlyRootfs || h.Privileged || h.Binds?.length || h.CapAdd?.length
+        || !Array.isArray(h.CapDrop) || !h.CapDrop.includes('ALL') || !Array.isArray(security) || !security.length || !security.every(s => s === 'no-new-privileges' || s === 'no-new-privileges:true')
+        || !['', 'private'].includes(h.PidMode ?? '') || !['', 'private'].includes(h.UsernsMode ?? '') || !['', 'private'].includes(h.UTSMode ?? '') || !['', 'private'].includes(h.CgroupnsMode ?? '') || h.IpcMode !== 'private' || h.NetworkMode !== 'none'
+        || h.Devices?.length || h.DeviceRequests?.length || h.VolumesFrom?.length || h.RestartPolicy?.Name !== 'no'
+        || !Number.isSafeInteger(h.Memory) || h.Memory < 128 * 1024 * 1024 || h.Memory > 4 * 1024 * 1024 * 1024 || h.MemorySwap !== h.Memory
+        || !Number.isSafeInteger(h.PidsLimit) || h.PidsLimit < 16 || h.PidsLimit > 512
+        || !Array.isArray(c.Mounts))
+        throw failure();
+    const expected = [{ name: volumes.socket, destination: '/tmp/.X11-unix', rw: false }, { name: volumes.profile, destination: '/home/entitybox', rw: true }, { name: volumes.work, destination: '/work', rw: true }];
+    const actual = c.Mounts.filter((m) => m.Type !== 'tmpfs');
+    if (actual.length !== expected.length)
+        throw failure();
+    for (const e of expected) {
+        const matches = actual.filter((m) => m.Type === 'volume' && m.Name === e.name && m.Destination === e.destination && m.RW === e.rw);
+        if (matches.length !== 1)
+            throw failure();
+        const v = rows.find(r => r.Name === e.name);
+        const volumeLabels = e.name === volumes.socket ? { 'ai.add.entitybox.display.version': '1', 'ai.add.entitybox.display.capacity': binding.capacityId, 'ai.add.entitybox.display.desktop': binding.desktopId, 'ai.add.entitybox.display.runtime': binding.runtimeId } : labels;
+        if (!v || v.Driver !== 'local' || Object.keys(v.Options ?? {}).length || !labelMatch(v.Labels, volumeLabels))
+            throw failure();
+    }
+    if (c.Mounts.some((m) => m.Type === 'tmpfs' && !['/tmp', '/run'].includes(m.Destination)))
+        throw failure();
+    if (c.State.Restarting)
+        throw failure();
+    if (c.State.Running === true && Number.isSafeInteger(c.State.Pid) && c.State.Pid > 0 && c.State.Paused === true && c.State.Status === 'paused')
+        return 'paused';
+    if (c.State.Running === true && Number.isSafeInteger(c.State.Pid) && c.State.Pid > 0 && c.State.Paused === false && c.State.Status === 'running')
+        return 'running';
+    if (c.State.Running === false && c.State.Pid === 0 && c.State.Paused === false && ['exited', 'dead'].includes(c.State.Status))
+        return 'stopped';
+    throw failure();
+}
+/** One-use owner for an already paused application. It resumes only after a
+ * fresh native lease check, and freezes the entire namespace when fenced.
+ * A successful pause is final for this object: a late callback from an old
+ * task cannot pause a replacement owner. The adapter must keep the SQL
+ * reservation until this proof AND task/MCP stop proof both succeed.
+ *
+ * This is not a daemon-crash watchdog or a human-control grant. A durable
+ * capacity owner and independent watchdog are required before registration
+ * in the production request pump. */
+class EntityboxApplicationBoundary {
+    lease;
+    binding;
+    docker;
+    used = false;
+    startup = Promise.resolve();
+    quiescing;
+    proven;
+    abort = () => { void this.pauseAndVerify().catch(() => { }); };
+    constructor(lease, binding, docker) {
+        this.lease = lease;
+        this.binding = binding;
+        this.docker = docker;
+    }
+    static async attach(lease, binding, docker) {
+        lease.assertActive();
+        const copy = Object.freeze({ ...binding });
+        if (await inspectEntityboxApplication(copy, lease.identity.scope, docker) !== 'paused')
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Dedicated applications must be paused before a task takes ownership');
+        lease.assertActive();
+        return new EntityboxApplicationBoundary(lease, copy, docker);
+    }
+    resume() {
+        if (this.used || this.proven)
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Application ownership cannot be reused');
+        this.used = true;
+        this.startup = Promise.resolve().then(async () => {
+            this.lease.assertActive();
+            await this.lease.authorizeChallenge();
+            this.lease.assertActive();
+            if (await inspectEntityboxApplication(this.binding, this.lease.identity.scope, this.docker) !== 'paused')
+                throw failure();
+            this.lease.assertActive();
+            await this.docker(['container', 'unpause', this.binding.containerId]);
+            this.lease.assertActive();
+            if (await inspectEntityboxApplication(this.binding, this.lease.identity.scope, this.docker) !== 'running')
+                throw failure();
+            this.lease.assertActive();
+        });
+        this.lease.signal.addEventListener('abort', this.abort, { once: true });
+        if (this.lease.signal.aborted)
+            this.abort();
+        return this.startup.catch(async () => { this.lease.fence(); try {
+            await this.pauseAndVerify();
+        }
+        catch { } throw new entitybox_execution_lease_1.EntityboxExecutionError('Dedicated applications could not resume under verified ownership'); });
+    }
+    pauseAndVerify() {
+        if (this.proven)
+            return Promise.resolve(this.proven);
+        if (this.quiescing)
+            return this.quiescing;
+        this.quiescing = Promise.resolve().then(async () => {
+            // Join an unpause already in flight. An observation timeout must not
+            // turn that unknown operation into successful pause proof.
+            try {
+                await this.startup;
+            }
+            catch { }
+            let state = await inspectEntityboxApplication(this.binding, this.lease.identity.scope, this.docker);
+            if (state === 'running') {
+                await this.docker(['container', 'pause', this.binding.containerId]);
+                state = await inspectEntityboxApplication(this.binding, this.lease.identity.scope, this.docker);
+            }
+            if (state === 'running')
+                throw failure();
+            this.proven = Object.freeze({ capacityId: this.binding.capacityId, containerId: this.binding.containerId, attemptId: this.lease.identity.attemptId, state, observedAt: new Date().toISOString() });
+            this.lease.signal.removeEventListener('abort', this.abort);
+            return this.proven;
+        });
+        this.lease.fence();
+        return this.quiescing.catch(error => { this.quiescing = undefined; throw error; });
+    }
+}
+exports.EntityboxApplicationBoundary = EntityboxApplicationBoundary;

package/dist/entitybox-application-guard-core.d.ts

@@ -0,0 +1,44 @@
+import { type EntityboxApplicationBinding, type EntityboxApplicationDocker, type EntityboxApplicationQuiescence } from './entitybox-application-boundary';
+import { type EntityboxExecutionIdentity } from './entitybox-execution-lease';
+type Packet = {
+    type: string;
+    [key: string]: unknown;
+};
+/** Trusted independent host process state machine. It is the sole application
+ * mutator while attached. A lost Docker mutation reply poisons reuse until
+ * the same namespace is actually stopped; observing paused is not sufficient
+ * when an earlier unpause/pause may still reach the engine. */
+export declare class EntityboxApplicationGuardCore {
+    private readonly docker;
+    private readonly emit;
+    private readonly now;
+    readonly identity: Readonly<EntityboxExecutionIdentity>;
+    readonly binding: Readonly<EntityboxApplicationBinding>;
+    readonly finished: Promise<EntityboxApplicationQuiescence>;
+    private resolve;
+    private phase;
+    private pending?;
+    private deadline;
+    private nextChallenge;
+    private nextInspect;
+    private uncertainty;
+    private attached;
+    private reported;
+    private startup;
+    private stopping?;
+    constructor(identity: EntityboxExecutionIdentity, binding: EntityboxApplicationBinding, docker: EntityboxApplicationDocker, emit: (packet: Packet) => void, now?: () => number);
+    state(): {
+        phase: "running" | "ready" | "initial" | "resuming" | "fenced" | "finished";
+        uncertain: boolean;
+    };
+    start(): Promise<void>;
+    message(packet: unknown): void;
+    tick(): void;
+    fence(): void;
+    private active;
+    private challenge;
+    private send;
+    private unverified;
+    private quiesce;
+}
+export {};

package/dist/entitybox-application-guard-core.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxApplicationGuardCore = void 0;
+const crypto_1 = require("crypto");
+const perf_hooks_1 = require("perf_hooks");
+const entitybox_application_boundary_1 = require("./entitybox-application-boundary");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const entitybox_mcp_contract_1 = require("./entitybox-mcp-contract");
+const uuid = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+/** Trusted independent host process state machine. It is the sole application
+ * mutator while attached. A lost Docker mutation reply poisons reuse until
+ * the same namespace is actually stopped; observing paused is not sufficient
+ * when an earlier unpause/pause may still reach the engine. */
+class EntityboxApplicationGuardCore {
+    docker;
+    emit;
+    now;
+    identity;
+    binding;
+    finished;
+    resolve;
+    phase = 'initial';
+    pending;
+    deadline = 0;
+    nextChallenge = Infinity;
+    nextInspect = 0;
+    uncertainty = false;
+    attached = false;
+    reported = false;
+    startup = Promise.resolve();
+    stopping;
+    constructor(identity, binding, docker, emit, now = () => perf_hooks_1.performance.now()) {
+        this.docker = docker;
+        this.emit = emit;
+        this.now = now;
+        if (!identity || !uuid.test(identity.requestId) || !uuid.test(identity.attemptId))
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Invalid application guard identity');
+        this.identity = Object.freeze({ ...identity, scope: (0, entitybox_mcp_contract_1.parseEntityboxMcpScope)(identity.scope) });
+        this.binding = Object.freeze({ ...binding });
+        this.finished = new Promise(resolve => { this.resolve = resolve; });
+    }
+    state() { return { phase: this.phase, uncertain: this.uncertainty }; }
+    async start() {
+        if (this.phase !== 'initial')
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Application guard cannot be reused');
+        if (await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(this.binding, this.identity.scope, this.docker) !== 'paused')
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Application guard requires paused capacity');
+        this.attached = true;
+        if (this.phase !== 'initial') {
+            this.quiesce();
+            return;
+        }
+        this.phase = 'ready';
+        this.send({ type: 'ready' });
+    }
+    message(packet) {
+        const p = packet;
+        if (this.phase === 'finished')
+            return;
+        if (p?.type === 'stop') {
+            this.fence();
+            return;
+        }
+        if (p?.type === 'resume' && this.phase === 'ready') {
+            this.phase = 'resuming';
+            this.deadline = this.now() + 10000;
+            this.challenge();
+            return;
+        }
+        if (p?.type === 'grant' && typeof p.id === 'string' && this.pending && p.id === this.pending.id && (this.phase === 'resuming' || this.phase === 'running')) {
+            const deadline = this.pending.at + 10000;
+            if (this.now() >= this.deadline || this.now() >= deadline) {
+                this.fence();
+                return;
+            }
+            this.deadline = deadline;
+            this.pending = undefined;
+            if (this.phase === 'resuming') {
+                // Assign before any asynchronous work; fence joins this exact resume.
+                this.startup = Promise.resolve().then(async () => {
+                    if (await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(this.binding, this.identity.scope, this.docker) !== 'paused')
+                        throw Error();
+                    if (!this.active())
+                        return;
+                    try {
+                        await this.docker(['container', 'unpause', this.binding.containerId]);
+                    }
+                    catch {
+                        this.uncertainty = true;
+                        throw Error();
+                    }
+                    if (!this.active())
+                        return;
+                    if (await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(this.binding, this.identity.scope, this.docker) !== 'running')
+                        throw Error();
+                    if (!this.active())
+                        return;
+                    this.phase = 'running';
+                    this.nextChallenge = this.now() + 3000;
+                    this.send({ type: 'started' });
+                }).catch(() => { this.fence(); });
+            }
+            else
+                this.nextChallenge = this.now() + 3000;
+            return;
+        }
+        this.fence();
+    }
+    tick() {
+        if (this.phase === 'finished')
+            return;
+        if ((this.phase === 'running' || this.phase === 'resuming') && this.now() >= this.deadline)
+            this.fence();
+        if (this.phase === 'running' && this.now() >= this.nextChallenge)
+            this.challenge();
+        if (this.phase === 'fenced' && this.now() >= this.nextInspect)
+            this.quiesce();
+    }
+    fence() { if (this.phase === 'finished')
+        return; this.phase = 'fenced'; this.pending = undefined; this.nextChallenge = Infinity; this.quiesce(); }
+    active() { if (this.phase === 'fenced' || this.phase === 'finished')
+        return false; if (this.now() >= this.deadline) {
+        this.fence();
+        return false;
+    } return true; }
+    challenge() { if (this.pending || !this.active())
+        return; this.nextChallenge = Infinity; this.pending = { id: (0, crypto_1.randomUUID)(), at: this.now() }; this.send({ type: 'challenge', id: this.pending.id }); }
+    send(packet) { try {
+        this.emit(packet);
+    }
+    catch {
+        this.fence();
+    } }
+    unverified() { if (this.reported)
+        return; this.reported = true; this.send({ type: 'unverified' }); }
+    quiesce() {
+        if (!this.attached || this.stopping || this.phase === 'finished')
+            return;
+        this.stopping = Promise.resolve().then(async () => {
+            await this.startup;
+            let state = await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(this.binding, this.identity.scope, this.docker);
+            if (state === 'running') {
+                try {
+                    await this.docker(['container', 'pause', this.binding.containerId]);
+                }
+                catch {
+                    this.uncertainty = true;
+                    throw Error();
+                }
+                state = await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(this.binding, this.identity.scope, this.docker);
+            }
+            // A stopped namespace cannot be restarted by a delayed pause/unpause.
+            if (state === 'running' || (state === 'paused' && this.uncertainty)) {
+                this.unverified();
+                return;
+            }
+            const proof = Object.freeze({ capacityId: this.binding.capacityId, containerId: this.binding.containerId, attemptId: this.identity.attemptId, state, observedAt: new Date().toISOString() });
+            this.phase = 'finished';
+            this.resolve(proof);
+            this.send({ type: 'stopped', proof });
+        }).catch(() => { this.unverified(); }).finally(() => { this.stopping = undefined; this.nextInspect = this.now() + 1000; });
+    }
+}
+exports.EntityboxApplicationGuardCore = EntityboxApplicationGuardCore;

package/dist/entitybox-application-guard-process.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entitybox-application-guard-process.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const entitybox_application_guard_core_1 = require("./entitybox-application-guard-core");
+const entitybox_host_process_1 = require("./entitybox-host-process");
+const entitybox_recovery_store_1 = require("./entitybox-recovery-store");
+// Only the native host starts this child. No RPC token, pairing, provider key,
+// Docker socket or guard IPC channel enters the application container.
+if (!process.send)
+    process.exit(78);
+const exec = (0, util_1.promisify)(child_process_1.execFile);
+let core, configured = false;
+const timer = setInterval(() => core?.tick(), 50);
+const startup = setTimeout(() => { if (!configured)
+    process.exit(78); }, 10000);
+function fence() { if (core)
+    core.fence();
+else
+    process.exit(78); }
+function send(packet) { if (process.connected)
+    process.send?.(packet, error => { if (error)
+        fence(); });
+else
+    fence(); }
+process.on('message', async (packet) => {
+    try {
+        if (Buffer.byteLength(JSON.stringify(packet)) > 16000)
+            throw Error();
+        if (!configured) {
+            const p = packet;
+            if (p?.type !== 'configure' || !/^[-a-zA-Z0-9_.]{1,80}$/.test(p.context))
+                throw Error();
+            configured = true;
+            clearTimeout(startup);
+            const docker = async (args) => {
+                // Mutations are never killed at an observation deadline. The guard
+                // joins the actual CLI lifecycle; any failed reply poisons reuse.
+                const mutation = ['pause', 'unpause'].includes(args[1]);
+                return (await exec('docker', ['--context', p.context, ...args], { windowsHide: true, ...(mutation ? {} : { timeout: 5000 }), maxBuffer: 1024 * 1024 })).stdout.trim();
+            };
+            let emit = send;
+            if (p.recovery) {
+                const store = new entitybox_recovery_store_1.EntityboxRecoveryStore(p.recovery.directory), guard = await (0, entitybox_host_process_1.readEntityboxHostProcess)();
+                if (store.hostId !== p.recovery.hostId || !guard)
+                    throw Error();
+                const host = (0, entitybox_recovery_store_1.parseEntityboxRecoveryHost)({ hostId: store.hostId, dockerContext: p.context, controller: p.recovery.controller, guard });
+                emit = (packet) => {
+                    const event = packet;
+                    if (event?.type === 'stopped') {
+                        // Core has joined every mutation and becomes permanently finished
+                        // BEFORE emitting. Durable publication precedes any IPC receipt.
+                        try {
+                            store.writeProof({ version: 1, host, identity: p.identity, application: p.binding, proof: event.proof });
+                        }
+                        catch {
+                            send({ type: 'unverified' });
+                            return;
+                        }
+                    }
+                    send(event?.type === 'ready' ? { ...event, process: guard } : packet);
+                };
+            }
+            if (!process.connected)
+                throw Error();
+            core = new entitybox_application_guard_core_1.EntityboxApplicationGuardCore(p.identity, p.binding, docker, emit);
+            void core.finished.then(() => { clearInterval(timer); if (process.connected)
+                process.disconnect(); });
+            void core.start().catch(() => { send({ type: 'unverified' }); clearInterval(timer); if (process.connected)
+                process.disconnect(); });
+            return;
+        }
+        core?.message(packet);
+    }
+    catch {
+        fence();
+    }
+});
+process.on('disconnect', fence);
+process.on('SIGTERM', fence);
+process.on('SIGINT', fence);
+process.on('uncaughtException', fence);
+process.on('unhandledRejection', fence);

package/dist/entitybox-application-guard.d.ts

@@ -0,0 +1,46 @@
+import { type EntityboxExecutionLease } from './entitybox-execution-lease';
+import { type EntityboxApplicationBinding, type EntityboxApplicationQuiescence } from './entitybox-application-boundary';
+import { type EntityboxRecoveryStore } from './entitybox-recovery-store';
+/** Host-side handle. Production adapters must retain this owner until stop
+ * proof and child exit settle. A disappeared guard never grants reuse. */
+export declare class EntityboxApplicationGuard {
+    private readonly lease;
+    readonly binding: Readonly<EntityboxApplicationBinding>;
+    private readonly proc;
+    private readonly context;
+    private readonly requireInventory;
+    private readonly recovery?;
+    readonly processId: number;
+    readonly closed: Promise<void>;
+    private readonly ready;
+    private readonly started;
+    private readonly stopped;
+    private readyResolve;
+    private readyReject;
+    private startResolve;
+    private startReject;
+    private stopResolve;
+    private stopReject;
+    private proof?;
+    private guardIdentity?;
+    private used;
+    private closing;
+    private didClose;
+    private stopping?;
+    private abort;
+    private constructor();
+    static attach(lease: EntityboxExecutionLease, binding: EntityboxApplicationBinding, options?: {
+        dockerContext?: string;
+        requireInventory?: boolean;
+        recoveryStore?: EntityboxRecoveryStore;
+        onOwner?: (owner: EntityboxApplicationGuard) => void;
+    }): Promise<EntityboxApplicationGuard>;
+    resume(): Promise<void>;
+    pauseAndVerify(): Promise<EntityboxApplicationQuiescence>;
+    private docker;
+    private emergencyPause;
+    private send;
+    private message;
+    private grant;
+    private deadline;
+}