@zq-silk/yui 2.17.0 → 2.19.0

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/messageHealth.js

@@ -0,0 +1,354 @@
+import { createTaskEvent } from "../event/taskEvent.js";
+import { createGlobalRoleMessage } from "../message/message.js";
+import { hasRuntimeCleanupObligation, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { providerRetryPending } from "../runtime/providerRetry.js";
+import { globalInputBacklog } from "../message/globalInputBacklog.js";
+// These are observation thresholds, not leases or authority to release a writer.
+export const MESSAGE_HEALTH_WARNING_MS = 5 * 60_000;
+export const MESSAGE_HEALTH_CRITICAL_MS = 30 * 60_000;
+const HEADER = "Yui message health v1\n";
+const NOTICE = "operator-notice:message-health:";
+export function classifyMessageHealth(facts, now) {
+    const ageMs = facts.oldestAt === null ? 0 : Math.max(0, +now - Date.parse(facts.oldestAt));
+    const occupancyMs = facts.processingAt === null ? 0 : Math.max(0, +now - Date.parse(facts.processingAt));
+    let state;
+    let reason;
+    if (facts.stopped) {
+        state = "paused";
+        reason = "explicit-stop-pause-or-lifecycle";
+    }
+    else if (facts.count === 0 && facts.handling) {
+        state = "busy";
+        reason = "claimed-input-handling-is-not-delivery-proof";
+    }
+    else if (facts.count === 0 && facts.processingAt === null) {
+        state = "clear";
+        reason = "no-awaiting-delivery";
+    }
+    else if (facts.turnStatus === "accepted" && !facts.blocked) {
+        state = "busy";
+        reason = "accepted-turn-duration-is-not-a-fault";
+    }
+    else if (facts.retryDeadline !== undefined && +now <= Date.parse(facts.retryDeadline)) {
+        state = "recovering";
+        reason = "bounded-provider-retry-owned";
+    }
+    else {
+        reason = facts.retryDeadline !== undefined ? "retry-budget-expired"
+            : facts.blocked ? "retained-delivery-or-processing-barrier"
+                : facts.turnStatus === "delivery-unknown" ? "delivery-uncertain"
+                    : facts.turnStatus === "submitting" ? "submission-unsettled" : "no-delivery-progress";
+        state = Math.max(ageMs, occupancyMs) >= MESSAGE_HEALTH_CRITICAL_MS ? "critical"
+            : Math.max(ageMs, occupancyMs) >= MESSAGE_HEALTH_WARNING_MS ? "warning" : "waiting";
+    }
+    return { state, reason, ageMs, occupancyMs };
+}
+// Display-only shell arguments; guidance never executes these commands.
+function arg(value) {
+    return /^[a-zA-Z0-9_.:/-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`;
+}
+function recoveryGuidance(o) {
+    const { taskId, roleName } = o.target;
+    const owner = taskId === undefined ? "Operator (or the user if Operator itself is unavailable)"
+        : roleName === "leader" ? "Operator; the affected Leader must not synchronously stop itself"
+            : "the authorized Task Leader, or Operator";
+    const retryRead = taskId === undefined ? `yui session retry ${arg(roleName)} show`
+        : `yui task role session retry ${arg(taskId)} ${arg(roleName)} show`;
+    const lines = [
+        `Responsible: ${owner}. Guidance is not authorization and executes nothing.`,
+        `Snapshot ${o.observedAt}; Current state: ${o.state}; reason: ${o.reason}. Refresh yui controller status --verbose --json before acting; an old notice is not a current instruction.`,
+        `Exact target: Session=${o.session ?? "unreported"}, attempt=${o.attemptId ?? "unreported"}, batch=${o.batchId ?? "none"}, wake=${o.wakeId ?? "none"}.`,
+        `Read first: ${[...o.reads, retryRead, ...(o.deliveryEvidence ? [o.deliveryEvidence.read] : [])].join("; ")}.`,
+        "Check current CLI help and reported Host capabilities as the responsible caller. Missing capability, inaccessible evidence or an identity change blocks the proposed action; do not guess another command or target."
+    ];
+    if (o.state === "recovering") {
+        lines.push("Existing bounded retry owns recovery. Observe its exact attempt/deadline; do not duplicate or interrupt it. Escalate its retained failure only if exhausted or needs-attention.");
+    }
+    else if (o.state === "busy" || o.state === "waiting") {
+        lines.push("No intervention is indicated: accepted work or claimed handling can be slow. Inspect actual progress and delivery evidence; silence or a missing ACK is not permission to interrupt.");
+    }
+    else if (o.state === "paused") {
+        lines.push("Respect the deliberate stop/pause, human ownership, matching InputRequest or pending lifecycle cleanup. Inspect that existing obligation; this notice does not authorize resumption or another stop.");
+    }
+    else if (o.state === "clear") {
+        lines.push("Only delivery backlog clearance was observed. No management action is indicated; inspect original inputs and handling before concluding business recovery.");
+    }
+    else if (taskId === undefined) {
+        lines.push("No per-GlobalRole Host-stop command is established by this candidate. Read the original Global Message/control and retry evidence; use current caller capability discovery for a supported targeted lifecycle action. Do not translate Task commands to a GlobalRole or use a stop-all fallback.");
+    }
+    else {
+        const target = `${arg(taskId)} ${arg(roleName)}`;
+        lines.push("Choose only the path matching refreshed evidence, not a stop/replace/retry sequence. Prefer correction plus guarded retry for a proven rejection when sufficient; stop is for an independently established residual Host barrier, and replacement is not the default.");
+        lines.push(`Observed barrier: delivery=${o.deliveryEvidence?.outcome ?? "unreported"}; detail=${o.deliveryEvidence?.detail ?? "unreported"}; Host=${o.hostObservation.state}/${o.hostObservation.reconciliation ?? "unreported"}; retry=${o.retry?.status ?? "unreported"}. These observations do not establish quiescence or prove Goal is the cause; do not clear Goal merely because it says stalled.`);
+        if (o.session !== null && o.blocked) {
+            lines.push(`For confirmed residual Host ownership, the responsible supervisor may consider the existing targeted management path without waiting for a full repair package or every historical projection to align. Template: yui task role session stop ${target} --reason '<verified target, authority and stop rationale>'. First refresh the exact Session/Host identity, native/background work and event persistence; normal busy work, owned retry, intentional pause, unpersisted Host events or unknown cleanup consequences block a routine stop. The CLI captures and fences the current target; this snapshot cannot pin a later invocation.`);
+            lines.push("A stop request being saved is not physical stop. Require the exact Host/resource cleanup result; if cleanup fails or volatile facts remain, retain that process and evidence and escalate the precise boundary, without force-kill or claiming it stopped. After proven stop, let existing authorized delivery/lifecycle reuse the retained conversation when supported; verify the actual native Session identity, never infer reuse from Host ready.");
+            lines.push(`Only if reuse is unsuitable and deliberate replacement is justified, preserve durable progress and use the separately authorized template: yui task role session new ${target} --reason '<why replacement is necessary>'. This requests fresh Session selection after fenced cleanup, not same-conversation reuse. A self-replacing Leader must end its turn. Retained inputs/claims still require inspection, not replay.`);
+        }
+        else {
+            lines.push("A current controlled Session/residual Host barrier is not established. Inspect the missing runtime or Assignment evidence first; no targeted stop is recommended from this snapshot.");
+        }
+        if (o.wakeId !== null && roleName === "leader") {
+            const wakeTarget = `${arg(taskId)} ${arg(o.wakeId)}`;
+            if (o.deliveryEvidence?.outcome === "rejected") {
+                lines.push(`After correcting the rejection cause, and only if this exact wake is still unconsumed, its original claim matches and native acceptance/activity are proven absent: yui task wake retry ${wakeTarget} --reason '<verified correction and quiescence>'. Queued is not accepted. Do not retry accepted/unknown input. This candidate does not establish resolve support for rejected wakes; do not assume another recovery package is installed.`);
+            }
+            else if (o.deliveryEvidence?.outcome === "unknown") {
+                lines.push(`Do not replay unknown input. After exact shared-native/background/writer quiescence and persisted evidence, with the original unknown claim still current: yui task wake resolve ${wakeTarget} --reason '<exact quiescence evidence>'. This releases only scheduling without replay, ACK or acceptance. The rightful handler must inspect original effects and settle still-valid obligations separately.`);
+            }
+            else {
+                lines.push("Deferred, accepted or unreported delivery does not meet this candidate's rejected-retry/unknown-resolve preconditions. Keep the original wake and inspect the runtime barrier instead of mechanically invoking either action.");
+            }
+        }
+    }
+    lines.push("Verify separately: management request saved; exact physical stop if requested; retained conversation reused or explicit replacement recorded; subsequent original wake/message actually accepted by Provider; real handling/progress and remaining obligations. Host ready, pending=0, command success or alert ACK alone proves none of the later stages. If evidence is missing, recovery remains unverified.");
+    lines.push("If an action is refused or fails, retain its exact target, receipt/error, original input and workspace; report the smallest missing capability, authority or cleanup evidence to the responsible supervisor. No private retry loop, forced ACK, queue clearing, raw DB edits, unknown-effect replay, model/account/permission changes or whole-Controller/all-Session restart.");
+    return lines.join("\n");
+}
+function eventType(roleName) { return `message.health.${roleName}`; }
+function prefix(target) { return `${HEADER}${target.roleName}\n`; }
+function noticeId(saved) { return NOTICE + encodeURIComponent(saved.id); }
+function latest(store, target) {
+    if (target.taskId !== undefined) {
+        const event = store.queryContextRecords(target.taskId, { family: "task-event",
+            eventTypes: [eventType(target.roleName)], descending: true, limit: 1 }).records[0]?.value;
+        return event ? { id: `${target.taskId}/${event.id}`,
+            read: `yui task event show ${arg(target.taskId)} ${arg(event.id)}`,
+            evidence: JSON.parse(event.payload.evidence) } : null;
+    }
+    const message = store.queryGlobalRoleMessages(target.roleName, {
+        systemBodyPrefix: prefix(target), descending: true, limit: 1
+    }).messages[0];
+    return message ? { id: `${target.roleName}/${message.id}`,
+        read: `yui role message show ${arg(target.roleName)} ${arg(message.id)}`,
+        evidence: JSON.parse(message.body.slice(prefix(target).length)) } : null;
+}
+function record(store, target, evidence, now) {
+    if (target.taskId !== undefined) {
+        const event = createTaskEvent(store.nextEventId(target.taskId), target.taskId, eventType(target.roleName), { evidence: JSON.stringify(evidence) }, now);
+        store.saveEvent(target.taskId, event);
+        return { id: `${target.taskId}/${event.id}`, read: `yui task event show ${arg(target.taskId)} ${arg(event.id)}`, evidence };
+    }
+    const message = createGlobalRoleMessage(store.nextGlobalRoleMessageId(), target.roleName, prefix(target) + JSON.stringify(evidence), "system", { type: "system" }, now);
+    store.saveGlobalRoleMessage(message);
+    return { id: `${target.roleName}/${message.id}`, read: `yui role message show ${arg(target.roleName)} ${arg(message.id)}`, evidence };
+}
+function alertStatus(store, saved) {
+    if (!saved)
+        return { stage: "not-generated", reason: null, messageId: null };
+    const message = store.queryGlobalRoleMessages("operator", {
+        requestId: noticeId(saved), limit: 1
+    }).messages[0];
+    if (message?.inbox?.ack)
+        return { stage: "handled", reason: null, messageId: message.id };
+    if (message?.delivery)
+        return { stage: message.delivery.via === "provider" ? "delivered" : "transport-accepted",
+            reason: message.delivery.via === "provider" ? null : "provider-acceptance-unconfirmed", messageId: message.id };
+    if (message)
+        return { stage: "saved", messageId: message.id,
+            reason: message.notDelivered?.reason ?? message.control?.outcome
+                ?? (store.getGlobalRole("operator")?.enabled === false ? "operator-disabled"
+                    : globalInputBacklog([message], store.getGlobalRoleSessionSet("operator")).reason) };
+    return { stage: "generated", messageId: null,
+        reason: store.getGlobalRole("operator") === null ? "operator-unconfigured"
+            : operatorAvailable(store) ? "operator-notice-pending" : "operator-unavailable" };
+}
+function operatorAvailable(store) {
+    const sessions = store.getGlobalRoleSessionSet("operator");
+    return sessions?.sessions[sessions.activeAgentId]?.status === "active" && sessions.providerBinding != null;
+}
+/** Same Global Message queue and receipt contract as ordinary Operator notices.
+ * No Task mailbox is involved. A busy/unavailable Operator never loses evidence.
+ * At most one unsent engineering notice; original failed notices are not replayed. */
+function notify(store, saved, observation, now) {
+    if (store.getGlobalRole("operator") === null
+        || !operatorAvailable(store)
+        || store.queryGlobalRoleMessages("operator", { requestId: noticeId(saved), limit: 1 }).count
+        || store.queryGlobalRoleMessages("operator", { pending: true, operatorNotice: true, limit: 1 }).count)
+        return;
+    const { phase } = saved.evidence;
+    const sessions = store.getGlobalRoleSessionSet("operator");
+    const session = sessions.sessions[sessions.activeAgentId];
+    const message = createGlobalRoleMessage(store.nextGlobalRoleMessageId(), "operator", [
+        `Yui-Summary: Message delivery ${observation.state}: ${observation.target.taskId ?? "global"}/${observation.target.roleName} (retained ${phase} evidence).`,
+        `Inspect: ${saved.read}`,
+        `Original diagnostic phase=${phase}, first=${saved.evidence.firstAt}, latest evidence=${saved.evidence.at}; guidance below uses the current observation.`,
+        "Independent diagnostics: yui controller status --verbose --json",
+        `Waiting=${observation.count}, pending=${observation.pendingCount}, processing=${observation.processingCount}, ageMs=${observation.ageMs}, occupancyMs=${observation.occupancyMs}; answered inputs=${observation.answeredInputs.join(", ") || "none observed"}.`,
+        observation.recovery,
+        "Do not ACK business inputs, release unknown writers, replay input, replace Sessions or change models automatically."
+    ].join("\n"), "system", { type: "system" }, now, { inputControl: { action: "queue", requestId: noticeId(saved) } });
+    store.saveGlobalRoleMessage({ ...message,
+        deliveryTarget: { agentId: session.agentId, nativeSessionId: session.nativeSessionId } });
+}
+function oldest(times) {
+    return times.filter((time) => time != null).sort()[0] ?? null;
+}
+function observe(store, target, now, hosts) {
+    const { taskId, roleName } = target;
+    const owner = taskId === undefined ? { scope: "global", roleName }
+        : { scope: "task", taskId, roleName };
+    const task = taskId === undefined ? null : store.getTask(taskId);
+    const role = taskId === undefined ? store.getGlobalRole(roleName) : store.getRole(taskId, roleName);
+    const sessions = taskId === undefined ? store.getGlobalRoleSessionSet(roleName)
+        : store.getTaskRoleSessionSet(taskId, roleName);
+    const session = sessions?.sessions[sessions.activeAgentId];
+    const binding = sessions?.providerBinding;
+    const currentBinding = binding != null && session !== undefined
+        && binding.conversations.some(conversation => conversation.status === "current"
+            && conversation.epoch === binding.currentConversationEpoch && conversation.conversationId === session.nativeSessionId);
+    const turn = currentBinding && binding?.run?.authorityEpoch === binding.authority.epoch ? binding.run : null;
+    const mailbox = taskId === undefined
+        ? roleName === "operator" ? store.getWorkMailbox({ kind: "operator" }) : null
+        : store.getWorkMailbox({ kind: "role", taskId, roleName });
+    const handlingOnly = mailbox?.processing?.owner.startsWith("agent-inbox:") ?? false;
+    const batches = [mailbox?.pending, handlingOnly ? null : mailbox?.processing?.batch].filter(batch => batch != null);
+    const refs = batches.flatMap(batch => [...batch.refs]);
+    const wakeId = mailbox?.processing?.owner.startsWith("leader-notification:")
+        ? mailbox.processing.owner.slice("leader-notification:".length) : null;
+    const wake = wakeId && taskId ? store.getTaskWake(taskId, wakeId) : null;
+    const delivery = taskId && mailbox?.processing ? store.queryContextRecords(taskId, {
+        family: "task-event", eventTypes: ["notification.delivery"],
+        eventAttemptId: mailbox.processing.batchId, descending: true, limit: 1
+    }).records[0]?.value : undefined;
+    // Delivery failures stay visible even when ordinary pending excludes notDelivered.
+    // Handling-only historical receipts never become new queue work.
+    const globalPage = taskId === undefined ? store.queryGlobalRoleMessages(roleName, {
+        awaitingDelivery: true, unclaimed: true, excludeHealthNotices: true, limit: 8
+    }) : null;
+    const handling = handlingOnly || taskId === undefined && store.queryGlobalRoleMessages(roleName, {
+        awaitingDelivery: true, handling: true, excludeHealthNotices: true, limit: 1
+    }).count > 0;
+    const messages = globalPage?.messages ?? [];
+    const taskPage = taskId === undefined ? null : store.queryContextRecords(taskId, {
+        family: "task-message", queuedForRole: roleName, unhandledMessages: true, limit: 8
+    });
+    const taskMessages = taskPage?.records.map(record => record.value) ?? [];
+    const host = hosts.find(item => item.taskId === taskId && item.roleName === roleName
+        && item.attemptId === turn?.attemptId && item.nativeSessionId === session?.nativeSessionId);
+    let hostObservation = host
+        ? { state: host.state, observedAt: host.observedAt, reconciliation: host.reconciliation }
+        : { state: "unobserved", observedAt: null, reconciliation: null };
+    if (taskId === undefined && turn?.status === "accepted") {
+        // Reuse existing Global Host failure evidence, never probe a second time.
+        const failure = store.queryGlobalRoleMessages(roleName, {
+            systemBodyPrefix: "Yui Global failure evidence ", descending: true, limit: 1
+        }).messages[0];
+        if (failure) {
+            const facts = JSON.parse(failure.body.slice(failure.body.indexOf("\n") + 1));
+            if (facts.reason === "host-terminal-unobservable" && facts.attemptId === turn.attemptId
+                && facts.nativeSessionId === session?.nativeSessionId && failure.createdAt >= turn.updatedAt) {
+                hostObservation = { state: typeof facts.hostState === "string" ? facts.hostState : "unobservable",
+                    observedAt: failure.createdAt, reconciliation: facts.cause ?? null };
+            }
+        }
+    }
+    const count = batches.reduce((n, batch) => n + batch.requestCount, 0)
+        + (globalPage?.count ?? 0) + (taskPage?.count ?? 0);
+    const answeredInputs = refs.flatMap(ref => {
+        if (ref.type !== "input")
+            return [];
+        return store.getInputRequest(ref.taskId, ref.id)?.status === "answered" ? [`${ref.taskId}/${ref.id}`] : [];
+    });
+    // Only explicit matching blocked refs constitute a user wait. An unrelated
+    // open InputRequest must not hide an answered input stuck in the same Task.
+    const waitingInputs = taskId === undefined || roleName === "leader" ? [] :
+        store.listOpenInputRequests([taskId]).filter(request => request.blockedRefs.some(ref => ref.type === "run" && refs.some(queued => queued.type === "run" && queued.id === ref.id)
+            || ref.type === "work-item" && taskMessages.some(message => message.recipient?.workItemId === ref.id)))
+            .map(request => request.id);
+    const facts = {
+        count, handling, oldestAt: oldest([...batches.map(batch => batch.firstQueuedAt), globalPage?.oldestCreatedAt,
+            taskMessages[0]?.createdAt]),
+        processingAt: handlingOnly && count === 0 ? null : mailbox?.processing?.startedAt ?? null,
+        blocked: mailbox?.processing != null && wake?.status !== "consumed"
+            && turn?.status !== "accepted"
+            || messages.some(message => message.notDelivered !== undefined
+                || message.control?.outcome === "delivery-unknown" || message.control?.outcome === "pending")
+            || taskMessages.some(message => message.continuation?.notDeliveredReason !== undefined)
+            || ["idle", "failed", "exited", "unobservable"].includes(hostObservation.state)
+                && hostObservation.reconciliation !== "terminal-republished",
+        stopped: role?.enabled === false || session?.endReason === "stopped"
+            || task !== null && (!["active", "draft"].includes(task.status) || task.executionGate.state !== "enabled")
+            || binding?.authority.owner === "human" || binding?.goal?.status === "paused"
+            || waitingInputs.length > 0
+            || hasRuntimeCleanupObligation(store.getWorkMailbox(runtimeLifecycleTarget(owner))),
+        turnStatus: turn?.status,
+        ...(currentBinding && providerRetryPending(binding)
+            && binding.retry.nativeSessionId === session.nativeSessionId
+            && binding.retry.authorityEpoch === binding.authority.epoch ? { retryDeadline: binding.retry.deadline } : {})
+    };
+    const classification = classifyMessageHealth(facts, now);
+    const readBase = taskId ? `yui task role session inspect ${arg(taskId)} ${arg(roleName)}`
+        : `yui config role show ${arg(roleName)}`;
+    const observation = {
+        ...facts, ...classification, target, observedAt: now.toISOString(),
+        session: session?.nativeSessionId ?? null, agentId: session?.agentId ?? null, hostObservation,
+        attemptId: turn?.attemptId ?? null, nativeTurnId: turn?.nativeTurnId ?? null,
+        host: binding?.authority.holderId ?? null, authority: binding?.authority.owner ?? null,
+        retry: binding?.retry ? { status: binding.retry.status, deadline: binding.retry.deadline,
+            attempts: binding.retry.attempts } : null,
+        wakeId, batchId: mailbox?.processing?.batchId ?? null, processingOwner: mailbox?.processing?.owner ?? null,
+        deliveryEvidence: delivery ? { outcome: delivery.payload.outcome ?? "unreported",
+            detail: delivery.payload.detail ?? null,
+            read: `yui task event show ${arg(taskId)} ${arg(delivery.id)}` } : null,
+        pendingCount: (mailbox?.pending?.requestCount ?? 0) + (globalPage?.count ?? 0) + (taskPage?.count ?? 0),
+        processingCount: mailbox?.processing?.batch.requestCount ?? 0,
+        pendingSince: mailbox?.pending?.firstQueuedAt ?? globalPage?.oldestCreatedAt ?? taskMessages[0]?.createdAt ?? null,
+        waitingInputs,
+        refs: [...refs.slice(0, 8), ...messages.map(message => ({
+                messageId: message.id, control: message.control ?? null, notDelivered: message.notDelivered ?? null
+            })), ...taskMessages.map(message => ({
+                messageId: message.id, recipient: message.recipient, continuation: message.continuation ?? null
+            }))], omittedRefs: Math.max(0, refs.length - 8) + Math.max(0, (globalPage?.count ?? 0) - messages.length)
+            + Math.max(0, (taskPage?.count ?? 0) - taskMessages.length),
+        answeredInputs: answeredInputs.slice(0, 8),
+        reads: [readBase, ...(wakeId && taskId ? [`yui task wake show ${arg(taskId)} ${arg(wakeId)}`] : []),
+            ...messages.map(message => `yui role message show ${arg(roleName)} ${arg(message.id)}`),
+            ...taskMessages.map(message => `yui task message show ${arg(`${taskId}/${message.id}`)}`)]
+    };
+    return { ...observation, recovery: recoveryGuidance(observation) };
+}
+/** Low-rate Controller observation, not an Agent loop. All decisions use current
+ * records inside each short transaction; evidence + queue admission are atomic.
+ * Open Event/Message content carries audit facts; no new storage envelope/index
+ * or independently writable scheduler state is introduced. */
+export function reconcileMessageHealth(store, now = new Date(), hosts = []) {
+    const targets = store.listTasks().filter(task => task.status !== "archived").flatMap(task => store.listRoles(task.id).map(role => ({ taskId: task.id, roleName: role.name })));
+    targets.push(...store.listGlobalRoles().map(role => ({ roleName: role.name })));
+    const items = [];
+    for (const target of targets) {
+        store.transaction(tx => {
+            const observation = observe(tx, target, now, hosts);
+            let saved = latest(tx, target);
+            const previous = saved?.evidence;
+            const active = previous !== undefined && previous.phase !== "recovered";
+            const growing = active && observation.state === "warning" && observation.ageMs >= 15 * 60_000
+                && observation.count >= Math.max(8, previous.initialCount * 2);
+            const desired = growing ? "critical" : observation.state;
+            const phase = desired === "warning" || desired === "critical"
+                ? (!active || desired === "critical" && previous.phase === "warning" ? desired : null)
+                : desired === "clear" && active ? "recovered" : null;
+            if (phase !== null) {
+                saved = record(tx, target, {
+                    phase, firstAt: active ? previous.firstAt : now.toISOString(), at: now.toISOString(),
+                    initialCount: active ? previous.initialCount : observation.count,
+                    peakCount: Math.max(active ? previous.peakCount : 0, observation.count),
+                    previous: saved?.id ?? null, observation
+                }, now);
+            }
+            if (saved !== null)
+                notify(tx, saved, observation, now);
+            if (observation.count > 0 || observation.processingAt !== null || saved !== null) {
+                items.push({ ...observation, evidence: saved?.read ?? null, alert: alertStatus(tx, saved),
+                    incident: saved ? { phase: saved.evidence.phase, firstAt: saved.evidence.firstAt,
+                        latestEvidenceAt: saved.evidence.at, initialCount: saved.evidence.initialCount } : null });
+            }
+        });
+    }
+    // Status is an O(1) cached bounded view; exact originals remain independently readable.
+    const priority = (state) => state === "critical" ? 0 : state === "warning" ? 1 : state === "clear" ? 3 : 2;
+    items.sort((a, b) => priority(a.state) - priority(b.state) || b.ageMs - a.ageMs);
+    return { observedAt: now.toISOString(), warningAfterMs: MESSAGE_HEALTH_WARNING_MS,
+        criticalAfterMs: MESSAGE_HEALTH_CRITICAL_MS, total: items.length, omitted: Math.max(0, items.length - 64),
+        items: items.slice(0, 64) };
+}

package/dist/controller/runtime.js

@@ -1,4 +1,7 @@
 import { isDeepStrictEqual } from "node:util";
+import { ControllerDiagnosticJournal } from "./diagnosticJournal.js";
+import { reconcileMessageHealth } from "./messageHealth.js";
+import { monotonicMilliseconds } from "../core/controllerTelemetry.js";
 import { prepareNativeHostSteer } from "./nativeHostInput.js";
 import { archiveLeaderTask } from "../task/leaderArchive.js";
 import { TaskWorkspaceCoordinator } from "../repository/taskWorkspaceCoordinator.js";
@@ -61,7 +64,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";
@@ -72,8 +74,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);
@@ -111,6 +159,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, {
@@ -532,7 +584,10 @@ 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"
+        let messageHealthHosts = [];
+        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), {
@@ -551,6 +606,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,
@@ -573,7 +629,13 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
                 }
             }),
             jobSupervisor,
-            hostTerminalRecovery: () => recoverTaskHostTerminals(home, store, options.onError ?? (() => undefined)),
+            messageHealth: async (now) => workerMaintenance
+                ? await asyncStoreClient.invokeObserver("reconcileMessageHealth", [now, messageHealthHosts])
+                : reconcileMessageHealth(store, now, messageHealthHosts),
+            hostTerminalRecovery: async () => {
+                messageHealthHosts = [];
+                messageHealthHosts = await recoverTaskHostTerminals(home, store, options.onError ?? (() => undefined));
+            },
             globalInputDelivery: (deliveryOptions) => deliverGlobalInputs(home, store, async (roleName) => {
                 await lifecycleDispatcher("runtime.ensure-role-session", { scope: "global", roleName });
             }, options.onError ?? (() => undefined), deliveryOptions),
@@ -581,8 +643,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);
                 }
             },
@@ -600,6 +666,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,

package/dist/controller/taskHostTerminalRecovery.js

@@ -3,6 +3,7 @@ import { currentProviderConversation } from "../runtime/providerRuntimeIdentity.
 import { providerRetryPending } from "../runtime/providerRetry.js";
 /** Existing full reconciliation pass only; no new timer, input or Session. */
 export async function recoverTaskHostTerminals(home, store, onError, reconcile = reconcileAgentHostTurn) {
+    const observations = [];
     for (const candidate of store.listRuntimeSessionCandidates({ scope: "task" })) {
         const owner = candidate.owner;
         if (owner.scope !== "task")
@@ -20,14 +21,24 @@ export async function recoverTaskHostTerminals(home, store, onError, reconcile =
                     attemptId: turn.attemptId, nativeTurnId: turn.nativeTurnId,
                     authority: { epoch: binding.authority.epoch, owner: "controller", holderId: binding.authority.holderId }
                 } });
+            observations.push({ taskId: owner.taskId, roleName: owner.roleName,
+                nativeSessionId: currentProviderConversation(binding).conversationId, attemptId: turn.attemptId,
+                state: result.snapshot.state, reconciliation: result.reconciliation ?? null,
+                outcome: result.outcome, observedAt: new Date().toISOString() });
             if (result.outcome === "rejected" || result.reconciliation === "unsupported") {
                 throw new Error(result.failure?.detail
                     ?? "Host terminal reconciliation is unsupported; retain the original input and inspect Host/Inbox evidence.");
             }
         }
         catch (error) {
+            if (!observations.some(item => item.taskId === owner.taskId && item.roleName === owner.roleName)) {
+                observations.push({ taskId: owner.taskId, roleName: owner.roleName,
+                    nativeSessionId: currentProviderConversation(binding).conversationId, attemptId: turn.attemptId,
+                    state: "unobservable", reconciliation: null, outcome: "unavailable", observedAt: new Date().toISOString() });
+            }
             onError(new Error(`Task Host terminal recovery ${owner.taskId}/${owner.roleName}/${turn.attemptId}: `
                 + `${error instanceof Error ? error.message : String(error)} No input was replayed.`, { cause: error }));
         }
     }
+    return observations;
 }