@jini-ai/daemon 0.5.2 → 0.5.4

package/dist/read-only-tools.d.ts

@@ -1,130 +1,2 @@
-import { type Principal, type ToolRegistry } from '@jini-ai/core';
-import type { ToolExecutor } from './tool-executor.js';
-import type { IdGenerator } from '@jini-ai/core/primitives';
-/**
- * A `Principal` narrowed to tools that only read.
- *
- * An HTTP route preflight only ever validates the OUTER `toolId` — the one the caller
- * named in the HTTP request. It cannot see what a consumer's own `ToolExecutor` composition does
- * once `bridge.execute()` hands control to `deps.toolExecutor`: a decorator that composition
- * stacks on top of the bare executor (a recovery loop that retries through a different tool id
- * after a failure, for instance) can dispatch a tool the caller never named, using the exact same
- * `principal` the outer call carried — one hop past the only check the HTTP route ever ran. Adding a
- * second request-shaped flag would not close that gap either: it would have to be threaded, by
- * hand, through every decorator between here and the handler, and a decorator that forgot would
- * fail open silently. `principal` is the one value every layer already passes unchanged, so the
- * constraint travels as an ATTENUATED IDENTITY instead — a principal permitted to invoke only
- * read-only tools, checkable by {@link refuseNonReadOnlyDispatch} at any depth a consumer's own
- * composition cares to ask.
- *
- * A distinct field rather than a `Principal.roles` entry: `roles` is what a `ToolPolicy` branches
- * on, and a synthetic role would silently join that decision for every registration in the
- * process. This field is inert to everything except {@link refuseNonReadOnlyDispatch}.
- */
-export interface ReadOnlyConstrainedPrincipal extends Principal {
-    readonly toolAccess: 'read-only';
-}
-/**
- * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
- * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
- * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
- */
-export declare const defaultDaemonMessages: {
-    readOnly: {
-        unverifiableMessage: string;
-        toolRefusalMessage: ({ toolId }: {
-            toolId: string;
-        }) => string;
-    };
-};
-/** Required host wording; absent metadata is always a refusal. */
-export interface ReadOnlyToolMessages {
-    readonly unverifiableMessage: string;
-    toolRefusalMessage(required: {
-        toolId: string;
-    }): string;
-}
-export interface ReadOnlyToolCheckRequired {
-    readonly toolId: string;
-    readonly registry: Pick<ToolRegistry, 'list'> | undefined;
-    readonly messages: ReadOnlyToolMessages;
-}
-export interface ReadOnlyToolConstraintRequired {
-    readonly inner: ToolExecutor;
-    readonly registry: Pick<ToolRegistry, 'list'> | undefined;
-    readonly idGenerator: IdGenerator;
-    readonly messages: ReadOnlyToolMessages;
-}
-/** @returns A copied, attenuated principal; its roles are unchanged. */
-export declare function constrainPrincipalToReadOnlyTools({ principal }: {
-    principal: Principal;
-}, _optional?: Record<string, never>): ReadOnlyConstrainedPrincipal;
-/** @returns Whether attenuation survived the executor/decorator boundary. */
-export declare function principalIsReadOnlyConstrained({ principal }: {
-    principal: Principal;
-}, _optional?: Record<string, never>): boolean;
-/** @returns Required host wording for an unknown or non-read-only tool. */
-export declare function readOnlyToolRefusalMessage({ toolId, messages }: {
-    toolId: string;
-    messages: ReadOnlyToolMessages;
-}, _optional?: Record<string, never>): string;
-/**
- * Single read-only registration decision, shared by routes and inner dispatch.
- * @returns Null for an explicitly read-only registration, otherwise host refusal text.
- */
-export declare function checkReadOnlyTool({ toolId, registry, messages }: ReadOnlyToolCheckRequired, _optional?: Record<string, never>): string | null;
-/**
- * THE read-only dispatch decision for any tool id a consumer's own `ToolExecutor` composition is
- * about to invoke — the outer call the route already checked, or a nested one a decorator issues
- * one or more hops in. Every consumer's own composition should ask this before dispatching on
- * behalf of a principal it did not itself resolve; none should re-implement the check, so changing
- * what the constraint means stays one edit.
- *
- * @param required.principal - The principal the dispatch would run under. Unconstrained ⇒ always
- *   `null` — this is a no-op for every pre-existing caller that never attenuates a principal.
- * @param required.toolId - The id actually about to be dispatched, which is not necessarily the id
- *   named in the original request — that difference is the whole reason this function exists.
- * @param required.registry - Descriptors to resolve `toolId` against; `undefined` ⇒ refuse (an
- *   unverifiable constrained dispatch is refused, never waived, matching `checkReadOnlyTool`).
- * @returns `null` when the dispatch may proceed, otherwise the refusal text to report.
- * @complexity O(1) for an unconstrained principal; O(n) in registered tool count for a constrained
- *   one, since `ToolRegistry` exposes enumeration rather than lookup by id.
- */
-export declare function refuseNonReadOnlyDispatch(required: ReadOnlyToolCheckRequired & {
-    readonly principal: Principal;
-}, _optional?: Record<string, never>): string | null;
-/** @returns Caller-formatted recovery refusal, preserving the original refusal verbatim as input. */
-export declare function readOnlyRemedyRefusalMessage({ refusal, formatMessage }: {
-    refusal: string;
-    formatMessage: (required: {
-        refusal: string;
-    }) => string;
-}, _optional?: Record<string, never>): string;
-/**
- * Wraps `inner` so a read-only-constrained principal (one {@link constrainPrincipalToReadOnlyTools}
- * attenuated) cannot dispatch a tool that isn't registered read-only — whichever layer chose the
- * id. This is what turns the attenuation into an actual gate rather than a field nobody reads:
- * {@link refuseNonReadOnlyDispatch} is the decision, this is its enforcement point.
- *
- * **Compose this as close to the bare `ToolExecutor` as your own stack allows** — directly around
- * `@jini-ai/daemon`'s `createToolExecutor` output, beneath any decorator of your own that might
- * dispatch a tool id the caller never named (a retry, a recovery loop that calls a different tool
- * as a remedy, ...). Every such decorator's own `inner.execute` call still has to come through here
- * to reach a handler, which is what makes this a gate on the CLASS of defect (an unnamed nested
- * dispatch) rather than on one instance of it.
- *
- * `delegatedToolExecuteRoute`'s own `handle` additionally composes this around whatever
- * `ToolExecutor` a host supplies, whenever a call attenuates its principal. That outer composition
- * only re-covers the SAME outer `toolId` the route preflight already checked — it
- * cannot see a nested dispatch a host's own inner decorator issues, because that decorator holds a
- * reference to whatever `ToolExecutor` IT was built with, not to the HTTP route's wrapped one. Closing
- * the nested case for a given host's stack requires that host to compose this decorator itself,
- * innermost, in its own `ToolExecutor` construction — this export exists so it can, without having
- * to rediscover or reimplement the mechanism.
- *
- * @returns A drop-in `ToolExecutor`; `resumeConfirmation`/`cancel`/`getAuditRecord` delegate
- *   straight through.
- * @complexity One extra property read per unconstrained call; one registry scan per constrained one.
- */
-export declare function withReadOnlyToolConstraint({ inner, registry, idGenerator, messages }: ReadOnlyToolConstraintRequired, _optional?: Record<string, never>): ToolExecutor;
+export * from './core/read-only-tools.js';
 //# sourceMappingURL=read-only-tools.d.ts.map

package/dist/read-only-tools.js

@@ -1,115 +1,3 @@
-import { isReadOnlyTool } from '@jini-ai/core';
-/**
- * Default daemon refusal wording, replaceable by the host. Unknown registrations and writes share
- * one refusal: neither corroborates a safe read, and catalog discovery already reveals existence.
- * Missing verification metadata always refuses, naming the missing wiring so the host can fix it.
- */
-export const defaultDaemonMessages = {
-    readOnly: {
-        unverifiableMessage: 'this host cannot verify read-only tools — POST /api/delegated-tool-calls was mounted without DelegatedToolsHttpDeps.toolRegistry, so a requireReadOnly call cannot be checked and is refused',
-        toolRefusalMessage: ({ toolId }) => `tool "${toolId}" is not registered as read-only — this gateway executes only tools whose registration declares readOnly; call it through execute_delegated_tool instead`,
-    },
-};
-/** @returns A copied, attenuated principal; its roles are unchanged. */
-export function constrainPrincipalToReadOnlyTools({ principal }, _optional = {}) {
-    return { ...principal, toolAccess: 'read-only' };
-}
-// Read structurally so passing through layers typed as the base Principal cannot erase the
-// execution's authority constraint.
-/** @returns Whether attenuation survived the executor/decorator boundary. */
-export function principalIsReadOnlyConstrained({ principal }, _optional = {}) {
-    return 'toolAccess' in principal && principal.toolAccess === 'read-only';
-}
-/** @returns Required host wording for an unknown or non-read-only tool. */
-export function readOnlyToolRefusalMessage({ toolId, messages }, _optional = {}) {
-    return messages.toolRefusalMessage({ toolId });
-}
-// Unknown registrations and omitted read-only classification both lack evidence of safety.
-// Every dispatch/preflight consults this decision; recovery preflight prevents asking a human
-// for form input that the innermost gate would refuse after submission.
-/**
- * Single read-only registration decision, shared by routes and inner dispatch.
- * @returns Null for an explicitly read-only registration, otherwise host refusal text.
- */
-export function checkReadOnlyTool({ toolId, registry, messages }, _optional = {}) {
-    if (registry === undefined)
-        return messages.unverifiableMessage;
-    const descriptor = registry.list({}).find((candidate) => candidate.id === toolId);
-    if (isReadOnlyTool({ descriptor }))
-        return null;
-    return readOnlyToolRefusalMessage({ toolId, messages });
-}
-/**
- * THE read-only dispatch decision for any tool id a consumer's own `ToolExecutor` composition is
- * about to invoke — the outer call the route already checked, or a nested one a decorator issues
- * one or more hops in. Every consumer's own composition should ask this before dispatching on
- * behalf of a principal it did not itself resolve; none should re-implement the check, so changing
- * what the constraint means stays one edit.
- *
- * @param required.principal - The principal the dispatch would run under. Unconstrained ⇒ always
- *   `null` — this is a no-op for every pre-existing caller that never attenuates a principal.
- * @param required.toolId - The id actually about to be dispatched, which is not necessarily the id
- *   named in the original request — that difference is the whole reason this function exists.
- * @param required.registry - Descriptors to resolve `toolId` against; `undefined` ⇒ refuse (an
- *   unverifiable constrained dispatch is refused, never waived, matching `checkReadOnlyTool`).
- * @returns `null` when the dispatch may proceed, otherwise the refusal text to report.
- * @complexity O(1) for an unconstrained principal; O(n) in registered tool count for a constrained
- *   one, since `ToolRegistry` exposes enumeration rather than lookup by id.
- */
-export function refuseNonReadOnlyDispatch(required, _optional = {}) {
-    if (!principalIsReadOnlyConstrained({ principal: required.principal }))
-        return null;
-    return checkReadOnlyTool(required);
-}
-// Report the original failure alongside the refused remedy; silently hiding an automatic
-// recovery attempt would mislead the caller even when the constraint correctly prevents writes.
-/** @returns Caller-formatted recovery refusal, preserving the original refusal verbatim as input. */
-export function readOnlyRemedyRefusalMessage({ refusal, formatMessage }, _optional = {}) {
-    return formatMessage({ refusal });
-}
-// A route can validate the caller's read-only tool and still miss a recovery decorator choosing
-// a writing remedy afterward. Enforce on every actual dispatch at the innermost executor to
-// close that class of authority laundering, including dispatchers introduced later.
-/**
- * Wraps `inner` so a read-only-constrained principal (one {@link constrainPrincipalToReadOnlyTools}
- * attenuated) cannot dispatch a tool that isn't registered read-only — whichever layer chose the
- * id. This is what turns the attenuation into an actual gate rather than a field nobody reads:
- * {@link refuseNonReadOnlyDispatch} is the decision, this is its enforcement point.
- *
- * **Compose this as close to the bare `ToolExecutor` as your own stack allows** — directly around
- * `@jini-ai/daemon`'s `createToolExecutor` output, beneath any decorator of your own that might
- * dispatch a tool id the caller never named (a retry, a recovery loop that calls a different tool
- * as a remedy, ...). Every such decorator's own `inner.execute` call still has to come through here
- * to reach a handler, which is what makes this a gate on the CLASS of defect (an unnamed nested
- * dispatch) rather than on one instance of it.
- *
- * `delegatedToolExecuteRoute`'s own `handle` additionally composes this around whatever
- * `ToolExecutor` a host supplies, whenever a call attenuates its principal. That outer composition
- * only re-covers the SAME outer `toolId` the route preflight already checked — it
- * cannot see a nested dispatch a host's own inner decorator issues, because that decorator holds a
- * reference to whatever `ToolExecutor` IT was built with, not to the HTTP route's wrapped one. Closing
- * the nested case for a given host's stack requires that host to compose this decorator itself,
- * innermost, in its own `ToolExecutor` construction — this export exists so it can, without having
- * to rediscover or reimplement the mechanism.
- *
- * @returns A drop-in `ToolExecutor`; `resumeConfirmation`/`cancel`/`getAuditRecord` delegate
- *   straight through.
- * @complexity One extra property read per unconstrained call; one registry scan per constrained one.
- */
-export function withReadOnlyToolConstraint({ inner, registry, idGenerator, messages }, _optional = {}) {
-    return {
-        execute: async (requiredArgs, optionalArgs = {}) => {
-            const { principal, toolId } = requiredArgs;
-            const refusal = refuseNonReadOnlyDispatch({ principal, toolId, registry, messages });
-            // Deny before inner: no handler or kernel audit record exists. Use the authorization result
-            // union instead of throwing, and mint a denial ID because there is no inner execution ID.
-            if (refusal !== null)
-                return { executionId: idGenerator.newId(), status: 'denied', error: refusal };
-            return inner.execute(requiredArgs, optionalArgs);
-        },
-        resumeConfirmation: (requiredArgs) => inner.resumeConfirmation(requiredArgs),
-        cancel: (requiredArgs) => inner.cancel(requiredArgs),
-        getAuditRecord: (requiredArgs) => inner.getAuditRecord(requiredArgs),
-    };
-}
+// Compatibility path; the shared implementation lives in core.
+export * from './core/read-only-tools.js';
 //# sourceMappingURL=read-only-tools.js.map

package/dist/run-credentials.d.ts

@@ -3,60 +3,70 @@ export interface RunScopedCaller {
     readonly principalId: string;
 }
 export interface CredentialCryptoPort {
-    mintToken(args: Record<string, never>): string;
+    mintToken(args: Record<string, never>, optional?: Record<string, never>): string;
     digest(args: {
         token: string;
-    }): string;
+    }, optional?: Record<string, never>): string;
     tokensMatch(args: {
         presented: string;
         expected: string;
-    }): boolean;
+    }, optional?: Record<string, never>): boolean;
 }
-/** Explicit Node adapter; consumers can inject an alternate crypto implementation. */
-export declare function createNodeCredentialCrypto(_args: Record<string, never>): CredentialCryptoPort;
+/** Explicit Node crypto adapter: 32 random bytes produce a 64-hex-character bearer.
+ * Length rejection reveals only that fixed public length; content matching is timing-safe.
+ * Consumers can inject an alternate implementation. */
+export declare function createNodeCredentialCrypto(_args: Record<string, never>, _optional?: Record<string, never>): CredentialCryptoPort;
 export interface RunScopedCallerResolver {
     resolveCaller(args: {
         token: string;
-    }): RunScopedCaller | undefined;
+    }, optional?: Record<string, never>): RunScopedCaller | undefined;
 }
+/** A bridge receives a per-run credential, never the proxy boot token: that token would let it
+ * assert another principal or start unrelated runs. Resolve identity server-side from the live
+ * principal on every call; terminal liveness revokes access even if explicit cleanup fails.
+ * Lookup keys are SHA-256 digests rather than raw bearer secrets. Restart drops the local store. */
 export interface RunScopedCredentials extends RunScopedCallerResolver {
+    /** Idempotent for a live run; refuses unknown/ended runs and empty or colliding tokens. */
     mint(args: {
         runId: string;
-    }): string;
+    }, optional?: Record<string, never>): string;
     resolvePrincipal(args: {
         token: string;
-    }): string | undefined;
+    }, optional?: Record<string, never>): string | undefined;
+    /** Idempotent cleanup to prevent map growth; liveness is checked independently. */
     revoke(args: {
         runId: string;
-    }): void;
+    }, optional?: Record<string, never>): void;
 }
 export declare function createRunScopedCredentials(deps: {
     principalOfLiveRun(args: {
         runId: string;
-    }): string | undefined;
+    }, optional?: Record<string, never>): string | undefined;
     crypto: Pick<CredentialCryptoPort, 'mintToken' | 'digest'>;
-}): RunScopedCredentials;
+}, _optional?: Record<string, never>): RunScopedCredentials;
+/** Preserve an operator token or mint one before spawning a child, which inherits env at spawn.
+ * Repeated calls must not rotate the value and invalidate a child that already received it. */
 export declare function ensureAgentDaemonToken({ env, envVarName, crypto }: {
     env: Record<string, string | undefined>;
     envVarName: string;
     crypto: Pick<CredentialCryptoPort, 'mintToken'>;
-}): string;
+}, _optional?: Record<string, never>): string;
 export interface RouteAccessPolicy {
     /** Return a URL-decoded run ID; malformed encoding must throw URIError. */
     targetRun(args: {
         path: string;
-    }): string | undefined;
+    }, optional?: Record<string, never>): string | undefined;
     allowsRunScoped(args: {
         method: string;
         path: string;
-    }): boolean;
+    }, optional?: Record<string, never>): boolean;
     isDelegatedCall(args: {
         method: string;
         path: string;
-    }): boolean;
+    }, optional?: Record<string, never>): boolean;
     isEventStream(args: {
         path: string;
-    }): boolean;
+    }, optional?: Record<string, never>): boolean;
 }
 /** Host supplies route names; this module owns matching and run isolation. */
 export declare function createRouteAccessPolicy({ runPathPrefix, delegatedToolCallsPath, eventStreamSuffix, allowedRoutes }: {
@@ -67,7 +77,7 @@ export declare function createRouteAccessPolicy({ runPathPrefix, delegatedToolCa
         method: string;
         path: RegExp;
     }[];
-}): RouteAccessPolicy;
+}, _optional?: Record<string, never>): RouteAccessPolicy;
 export type AccessDecision = {
     allowed: true;
     principalHeader?: {
@@ -80,6 +90,12 @@ export type AccessDecision = {
     body: unknown;
 };
 /** Transport-independent bearer gate. Apply principalHeader only after an allowed decision. */
+/** Loopback is not authentication: another local process can reach the daemon. No peer-address
+ * exemption is allowed. Missing configuration refuses service (503); bad credentials receive 401.
+ * Mount authentication before body parsing and ownership checks. Explicit path exemptions use
+ * exact equality and apply only without a credential; presenting one always opts into validation.
+ * A run bearer is bound to its run before route allowlisting and overwrites caller identity.
+ * Mount the delegated-body gate after parsing so body.runId must also match that credential. */
 export declare function authorizeDaemonRequest({ request, env, envVarName, principalHeaderName, authorizationHeaderName, crypto, routes }: {
     request: {
         method: string;
@@ -98,20 +114,26 @@ export declare function authorizeDaemonRequest({ request, env, envVarName, princ
     runScopedCallers?: RunScopedCallerResolver;
     validateDelegatedRunId?: boolean;
 }): AccessDecision;
+/** Ownership survives terminal transition until the run record expires; live-principal mappings
+ * instead end with execution. Keep ownership in the run-owning process so lifetimes cannot drift. */
 export interface RunOwnerRegistry {
     record(args: {
         runId: string;
         principalId: string;
-    }): void;
+    }, optional?: Record<string, never>): void;
     ownerOf(args: {
         runId: string;
-    }): string | undefined;
+    }, optional?: Record<string, never>): string | undefined;
     forget(args: {
         runId: string;
-    }): void;
+    }, optional?: Record<string, never>): void;
 }
-export declare function createRunOwnerRegistry(_args: Record<string, never>): RunOwnerRegistry;
+export declare function createRunOwnerRegistry(_args: Record<string, never>, _optional?: Record<string, never>): RunOwnerRegistry;
 /** Mount after the bearer gate; principalId must be server verified. */
+/** Trust principal headers only downstream of the bearer gate. Missing identity fails closed.
+ * Non-owners receive the exact unknown-run response (including the JSON/SSE distinction), so
+ * refusal cannot confirm existence. An existing unowned run or failed lookup also denies; only
+ * a genuinely absent run passes to the route for its own 404. */
 export declare function authorizeRunOwnership({ runId, principalId, principalHeaderName, registry, runExists, eventStream }: {
     runId: string | undefined;
     principalId: string | undefined;
@@ -121,7 +143,9 @@ export declare function authorizeRunOwnership({ runId, principalId, principalHea
         runId: string;
     }) => Promise<boolean>;
     eventStream: boolean;
-}): Promise<AccessDecision>;
+}, _optional?: Record<string, never>): Promise<AccessDecision>;
+/** Shadow an unscoped run list with this owner-filtered view: exposing ids would make another
+ * principal's runs enumerable. Omit unowned records and refuse a missing principal. */
 export declare function listOwnedRuns<Run extends {
     id: string;
 }>({ runs, registry, principalId, principalHeaderName }: {
@@ -129,7 +153,7 @@ export declare function listOwnedRuns<Run extends {
     registry: RunOwnerRegistry;
     principalId: string | undefined;
     principalHeaderName: string;
-}): {
+}, _optional?: Record<string, never>): {
     allowed: true;
     runs: Run[];
 } | Exclude<AccessDecision, {

package/dist/run-credentials.js

@@ -1,7 +1,9 @@
 import { timingSafeTokenMatch } from '@jini-ai/core';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-/** Explicit Node adapter; consumers can inject an alternate crypto implementation. */
-export function createNodeCredentialCrypto(_args) {
+/** Explicit Node crypto adapter: 32 random bytes produce a 64-hex-character bearer.
+ * Length rejection reveals only that fixed public length; content matching is timing-safe.
+ * Consumers can inject an alternate implementation. */
+export function createNodeCredentialCrypto(_args, _optional = {}) {
     return {
         mintToken: () => randomBytes(32).toString('hex'),
         digest: ({ token }) => createHash('sha256').update(token, 'utf8').digest('hex'),
@@ -10,7 +12,7 @@ export function createNodeCredentialCrypto(_args) {
         },
     };
 }
-export function createRunScopedCredentials(deps) {
+export function createRunScopedCredentials(deps, _optional = {}) {
     const runByDigest = new Map();
     const tokens = new Map();
     const resolveCaller = ({ token }) => {
@@ -46,7 +48,9 @@ export function createRunScopedCredentials(deps) {
         },
     };
 }
-export function ensureAgentDaemonToken({ env, envVarName, crypto }) {
+/** Preserve an operator token or mint one before spawning a child, which inherits env at spawn.
+ * Repeated calls must not rotate the value and invalidate a child that already received it. */
+export function ensureAgentDaemonToken({ env, envVarName, crypto }, _optional = {}) {
     const existing = env[envVarName];
     if (typeof existing === 'string' && existing.length > 0)
         return existing;
@@ -57,7 +61,7 @@ export function ensureAgentDaemonToken({ env, envVarName, crypto }) {
     return token;
 }
 /** Host supplies route names; this module owns matching and run isolation. */
-export function createRouteAccessPolicy({ runPathPrefix, delegatedToolCallsPath, eventStreamSuffix, allowedRoutes }) {
+export function createRouteAccessPolicy({ runPathPrefix, delegatedToolCallsPath, eventStreamSuffix, allowedRoutes }, _optional = {}) {
     return {
         targetRun({ path }) {
             // Binding is case insensitive as in the original gate, while the allowlist remains exact.
@@ -80,6 +84,12 @@ function notFound(runId, stream) {
     return { allowed: false, status: 404, body: { error: { code: 'NOT_FOUND', message: stream ? 'run was not found' : `run "${runId}" was not found` } } };
 }
 /** Transport-independent bearer gate. Apply principalHeader only after an allowed decision. */
+/** Loopback is not authentication: another local process can reach the daemon. No peer-address
+ * exemption is allowed. Missing configuration refuses service (503); bad credentials receive 401.
+ * Mount authentication before body parsing and ownership checks. Explicit path exemptions use
+ * exact equality and apply only without a credential; presenting one always opts into validation.
+ * A run bearer is bound to its run before route allowlisting and overwrites caller identity.
+ * Mount the delegated-body gate after parsing so body.runId must also match that credential. */
 export function authorizeDaemonRequest({ request, env, envVarName, principalHeaderName, authorizationHeaderName, crypto, routes }, { exemptPaths = [], runScopedCallers, validateDelegatedRunId = false } = {}) {
     const authorization = request.headers[authorizationHeaderName];
     if (exemptPaths.includes(request.path) && authorization === undefined)
@@ -115,7 +125,7 @@ export function authorizeDaemonRequest({ request, env, envVarName, principalHead
     }
     return { allowed: true, principalHeader: { name: principalHeaderName, value: caller.principalId } };
 }
-export function createRunOwnerRegistry(_args) {
+export function createRunOwnerRegistry(_args, _optional = {}) {
     const owners = new Map();
     return {
         record: ({ runId, principalId }) => { owners.set(runId, principalId); },
@@ -127,7 +137,11 @@ function principalRequired(principalHeaderName) {
     return { allowed: false, status: 401, body: { error: { code: 'UNAUTHENTICATED', message: `${principalHeaderName} is required on run-scoped requests` } } };
 }
 /** Mount after the bearer gate; principalId must be server verified. */
-export async function authorizeRunOwnership({ runId, principalId, principalHeaderName, registry, runExists, eventStream }) {
+/** Trust principal headers only downstream of the bearer gate. Missing identity fails closed.
+ * Non-owners receive the exact unknown-run response (including the JSON/SSE distinction), so
+ * refusal cannot confirm existence. An existing unowned run or failed lookup also denies; only
+ * a genuinely absent run passes to the route for its own 404. */
+export async function authorizeRunOwnership({ runId, principalId, principalHeaderName, registry, runExists, eventStream }, _optional = {}) {
     if (!principalId)
         return principalRequired(principalHeaderName);
     if (!runId)
@@ -144,7 +158,9 @@ export async function authorizeRunOwnership({ runId, principalId, principalHeade
     catch { /* Unknown ownership fails closed on lookup failure. */ }
     return exists ? notFound(runId, eventStream) : { allowed: true };
 }
-export function listOwnedRuns({ runs, registry, principalId, principalHeaderName }) {
+/** Shadow an unscoped run list with this owner-filtered view: exposing ids would make another
+ * principal's runs enumerable. Omit unowned records and refuse a missing principal. */
+export function listOwnedRuns({ runs, registry, principalId, principalHeaderName }, _optional = {}) {
     if (!principalId)
         return principalRequired(principalHeaderName);
     return { allowed: true, runs: runs.filter(run => registry.ownerOf({ runId: run.id }) === principalId) };

package/dist/run-lifecycle.d.ts

@@ -15,7 +15,7 @@ export interface StartRunInput {
     readonly idempotencyKey?: string;
     /** Override the generated run id — test/fixture hook only. */
     readonly runId?: string;
-    /** When set, arms an inactivity watchdog that fails the run as a resumable failure if no `emit()` occurs within this window. */
+    /** When set, arms an inactivity watchdog that fails the run permanently if no `emit()` occurs within this window. */
     readonly inactivityTimeoutMs?: number;
 }
 export interface StartRunResult {

package/dist/run-lifecycle.js

@@ -450,10 +450,9 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
     }
     /**
      * Fires when a run's inactivity watchdog times out with no intervening
-     * `emit()`/`finish()`. Classified as a resumable failure (`code: null,
-     * signal: null`), mirroring OD's own timeout/inactivity classification
-     * (`isResumableFailure` in the researched `run-failure-classification.ts`
-     * treats timeout/inactivity as one of only two resumable categories).
+     * `emit()`/`finish()`. A deliberate watchdog kill is permanent: automatically restarting
+     * it would undo the operator's inactivity policy. Other unexpected process failures still
+     * retain their original runtime classification.
      *
      * The `!record || isTerminalRunState(...)` guard below is defensive only and is currently
      * unreachable through the public API — deliberately kept, not fake-tested, and the reason is
@@ -479,7 +478,9 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
             return;
         }
         try {
-            await lifecycle.finish({ runId, status: 'failed', code: null, signal: null, resumable: true });
+            // A deliberate inactivity kill is permanent for this attempt, not an auto-resume signal.
+            await lifecycle.emit({ runId, input: { event: 'agent', data: { type: 'status', label: 'Stopped by inactivity watchdog', detail: 'inactivity-watchdog' } } });
+            await lifecycle.finish({ runId, status: 'failed', code: null, signal: null, resumable: false });
         }
         catch (error) {
             const context = { source: 'inactivity-timeout', runId, error };

package/dist/scheduler.d.ts

@@ -5,4 +5,9 @@ export interface SchedulerPort {
         readonly callback: () => void;
     }): () => void;
 }
+/** Native host timers; an abandoned exchange must not keep a Node process alive by itself.
+ * Cancellation is idempotent, and scheduling never invokes the callback synchronously. */
+export declare function createTimeoutScheduler(_required: Record<string, never>, { keepAlive }?: {
+    readonly keepAlive?: boolean;
+}): SchedulerPort;
 //# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.js

@@ -1,2 +1,14 @@
-export {};
+/** Native host timers; an abandoned exchange must not keep a Node process alive by itself.
+ * Cancellation is idempotent, and scheduling never invokes the callback synchronously. */
+export function createTimeoutScheduler(_required, { keepAlive = false } = {}) {
+    return {
+        schedule({ delayMs, callback }) {
+            const timer = setTimeout(callback, delayMs);
+            // Exchanges may be abandoned; active start gates must keep their timeout alive until settlement.
+            if (!keepAlive)
+                timer.unref?.();
+            return () => clearTimeout(timer);
+        },
+    };
+}
 //# sourceMappingURL=scheduler.js.map