@zq-silk/yui 2.16.0 → 2.18.0

package/dist/controller/globalRuntimeAttention.js

@@ -102,15 +102,19 @@ export function runtimeDiagnosticEvidence(messages, key) {
 /** Global observations have no Task event history. Keep original failed
  * attempts as ordinary record-only Messages before replacing the live binding. */
 export function recordGlobalRuntimeFailure(store, roleName, identity, facts, now) {
+    return recordFailure(store, roleName, identity, facts, now, [...store.listGlobalRoleMessages(roleName)]);
+}
+function recordFailure(store, roleName, identity, facts, now, messages) {
     const diagnostic = diagnosticIdentity(store, roleName, identity, facts);
     const header = `${FAILURE_HEADER}${hash([identity, diagnostic.key])}\n`;
-    const previous = store.listGlobalRoleMessages(roleName).find(message => message.kind === "system" && message.body.startsWith(header));
+    const previous = messages.find(message => message.kind === "system" && message.body.startsWith(header));
     if (previous !== undefined)
         return `${roleName}/${previous.id}`;
     const message = createGlobalRoleMessage(store.nextGlobalRoleMessageId(), roleName, header + redactAgentErrorText(JSON.stringify({
         ...object(facts), diagnostic
     })), "system", { type: "system" }, now);
     store.saveGlobalRoleMessage(message);
+    messages.push(message);
     return `${roleName}/${message.id}`;
 }
 /** Reuse the Global Message inbox for an exact failure, not a recovery queue.
@@ -119,9 +123,13 @@ export function recordGlobalRuntimeAttention(store, roleName, identity, facts, n
     // A Home may have a custom Global Role without an Operator. Keep its own
     // diagnostic readable; never create a Role or launch a substitute Agent.
     const recipient = store.getGlobalRole("operator") === null ? roleName : "operator";
-    const failureRef = recordGlobalRuntimeFailure(store, roleName, identity, facts, now);
+    // These observations run in the caller's transaction. Reuse that exact
+    // history plus our appended record, rather than loading/parsing the whole
+    // Role history twice on every unchanged Host failure.
+    const messages = [...store.listGlobalRoleMessages(roleName)];
+    const failureRef = recordFailure(store, roleName, identity, facts, now, messages);
     const diagnostic = diagnosticIdentity(store, roleName, identity, facts);
-    const group = runtimeDiagnosticGroups(store.listGlobalRoleMessages(roleName))
+    const group = runtimeDiagnosticGroups(messages)
         .reverse().find(group => group.key === diagnostic.key && group.recoveredAt === undefined);
     const requestId = `runtime-attention:${hash([roleName, diagnostic.key, group?.episode ?? identity])}`;
     if (store.queryGlobalRoleMessages(recipient, { requestId, limit: 1 }).messages.length > 0)

package/dist/controller/jobControl.js

@@ -277,7 +277,7 @@ export function assertNonSecretJobInput(params) {
         }
     }
     const input = JSON.stringify({
-        env: params.env, steps: params.steps, requestId: params.requestId
+        env: params.env, steps: params.steps, requestId: params.requestId, files: params.files
     });
     // Reject recognizable key material regardless of the parameter name, and
     // URL userinfo before either hashing or persisting the specification.

package/dist/controller/jobDefinitionControl.js

@@ -5,6 +5,7 @@ import { requireKnownFields } from "../domain/validation.js";
 import { createJobDefinition, reviseJobDefinition, jobScopeKey, validateJobDefinition } from "../job/jobDefinition.js";
 import { acknowledgeUnknownDurableJob, requestDurableJobCancel, validateDurableJob, JOB_RUNNER_IMPLEMENTATION, executionNamespace } from "../job/durableJob.js";
 import { prepareBuiltinJob, projectRefreshDigest } from "../job/builtinJob.js";
+import { prepareGlobalShell } from "../job/globalShell.js";
 import { projectRefreshTargetDigest, requireRefreshProject } from "../repository/projectRefresh.js";
 import { assertCallerAuthorized, assertNonSecretJobInput, createDurableJobControl, jobAuthorityBinding, validateStartParams, requireJobAssignment, parseDurableJobCaller } from "./jobControl.js";
 import { createFileArtifactPort } from "./jobSupervisor.js";
@@ -38,7 +39,7 @@ export function authorizeScope(store, scope, caller, allowPublic = false) {
     assertCallerAuthorized(store, caller, scope.kind === "task" ? scope.taskId : "");
 }
 function taskParams(job, caller, requestId) {
-    if (job.scope.kind !== "task" || job.configuration.kind !== "shell")
+    if (job.scope.kind !== "task" || job.configuration.kind !== "shell" || !("owner" in job.configuration))
         throw new Error("Not a Task Job.");
     return { ...job.configuration, taskId: job.scope.taskId, caller, requestId };
 }
@@ -60,8 +61,13 @@ export function authorizeDefinition(store, job, caller, write) {
             assertNonSecretJobInput(params);
     }
     else if (write) {
+        if (job.configuration.kind === "shell") {
+            prepareGlobalShell(job.configuration, "/job-validation");
+            assertNonSecretJobInput({ ...job.configuration, requestId: "global-shell-definition" });
+            return;
+        }
         if (job.configuration.kind !== "builtin")
-            throw new Error("Global Jobs require builtin actions.");
+            throw new Error("Not a global process Job.");
         prepareBuiltinJob(job.configuration, "/");
         if (job.configuration.action === "project.refresh") {
             if (job.builtin)
@@ -190,18 +196,21 @@ export function admitJobRun(store, home, scope, definitionId, caller, trigger, n
             }, now);
             return { run: result.job, created: result.created };
         }
-        if (job.configuration.kind !== "builtin")
-            throw new Error("Global Jobs require builtin actions.");
+        if (job.configuration.kind !== "builtin" && job.configuration.kind !== "shell")
+            throw new Error("Not a global process Job.");
         const id = `job-${randomUUID()}`;
         const locator = `artifacts/jobs/global/${id}`;
-        const spec = prepareBuiltinJob(job.configuration, join(home, locator), { home, runId: id });
+        const config = job.configuration;
+        const shell = config.kind === "shell";
+        const spec = shell ? prepareGlobalShell(config, join(home, locator, "workspace"))
+            : prepareBuiltinJob(config, join(home, locator), { home, runId: id });
         const actorId = service ? "service:schedule" : caller.scope === "user" ? "user" : `global:${caller.role}`;
         let run = {
             schemaVersion: 1, scope: "global", id, definitionId: job.id, definitionRevision: job.revision,
-            trigger: structuredClone(trigger), action: job.configuration.action,
+            trigger: structuredClone(trigger), action: shell ? "shell.exec" : config.action,
             ...(service === undefined ? {} : { serviceAuthorization: structuredClone(service) }),
-            actionInput: structuredClone(job.configuration.input),
-            ...(job.configuration.projectId === undefined ? {} : { projectId: job.configuration.projectId }),
+            actionInput: structuredClone(shell ? config : config.input),
+            ...(!shell && config.projectId !== undefined ? { projectId: config.projectId } : {}),
             ...spec, status: "queued", artifactsLocator: locator,
             idempotencyKey: createHash("sha256").update(JSON.stringify([actorId, requestId])).digest("hex"),
             operation: {
@@ -280,10 +289,12 @@ export function authorizeGlobalJobStart(store, run) {
     const projects = run.action === "project.refresh" ? store.listProjects() : [];
     const home = store.rootDirectory();
     try {
-        const compiled = prepareBuiltinJob({
-            kind: "builtin", action: run.action, input: run.actionInput,
-            ...(run.projectId === undefined ? {} : { projectId: run.projectId })
-        }, run.workspace, { home, runId: run.id });
+        const compiled = run.action === "shell.exec"
+            ? prepareGlobalShell(run.actionInput, join(home, "artifacts/jobs/global", run.id, "workspace"))
+            : prepareBuiltinJob({
+                kind: "builtin", action: run.action, input: run.actionInput,
+                ...(run.projectId === undefined ? {} : { projectId: run.projectId })
+            }, run.workspace, { home, runId: run.id });
         if (run.action === "project.refresh") {
             const definition = store.getJobDefinition({ kind: "global" }, run.definitionId);
             if (definition?.builtin)
@@ -297,7 +308,7 @@ export function authorizeGlobalJobStart(store, run) {
                 throw new Error("Project refresh Run workspace does not match its artifact directory.");
             }
         }
-        if (JSON.stringify(compiled.steps) !== JSON.stringify(run.steps)
+        if (compiled.workspace !== run.workspace || JSON.stringify(compiled.steps) !== JSON.stringify(run.steps)
             || JSON.stringify(compiled.env) !== JSON.stringify(run.env) || compiled.head !== run.head) {
             throw new Error("Global JobRun does not match its controlled action.");
         }

package/dist/controller/jobSupervisor.js

@@ -199,6 +199,8 @@ export class DurableJobSupervisor {
             return;
         }
         const spec = {
+            ...(!("taskId" in job) && "action" in job && job.action === "shell.exec"
+                ? { files: job.actionInput.files } : {}),
             jobId: job.id,
             ...("taskId" in job ? { taskId: job.taskId } : { scope: "global" }),
             workspace: job.workspace,
@@ -386,6 +388,8 @@ export class DurableJobSupervisor {
             return fallback;
         if (job.action === "system.noop")
             return { ...fallback, data: { action: "system.noop" } };
+        if (job.action === "shell.exec")
+            return fallback;
         const raw = this.#artifacts.readBusinessResult?.(executionNamespace(job), job.id);
         if (raw !== null && raw !== undefined) {
             try {

package/dist/controller/providerRetryAdmission.js

@@ -1,3 +1,4 @@
+import { assertRoleEnabled, isEnabled } from "../role/availability.js";
 import { admitProviderRetry, cancelProviderRetry, providerRetryAttemptId, providerRetryPending } from "../runtime/providerRetry.js";
 import { blockingProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
 import { validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
@@ -20,6 +21,8 @@ export function ownedProviderInput(input) {
 export function retryIntentBlocker(store, input, retry) {
     if (input.taskId === undefined) {
         const role = store.getGlobalRole(input.roleName);
+        if (role !== null && !isEnabled(role))
+            return "role-disabled";
         const sessions = store.getGlobalRoleSessionSet(input.roleName);
         if (role === null || sessions?.activeAgentId !== role.activeAgentId)
             return "role-changed";
@@ -38,6 +41,8 @@ export function retryIntentBlocker(store, input, retry) {
         || task.executionGate.state !== "enabled")
         return "task-execution-stopped";
     const role = store.getRole(input.taskId, input.roleName);
+    if (role !== null && !isEnabled(role))
+        return "role-disabled";
     const sessions = store.getTaskRoleSessionSet(input.taskId, input.roleName);
     if (role === null || sessions?.activeAgentId !== role.activeAgentId)
         return "role-changed";
@@ -54,6 +59,10 @@ export function retryIntentBlocker(store, input, retry) {
 /** Shared by automatic recovery and every ordinary Host submit. The native
  * writer CAS remains the only grant; a scheduled successor is not a grant. */
 export function admitOwnedProviderInput(store, binding, input) {
+    const role = input.taskId === undefined ? store.getGlobalRole(input.roleName)
+        : store.getRole(input.taskId, input.roleName);
+    if (role !== null)
+        assertRoleEnabled(role);
     const retry = binding.retry;
     const sameReviewSuccessor = retry?.successorReviewRoundId !== undefined && input.taskId !== undefined && input.runId !== undefined
         && store.getRun(input.taskId, input.runId)?.reviewRoundId === retry.successorReviewRoundId;

package/dist/controller/providerRetryDelivery.js

@@ -1,4 +1,5 @@
 import { performance } from "node:perf_hooks";
+import { isEnabled } from "../role/availability.js";
 import { runTaskCommand } from "../commands/taskCommands.js";
 import { routeRoleEvent } from "../scheduler/operatorEvent.js";
 import { createTaskEvent } from "../event/taskEvent.js";
@@ -64,12 +65,19 @@ export function createProviderRetryHooks(home, store, ports = {}) {
     const key = (set) => set.owner.scope === "task"
         ? `role:${encodeURIComponent(set.owner.taskId)}/${encodeURIComponent(set.owner.roleName)}`
         : `global-role:${encodeURIComponent(set.owner.roleName)}`;
+    const disabled = (set) => {
+        const role = set.owner.scope === "task"
+            ? store.getRole(set.owner.taskId, set.owner.roleName) : store.getGlobalRole(set.owner.roleName);
+        return role !== null && !isEnabled(role);
+    };
     return {
         deadlines() {
             return store.listProviderRetrySessions().flatMap(set => {
                 const retry = set.providerBinding.retry;
                 if (retry.status !== "waiting")
                     return [];
+                if (disabled(set))
+                    return [];
                 // Busy or already-queued work awaits the next ordinary pass without a
                 // zero-delay timer loop. Waiting never consumes an execution attempt.
                 const wall = (ports.now ?? (() => new Date()))().getTime();
@@ -97,6 +105,10 @@ export function createProviderRetryHooks(home, store, ports = {}) {
                     const scoped = { ...(owner.scope === "task" ? { taskId: owner.taskId } : {}), roleName: owner.roleName };
                     const session = set.sessions[set.activeAgentId];
                     const blocker = retryIntentBlocker(store, scoped, retry);
+                    // Configuration pause neither settles input nor cancels an already
+                    // admitted attempt. Normal ingress still records its exact terminal.
+                    if (blocker === "role-disabled")
+                        continue;
                     if (blocker !== undefined && blocker !== "background-work-unsettled") {
                         stop(set, blocker, at);
                         continue;
@@ -175,6 +187,10 @@ export function createProviderRetryHooks(home, store, ports = {}) {
                                     || latest.status !== "waiting")
                                     return;
                                 const reason = retryIntentBlocker(store, scoped, latest);
+                                // Snapshotting yields to configuration changes. Apply the same
+                                // pause semantics as the pre-await check, without settling intent.
+                                if (reason === "role-disabled")
+                                    return;
                                 if (reason !== undefined)
                                     throw new Error(reason);
                                 runTaskCommand(["run", "retry", `${owner.taskId}/${previous.id}`], store, {

package/dist/controller/runtime.js

@@ -1,7 +1,10 @@
 import { isDeepStrictEqual } from "node:util";
+import { ControllerDiagnosticJournal } from "./diagnosticJournal.js";
+import { monotonicMilliseconds } from "../core/controllerTelemetry.js";
 import { prepareNativeHostSteer } from "./nativeHostInput.js";
 import { archiveLeaderTask } from "../task/leaderArchive.js";
 import { TaskWorkspaceCoordinator } from "../repository/taskWorkspaceCoordinator.js";
+import { assertRoleEnabled, RoleDisabledError } from "../role/availability.js";
 import { AGENT_OPERATIONAL_ENVIRONMENT_NAMES, NATIVE_AGENT_ENVIRONMENT_NAMES, nativeAgentEnvironmentNames, YUI_MANAGED_RUNTIME_ENVIRONMENT_NAMES } from "../agent/launchEnvironment.js";
 import { runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
 import { reconciliationIntervalMilliseconds, resolveAgentLaunchInactivityTimeoutSeconds, resolveControllerTaskConcurrency, resolveDeliveryTimeoutSeconds, resolveRuntimeHealth, resolveTmuxBin, resolveTmuxHistoryLimit } from "../config/yuiConfig.js";
@@ -60,7 +63,6 @@ import { authorizeJobStart } from "./jobControl.js";
 import { authorizeGlobalJobStart, createJobDefinitionControl } from "./jobDefinitionControl.js";
 import { reconcileTaskDelegation } from "./jobTaskDelegationControl.js";
 import { createScheduleControl, reconcileSchedules } from "./scheduleControl.js";
-import { reconcileProjectSync } from "../job/projectSync.js";
 import { createFileArtifactPort, createLinuxProcessPort, DurableJobSupervisor } from "./jobSupervisor.js";
 import { createProviderRetryHooks } from "./providerRetryDelivery.js";
 import { createRuntimeResourceActivityTracker } from "./resourceInventory.js";
@@ -71,8 +73,54 @@ import { AsyncRuntimeEventProcessor, createAsyncRuntimeObserver, FileRuntimeEven
 import { RuntimeLaunchCoordinator } from "./runtimeLaunchCoordinator.js";
 import { SessionOwnerReconciliation } from "./sessionOwnerReconciliation.js";
 import { readTaskAgentCapabilities } from "./agentCapabilities.js";
+import { workerSchedulerStore } from "./workerSchedulerStore.js";
+import { deserializeError } from "../core/boundedRpc.js";
 /** Production composition root for the current SQLite TaskStore + tmux Controller. */
 export async function startFileTaskControllerRuntime(home, options = {}) {
+    const diagnostics = new ControllerDiagnosticJournal(home);
+    let timer;
+    const closeDiagnostics = async () => {
+        if (timer !== undefined)
+            clearInterval(timer);
+        await diagnostics.close();
+    };
+    try {
+        const running = await createFileTaskControllerRuntime(home, {
+            ...options,
+            diagnosticMetrics: () => diagnostics.metrics(),
+            onError: error => { diagnostics.error(error); options.onError?.(error); }
+        });
+        let expectedAt = monotonicMilliseconds() + 250;
+        timer = setInterval(() => {
+            const now = monotonicMilliseconds();
+            const lagMs = Math.max(0, now - expectedAt);
+            expectedAt = now + 250;
+            diagnostics.observe({
+                ...running.runtime.runtimeMetrics(),
+                commands: {
+                    routes: running.server.commandObserver.snapshot(),
+                    eventLoopDelay: running.server.eventLoopDelay.snapshot()
+                }
+            }, lagMs);
+        }, 250);
+        timer.unref();
+        const closed = running.closed.finally(closeDiagnostics);
+        return { ...running, closed, close: async () => {
+                try {
+                    await running.close();
+                }
+                finally {
+                    await closeDiagnostics();
+                }
+            } };
+    }
+    catch (error) {
+        diagnostics.error(error);
+        await closeDiagnostics();
+        throw error;
+    }
+}
+async function createFileTaskControllerRuntime(home, options) {
     // The current Home always uses SQLite. The persistence worker is enabled by
     // default; YUI_STORE_WORKER=0/false keeps the same database in-process.
     const useWorker = resolveStoreWorkerEnabledForHome(home, options.environment ?? process.env);
@@ -110,6 +158,10 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         closeTelemetry = () => telemetry?.sink.close() ?? Promise.resolve();
         const schedulerStore = options.schedulerStore
             ?? new FileSchedulerStoreAdapter(store, telemetry);
+        // Injected stores/adapters retain their owner and semantics. Only the
+        // production SQLite adapter shares the worker's exact Home and behavior.
+        const workerMaintenance = asyncStoreClient !== undefined
+            && options.store === undefined && options.schedulerStore === undefined;
         const domainIdentity = options.domainIdentity
             ?? ephemeralDomainFromEnvironment(options.environment ?? process.env);
         const planner = options.planner ?? new FileRoleLaunchPlanner(home, store, {
@@ -531,7 +583,9 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         const continuationReconciler = options.continuationMetadata === undefined
             ? undefined
             : new ProviderContinuationReconciliationService(store, schedulerStore, options.continuationMetadata, options.onError);
-        const running = await startFileTaskController(home, schedulerStore, delivery, (method, params) => method === "task.role-capabilities"
+        const running = await startFileTaskController(home, workerMaintenance
+            ? workerSchedulerStore(schedulerStore, asyncStoreClient)
+            : schedulerStore, delivery, (method, params) => method === "task.role-capabilities"
             ? readTaskAgentCapabilities(store, catalogs, params)
             : method === "web.start" || method === "web.stop" || method === "web.status"
                 ? web.dispatch(method, params) : lifecycleDispatcher(method, params), {
@@ -550,6 +604,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
                 ?? resolveRuntimeHealth(durableConfig.runtimeHealth).diagnosticAfterMs,
             now: options.now,
             onError: options.onError,
+            diagnosticMetrics: options.diagnosticMetrics,
             lifecycleHost,
             providerRetry: createProviderRetryHooks(home, store, {
                 now: options.now,
@@ -580,8 +635,12 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             jobDefinitions: createJobDefinitionControl(store, home),
             schedules: {
                 control: createScheduleControl(store, home),
-                reconcile: now => {
-                    reconcileProjectSync(store, now, options.onError);
+                reconcile: async (now) => {
+                    const errors = workerMaintenance
+                        ? await asyncStoreClient.invokeObserver("reconcileProjectSync", [now])
+                        : schedulerStore.reconcileProjectSync(now);
+                    for (const error of errors)
+                        options.onError?.(deserializeError(error));
                     reconcileSchedules(store, home, now, options.onError);
                 }
             },
@@ -599,6 +658,10 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
                 ?? (useWorker && asyncStoreClient !== undefined
                     ? new AsyncRuntimeEventProcessor(runtimeEventInbox, createAsyncRuntimeObserver((method, args) => asyncStoreClient.invokeObserver(method, args)))
                     : new FileRuntimeEventProcessor(runtimeEventInbox, schedulerStore)),
+            persistenceMetrics: () => ({
+                worker: asyncStoreClient?.observationMetrics() ?? null,
+                database: store instanceof SqliteTaskStore ? store.storageObservationMetrics() : null
+            }),
             runtimeObserver: options.runtimeObserver
                 ?? new AgentRuntimeObserver(store, runtimeEventInbox),
             domainIdentity,
@@ -740,6 +803,17 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                 });
             }
             catch (error) {
+                if (error instanceof RoleDisabledError) {
+                    const turn = (value.taskId === undefined
+                        ? store.getGlobalRoleSessionSet(value.roleName)
+                        : store.getTaskRoleSessionSet(value.taskId, value.roleName))?.providerBinding?.run;
+                    // The admission transaction rolled back. Only a new, unregistered
+                    // input may use the existing temporary-backpressure wire contract.
+                    // A matching prior registration remains fenced, never a fresh retry.
+                    if (turn?.attemptId !== value.attemptId) {
+                        throw applicationError("SESSION_BUSY", error.message);
+                    }
+                }
                 if (error instanceof AgentHostProviderSessionBusyError)
                     throw error;
                 if (error instanceof AgentHostProviderTurnFenceError) {
@@ -960,6 +1034,7 @@ export function createRuntimeLifecycleDispatcher(store, schedulerStore, sessionH
                 ? activeRun?.workspace
                     ?? currentDesiredManagedWorkspace(store, request.taskId, request.roleName)
                 : undefined;
+            assertRoleEnabled(role);
             // Only Draft planning may launch without an adopted delivery workspace.
             const workspaceFree = request.scope === "task"
                 && managedWorkspace === undefined
@@ -1082,6 +1157,7 @@ function assertRuntimeLaunchRequestCurrent(store, request) {
     if (role === null) {
         throw new Error(`Role no longer exists: ${request.owner.roleName}.`);
     }
+    assertRoleEnabled(role);
     const sessions = request.owner.scope === "task"
         ? store.getTaskRoleSessionSet(request.owner.taskId, request.owner.roleName)
         : store.getGlobalRoleSessionSet(request.owner.roleName);

package/dist/controller/runtimeLaunchCoordinator.js

@@ -92,7 +92,9 @@ export class RuntimeLaunchCoordinator {
             ...(request.runId === undefined ? {} : { runId: request.runId }),
             ...(request.environment === undefined ? {} : { environment: request.environment })
         };
-        const callback = beforeHostStart === undefined ? undefined : observePreflight;
+        // Even without a startup-facts consumer, recheck after asynchronous Host
+        // validation and immediately before creating the process.
+        const callback = beforeHostStart === undefined ? () => assertLaunchCurrent() : observePreflight;
         if (request.mode === "resume" && !request.nativeSessionId) {
             throw new Error("Restoring a Session requires its native session id.");
         }

package/dist/controller/workerSchedulerStore.js

@@ -0,0 +1,24 @@
+/**
+ * Keep maintenance read/check/write closures together on the persistence
+ * worker. These operations recheck their exact durable condition in one
+ * transaction and are idempotent under the worker's existing replay contract.
+ * Do not add admission/claim operations here: their result and unknown-effect
+ * contracts need a separate audit before moving across this boundary.
+ */
+const WORKER_MAINTENANCE = new Set([
+    "resolveExpiredInputRecommendations",
+    "recordRoleRunProgress",
+    "recordRoleRunDiagnostic",
+    "recordRoleRunStall"
+]);
+export function workerSchedulerStore(store, client) {
+    return new Proxy(store, {
+        get(target, property) {
+            if (WORKER_MAINTENANCE.has(property)) {
+                return (...args) => client.invokeObserver(String(property), args);
+            }
+            const value = Reflect.get(target, property);
+            return typeof value === "function" ? value.bind(target) : value;
+        }
+    });
+}

package/dist/core/boundedRpc.js

@@ -48,6 +48,10 @@ export function serializeError(error) {
 export function deserializeError(serialized) {
     const error = new Error(serialized.message);
     error.name = serialized.name;
+    if (serialized.code !== undefined)
+        Object.assign(error, { code: serialized.code });
+    if (serialized.stack !== undefined)
+        error.stack = serialized.stack;
     return error;
 }
 // -- Bounded slot pool (backpressure) ----------------------------------------

package/dist/core/controllerServer.js

@@ -311,7 +311,7 @@ async function routeRequest(socket, line, token, dispatcher, stop, status, telem
     // observation completes when the response is handed to the socket, so a
     // later status snapshot sees prior built-in completions and the dispatcher
     // service-time metric stays a distinct observation.
-    const observation = telemetry.commandObserver.start();
+    const observation = telemetry.commandObserver.start(request.method, request.id);
     const send = (response, onFlushed) => {
         observation.complete(isBuiltinControllerMethod(request.method) ? "builtin" : "dispatched", response.ok ? "success" : "failure");
         sendResponse(socket, response, onFlushed);

package/dist/core/controllerTelemetry.js

@@ -1,13 +1,69 @@
-/**
- * Pure-memory, fixed-space command observation for the Controller socket.
- *
- * The core server owns route/built-in command observation: every authenticated
- * request is counted once at the routing layer, and a bounded unrefed scheduler
- * samples event-loop delay so an already-written request's pre-dispatch wait is
- * observable even when the loop is saturated by scheduler projections. The
- * FileTaskController composes these snapshots into its runtime status metric;
- * nothing here is persisted and every snapshot is O(1).
- */
+import { createHash } from "node:crypto";
+/** Fixed-size retained diagnostics; live bookkeeping follows in-flight work.
+ * Not a log or scheduling authority. No params,
+ * prompts, paths, failure text or credentials are retained. Target/request
+ * hashes correlate an observation without publishing arbitrary input. */
+export class ControllerWorkObserver {
+    clock;
+    #active = new Map();
+    #recent = [];
+    #completed = 0;
+    #maximumMs = 0;
+    #slowest = null;
+    constructor(clock = monotonicMilliseconds) {
+        this.clock = clock;
+    }
+    start(phase, target) {
+        const token = {};
+        const entry = { phase, target: target === undefined ? null
+                : createHash("sha256").update(target).digest("hex").slice(0, 16), startedAt: this.clock() };
+        this.#active.set(token, entry);
+        return (failed = false) => {
+            if (!this.#active.delete(token))
+                return;
+            const elapsedMs = Math.max(0, this.clock() - entry.startedAt);
+            this.#completed++;
+            this.#maximumMs = Math.max(this.#maximumMs, elapsedMs);
+            const completed = { phase, target: entry.target, startedAtMs: entry.startedAt, elapsedMs, failed };
+            if (this.#slowest === null || elapsedMs > this.#slowest.elapsedMs)
+                this.#slowest = completed;
+            this.#recent.push(completed);
+            if (this.#recent.length > 16)
+                this.#recent.shift();
+        };
+    }
+    async observe(phase, target, action) {
+        const finish = this.start(phase, target);
+        try {
+            const value = await action();
+            finish();
+            return value;
+        }
+        catch (error) {
+            finish(true);
+            throw error;
+        }
+    }
+    snapshot() {
+        const active = [];
+        for (const entry of this.#active.values()) {
+            active.push({ phase: entry.phase, target: entry.target, startedAtMs: entry.startedAt,
+                ageMs: Math.max(0, this.clock() - entry.startedAt) });
+            if (active.length === 16)
+                break;
+        }
+        return {
+            completed: this.#completed, maximumMs: this.#maximumMs, inFlight: this.#active.size,
+            active, slowest: this.#slowest,
+            recent: [...this.#recent]
+        };
+    }
+}
+/** Small worker-response observation; no historical arrays on the RPC wire. */
+export function compactWorkObservation(observer) {
+    const { completed, maximumMs, slowest, recent } = observer.snapshot();
+    return { completed, maximumMs, slowest, latest: recent.at(-1) ?? null };
+}
 const CONTROLLER_DELAY_BUCKETS_MS = [10, 50, 100, 250, 500, 1_000, 3_000];
 const DEFAULT_EVENT_LOOP_DELAY_INTERVAL_MS = 50;
 const BUILTIN_METHODS = new Set([
@@ -19,6 +75,12 @@ const BUILTIN_METHODS = new Set([
     "controller.rollback-handover",
     "controller.handover-state"
 ]);
+const OBSERVED_METHODS = new Set([...BUILTIN_METHODS,
+    "scheduler.signal", "scheduler.scan", "scheduler.configure",
+    "runtime.ensure-role-session", "runtime.stop-role-session",
+    "capability.search", "capability.describe", "capability.call",
+    "schedule.control", "job.definition", "job.start", "job.get", "job.cancel", "job.acknowledge"
+]);
 export function isBuiltinControllerMethod(method) {
     return BUILTIN_METHODS.has(method);
 }
@@ -47,19 +109,23 @@ export class ControllerCommandObserver {
     #completed = 0;
     #failed = 0;
     #inFlight = 0;
-    /** Monotonic arrival timestamps of in-flight observations (FIFO). */
-    #inFlightStarted = [];
+    /** Insertion order preserves arrival order; completion removes its own token. */
+    #inFlightStarted = new Map();
     #builtinCompleted = 0;
     #builtinFailed = 0;
     #dispatchedCompleted = 0;
     #dispatchedFailed = 0;
+    #observations;
     constructor(clock = monotonicMilliseconds) {
         this.#clock = clock;
+        this.#observations = new ControllerWorkObserver(clock);
     }
-    start() {
+    start(method = "unknown", requestId) {
         this.#received += 1;
         this.#inFlight += 1;
-        this.#inFlightStarted.push(this.#clock());
+        const token = {};
+        this.#inFlightStarted.set(token, this.#clock());
+        const finish = this.#observations.start(OBSERVED_METHODS.has(method) ? method : "other", requestId);
         let completed = false;
         return {
             complete: (kind, outcome) => {
@@ -67,7 +133,8 @@ export class ControllerCommandObserver {
                     return;
                 completed = true;
                 this.#inFlight = Math.max(0, this.#inFlight - 1);
-                this.#inFlightStarted.shift();
+                this.#inFlightStarted.delete(token);
+                finish(outcome === "failure");
                 this.#completed += 1;
                 if (outcome === "failure")
                     this.#failed += 1;
@@ -87,9 +154,9 @@ export class ControllerCommandObserver {
         };
     }
     snapshot() {
-        const oldest = this.#inFlightStarted.length === 0
+        const oldest = this.#inFlightStarted.size === 0
             ? null
-            : Math.max(0, this.#clock() - this.#inFlightStarted[0]);
+            : Math.max(0, this.#clock() - this.#inFlightStarted.values().next().value);
         return {
             received: this.#received,
             completed: this.#completed,
@@ -103,7 +170,8 @@ export class ControllerCommandObserver {
             dispatched: {
                 completed: this.#dispatchedCompleted,
                 failed: this.#dispatchedFailed
-            }
+            },
+            observations: this.#observations.snapshot()
         };
     }
 }
@@ -122,6 +190,7 @@ export class ControllerEventLoopDelay {
     #expectedAt = 0;
     #samples = 0;
     #maximumLagMs = 0;
+    #maximumObservedAtMs = null;
     #buckets = new Map(CONTROLLER_DELAY_BUCKETS_MS.map((threshold) => [threshold, 0]));
     #stopped = false;
     constructor(clock = monotonicMilliseconds, scheduler = productionTelemetryScheduler, intervalMs = DEFAULT_EVENT_LOOP_DELAY_INTERVAL_MS) {
@@ -142,7 +211,10 @@ export class ControllerEventLoopDelay {
         this.#expectedAt = this.#clock() + this.#intervalMs;
         this.#samples += 1;
         const bounded = Math.ceil(lag);
-        this.#maximumLagMs = Math.max(this.#maximumLagMs, bounded);
+        if (this.#maximumObservedAtMs === null || bounded > this.#maximumLagMs) {
+            this.#maximumLagMs = bounded;
+            this.#maximumObservedAtMs = this.#clock();
+        }
         for (const threshold of CONTROLLER_DELAY_BUCKETS_MS) {
             if (bounded <= threshold) {
                 this.#buckets.set(threshold, (this.#buckets.get(threshold) ?? 0) + 1);
@@ -158,6 +230,7 @@ export class ControllerEventLoopDelay {
         return {
             samples: this.#samples,
             maximumLagMs: this.#maximumLagMs,
+            maximumObservedAtMs: this.#maximumObservedAtMs,
             lagBuckets: Object.fromEntries(CONTROLLER_DELAY_BUCKETS_MS.map((threshold) => [
                 `le${threshold}ms`,
                 this.#buckets.get(threshold) ?? 0