@jini-ai/daemon 0.6.17 → 0.6.19

package/dist/http/terminals.js

@@ -25,6 +25,8 @@
  * - Adapts `deps.manager.attach`'s push/end sink to `sse.ts`'s generic SSE
  *   channel, the same way `runs.ts` adapts `RunLifecycle.stream`.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { TERMINAL_CREATE_TOOL_ID } from '../index.js';
 import { createApiError } from '@jini-ai/protocol';
@@ -38,7 +40,7 @@ import { isRecord, readOptionalNonEmptyString, readOptionalNumber, resolveResour
 import { err, ok } from '@jini-ai/http-kit';
 function defaultTerminalsInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /** Every one-off `terminal.create` tool call gets its own opaque `RunRef` — matching `db-ops.ts`'s `freshRun()`: these are single requests, not steps of a longer-lived agent run. */
 function freshRun() {

package/dist/http/tool-catalog.d.ts

@@ -36,6 +36,20 @@ export interface ToolCatalogEntry {
     readonly description: string;
     readonly inputSchema?: unknown;
     readonly source: string;
+    /**
+     * Set only on guidance entries that are not tools themselves (a retired-alias pointer, a
+     * namespace overview): every tool id the guidance points at. A read-only view shows guidance
+     * only when each target is a registered read-only tool, and hides guidance without targets.
+     */
+    readonly targetToolIds?: readonly string[];
+}
+/** Optional describe inputs. */
+export interface ToolCatalogDescribeOptions {
+    /**
+     * When set, the caller may use only these tool ids; guidance that lists tools (a namespace
+     * overview) should list only these. Never consulted for a registered tool's own entry.
+     */
+    readonly visibleToolIds?: ReadonlySet<string>;
 }
 /** Structurally identical to `@jini-ai/sqlite-chat`'s `searchToolCatalog`/`getToolCatalogEntry` — defined locally so this package incurs no `better-sqlite3` dependency. */
 export interface ToolCatalogQuery {
@@ -46,7 +60,7 @@ export interface ToolCatalogQuery {
     }) => readonly ToolCatalogSearchHit[];
     readonly describe: ({ id }: {
         readonly id: string;
-    }, _optional?: Record<string, never>) => ToolCatalogEntry | null;
+    }, optional?: ToolCatalogDescribeOptions) => ToolCatalogEntry | null;
 }
 export interface ToolCatalogHttpDeps {
     readonly catalog: ToolCatalogQuery;

package/dist/http/tool-execution-routes.d.ts

@@ -57,6 +57,8 @@ export interface ToolExecutionRoutesOptional {
     /** Defaults to {@link DEFAULT_TOOL_EXEC_MAX_BODY_BYTES}. */
     readonly maxBodyBytes?: number;
     readonly runWithContext?: RunWithToolContext;
+    /** Host-owned live-run/identity gate, after parsing and before either route dispatches. */
+    readonly authorizeRun?: RequestHandler;
 }
 /** The token + loopback gate; mounted before any body parser. Exported for hosts that need it on another path. */
 export declare function requireToolExecutionCaller(_required: Record<string, never>, { tokenEnvVar, env }?: Pick<ToolExecutionRoutesOptional, 'tokenEnvVar' | 'env'>): RequestHandler;
@@ -65,5 +67,5 @@ export declare function requireToolExecutionCaller(_required: Record<string, nev
  * `express.json()` with a smaller limit: this route parses its own body after its gate, and an
  * earlier parser would both buffer unauthenticated bodies and cap tool inputs at its own limit.
  */
-export declare function registerToolExecutionRoutes({ app, executor, listToolsFor }: ToolExecutionRoutesRequired, { tokenEnvVar, env, maxBodyBytes, runWithContext }?: ToolExecutionRoutesOptional): void;
+export declare function registerToolExecutionRoutes({ app, executor, listToolsFor }: ToolExecutionRoutesRequired, { tokenEnvVar, env, maxBodyBytes, runWithContext, authorizeRun }?: ToolExecutionRoutesOptional): void;
 //# sourceMappingURL=tool-execution-routes.d.ts.map

package/dist/http/tool-execution-routes.js

@@ -172,10 +172,11 @@ function catalogHandler({ listToolsFor }) {
  * `express.json()` with a smaller limit: this route parses its own body after its gate, and an
  * earlier parser would both buffer unauthenticated bodies and cap tool inputs at its own limit.
  */
-export function registerToolExecutionRoutes({ app, executor, listToolsFor }, { tokenEnvVar, env, maxBodyBytes = DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, runWithContext } = {}) {
+export function registerToolExecutionRoutes({ app, executor, listToolsFor }, { tokenEnvVar, env, maxBodyBytes = DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, runWithContext, authorizeRun } = {}) {
     const gate = requireToolExecutionCaller({}, { ...(tokenEnvVar === undefined ? {} : { tokenEnvVar }), ...(env === undefined ? {} : { env }) });
     const parser = express.json({ limit: maxBodyBytes });
-    app.post(TOOL_EXECUTIONS_ROUTE_PATH, gate, parser, executionHandler({ executor }, runWithContext === undefined ? {} : { runWithContext }), bodyParserFailure);
-    app.get(TOOL_CATALOG_ROUTE_PATH, gate, catalogHandler({ listToolsFor }));
+    const runGate = authorizeRun ? [authorizeRun] : [];
+    app.post(TOOL_EXECUTIONS_ROUTE_PATH, gate, parser, ...runGate, executionHandler({ executor }, runWithContext === undefined ? {} : { runWithContext }), bodyParserFailure);
+    app.get(TOOL_CATALOG_ROUTE_PATH, gate, ...runGate, catalogHandler({ listToolsFor }));
 }
 //# sourceMappingURL=tool-execution-routes.js.map

package/dist/http/xai.js

@@ -1,4 +1,3 @@
-import { redactSecrets } from '@jini-ai/core';
 /**
  * @module xai
  *
@@ -117,6 +116,8 @@ import { redactSecrets } from '@jini-ai/core';
  *    `@jini-ai/agent-runtime`'s already-shipped generic module, outside this file's own scope to alter
  *    without special-casing one provider's capitalization inside otherwise-generic code.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { beginOAuthPkce, clearStoredOAuthToken, completeOAuthPkce, getStoredOAuthToken, PendingAuthCache, resolveOAuthBearer, setStoredOAuthToken, startOAuthCallbackListener, validateBaseUrl, XAI_OAUTH_PROVIDER_CONFIG, XAI_OAUTH_REDIRECT_HOST, XAI_OAUTH_REDIRECT_PATH, XAI_OAUTH_REDIRECT_PORT, } from '@jini-ai/agent-runtime';
 import { createApiError } from '@jini-ai/protocol';
@@ -137,7 +138,7 @@ const DEFAULT_SEARCH_MODEL = 'grok-4.20-reasoning';
 const DEFAULT_SEARCH_TIMEOUT_MS = 30_000;
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
-    console.error(`[@jini-ai/http-kit] internal error (xai/${context.source}, correlationId=${context.correlationId})`, context.error);
+    console.error(`[@jini-ai/http-kit] internal error (xai/${context.source}, correlationId=${context.correlationId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
 }
 /** Resolves every optional `XaiHttpDeps` field to a concrete value. Idempotent — calling this again on an already-resolved object (e.g. `registerXaiRoutes`'s own single resolution, passed through to each route's `handle`) is a harmless pass-through. See module doc on why stateful fields (`pending`/`listenerRef`) must be resolved once per registration, not once per request. */
 function resolveXaiHttpDeps(deps) {

package/dist/idle-monitor.d.ts

@@ -0,0 +1,29 @@
+import type { Clock } from '@jini-ai/core/primitives';
+import type { SchedulerPort } from './scheduler.js';
+/** A one-shot observation lifecycle; stopping permanently cancels further observations. */
+export interface IdleMonitor {
+    /** Idempotent; callbacks queued before cancellation become harmless. */
+    stop(): void;
+    /** Hold busy state through asynchronous work. Null means intake is fenced; releases are idempotent. */
+    acquire(required: Record<string, never>, optional?: Record<string, never>): (() => void) | null;
+}
+/**
+ * Observe host busy state immediately, scheduling polls at most 1s ahead; fire once after a full
+ * observed idle interval. Busy observations discard idle credit; the next idle
+ * observation starts a new interval. acquire() also records activity between observations.
+ * @param input Injected synchronous busy predicate, finite positive idleMs, clock and scheduler.
+ * @param options onIdle runs synchronously after the monitor has stopped; its errors propagate.
+ * @returns A permanent, idempotent stop handle. Owns at most one scheduled callback.
+ * @throws RangeError for a non-positive or non-finite idleMs, before scheduling.
+ * @complexity O(1) time per observation and O(1) retained space.
+ * @example createIdleMonitor({ isBusy, idleMs: 900_000, clock, scheduler }, { onIdle });
+ */
+export declare function createIdleMonitor({ isBusy, idleMs, clock, scheduler }: {
+    readonly isBusy: () => boolean;
+    readonly idleMs: number;
+    readonly clock: Clock;
+    readonly scheduler: SchedulerPort;
+}, { onIdle }: {
+    readonly onIdle: () => void;
+}): IdleMonitor;
+//# sourceMappingURL=idle-monitor.d.ts.map

package/dist/idle-monitor.js

@@ -0,0 +1,64 @@
+/**
+ * Observe host busy state immediately, scheduling polls at most 1s ahead; fire once after a full
+ * observed idle interval. Busy observations discard idle credit; the next idle
+ * observation starts a new interval. acquire() also records activity between observations.
+ * @param input Injected synchronous busy predicate, finite positive idleMs, clock and scheduler.
+ * @param options onIdle runs synchronously after the monitor has stopped; its errors propagate.
+ * @returns A permanent, idempotent stop handle. Owns at most one scheduled callback.
+ * @throws RangeError for a non-positive or non-finite idleMs, before scheduling.
+ * @complexity O(1) time per observation and O(1) retained space.
+ * @example createIdleMonitor({ isBusy, idleMs: 900_000, clock, scheduler }, { onIdle });
+ */
+export function createIdleMonitor({ isBusy, idleMs, clock, scheduler }, { onIdle }) {
+    if (!Number.isFinite(idleMs) || idleMs <= 0) {
+        throw new RangeError('idleMs must be finite and positive');
+    }
+    let stopped = false;
+    let active = 0;
+    let idleSince;
+    let cancelPending;
+    const stop = () => {
+        stopped = true;
+        cancelPending?.();
+        cancelPending = undefined;
+    };
+    // The host owns parking; this callback only observes state and reports idle.
+    const observe = () => {
+        if (stopped)
+            return;
+        const now = clock.nowMs();
+        if (active > 0 || isBusy())
+            idleSince = undefined;
+        else
+            idleSince ??= now;
+        const remainingMs = idleSince === undefined ? idleMs : idleMs - (now - idleSince);
+        if (remainingMs <= 0) {
+            stop();
+            onIdle();
+            return;
+        }
+        cancelPending = scheduler.schedule({ delayMs: Math.min(1_000, remainingMs), callback: observe });
+    };
+    observe();
+    return {
+        stop,
+        acquire(_required, _optional = {}) {
+            if (stopped)
+                return null;
+            active++;
+            idleSince = undefined;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                active--;
+                // A sub-poll request is still activity. Start its idle credit at completion, not at
+                // the previous observation, so frequent short calls cannot trigger a premature park.
+                if (active === 0)
+                    idleSince = clock.nowMs();
+            };
+        },
+    };
+}
+//# sourceMappingURL=idle-monitor.js.map

package/dist/image-prompt-delivery.d.ts

@@ -22,7 +22,7 @@ export interface ImagePromptDelivery {
 export declare function augmentPromptWithImageAttachments({ prompt, imagePaths }: {
     readonly prompt: string;
     readonly imagePaths: readonly string[];
-}): string;
+}, _optional?: Record<string, never>): string;
 /**
  * Directories a 'prompt-path' def's CLI must be allowed to read from so it
  * can actually open the files the augmented prompt just told it about — the

package/dist/image-prompt-delivery.js

@@ -45,13 +45,14 @@ import path from 'node:path';
  * @complexity O(n) in the number of images — one line rendered per path, no I/O.
  * @overallScore 100
  */
-export function augmentPromptWithImageAttachments({ prompt, imagePaths }) {
+export function augmentPromptWithImageAttachments({ prompt, imagePaths }, _optional = {}) {
     const list = imagePaths.map((imagePath, index) => `${index + 1}. ${imagePath}`).join('\n');
     const plural = imagePaths.length === 1;
     return (`${prompt}\n\n---\n` +
         `The user attached the following image ${plural ? 'file' : 'files'} to this message. ` +
-        `${plural ? 'It is a' : 'These are'} real file${plural ? '' : 's'} on disk — read ${plural ? 'it' : 'each one'} directly ` +
-        `(e.g. with your file-reading tool) before responding:\n${list}`);
+        `${plural ? 'It is a' : 'These are'} real file${plural ? '' : 's'} on disk — read ${plural ? 'it' : 'each one'} ` +
+        `with the host attachment/image tool first, or your native Read/image tool for this supplied path. ` +
+        `Never use Bash, a shell command or a script to inspect attachments:\n${list}`);
 }
 /**
  * Directories a 'prompt-path' def's CLI must be allowed to read from so it

package/dist/index.d.ts

@@ -79,6 +79,7 @@
  */
 export * from './event-log.js';
 export * from './close-status.js';
+export * from './idle-monitor.js';
 export * from './run-lifecycle.js';
 export * from './ai-trace-lifecycle.js';
 export * from './tool-executor.js';

package/dist/index.js

@@ -79,6 +79,7 @@
  */
 export * from './event-log.js';
 export * from './close-status.js';
+export * from './idle-monitor.js';
 export * from './run-lifecycle.js';
 export * from './ai-trace-lifecycle.js';
 export * from './tool-executor.js';

package/dist/legacy-data-migration.js

@@ -16,6 +16,7 @@
  * connection opens, so it can't race a concurrent open of the destination.
  */
 import * as nodeFilesystem from 'node:fs';
+import { redactSecrets } from '@jini-ai/core';
 import * as path from 'node:path';
 const DEFAULT_MARKER_FILE = '.migrated-from';
 /**
@@ -254,7 +255,8 @@ function stagePromoteAndMark({ plan, markerFile, payloadEntries, writeMarker },
 export function migrateLegacyDataDirSync(requiredArgs, optionalArgs = {}) {
     const options = { ...requiredArgs, ...optionalArgs };
     const fs = options.filesystem ?? nodeFilesystem;
-    const log = options.logger ?? { info: ({ message }) => console.log(`[jini-migrate] ${message}`) };
+    // Paths and payload names are host input, so the default sink redacts the complete diagnostic.
+    const log = options.logger ?? { info: ({ message }) => console.log(redactSecrets({ input: `[jini-migrate] ${message}` }, { redactPii: false })) };
     const markerFile = options.markerFile ?? DEFAULT_MARKER_FILE;
     const plan = planMigration({ legacyDir: options.legacyDir, dataDir: options.dataDir, markerFile }, fs);
     if ('status' in plan)

package/dist/remote-attachment-lookup.d.ts

@@ -18,6 +18,8 @@ export interface RemoteAttachmentLookupRequired {
     readonly token: string;
 }
 export interface RemoteAttachmentLookupOptional {
+    /** Explicit authenticated mount prefix. Omitted preserves the historical origin-root route. */
+    readonly pathPrefix?: string;
     /** Injectable `node:http.request`. */
     readonly request?: typeof http.request;
 }
@@ -25,5 +27,5 @@ export interface RemoteAttachmentLookupOptional {
  * Creates the remote lookup.
  * @complexity One loopback round trip per call; O(response bytes).
  */
-export declare function createRemoteAttachmentLookup({ baseUrl, token }: RemoteAttachmentLookupRequired, { request }?: RemoteAttachmentLookupOptional): AttachmentLookup;
+export declare function createRemoteAttachmentLookup({ baseUrl, token }: RemoteAttachmentLookupRequired, { request, pathPrefix }?: RemoteAttachmentLookupOptional): AttachmentLookup;
 //# sourceMappingURL=remote-attachment-lookup.d.ts.map

package/dist/remote-attachment-lookup.js

@@ -56,8 +56,8 @@ function unwrap({ status, body }) {
  * Creates the remote lookup.
  * @complexity One loopback round trip per call; O(response bytes).
  */
-export function createRemoteAttachmentLookup({ baseUrl, token }, { request = http.request } = {}) {
-    const url = new URL(ATTACHMENT_LOOKUP_ROUTE_PATH, baseUrl);
+export function createRemoteAttachmentLookup({ baseUrl, token }, { request = http.request, pathPrefix = '' } = {}) {
+    const url = new URL(`${pathPrefix.replace(/\/$/, '')}${ATTACHMENT_LOOKUP_ROUTE_PATH}`, baseUrl);
     const call = async (payload) => unwrap(await postJson({ url, token, payload }, { request }));
     return {
         resolveForRun: async ({ ref, runId }) => ((await call({ op: 'resolveForRun', ref, runId })) ?? undefined),

package/dist/routines/scheduler.js

@@ -20,6 +20,8 @@
  * faithful port, not a redesign, per the proposal's own warning against "casually reinventing"
  * the race-safe scheduled-slot claim below.
  */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { nextRunAtForSchedule } from './schedule.js';
 function clearRoutinePlaceholderId(value) {
@@ -43,10 +45,10 @@ export class ScheduledRunPersistenceError extends Error {
         this.name = 'ScheduledRunPersistenceError';
     }
 }
-/** What a failed scheduled run logs: the underlying error's message when there is one. */
+/** Preserve the underlying failure (including its code) for the redacted log diagnostic. */
 function scheduledRunFailureDetail(error) {
     const cause = error instanceof ScheduledRunPersistenceError ? error.originalError : error;
-    return cause instanceof Error ? cause.message : cause;
+    return cause;
 }
 function isScheduledRunPersistenceError(error) {
     return error instanceof ScheduledRunPersistenceError;
@@ -141,7 +143,7 @@ export class RoutineService {
                 this.rescheduleOne({ routineId: routine.id });
             })
                 .catch((error) => {
-                console.error(`[@jini-ai/daemon] routine ${routine.id} scheduled run failed:`, scheduledRunFailureDetail(error));
+                console.error(`[@jini-ai/daemon] routine ${routine.id} scheduled run failed:`, redactSecrets({ input: inspect(scheduledRunFailureDetail(error)) }, { redactPii: false }));
                 if (isScheduledRunPersistenceError(error)) {
                     this.retryScheduledSlot(routine.id, fireAt);
                 }
@@ -249,7 +251,7 @@ export class RoutineService {
             discardError = err;
         }
         if (discardError != null) {
-            console.error(`[@jini-ai/daemon] routine ${attempt.routine.id} prepare cleanup failed:`, errorMessage(discardError));
+            console.error(`[@jini-ai/daemon] routine ${attempt.routine.id} prepare cleanup failed:`, redactSecrets({ input: inspect(discardError) }, { redactPii: false }));
         }
         run.projectId = clearRoutinePlaceholderId(run.projectId);
         run.conversationId = clearRoutinePlaceholderId(run.conversationId);

package/dist/routing-tool-executor.d.ts

@@ -23,7 +23,12 @@ export interface RoutingToolExecutorRequired {
 }
 /**
  * Creates the routing executor.
+ * @param required Local/remote executors and the owning registry's routing predicate.
+ * @param optional.acquireActivity Host busy lease, released on success or failure after real work.
+ * @returns One executor preserving the selected route's result/error and cancellation policy.
  * @complexity O(1) plus `isLocal`'s own cost per call.
  */
-export declare function createRoutingToolExecutor({ local, remote, isLocal }: RoutingToolExecutorRequired, _optional?: Record<string, never>): ToolExecutor;
+export declare function createRoutingToolExecutor({ local, remote, isLocal }: RoutingToolExecutorRequired, { acquireActivity }?: {
+    readonly acquireActivity?: () => () => void;
+}): ToolExecutor;
 //# sourceMappingURL=routing-tool-executor.d.ts.map

package/dist/routing-tool-executor.js

@@ -1,10 +1,23 @@
 /**
  * Creates the routing executor.
+ * @param required Local/remote executors and the owning registry's routing predicate.
+ * @param optional.acquireActivity Host busy lease, released on success or failure after real work.
+ * @returns One executor preserving the selected route's result/error and cancellation policy.
  * @complexity O(1) plus `isLocal`'s own cost per call.
  */
-export function createRoutingToolExecutor({ local, remote, isLocal }, _optional = {}) {
+export function createRoutingToolExecutor({ local, remote, isLocal }, { acquireActivity } = {}) {
     return {
-        execute: (args, optional) => (isLocal({ toolId: args.toolId }) ? local : remote).execute(args, optional),
+        async execute(args, optional) {
+            // HTTP disconnects/cancel requests may precede actual completion. The embedding's busy
+            // lease follows the real executor promise, including its approval wait and cleanup.
+            const release = acquireActivity?.();
+            try {
+                return await (isLocal({ toolId: args.toolId }) ? local : remote).execute(args, optional);
+            }
+            finally {
+                release?.();
+            }
+        },
         resumeConfirmation: (args) => local.resumeConfirmation(args),
         cancel: (args) => {
             local.cancel(args);

package/dist/run-lifecycle.d.ts

@@ -1,19 +1,3 @@
-/**
- * `RunLifecycle` — start/stream/cancel/resume a run keyed on an opaque
- * `contextRef` (extraction-plan §2.1: runs key on an opaque `contextRef`,
- * never a product-record identifier), generalized from OD's `design.runs` service
- * (`apps/daemon/src/runtimes/runs.ts` + the terminal-decision half of
- * `apps/daemon/src/runtimes/start-chat-run.ts`, `arch/server-startserver-endgame`
- * branch — see `archived provenance ledger` for exact line citations).
- *
- * Scope boundary: this module owns the run *state machine* and its event
- * log — create, transition, emit, replay, cancellation-intent propagation,
- * idempotent start/finish, resume. It does not spawn or signal a subprocess;
- * that is `@jini-ai/agent-runtime`'s job (extraction-plan task 7). A driver
- * (today: this package's tests; later: agent-runtime) calls `emit()` for
- * agent/stdout/stderr/error events, observes cancellation via
- * `onCancelRequested`, and calls `finish()` once it knows the real outcome.
- */
 import type { DelegatedResultCorrelation } from './delegated-result-correlation.js';
 import type { RunAgentPayload, RunCancelRequest, RunChunkPayload, RunErrorPayload, RunProtocolEvent, RunStartPayload, RunStatus } from '@jini-ai/protocol';
 import type { EventLog, EventLogEntry, EventLogReplayResult } from './event-log.js';

package/dist/run-lifecycle.js

@@ -1,3 +1,21 @@
+/**
+ * `RunLifecycle` — start/stream/cancel/resume a run keyed on an opaque
+ * `contextRef` (extraction-plan §2.1: runs key on an opaque `contextRef`,
+ * never a product-record identifier), generalized from OD's `design.runs` service
+ * (`apps/daemon/src/runtimes/runs.ts` + the terminal-decision half of
+ * `apps/daemon/src/runtimes/start-chat-run.ts`, `arch/server-startserver-endgame`
+ * branch — see `archived provenance ledger` for exact line citations).
+ *
+ * Scope boundary: this module owns the run *state machine* and its event
+ * log — create, transition, emit, replay, cancellation-intent propagation,
+ * idempotent start/finish, resume. It does not spawn or signal a subprocess;
+ * that is `@jini-ai/agent-runtime`'s job (extraction-plan task 7). A driver
+ * (today: this package's tests; later: agent-runtime) calls `emit()` for
+ * agent/stdout/stderr/error events, observes cancellation via
+ * `onCancelRequested`, and calls `finish()` once it knows the real outcome.
+ */
+import { inspect } from 'node:util';
+import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { RUN_PROTOCOL_VERSION, isTerminalRunState } from '@jini-ai/protocol';
 import { createInactivityWatchdog } from './close-status.js';
@@ -455,11 +473,11 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
                 input.onInternalError(context);
             // eslint-disable-next-line no-console
             else
-                console.error(`[@jini-ai/daemon] internal error (${context.source}, runId=${context.runId})`, context.error);
+                console.error(`[@jini-ai/daemon] internal error (${context.source}, runId=${context.runId})`, redactSecrets({ input: inspect(context.error) }, { redactPii: false }));
         }
         catch (sinkError) {
             // eslint-disable-next-line no-console
-            console.error(`[@jini-ai/daemon] internal error sink failed (${context.source}, runId=${context.runId})`, sinkError);
+            console.error(`[@jini-ai/daemon] internal error sink failed (${context.source}, runId=${context.runId})`, redactSecrets({ input: inspect(sinkError) }, { redactPii: false }));
         }
     }
     /** Trims the oldest terminal records until `terminalRunOrder` is back at or under `maxTerminalRuns`. */
@@ -531,14 +549,14 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
                 }
                 else {
                     // eslint-disable-next-line no-console
-                    console.error(`[@jini-ai/daemon] internal error (inactivity-timeout, runId=${runId})`, error);
+                    console.error(`[@jini-ai/daemon] internal error (inactivity-timeout, runId=${runId})`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
                 }
             }
             catch (sinkError) {
                 // A diagnostic sink must not turn a contained timer failure into another unhandled
                 // rejection.
                 // eslint-disable-next-line no-console
-                console.error(`[@jini-ai/daemon] internal error sink failed (inactivity-timeout, runId=${runId})`, sinkError);
+                console.error(`[@jini-ai/daemon] internal error sink failed (inactivity-timeout, runId=${runId})`, redactSecrets({ input: inspect(sinkError) }, { redactPii: false }));
             }
         }
     }
@@ -579,13 +597,13 @@ export function createRunLifecycle(requiredArgs, optionalArgs = {}) {
                 }
                 else {
                     // eslint-disable-next-line no-console
-                    console.error(`[@jini-ai/daemon] internal error (slow-run-notice, runId=${runId})`, error);
+                    console.error(`[@jini-ai/daemon] internal error (slow-run-notice, runId=${runId})`, redactSecrets({ input: inspect(error) }, { redactPii: false }));
                 }
             }
             catch (sinkError) {
                 // Same containment reasoning as `handleInactivityTimeout`'s own catch below it.
                 // eslint-disable-next-line no-console
-                console.error(`[@jini-ai/daemon] internal error sink failed (slow-run-notice, runId=${runId})`, sinkError);
+                console.error(`[@jini-ai/daemon] internal error sink failed (slow-run-notice, runId=${runId})`, redactSecrets({ input: inspect(sinkError) }, { redactPii: false }));
             }
         }
     }

package/dist/surface-exchanges.d.ts

@@ -68,6 +68,8 @@ export type { SchedulerPort } from './scheduler.js';
 export declare const DEFAULT_SURFACE_IDLE_TTL_MS: number;
 /**
  * Hard ceiling on one exchange's total life, regardless of activity.
+ * Applies only without an executor lifetime. The historical paired-transport rationale below
+ * describes unleased callers; run-bound cards ignore both deadlines and end with their call.
  *
  * Exists because the idle deadline alone is unbounded in aggregate — a human answering every four
  * minutes could hold a call open indefinitely, and the call is not ours to hold: it is an HTTP
@@ -92,7 +94,9 @@ export declare const DEFAULT_SURFACE_MAX_LIFETIME_MS: number;
  * @param deps.idGenerator - Id source, injected so a test can assert a known value.
  * @param deps.clock - Wall clock for {@link SurfaceExchange.expiresAtMs}. The injected scheduler owns
  * the timers; the clock dates and checks their deadlines.
- * @complexity O(1) per send/receive/deliver. Each exchange owns two `unref`'d timers.
+ * @complexity O(1) per receive, O(n) per accepted answer in active/retained exchanges, and O(t)
+ * per send to t observing tabs. Closed recovery entries are capped at 128. Unleased exchanges own
+ * two timers; run-bound exchanges own one cancellation subscription and no deadline timers.
  */
 export declare function createSurfaceExchangeStore(deps: {
     scheduler: SchedulerPort;

package/dist/surface-exchanges.js

@@ -1,4 +1,5 @@
 export { SURFACE_EXCHANGE_ID_PARAM, SURFACE_DISMISSED_PARAM, SURFACE_TYPED_ANSWER_PARAM, } from '@jini-ai/core';
+import { createSurfaceRestoration } from './surface-restoration.js';
 /**
  * How long an exchange may sit with nothing happening before it gives up.
  *
@@ -10,6 +11,8 @@ export { SURFACE_EXCHANGE_ID_PARAM, SURFACE_DISMISSED_PARAM, SURFACE_TYPED_ANSWE
 export const DEFAULT_SURFACE_IDLE_TTL_MS = 5 * 60 * 1000;
 /**
  * Hard ceiling on one exchange's total life, regardless of activity.
+ * Applies only without an executor lifetime. The historical paired-transport rationale below
+ * describes unleased callers; run-bound cards ignore both deadlines and end with their call.
  *
  * Exists because the idle deadline alone is unbounded in aggregate — a human answering every four
  * minutes could hold a call open indefinitely, and the call is not ours to hold: it is an HTTP
@@ -29,6 +32,12 @@ class SurfaceExchangeEndedError extends Error {
     }
     terminal;
 }
+/** Run-bound cards use cancellation instead of a date; other callers retain both timed budgets. */
+function initialSurfaceDeadlines({ leased, nowMs, idleTtlMs, maxLifetimeMs }) {
+    if (leased)
+        return { idle: Number.POSITIVE_INFINITY, lifetime: Number.POSITIVE_INFINITY };
+    return { idle: nowMs + idleTtlMs, lifetime: nowMs + maxLifetimeMs };
+}
 /**
  * Creates an in-process store of open surface exchanges.
  *
@@ -42,13 +51,18 @@ class SurfaceExchangeEndedError extends Error {
  * @param deps.idGenerator - Id source, injected so a test can assert a known value.
  * @param deps.clock - Wall clock for {@link SurfaceExchange.expiresAtMs}. The injected scheduler owns
  * the timers; the clock dates and checks their deadlines.
- * @complexity O(1) per send/receive/deliver. Each exchange owns two `unref`'d timers.
+ * @complexity O(1) per receive, O(n) per accepted answer in active/retained exchanges, and O(t)
+ * per send to t observing tabs. Closed recovery entries are capped at 128. Unleased exchanges own
+ * two timers; run-bound exchanges own one cancellation subscription and no deadline timers.
  */
 export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_IDLE_TTL_MS, maxLifetimeMs = DEFAULT_SURFACE_MAX_LIFETIME_MS } = {}) {
     if (!Number.isFinite(idleTtlMs) || idleTtlMs <= 0 || !Number.isFinite(maxLifetimeMs) || maxLifetimeMs <= 0)
         throw new Error('surface deadlines must be finite and positive');
     const openExchanges = new Map();
-    return {
+    const restoration = createSurfaceRestoration({ clock: deps.clock, defaultChannel: deps.defaultChannel,
+        deliver: (required, optional) => store.deliver(required, optional) });
+    const store = {
+        restore: restoration.restore,
         open({ binding, emit }, _optional = {}) {
             // Waiting without a live emitter is a deadlock; reject before allocating any timers or ID.
             if (typeof emit !== 'function')
@@ -56,13 +70,20 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
             const id = deps.idGenerator.newId();
             if (!id || openExchanges.has(id))
                 throw new Error('surface exchange ID must be unique and nonempty');
+            const lifetime = emit.exchangeLifetime;
+            // Only the executor can supply this lease. Plain emitters (including bounded visitor
+            // confirmations) retain their existing deadlines. No card/tool needs its own TTL override.
+            const leased = lifetime !== undefined && lifetime.principalId === binding.principalId;
+            const recovery = leased ? restoration.track({ id, binding, lifetime }) : undefined;
             const inbox = [];
             const waiters = [];
             let terminal;
             let cancelIdle;
             let cancelLifetime;
-            const lifetimeDeadline = deps.clock.nowMs() + maxLifetimeMs;
-            let idleDeadline = deps.clock.nowMs() + idleTtlMs;
+            const deadlines = initialSurfaceDeadlines({ leased, nowMs: deps.clock.nowMs(), idleTtlMs, maxLifetimeMs });
+            const lifetimeDeadline = deadlines.lifetime;
+            let idleDeadline = deadlines.idle;
+            const closeOnAbort = () => end({ status: 'abandoned' });
             function end(reason) {
                 if (terminal)
                     return;
@@ -70,6 +91,8 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                 cancelIdle?.();
                 cancelLifetime?.();
                 openExchanges.delete(id);
+                lifetime?.signal.removeEventListener('abort', closeOnAbort);
+                recovery?.end();
                 while (waiters.length > 0)
                     waiters.shift()(reason);
             }
@@ -79,7 +102,7 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                     end({ status: 'expired' });
             }
             function armIdle() {
-                if (terminal)
+                if (terminal || leased)
                     return;
                 cancelIdle?.();
                 idleDeadline = deps.clock.nowMs() + idleTtlMs;
@@ -87,7 +110,8 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
             }
             // Register only after both timers are installed, so scheduler failure leaves no discoverable exchange.
             try {
-                cancelLifetime = deps.scheduler.schedule({ delayMs: maxLifetimeMs, callback: () => end({ status: 'expired' }) });
+                if (!leased)
+                    cancelLifetime = deps.scheduler.schedule({ delayMs: maxLifetimeMs, callback: () => end({ status: 'expired' }) });
                 armIdle();
             }
             catch (error) {
@@ -102,6 +126,7 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                     expireIfDue();
                     if (terminal)
                         return;
+                    recovery?.answered();
                     armIdle();
                     const waiter = waiters.shift();
                     if (waiter)
@@ -112,6 +137,11 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                         inbox.push(params);
                 },
             });
+            if (leased) {
+                lifetime.signal.addEventListener('abort', closeOnAbort, { once: true });
+                if (lifetime.signal.aborted)
+                    closeOnAbort();
+            }
             return {
                 id,
                 async send({ emission }, _optional = {}) {
@@ -119,7 +149,10 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
                     if (terminal)
                         throw new SurfaceExchangeEndedError({ id, terminal });
                     armIdle();
-                    await emit(emission);
+                    const sent = recovery === undefined ? emission : { ...emission, payload: { ...emission.payload,
+                            surfaceExchange: { exchangeId: id, toolId: binding.toolId, runId: lifetime.runId } } };
+                    await recovery?.send({ emission: sent });
+                    await emit(sent);
                 },
                 async receive(_args, _optional = {}) {
                     expireIfDue();
@@ -166,6 +199,7 @@ export function createSurfaceExchangeStore(deps, { idleTtlMs = DEFAULT_SURFACE_I
         },
         size: () => openExchanges.size,
     };
+    return store;
 }
 /**
  * The one-shot case: send once, wait once, close.