@zq-silk/yui 2.8.1 → 2.10.0

package/dist/controller/controller.js

@@ -689,6 +689,7 @@ export class FileTaskController {
     #onMaintenanceFenceDefer;
     #leaderWakeFence;
     #jobSupervisor;
+    #schedules;
     #globalInputDelivery;
     #providerRetry;
     #continuationReconciler;
@@ -741,6 +742,7 @@ export class FileTaskController {
         this.#onMaintenanceFenceDefer = options.onMaintenanceFenceDefer;
         this.#leaderWakeFence = options.leaderWakeFence;
         this.#jobSupervisor = options.jobSupervisor;
+        this.#schedules = options.schedules;
         this.#continuationReconciler = options.continuationReconciler;
         this.#hostTerminalRecovery = options.hostTerminalRecovery;
         this.#globalInputDelivery = options.globalInputDelivery;
@@ -1014,6 +1016,7 @@ export class FileTaskController {
                     // DurableJob reconciliation runs before the scheduler pass so a
                     // terminal job's Leader wakeup is enqueued in the same pass that
                     // processes Leader wakeups.
+                    this.#schedules?.reconcile(this.#now());
                     this.#jobSupervisor?.reconcile(this.#now());
                     if (scope.kind === "full") {
                         result = await runControllerSchedulerPass(this.store, this.delivery, this.#now(), this.#workspacePreparer, scope, false, runtimeCleanupOutcomes, this.#lifecycleHost, this.#stallWindowMs, this.#maintenanceFence, this.#onMaintenanceFenceDefer, runtimeFailedTaskIds, this.#diagnosticAfterMs, this.#leaderWakeFence, this.#onError);
@@ -1631,6 +1634,38 @@ export async function startFileTaskController(home, store, delivery, dispatcher,
                     lifecycleRequests.delete(request);
                 }
             }
+            if (method === "schedule.control") {
+                if (options.schedules === undefined)
+                    throw controllerApplicationError("METHOD_NOT_FOUND", "Schedules unavailable.");
+                try {
+                    return jobControlJson(options.schedules.control(params, options.now?.() ?? new Date()));
+                }
+                catch (error) {
+                    if (error instanceof Error && error.name === "Error")
+                        error.name = "CoreJobError";
+                    throw error;
+                }
+            }
+            if (method === "job.definition") {
+                if (options.jobDefinitions === undefined)
+                    throw controllerApplicationError("METHOD_NOT_FOUND", "Job definitions unavailable.");
+                let result;
+                try {
+                    result = options.jobDefinitions(params, new Date());
+                }
+                catch (error) {
+                    if (error instanceof Error && error.name === "Error")
+                        error.name = "CoreJobError";
+                    throw error;
+                }
+                // The service has validated this scope. Only execution mutations need
+                // reconciliation; definition reads/edits do not start background work.
+                const input = params;
+                if (["run", "run-cancel", "run-acknowledge"].includes(input.op)) {
+                    runtime.signal(input.scope.kind === "task" ? `task:${input.scope.taskId}` : "operator");
+                }
+                return jobControlJson(result);
+            }
             if (method === "job.start" || method === "job.get" || method === "job.cancel" || method === "job.acknowledge") {
                 const control = options.jobControl;
                 if (control === undefined) {

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { deliveredMessageWake, pinMessageRevisions, taskMessageInboxReceipt, unfinishedLeaderInbox } from "../message/taskInboxOwnership.js";
+import { nonReplayableMessageWake, pinMessageRevisions, taskMessageInboxReceipt, unfinishedLeaderInbox } from "../message/taskInboxOwnership.js";
 import { contextSnapshotRef } from "../context/contextSnapshot.js";
 import { freezeRunContextSnapshot } from "../context/runContextPack.js";
 import { taskNotificationPresentation } from "../interaction/notificationPresentation.js";
@@ -30,6 +30,7 @@ import { SYSTEM_OPERATOR_ROLE } from "../role/systemRoles.js";
 import { standardAgentError } from "../runtime/agentError.js";
 import { recordTaskAgentError } from "./taskAgentError.js";
 import { recordGlobalRuntimeAttention, recordGlobalRuntimeFailure, recordGlobalRuntimeRecovery } from "./globalRuntimeAttention.js";
+import { checkInboxTurn } from "./inboxTurnCheck.js";
 import { queueOperatorNotification } from "./operatorNotification.js";
 import { claimOperatorAttention } from "../scheduler/operatorEvent.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
@@ -466,7 +467,7 @@ export class FileSchedulerStoreAdapter {
                     const outcome = input.kind === "input.accepted" ? "accepted"
                         : input.kind === "input.rejected" ? "rejected" : "delivery-unknown";
                     if (message.control?.outcome !== "accepted" && message.control?.outcome !== "rejected") {
-                        const updated = { ...message, control: { requestId: message.inputControl.requestId,
+                        const updated = { ...message, control: { ...message.control, requestId: message.inputControl.requestId,
                                 receiptId: receipt, outcome, observedAt: at } };
                         store.updateGlobalRoleMessage(outcome === "accepted"
                             ? markGlobalRoleMessageDelivered(updated, new Date(at)) : updated);
@@ -490,6 +491,10 @@ export class FileSchedulerStoreAdapter {
             }
             store.saveGlobalRoleSessionSet(updateGlobalRoleProviderRuntime(sessions, binding, now));
             settleGlobalRetryInput(store, fence.roleName, binding, now);
+            if (["turn.completed", "turn.failed", "turn.cancelled"].includes(input.kind)) {
+                checkInboxTurn(store, { scope: "global", roleName: fence.roleName, agentId: fence.agentId,
+                    nativeSessionId: fence.nativeSessionId }, binding.run, now);
+            }
             if (input.kind === "turn.failed" && matches && input.payload.failure !== undefined
                 && !providerRetryPending(binding)) {
                 recordGlobalRuntimeAttention(store, fence.roleName, input.eventId, {
@@ -1157,8 +1162,7 @@ export class FileSchedulerStoreAdapter {
                     throw new AgentHostProviderSessionBusyError("The next Global input belongs to an explicit then handoff.");
                 }
                 if (message !== undefined) {
-                    if (store.queryGlobalRoleMessages(input.roleName, { handling: true, limit: 0 }).count > 0
-                        || message.inbox !== undefined || message.delivery !== undefined || message.notDelivered !== undefined
+                    if (message.inbox !== undefined || message.delivery !== undefined || message.notDelivered !== undefined
                         || message.control !== undefined && message.control.outcome !== "rejected"
                         || message.deliveryTarget?.agentId !== input.agentId
                         || message.deliveryTarget?.nativeSessionId !== input.nativeSessionId) {
@@ -1535,8 +1539,9 @@ export class FileSchedulerStoreAdapter {
         });
     }
     listActiveDurableJobs() {
-        return this.store.listActiveDurableJobs();
+        return [...this.store.listActiveDurableJobs(), ...this.store.listActiveGlobalJobRuns()];
     }
+    getGlobalJobRun(id) { return this.store.getGlobalJobRun(id); }
     /**
      * Apply one durable-job transition and, in the SAME transaction, enqueue
      * the Leader wakeup. A terminal job without its wakeup enqueued is a lost
@@ -1548,10 +1553,24 @@ export class FileSchedulerStoreAdapter {
      */
     transitionDurableJob(taskId, jobId, transition, now, wakeup) {
         return this.store.transaction((store) => {
+            if (taskId === "global") {
+                const current = store.getGlobalJobRun(jobId);
+                if (current === null)
+                    return null;
+                const next = transition(current);
+                if ("taskId" in next)
+                    throw new Error("A global JobRun cannot change scope.");
+                store.saveGlobalJobRun(next);
+                if (wakeup !== undefined)
+                    enqueueWork(store, { kind: "operator" }, "global-job-finished", now, [{ type: "global-job-run", id: jobId }], { source: "global-job", dedupeKey: `operator-global-job-run:${jobId}` });
+                return next;
+            }
             const current = store.getDurableJob(taskId, jobId);
             if (current === null)
                 return null;
             const next = transition(current);
+            if (!("taskId" in next))
+                throw new Error("A Task JobRun cannot change scope.");
             store.saveDurableJob(taskId, next);
             if (wakeup !== undefined) {
                 enqueueWork(store, { kind: "role", taskId, roleName: "leader" }, wakeup.reason, now, [...wakeup.refs]);
@@ -1672,12 +1691,24 @@ export class FileSchedulerStoreAdapter {
                     store.saveTaskRoleSessionSet(selectNewTaskRoleSession(set, set.activeAgentId, now));
                 const event = createTaskEvent(store.nextEventId(owner.taskId), owner.taskId, "runtime.session-replaced", { roleName: owner.roleName }, now);
                 store.saveEvent(owner.taskId, event);
-                // Accepted notification batches are already consumed; unresolved old
-                // claims belong to the discarded runtime, not to its successor.
+                // Release only operational occupancy after exact runtime stop. Neither
+                // an uncertain automatic submission nor an Agent's handling claim may
+                // be replayed as input to the replacement.
                 const leaderTarget = { kind: "role", taskId: owner.taskId, roleName: "leader" };
                 const leaderMailbox = store.getWorkMailbox(leaderTarget);
-                if (owner.roleName === "leader" && leaderMailbox?.processing?.owner.startsWith("leader-notification:")) {
-                    store.saveWorkMailbox(releaseProcessing(leaderMailbox, leaderMailbox.processing.batchId));
+                if (owner.roleName === "leader" && leaderMailbox?.processing != null) {
+                    const processing = leaderMailbox.processing;
+                    if (processing.owner.startsWith("leader-notification:")) {
+                        store.saveEvent(owner.taskId, createTaskEvent(store.nextEventId(owner.taskId), owner.taskId, "notification.resolved", {
+                            wakeId: processing.owner.slice("leader-notification:".length), attemptId: processing.batchId,
+                            reason: "Session replacement after verified native/resource stop; inspect original effects.",
+                            outcome: "released-without-replay"
+                        }, now));
+                        store.saveWorkMailbox(completeProcessing(leaderMailbox, processing.batchId));
+                    }
+                    else if (processing.owner.startsWith("agent-inbox:")) {
+                        store.saveWorkMailbox(completeProcessing(leaderMailbox, processing.batchId));
+                    }
                 }
                 enqueueWork(store, leaderTarget, "session-replaced", now, [{ type: "event", taskId: owner.taskId, id: event.id }]);
             }
@@ -1824,6 +1855,24 @@ export class FileSchedulerStoreAdapter {
             if (mailbox === null)
                 return null;
             const provider = store.getTaskRoleSessionSet(taskId, "leader")?.providerBinding?.run;
+            // Only a committed lifecycle event opens this initialization path, not a
+            // caller-supplied reason string. Consume that event once, separately from
+            // business input. It exists only after exact-owner cleanup completed.
+            const recoveryRefs = mailbox.pending?.reasons.includes("session-replaced")
+                ? mailbox.pending.refs.filter(ref => {
+                    if (ref.type !== "event" || ref.taskId !== taskId)
+                        return false;
+                    const event = store.queryContextRecords(taskId, { family: "task-event", ids: [ref.id],
+                        eventTypes: ["runtime.session-replaced"], limit: 1 }).records[0]?.value;
+                    return event?.payload.roleName === "leader";
+                }) : [];
+            // Valid earlier storage may retain an actively claimed mailbox even
+            // after replacement completed. Its durable wake/claim remains untouched.
+            if (recoveryRefs.length > 0 && mailbox.processing?.owner.startsWith("agent-inbox:")
+                && !(provider && ["submitting", "accepted", "delivery-unknown"].includes(provider.status))) {
+                mailbox = completeProcessing(mailbox, mailbox.processing.batchId);
+                store.saveWorkMailbox(mailbox);
+            }
             const processing = mailbox.processing;
             if (processing !== null) {
                 if (!processing.owner.startsWith("leader-notification:"))
@@ -1867,7 +1916,7 @@ export class FileSchedulerStoreAdapter {
                 return { wakeId, attemptId: nextAttempt, disposition: "submit",
                     presentation: taskNotificationPresentation(wake, store) };
             }
-            if (unfinishedLeaderInbox(store, taskId))
+            if (unfinishedLeaderInbox(store, taskId) && recoveryRefs.length === 0)
                 return null;
             if (mailbox.pending === null || (provider !== null && provider !== undefined
                 && ["submitting", "accepted", "delivery-unknown"].includes(provider.status)))
@@ -1880,7 +1929,7 @@ export class FileSchedulerStoreAdapter {
             const obsoleteIds = new Set();
             for (const message of store.listMessages(taskId)) {
                 if (pendingMessageIds.has(message.id) && (taskMessageInboxReceipt(store, message) !== undefined
-                    || deliveredMessageWake(store, message) !== undefined)) {
+                    || nonReplayableMessageWake(store, message) !== undefined)) {
                     obsoleteIds.add(message.id);
                 }
             }
@@ -1915,21 +1964,23 @@ export class FileSchedulerStoreAdapter {
             const handoffs = claimedMessages.filter(message => !obsoleteIds.has(message.id));
             // A quiet/new Session is not evidence that the claimed old Turn stopped.
             // Keep the exact pending intent until the original fence is provable.
-            if (handoffs.some((message) => interruptThenTerminalState(store, message) !== "ready"))
+            if (recoveryRefs.length === 0
+                && handoffs.some((message) => interruptThenTerminalState(store, message) !== "ready"))
                 return null;
             const handoffIds = new Set(handoffs.map((message) => message.id));
             if (availableRefs.length === 0 && obsoleteIds.size > 0) {
                 store.saveWorkMailbox(consumePendingBatch(mailbox, pending));
                 return null;
             }
-            const selectedRefs = handoffs.length === 0 ? availableRefs
+            const selectedRefs = recoveryRefs.length > 0 ? recoveryRefs : handoffs.length === 0 ? availableRefs
                 : availableRefs.filter((ref) => ref.type === "message" && handoffIds.has(ref.id));
-            const remainingRefs = handoffs.length === 0 ? []
-                : availableRefs.filter((ref) => !(ref.type === "message" && handoffIds.has(ref.id)));
+            const remainingRefs = recoveryRefs.length > 0 ? availableRefs.filter(ref => !recoveryRefs.includes(ref))
+                : handoffs.length === 0 ? []
+                    : availableRefs.filter((ref) => !(ref.type === "message" && handoffIds.has(ref.id)));
             const latest = latestTaskWake(store.listTaskWakes(taskId));
             const wakeId = store.nextTaskWakeId(taskId);
             const wake = createTaskWake({
-                id: wakeId, taskId, reasons: mailbox.pending.reasons,
+                id: wakeId, taskId, reasons: recoveryRefs.length > 0 ? ["session-replaced"] : mailbox.pending.reasons,
                 refs: pinMessageRevisions(store, taskId, selectedRefs),
                 fromCursor: latest?.toCursor ?? task.createdAt,
                 toCursor: new Date(Math.max(now.getTime(), Date.parse(mailbox.pending.lastQueuedAt))).toISOString(), now
@@ -2216,6 +2267,8 @@ export class FileSchedulerStoreAdapter {
                     }
                     sessions = settleStructuredProviderTurn(sessions, canonicalRunId, input.providerStatus, now, attemptId);
                     store.saveTaskRoleSessionSet(sessions);
+                    checkInboxTurn(store, { scope: "task", taskId: input.taskId, roleName: input.roleName,
+                        agentId: input.agentId, nativeSessionId: input.nativeSessionId }, sessions.providerBinding?.run, now);
                 }
                 if (input.observation !== undefined)
                     this.persistRuntimeObservation(input.observation, now);
@@ -2321,6 +2374,8 @@ export class FileSchedulerStoreAdapter {
             }
             if (input.observation !== undefined)
                 this.persistRuntimeObservation(input.observation, now);
+            checkInboxTurn(store, { scope: "task", taskId: input.taskId, roleName: input.roleName,
+                agentId: input.agentId, nativeSessionId: input.nativeSessionId }, sessions.providerBinding?.run, now);
             return {
                 session: sessions.sessions[input.agentId],
                 duplicate: false,
@@ -2807,6 +2862,10 @@ export class FileSchedulerStoreAdapter {
             // durable native terminal recorded just above remains the proof of record.
             current = settleGlobalRoleRuntimeTurn(current, input.nativeTurnId, input.providerStatus, now);
             store.saveGlobalRoleSessionSet(current);
+            if (current.providerBinding?.run?.nativeTurnId === input.nativeTurnId) {
+                checkInboxTurn(store, { scope: "global", roleName: input.roleName,
+                    agentId: input.agentId, nativeSessionId }, current.providerBinding.run, now);
+            }
             if (input.roleName === SYSTEM_OPERATOR_ROLE
                 && input.adapterId === "codex"
                 && completedStatus === "active") {

package/dist/controller/globalInputDelivery.js

@@ -6,11 +6,12 @@ import { providerRetryPending } from "../runtime/providerRetry.js";
 import { settleGlobalRetryInput } from "../message/globalProviderRetry.js";
 import { globalMessagePresentation } from "../interaction/notificationPresentation.js";
 import { recordGlobalRuntimeAttention, recordGlobalRuntimeRecovery } from "./globalRuntimeAttention.js";
+import { globalInboxRecovery } from "../message/globalInboxRecovery.js";
 /** Messages are the only queue. Host's atomic begin arbitrates native writers. */
 export async function deliverGlobalInputs(home, store, ensure, onError, options = {}) {
     for (const role of store.listGlobalRoles()) {
         try {
-            let pending = store.queryGlobalRoleMessages(role.name, { pending: true, limit: 64 }).messages;
+            let pending = store.queryGlobalRoleMessages(role.name, { pending: true, unclaimed: true, limit: 64 }).messages;
             if (hasRuntimeCleanupObligation(store.getWorkMailbox(runtimeLifecycleTarget({ scope: "global", roleName: role.name }))))
                 continue;
             let sessions = store.getGlobalRoleSessionSet(role.name);
@@ -20,7 +21,7 @@ export async function deliverGlobalInputs(home, store, ensure, onError, options
                 continue;
             if (sessions?.providerBinding?.retry !== undefined && !providerRetryPending(sessions.providerBinding)) {
                 store.transaction(tx => settleGlobalRetryInput(tx, role.name, tx.getGlobalRoleSessionSet(role.name)?.providerBinding, new Date()));
-                pending = store.queryGlobalRoleMessages(role.name, { pending: true, limit: 64 }).messages;
+                pending = store.queryGlobalRoleMessages(role.name, { pending: true, unclaimed: true, limit: 64 }).messages;
                 if (pending.length === 0)
                     continue;
             }
@@ -84,12 +85,13 @@ export async function deliverGlobalInputs(home, store, ensure, onError, options
                     || providerRetryPending(sessions?.providerBinding)
                     || hasRuntimeCleanupObligation(store.getWorkMailbox(runtimeLifecycleTarget({ scope: "global", roleName: role.name }))))
                     continue;
-                pending = store.queryGlobalRoleMessages(role.name, { pending: true, limit: 64 }).messages;
+                pending = store.queryGlobalRoleMessages(role.name, { pending: true, unclaimed: true, limit: 64 }).messages;
                 if (pending.length === 0)
                     continue;
             }
-            if (store.queryGlobalRoleMessages(role.name, { handling: true, limit: 0 }).count > 0)
-                continue;
+            const recovery = globalInboxRecovery(store, role.name, options.now ?? new Date());
+            const recovering = recovery !== undefined && recovery.inbox === undefined && recovery.delivery === undefined
+                && recovery.notDelivered === undefined && recovery.control === undefined;
             // Interrupt-then reserves the next legal slot even behind a large queue.
             const reservedPage = store.queryGlobalRoleMessages(role.name, {
                 pending: true, interruptThen: true, limit: 64
@@ -106,7 +108,7 @@ export async function deliverGlobalInputs(home, store, ensure, onError, options
                 store.updateGlobalRoleMessage(markGlobalRoleMessageNotDelivered(message, "native-session-or-authority-changed", new Date()));
             const obsoleteIds = new Set(obsolete.map(message => message.id));
             pending = pending.filter(message => !obsoleteIds.has(message.id));
-            if (pending.length === 0)
+            if (pending.length === 0 && !recovering)
                 continue;
             if (reservedPage.count > reserved.length && obsolete.length === reserved.length)
                 continue;
@@ -117,7 +119,15 @@ export async function deliverGlobalInputs(home, store, ensure, onError, options
                     && sessions.sessions[message.deliveryTarget.agentId]?.nativeSessionId === message.deliveryTarget.nativeSessionId;
             const claims = reserved.filter(message => !obsolete.includes(message));
             let next;
-            if (claims.length > 0) {
+            if (recovering) {
+                // The notice carries no original business input. An obsolete then
+                // target is never inherited; a current explicit reservation still
+                // owns its slot. Host admission checks this again atomically.
+                if (claims.length > 0)
+                    continue;
+                next = recovery;
+            }
+            else if (claims.length > 0) {
                 next = claims.find(message => {
                     const claim = message.interruptThen;
                     const binding = sessions?.providerBinding;

package/dist/controller/inboxTurnCheck.js

@@ -0,0 +1,64 @@
+import { createGlobalRoleMessage } from "../message/message.js";
+import { INBOX_CHECK_PREFIX, INBOX_CHECK_REASON, missingTurnHandling } from "../message/inboxTurn.js";
+import { readDigest } from "../output/boundedRead.js";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { enqueueWork } from "../coordination/workMailboxQueue.js";
+import { retiredTaskRecordIds } from "../task/taskRecordRetirement.js";
+import { completeProcessing } from "../coordination/workMailbox.js";
+/** Called inside exact-terminal persistence's transaction. A terminal checks
+ * receipts; it cannot infer a disposition. One existing notification per exact
+ * turn, no timer, retry queue, automatic ACK or reminder-of-reminder loop. */
+export function checkInboxTurn(store, actor, turn, now) {
+    if (!turn || !["completed", "failed", "cancelled"].includes(turn.status))
+        return;
+    const retired = actor.scope === "task" ? retiredTaskRecordIds(store.listEvents(actor.taskId), "message") : new Set();
+    const entries = actor.scope === "global" ? store.listGlobalRoleMessages(actor.roleName)
+        : [...(actor.roleName === "leader" ? store.listTaskWakes(actor.taskId) : []),
+            ...store.listMessages(actor.taskId).filter(message => !retired.has(message.id))];
+    const missing = missingTurnHandling(entries, actor, turn);
+    if (actor.scope === "task" && actor.roleName === "leader") {
+        const mailbox = store.getWorkMailbox({ kind: "role", taskId: actor.taskId, roleName: "leader" });
+        // End the exact active-consumption notification reservation only. Its
+        // original claim remains unfinished and discoverable; no writer is freed
+        // here (the caller already persisted an exact native terminal).
+        if (mailbox?.processing && entries.some(entry => entry.inbox?.claim.actor.attemptId === turn.attemptId
+            && entry.inbox.claim.actor.nativeSessionId === actor.nativeSessionId
+            && entry.inbox.claim.actor.agentId === actor.agentId
+            && mailbox.processing?.owner === `agent-inbox:${entry.id}`
+            && mailbox.processing.batchId === `inbox:${entry.id}`)) {
+            store.saveWorkMailbox(completeProcessing(mailbox, mailbox.processing.batchId));
+        }
+    }
+    if (!missing.length)
+        return;
+    const requestId = INBOX_CHECK_PREFIX + readDigest([actor.scope, actor.taskId, actor.roleName,
+        actor.agentId, actor.nativeSessionId, turn.attemptId]);
+    const facts = {
+        roleName: actor.roleName, nativeSessionId: actor.nativeSessionId, attemptId: turn.attemptId,
+        status: turn.status, count: String(missing.length), entries: missing.slice(0, 16).map(entry => entry.id).join(","),
+        read: actor.scope === "global" || actor.roleName === "leader" ? "yui inbox list --view history --json"
+            : `yui task message show ${actor.taskId}/${missing[0].id} --json`,
+        disposition: "Missing handling evidence, not unexecuted work. Read originals and prior effects; explicitly ack or retire within authority. Never replay external effects."
+    };
+    if (actor.scope === "global") {
+        if (store.queryGlobalRoleMessages(actor.roleName, { requestId, limit: 1 }).count)
+            return;
+        const notice = createGlobalRoleMessage(store.nextGlobalRoleMessageId(), actor.roleName, `Yui-Summary: ${missing.length} input(s) lack handling receipts after an exact native terminal.\n`
+            + JSON.stringify(facts), "system", { type: "system" }, now, { inputControl: { action: "queue", requestId } });
+        // Retain the original target: replacing a Session is not permission to
+        // replay this reminder elsewhere. Successors can inspect history explicitly.
+        store.saveGlobalRoleMessage({ ...notice,
+            deliveryTarget: { agentId: actor.agentId, nativeSessionId: actor.nativeSessionId } });
+    }
+    else {
+        if (store.listEvents(actor.taskId).some(event => event.type === INBOX_CHECK_REASON
+            && event.payload.requestId === requestId))
+            return;
+        const event = createTaskEvent(store.nextEventId(actor.taskId), actor.taskId, INBOX_CHECK_REASON, { ...facts, requestId }, now);
+        store.saveEvent(actor.taskId, event);
+        const task = store.getTask(actor.taskId);
+        if (task && ["active", "draft"].includes(task.status) && task.executionGate.state === "enabled") {
+            enqueueWork(store, { kind: "role", taskId: actor.taskId, roleName: "leader" }, INBOX_CHECK_REASON, now, [{ type: "event", taskId: actor.taskId, id: event.id }], { source: "inbox-check", dedupeKey: requestId });
+        }
+    }
+}

package/dist/controller/jobControl.js

@@ -9,7 +9,7 @@
  * preserves its admitted Job across authorized Session replacement.
  */
 import { execSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { resolve, sep } from "node:path";
 import { activeLiveRoleAgentSession } from "../executor/agentExecutor.js";
 import { acknowledgeUnknownDurableJob, createDurableJob, durableJobIdempotencyKey, isDurableJobTerminal, requestDurableJobCancel, retryDurableJobIdempotencyKey } from "../job/durableJob.js";
@@ -21,6 +21,7 @@ import { assertJobAssignmentScope, JobAssignmentScopeError } from "../job/jobAss
 import { assertContextRecordReadable } from "../context/taskContext.js";
 import { assertTaskProjectWriteAuthority } from "../task/taskAuthority.js";
 import { validateHttpPreview } from "../job/httpPreview.js";
+import { definitionFromTaskRun } from "../job/jobDefinition.js";
 export function createDurableJobControl(store) {
     const authority = createJobCallAuthority(store);
     return {
@@ -34,7 +35,7 @@ export function createDurableJobControl(store) {
                 requireJobAssignment(tx, params, params.caller);
                 assertNonSecretJobInput(params);
                 validateHttpPreview(params.env, params.steps);
-                const baseKey = durableJobIdempotencyKey({
+                const specificationKey = durableJobIdempotencyKey({
                     owner: params.owner,
                     projectId: params.projectId,
                     head: params.head,
@@ -42,6 +43,12 @@ export function createDurableJobControl(store) {
                     workspace: params.workspace,
                     env: params.env
                 });
+                const definition = params.definitionId === undefined ? null
+                    : tx.getJobDefinition({ kind: "task", taskId: params.taskId }, params.definitionId);
+                if (params.definitionId !== undefined && definition === null)
+                    throw jobDomainError("Job definition not found.");
+                const baseKey = definition === null ? specificationKey : createHash("sha256")
+                    .update(JSON.stringify([specificationKey, definition.id, definition.revision, params.trigger])).digest("hex");
                 const inputDigest = params.retryOf === undefined
                     ? baseKey
                     : retryDurableJobIdempotencyKey(baseKey, params.retryOf);
@@ -77,9 +84,29 @@ export function createDurableJobControl(store) {
                 }
                 authority.authorize(context, params.taskId);
                 validateStartParams(tx, params);
+                const previous = params.retryOf === undefined ? null : tx.getDurableJob(params.taskId, params.retryOf);
+                if (previous !== null) {
+                    requireJobAssignment(tx, previous, params.caller);
+                    if (definition === null && durableJobIdempotencyKey(previous) !== specificationKey) {
+                        throw jobDomainError("Legacy retry must preserve the original Run specification; update its Job definition for a changed configuration.");
+                    }
+                }
+                const definitionId = definition?.id ?? previous?.definitionId;
+                if (definitionId !== undefined) {
+                    const active = tx.listDurableJobs(params.taskId).find(run => run.definitionId === definitionId
+                        && (run.status === "queued" || run.status === "running" || run.status === "unknown-needs-attention"));
+                    if (active !== undefined)
+                        throw jobDomainError(`Job is already occupied by Run ${active.id} (${active.status}); no new Run was admitted.`);
+                }
                 const id = tx.nextDurableJobId(params.taskId);
                 const job = createDurableJob({
                     id,
+                    definitionId: definitionId ?? `definition-${randomUUID()}`,
+                    definitionRevision: definition?.revision ?? previous?.definitionRevision,
+                    trigger: params.trigger ?? {
+                        source: params.retryOf !== undefined ? "retry" : params.owner.kind === "integration-attempt" ? "integration" : "manual",
+                        key: requestId
+                    },
                     taskId: params.taskId,
                     owner: params.owner,
                     projectId: params.projectId,
@@ -94,6 +121,9 @@ export function createDurableJobControl(store) {
                     artifactsLocator: `artifacts/jobs/${params.taskId}/${id}`,
                     ...(params.retryOf === undefined ? {} : { retryOf: params.retryOf })
                 }, now);
+                if (tx.getJobDefinition({ kind: "task", taskId: params.taskId }, job.definitionId) === null) {
+                    tx.saveJobDefinition(definitionFromTaskRun(job));
+                }
                 tx.saveDurableJob(params.taskId, job);
                 return { job, created: true };
             });
@@ -191,7 +221,7 @@ function assertLeaderJobWriteScope(store, target, caller) {
         throw jobControlError("UNAUTHORIZED", error instanceof Error ? error.message : String(error));
     }
 }
-function requireJobAssignment(store, target, caller) {
+export function requireJobAssignment(store, target, caller) {
     try {
         assertJobAssignmentScope(store, target, caller);
     }
@@ -201,7 +231,7 @@ function requireJobAssignment(store, target, caller) {
         throw error;
     }
 }
-function jobAuthorityBinding(store, scope, roleName, taskId) {
+export function jobAuthorityBinding(store, scope, roleName, taskId) {
     // A Host detach/reattach preserves the native Session and its queued work.
     // Authenticate the live launch at ingress, but bind accepted Jobs to the
     // caller's durable Session identity, not its disposable Host generation.
@@ -232,7 +262,7 @@ function jobAuthorityBinding(store, scope, roleName, taskId) {
         role.activeAgentId, session.agentId, session.nativeSessionId
     ])).digest("hex");
 }
-function assertNonSecretJobInput(params) {
+export function assertNonSecretJobInput(params) {
     // Existing Jobs persist commands and environments. This boundary accepts
     // non-secret executable specifications only; credential resolution is not a
     // Job feature. Never hash a known secret then call the digest sanitized.
@@ -263,7 +293,7 @@ function assertNonSecretJobInput(params) {
  * workspace was not the stable checkout. Now it binds the job to the exact
  * managed workspace, verifies write access, and requires an active Task.
  */
-function validateStartParams(store, params) {
+export function validateStartParams(store, params) {
     validateJobTarget(store, params);
     assertCallerAuthorized(store, params.caller, params.taskId);
     assertLeaderJobWriteScope(store, params, params.caller);
@@ -384,7 +414,7 @@ function validateJobTarget(store, params) {
  * identity contract does not defend against another process with the same
  * user's filesystem access. Bare user calls cannot start or cancel Jobs.
  */
-function assertCallerAuthorized(store, caller, taskId) {
+export function assertCallerAuthorized(store, caller, taskId) {
     if (caller.scope === "user") {
         // rr13: A user-scope caller has no per-Session channel binding. Every
         // durable-state claim it could carry is replayable
@@ -508,7 +538,7 @@ export function parseDurableJobStartParams(value) {
     const retryOf = record.retryOf === undefined
         ? undefined
         : requiredId(record.retryOf, "job.start retryOf");
-    const caller = parseCaller(record.caller);
+    const caller = parseDurableJobCaller(record.caller);
     return {
         taskId,
         owner,
@@ -531,7 +561,7 @@ export function parseDurableJobRefParams(value) {
     return {
         taskId: requiredId(record.taskId, "DurableJob taskId"),
         jobId: requiredId(record.jobId, "DurableJob jobId"),
-        caller: parseCaller(record.caller)
+        caller: parseDurableJobCaller(record.caller)
     };
 }
 /**
@@ -548,7 +578,7 @@ export function parseDurableJobCancelParams(value) {
     return {
         taskId: requiredId(record.taskId, "DurableJob taskId"),
         jobId: requiredId(record.jobId, "DurableJob jobId"),
-        caller: parseCaller(record.caller)
+        caller: parseDurableJobCaller(record.caller)
     };
 }
 /**
@@ -564,7 +594,7 @@ export function parseDurableJobAcknowledgeParams(value) {
     return {
         taskId: requiredId(record.taskId, "DurableJob taskId"),
         jobId: requiredId(record.jobId, "DurableJob jobId"),
-        caller: parseCaller(record.caller)
+        caller: parseDurableJobCaller(record.caller)
     };
 }
 function parseJobOwner(value) {
@@ -645,7 +675,7 @@ function parseSteps(value) {
  * optional managed Session identity fields. The identity is verified against
  * durable state by `assertCallerAuthorized`; parsing only validates the JSON shape.
  */
-function parseCaller(value) {
+export function parseDurableJobCaller(value) {
     if (value === undefined) {
         throw jobControlError("INVALID_PARAMS", "job caller is required.");
     }