@zq-silk/yui 2.8.0 → 2.9.0

package/dist/commands/taskPublicationVerifyCommand.js

@@ -4,8 +4,15 @@ import { upsertTaskPublication } from "./taskPublicationCommands.js";
 import { dataError, runtimeError, taskNotFound, usageError, CliError } from "../errors/cliError.js";
 import { publicationExternalKey } from "../task/publicationReference.js";
 import { resolveTaskRecordReference } from "../task/taskRecordReference.js";
+import { assertPublicationToolObservation, canonicalPublicationUrl, parsePublicationToolObservation, publicationObservationNotBefore } from "../task/publicationToolObservation.js";
 export async function runTaskPublicationVerifyCommand(args, store, options) {
-    const reference = parsePublicationVerificationReference(args);
+    const observationIndex = args.indexOf("--observation");
+    if (observationIndex !== -1 && observationIndex !== args.length - 2) {
+        throw usageError("--observation must be followed by one JSON object at the end of the command.");
+    }
+    const supplied = observationIndex === -1 ? undefined
+        : parsePublicationToolObservation(args[observationIndex + 1]);
+    const reference = parsePublicationVerificationReference(observationIndex === -1 ? args : args.slice(0, observationIndex));
     const task = store.getTask(reference.taskId);
     if (task === null)
         throw taskNotFound(reference.taskId);
@@ -13,31 +20,48 @@ export async function runTaskPublicationVerifyCommand(args, store, options) {
         throw usageError(`Archived Task Publication cannot be verified: ${task.id}.`);
     }
     taskActor(options.environment, task.id);
-    const request = preparePublicationVerification(store, reference.taskId, reference.localId, options.environment);
-    const verifier = options.verifiers[request.publication.provider];
-    if (verifier === undefined) {
-        throw usageError(`Publication verification is not supported for provider `
-            + `${request.publication.provider}.`);
-    }
+    const request = preparePublicationVerification(store, reference.taskId, reference.localId, options.environment, supplied);
+    const now = options.now?.() ?? new Date();
     let observation;
-    try {
-        observation = await verifier.inspect({
-            provider: request.publication.provider,
-            repository: request.publication.repository,
-            externalKind: request.publication.externalKind,
-            externalId: request.publication.externalId,
-            ...(request.publication.externalUrl === undefined
-                ? {}
-                : { externalUrl: request.publication.externalUrl }),
-            expectedLocalCommit: request.expectedLocalCommit
-        });
-    }
-    catch (error) {
-        if (error instanceof CliError)
-            throw error;
-        throw runtimeError(`Publication verification failed for ${request.publication.provider}/`
-            + `${request.publication.repository}/${request.publication.externalId}.`, { cause: error });
+    if (supplied !== undefined) {
+        if (request.publication.evidence === supplied.evidence
+            && request.publication.supersedes === supplied.publicationId) {
+            return {
+                kind: "output",
+                output: `Tool observation already recorded: ${request.publication.id} (${request.publication.verification}).\n`,
+                data: { publication: request.publication, observation: supplied }
+            };
+        }
+        assertPublicationToolObservation(request.publication, supplied, now, request.observationNotBefore);
+        observation = supplied;
     }
+    else
+        try {
+            const verifier = options.verifiers[request.publication.provider];
+            if (verifier === undefined) {
+                throw usageError(`No built-in verifier for ${request.publication.provider}; `
+                    + "use --observation with evidence from an authorized tool.");
+            }
+            observation = await verifier.inspect({
+                provider: request.publication.provider,
+                repository: request.publication.repository,
+                externalKind: request.publication.externalKind,
+                externalId: request.publication.externalId,
+                ...(request.publication.externalUrl === undefined
+                    ? {}
+                    : { externalUrl: request.publication.externalUrl }),
+                ...(request.publication.targetBranch === undefined
+                    ? {}
+                    : { targetBranch: request.publication.targetBranch }),
+                expectedLocalCommit: request.expectedLocalCommit
+            });
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw runtimeError(`Publication verification failed for ${request.publication.provider}/`
+                + `${request.publication.repository}/${request.publication.externalId}.`, { cause: error });
+        }
     assertVerificationObservation(request, observation);
     const result = commitPublicationVerification(store, request, observation, options.now?.() ?? new Date());
     return {
@@ -54,7 +78,7 @@ export async function runTaskPublicationVerifyCommand(args, store, options) {
         data: { publication: result.reference, observation }
     };
 }
-function preparePublicationVerification(store, taskId, publicationId, environment) {
+function preparePublicationVerification(store, taskId, publicationId, environment, supplied) {
     return store.transaction((reader) => {
         const task = reader.getTask(taskId);
         if (task === null)
@@ -63,11 +87,18 @@ function preparePublicationVerification(store, taskId, publicationId, environmen
             throw usageError(`Archived Task Publication cannot be verified: ${task.id}.`);
         }
         const actor = taskActor(environment, task.id);
-        const publication = reader.getPublicationReference(task.id, publicationId);
+        let publication = reader.getPublicationReference(task.id, publicationId);
         if (publication === null) {
             throw dataError(`Publication reference not found: ${task.id}/${publicationId}.`);
         }
         const current = reader.findPublicationReferenceByExternalKey(publicationExternalKey(publication));
+        // Only the immediate immutable successor of this exact observation is a
+        // retry. A later observation/candidate must never revive an old receipt.
+        if (current?.taskId === task.id && current.supersedes === publication.id
+            && supplied?.taskId === task.id && supplied.publicationId === publication.id
+            && current.evidence === supplied.evidence) {
+            publication = current;
+        }
         if (current === null || current.taskId !== task.id || current.id !== publication.id) {
             throw usageError(`Publication ${publication.id} is not the current unsuperseded record `
                 + `for ${publicationExternalKey(publication)}.`);
@@ -84,7 +115,9 @@ function preparePublicationVerification(store, taskId, publicationId, environmen
             task: taskVerificationInvariant(task),
             actor,
             publication,
-            expectedLocalCommit: publication.localCommit
+            expectedLocalCommit: publication.localCommit,
+            observationNotBefore: supplied === undefined ? undefined
+                : publicationObservationNotBefore(publication, id => reader.getPublicationReference(task.id, id))
         };
     });
 }
@@ -99,6 +132,18 @@ function assertVerificationObservation(request, observation) {
     if (!/^[0-9a-f]{40}$/u.test(observation.headCommit)) {
         throw usageError("Provider observation requires an exact remote head.");
     }
+    if (publication.externalUrl !== undefined
+        && (observation.externalUrl === undefined
+            || canonicalPublicationUrl(observation.externalUrl, publication.provider)
+                !== canonicalPublicationUrl(publication.externalUrl, publication.provider))) {
+        throw usageError("Provider returned mismatched Publication service or URL.");
+    }
+    if (observation.targetBranch === undefined || observation.targetBranch.trim().length === 0) {
+        throw usageError("Provider observation requires an exact target branch.");
+    }
+    if (publication.targetBranch !== undefined && observation.targetBranch !== publication.targetBranch) {
+        throw usageError("Provider returned mismatched Publication target branch.");
+    }
     if (observation.state === "merged" && observation.remoteCommit === undefined) {
         throw usageError(`Merged remote ${publication.externalKind} did not expose a remote commit.`);
     }
@@ -130,6 +175,7 @@ function commitPublicationVerification(store, request, observation, now) {
             ...(observation.externalUrl === undefined
                 ? {}
                 : { externalUrl: observation.externalUrl }),
+            targetBranch: observation.targetBranch,
             localCommit: request.expectedLocalCommit,
             headCommit: observation.headCommit,
             ...(observation.remoteCommit === undefined ? {} : { remoteCommit: observation.remoteCommit }),
@@ -145,7 +191,7 @@ function commitPublicationVerification(store, request, observation, now) {
 }
 function parsePublicationVerificationReference(args) {
     const usage = "Task publication verify usage: "
-        + "yui task publication verify (<task>/<publication-id> | <task> <publication-id>).";
+        + "yui task publication verify (<task>/<publication-id> | <task> <publication-id>) [--observation <json>].";
     if (args.length !== 1 && args.length !== 2)
         throw usageError(usage);
     return resolveTaskRecordReference(args.length === 1 ? args[0] : `${args[0]}/${args[1]}`, { kind: "publicationReference", label: "Publication reference" });

package/dist/context/runContextPack.js

@@ -300,9 +300,9 @@ export function contextSnapshotDeltaRefIds(store, snapshot) {
         throw new Error(`Context Snapshot parent is missing or drifted: ${snapshot.parentRef.id}.`);
     }
     validateContextSnapshot(parent);
-    const previous = new Map(parent.refs.map((ref) => [ref.refId, ref]));
+    const previous = new Map(parent.refs.map((ref) => [`${ref.store}:${ref.refId}`, ref]));
     const changed = snapshot.refs.filter((ref) => {
-        const before = previous.get(ref.refId);
+        const before = previous.get(`${ref.store}:${ref.refId}`);
         return before === undefined
             || before.digest !== ref.digest
             || before.revision !== ref.revision
@@ -440,7 +440,7 @@ export function expandRunContextRef(store, taskId, runId, refId, refStore) {
 export function buildRunContextDelta(store, taskId, runId, after) {
     const pack = buildRunContextPack(store, taskId, runId);
     if (after === pack.digest || after === pack.snapshot.digest) {
-        return Object.freeze({ schemaVersion: 1, after, cursor: pack.digest, refs: [] });
+        return Object.freeze({ schemaVersion: 1, after, cursor: pack.digest, refs: [], removedRefs: [], complete: true });
     }
     const run = requireExactRun(store, taskId, runId);
     const snapshot = readRunContextSnapshot(store, run);
@@ -449,11 +449,31 @@ export function buildRunContextDelta(store, taskId, runId, after) {
         || (parentDigest === undefined && after === "none"))) {
         throw new Error("AgentRun Context delta cursor is outside the frozen Snapshot lineage.");
     }
+    const parent = snapshot.parentRef === undefined ? null
+        : store.getContextSnapshot(taskId, snapshot.parentRef.id);
+    if (snapshot.parentRef !== undefined && (parent === null || parent.digest !== parentDigest
+        || parent.sequence !== snapshot.parentRef.sequence)) {
+        throw new Error("AgentRun Context parent changed or is unavailable; reload the exact current pack.");
+    }
+    if (parent !== null)
+        validateContextSnapshot(parent);
+    const identity = (ref) => `${ref.store}:${ref.refId}`;
+    const previous = new Map((parent?.refs ?? []).map(ref => [identity(ref), ref]));
+    const present = new Set(pack.pointers.map(identity));
     return Object.freeze({
         schemaVersion: 1,
         after,
         cursor: pack.digest,
-        refs: pack.pointers.filter(ref => pack.deltaRefs.some(delta => delta.store === ref.store && delta.refId === ref.refId))
+        // deltaRefs is only a bounded launch hint. The immutable inventory (<=256)
+        // is the authority for a complete patch, including removals and changes
+        // beyond that hint's limit. Transport paginates large documents as usual.
+        refs: pack.pointers.filter(ref => {
+            const before = previous.get(identity(ref));
+            return before === undefined || contextContentDigest(before) !== contextContentDigest(ref);
+        }),
+        removedRefs: (parent?.refs ?? []).filter(ref => !present.has(identity(ref)))
+            .map(({ store, refId }) => ({ store, refId })),
+        complete: true
     });
 }
 function requireExactRun(store, taskId, runId) {

package/dist/context/taskContext.js

@@ -2,7 +2,7 @@ import { runExecutionObservation } from "../agentRun/agentRun.js";
 import { isGitArtifactRefString, parseGitArtifactRef } from "../artifacts/gitArtifactRef.js";
 import { taskNotFound, usageError } from "../errors/cliError.js";
 import { expandTaskMessageResult } from "../message/message.js";
-import { resolveManagedTaskReader } from "../runtime/managedCaller.js";
+import { currentManagedRuntime, resolveManagedTaskReader } from "../runtime/managedCaller.js";
 import { hasManagedIdentity } from "../runtime/managedIdentity.js";
 import { providerRetrySummary } from "../runtime/providerRetry.js";
 import { projectTaskRemoteDeliveryFromStore } from "../task/remoteDeliveryService.js";
@@ -12,6 +12,7 @@ import { contextContentDigest } from "./contextSnapshot.js";
 import { buildRunContextPack } from "./runContextPack.js";
 import { sourceRunContextValue } from "./sourceRunContext.js";
 import { boundedDocument, fitsReadBudget, summaryText, recordPage } from "../output/boundedRead.js";
+import { taskBriefGuard, taskPhase } from "./taskPhase.js";
 const MAX_RECORDS = 64;
 const MAX_VALUE_BYTES = 2048;
 const MAX_PAGE_BYTES = 24 * 1024;
@@ -26,6 +27,9 @@ export function readTaskContext(store, taskId, environment = {}) {
         const sources = authorizedSources(reader, scope, true);
         const count = sources.reduce((total, source) => total + source.count, 0);
         const cursor = currentCursor(reader, taskId);
+        const phase = scope.allow === undefined ? taskPhase(reader, scope.task) : undefined;
+        const phaseSource = phase?.activation?.source;
+        const priorMessageId = phaseSource?.priorMessageId;
         // Reserve a small, classified view before ordinary history consumes the
         // page. Counts and samples come from the exact same authorized read.
         const attention = summarizeAttention(reader, taskId, scope.allow);
@@ -44,7 +48,20 @@ export function readTaskContext(store, taskId, environment = {}) {
                 const content = valueBytes > MAX_VALUE_BYTES || ["role", "task-message", "run", "work-item", "project-knowledge"].includes(entry.ref.store)
                     ? { ref: entry.ref, summary: summarize(entry.value), omitted: true }
                     : { ...entry, omitted: false };
-                const record = { ...content, ...(entry.ref.store === "run" ? {
+                const revisedAfterActivation = entry.ref.store === "task-message" && phaseSource?.ref !== undefined
+                    && reader.queryContextRecords(taskId, {
+                        family: "task-event", eventTypes: ["message.updated"], eventMessageId: entry.ref.refId,
+                        afterSequence: sequence(phaseSource.ref.refId), limit: 0
+                    }).count > 0;
+                const record = { ...content,
+                    ...(entry.ref.store === "task-message" && phase?.activation?.disposition === "adopted"
+                        && priorMessageId !== undefined ? {
+                        phaseRelation: revisedAfterActivation ? "revised-after-activation-request"
+                            : entry.ref.refId === phaseSource?.messageId ? "activation-source"
+                                : Number(entry.ref.refId.slice("message-".length)) <= Number(priorMessageId.slice("message-".length))
+                                    ? "recorded-before-activation-request" : "recorded-after-activation-request"
+                    } : {}),
+                    ...(entry.ref.store === "run" ? {
                         execution: runExecutionObservation(entry.value, reader.getTaskRoleSessionSet(taskId, entry.value.roleName)?.providerBinding, runtimeEvents)
                     } : {}), ...(entry.ref.store === "role" ? {
                         providerRetry: providerRetrySummary(reader.getTaskRoleSessionSet(taskId, entry.value.name)?.providerBinding)
@@ -58,6 +75,14 @@ export function readTaskContext(store, taskId, environment = {}) {
         const result = {
             taskId, coreCursor: encode(cursor), throughCursor: encode(cursor),
             view: "current",
+            ...(scope.allow === undefined ? {
+                phase,
+                briefWriteGuard: taskBriefGuard(reader, scope.task)
+            } : {}),
+            caller: scope.caller === undefined ? { kind: "unmanaged-or-global" } : {
+                role: scope.caller.roleName,
+                executionAuthority: currentManagedRuntime(reader, environment, taskId)?.executionAuthority ?? "historical-read-only"
+            },
             collections: Object.entries(sources.reduce((counts, source) => {
                 counts[source.family] = (counts[source.family] ?? 0) + source.count;
                 return counts;
@@ -133,11 +158,16 @@ export function readTaskContextDelta(store, taskId, input, environment = {}) {
         const start = decode(input.after, taskId);
         const now = currentCursor(reader, taskId);
         const continuation = input.continuation === undefined ? undefined : decodePage(input.continuation, taskId);
+        if (continuation !== undefined && continuation.baseline !== encode(start)) {
+            throw usageError("Context continuation belongs to a different baseline; restart from the original starting cursor.");
+        }
         const bound = continuation ?? now;
         const after = continuation?.after ?? start.sequence;
-        if (start.sequence > bound.sequence || after < start.sequence || after > bound.sequence
+        if (start.source !== now.source || bound.source !== now.source
+            || start.sequence > bound.sequence || after < start.sequence || after > bound.sequence
+            || start.revision > bound.revision
             || bound.sequence > now.sequence || start.revision > now.revision || bound.revision > now.revision) {
-            throw usageError("Context cursor is outside the current Task history.");
+            throw usageError(`Context cursor is outside the current Task history; reread task context ${taskId} for a new bounded baseline.`);
         }
         const limit = input.limit ?? MAX_EVENTS;
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_EVENTS) {
@@ -163,11 +193,14 @@ export function readTaskContextDelta(store, taskId, input, environment = {}) {
         }
         const last = page.at(-1)?.ref.refId;
         const more = selected.count > page.length;
-        const through = { taskId, sequence: bound.sequence, revision: bound.revision };
+        const through = { taskId, source: bound.source, sequence: bound.sequence, revision: bound.revision };
         return {
-            taskId, events: page, count: selected.count, throughCursor: encode(through),
+            taskId, kind: "event-history", fromCursor: encode(start),
+            events: page, count: selected.count, complete: !more, throughCursor: encode(through),
+            stateChanged: start.revision !== bound.revision,
+            currentRead: `task context ${taskId}`,
             ...(more && last !== undefined
-                ? { continuation: encode({ ...through, after: sequence(last) }) } : {}),
+                ? { continuation: encode({ ...through, after: sequence(last), baseline: encode(start) }) } : {}),
             observations: []
         };
     });
@@ -568,7 +601,8 @@ export function materialize(store, refId, value) {
     return { ref: { store, refId, revision: String(record.revision ?? record.updatedAt ?? record.createdAt ?? digest), digest }, value };
 }
 function currentCursor(store, taskId) {
-    return { taskId, sequence: store.latestEventSequence(taskId), revision: store.getStateRevision() };
+    return { taskId, source: store.getHomeIdentity().homeId,
+        sequence: store.latestEventSequence(taskId), revision: store.getStateRevision() };
 }
 function sequence(id) {
     const result = /^event-(\d+)$/.exec(id);
@@ -584,20 +618,23 @@ function decode(value, taskId) {
         if (value.length > 1024)
             throw new Error("size");
         const cursor = JSON.parse(Buffer.from(value, "base64url").toString());
-        if (cursor.taskId !== taskId || !Number.isSafeInteger(cursor.sequence) || cursor.sequence < 0
+        if (cursor.taskId !== taskId || typeof cursor.source !== "string"
+            || !Number.isSafeInteger(cursor.sequence) || cursor.sequence < 0
             || !Number.isSafeInteger(cursor.revision) || cursor.revision < 0)
             throw new Error("shape");
-        return cursor;
+        return { taskId: cursor.taskId, source: cursor.source, sequence: cursor.sequence, revision: cursor.revision };
     }
     catch {
-        throw usageError("Invalid Context cursor for this Task.");
+        throw usageError("Invalid or expired Context cursor for this Task; reread current Context for a new bounded baseline.");
     }
 }
 function decodePage(value, taskId) {
-    const cursor = decode(value, taskId);
-    if (!Number.isSafeInteger(cursor.after) || cursor.after < 0)
-        throw usageError("Invalid Context continuation.");
-    return cursor;
+    const base = decode(value, taskId);
+    const cursor = JSON.parse(Buffer.from(value, "base64url").toString());
+    if (!Number.isSafeInteger(cursor.after) || cursor.after < 0 || typeof cursor.baseline !== "string") {
+        throw usageError("Invalid or expired Context continuation; reread current Context and start a new bounded window.");
+    }
+    return { ...base, after: cursor.after, baseline: cursor.baseline };
 }
 function freeze(value) {
     if (value !== null && typeof value === "object") {

package/dist/context/taskPhase.js

@@ -0,0 +1,99 @@
+import { contextContentDigest } from "./contextSnapshot.js";
+/** Existing immutable event payloads carry provenance, not a second authority
+ * record. No body or historical aggregate is copied into the current view. */
+export function activationSourceEvent(store, task) {
+    const requestId = task.activationRequest?.operation.requestId;
+    if (requestId === undefined)
+        return undefined;
+    return store.queryContextRecords(task.id, {
+        family: "task-event", eventTypes: ["task.activation-requested"], eventRequestId: requestId,
+        descending: true, limit: 1
+    }).records[0]?.value;
+}
+export function taskPhase(store, task) {
+    const request = task.activationRequest;
+    const event = activationSourceEvent(store, task);
+    const messageId = event?.payload.sourceMessageId;
+    const message = messageId === undefined ? undefined : store.queryContextRecords(task.id, {
+        family: "task-message", ids: [messageId], limit: 1
+    }).records[0];
+    const body = message?.value?.body;
+    const status = event?.payload.sourceText !== undefined ? "available"
+        : messageId === undefined ? "missing"
+            : body === undefined ? "unavailable"
+                : contextContentDigest(body) === event?.payload.sourceBodyDigest ? "available" : "changed";
+    return {
+        status: task.status,
+        executionGate: task.executionGate.state,
+        brief: taskBriefFreshness(store, task),
+        activation: request === undefined ? null : {
+            requestId: request.operation.requestId, disposition: request.disposition,
+            actor: request.operation.actorId, effect: request.operation.effect,
+            ...(request.afterPlanningRun === undefined ? {} : { afterPlanningRun: request.afterPlanningRun }),
+            source: {
+                status,
+                ...(event === undefined ? {} : {
+                    ref: { store: "task-event", refId: event.id, digest: contextContentDigest(event) },
+                    read: `task event show ${task.id} ${event.id}`,
+                    attribution: event.payload.sourceKind ?? "unspecified",
+                    ...(event.payload.priorMessageId === undefined ? {} : { priorMessageId: event.payload.priorMessageId }),
+                    ...(messageId === undefined ? {} : {
+                        messageId, messageRead: `task message show ${task.id}/${messageId}`
+                    })
+                }),
+                ...(status === "available" ? {} : {
+                    recovery: "Read the exact activation event and original input; missing provenance is not a new prohibition or permission."
+                })
+            }
+        }
+    };
+}
+export function activationWakeRefs(store, task) {
+    const event = activationSourceEvent(store, task);
+    if (event === undefined)
+        return [];
+    return [
+        { type: "event", taskId: task.id, id: event.id },
+        ...(event.payload.sourceMessageId === undefined ? [] : [
+            { type: "message", taskId: task.id, id: event.payload.sourceMessageId }
+        ])
+    ];
+}
+const BRIEF_RELEVANT_EVENTS = [
+    "message.sent", "message.updated", "message.native-user-input", "brief.updated",
+    "decision.recorded", "decision.superseded", "input.requested", "input.answered", "input.cancelled", "input.auto-answered",
+    "run.completed", "run.failed", "run.cancelled", "job.state-changed", "work.accepted",
+    "runtime.role-delivery-failed", "run.retired",
+    "work.updated", "work.edited", "work.scope-updated", "work.rejected", "work.retired",
+    "review.completed", "review.failed", "integration.updated", "integration.completed", "integration.failed",
+    "milestone.added",
+    "task.activation-requested", "task.activation-adopted", "task.activated",
+    "task.execution-started", "task.execution-stopped", "task.reopened", "task.updated"
+];
+function latestBriefChange(store, taskId) {
+    return store.queryContextRecords(taskId, {
+        family: "task-event", eventTypes: BRIEF_RELEVANT_EVENTS, descending: true, limit: 1
+    }).records[0]?.value;
+}
+function taskBriefFreshness(store, task) {
+    const brief = store.getTaskBrief(task.id);
+    const last = latestBriefChange(store, task.id);
+    return {
+        status: brief === null ? "missing" : last === undefined ? "unverified"
+            : last.type === "brief.updated" ? "current-at-last-semantic-write" : "refresh-needed",
+        ...(last === undefined ? {} : { changedBy: { store: "task-event", refId: last.id, type: last.type } }),
+        read: `task brief show ${task.id}`,
+        note: "Leader-maintained summary; lifecycle, gate and Session authority are separate live facts."
+    };
+}
+/** Optimistic guard for semantic edits, independent of wall clocks and noisy
+ * runtime heartbeats. New input/result/decision/progress invalidates an old
+ * writer even when its Brief text itself has not changed. */
+export function taskBriefGuard(store, task) {
+    const latest = latestBriefChange(store, task.id)?.id;
+    return contextContentDigest({
+        taskId: task.id, status: task.status, gate: task.executionGate,
+        title: task.title, description: task.description, activation: task.activationRequest,
+        brief: store.getTaskBrief(task.id), latest
+    });
+}

package/dist/controlPlaneCli.js

@@ -24,6 +24,7 @@ import { operatorOfflineCommand, taskDiagnosticTarget } from "./cli/managedDiagn
 import { assertConfigurationAuthority, assertTaskInvocationScope } from "./cli/invocationAuthority.js";
 import { requireManagedGlobalCaller, requireManagedGlobalReader, ManagedRuntimeDriftError } from "./runtime/managedCaller.js";
 import { sessionCallerEnvironment, requireManagedCaller } from "./runtime/sessionCaller.js";
+import { maintenanceCallerEnvironment } from "./storage/maintenanceCaller.js";
 import { checkCurrentSkills, SKILL_REUSE_RULE } from "./context/currentSkills.js";
 import { roleSkillIds } from "./context/roleSessionContext.js";
 import { hasManagedIdentity } from "./runtime/managedIdentity.js";
@@ -38,6 +39,7 @@ import { runConfigCommand } from "./commands/configCommands.js";
 import { runConfigOverview } from "./commands/configOverview.js";
 import { parseControllerCleanupOptions, parseControllerRuntimeSnapshot, parseControllerStatusOptions, renderControllerResourceStatus, renderRuntimeIdentitySection, runInteractiveControllerCleanup, summarizeDurablePhysicalMismatch } from "./commands/controllerCommands.js";
 import { runDurableJobCommand } from "./commands/durableJobCommands.js";
+import { runScheduleCommand } from "./commands/scheduleCommands.js";
 import { parseExecutionAuditOptions, runExecutionAuditCommand } from "./commands/executionAuditCommands.js";
 import { runGlobalRoleCommand, previewGlobalRoleAgentConfigurationMutation } from "./commands/globalRoleCommands.js";
 import { runJobCommand } from "./commands/jobCommands.js";
@@ -1962,6 +1964,11 @@ export async function main() {
             emit(runJobCommand(resolved.slice(1), store, { runtime }));
             return;
         }
+        if (resolved[0] === "schedule") {
+            const result = await runScheduleCommand(resolved.slice(1), { home, environment: process.env });
+            emit(JSON.stringify(result, null, 2), false, result);
+            return;
+        }
         if (resolved[0] === "job") {
             emit(await runDurableJobCommand(resolved.slice(1), {
                 home,
@@ -1999,6 +2006,23 @@ async function preflightManagedTaskControlPlane() {
     if (taskFinalReviewInvocation.error !== undefined) {
         throw new Error(taskFinalReviewInvocation.error);
     }
+    if (["doctor", "upgrade", "update"].includes(args[0] ?? "")) {
+        const home = resolveYuiHome(process.env);
+        Object.assign(process.env, maintenanceCallerEnvironment(home, process.env, args[0] !== "doctor"));
+        if (!hasManagedIdentity(process.env)
+            || (process.env.YUI_SESSION_SCOPE === "global" && process.env.YUI_ROLE === "operator")) {
+            if (process.env.YUI_SESSION_SCOPE === "global") {
+                const manifest = assertManagedSessionManifest(home, "global");
+                if (manifest !== undefined && manifest.roleKind !== "operator") {
+                    throw new ManagedRuntimeDriftError("Managed global invocation does not match its Session Manifest.");
+                }
+            }
+            if (taskFinalReviewInvocation.request !== undefined) {
+                throw new Error("Task final-review contract cannot be established by Home maintenance.");
+            }
+            return { contract: undefined, verifiedStore: undefined };
+        }
+    }
     // Desktop clients may carry only their provider-native identity. Resolve
     // command-local hints before any public/Task/Global routing. This reads this
     // Home only, and never creates a Session or mutates its registration.
@@ -2094,11 +2118,6 @@ async function preflightManagedGlobalControlPlane() {
         || manifest.roleKind !== expectedRoleKind)) {
         throw new ManagedRuntimeDriftError("Managed global invocation does not match its Session Manifest.");
     }
-    if (expectedRoleKind === "operator" && ["doctor", "upgrade", "update"].includes(args[0] ?? "")) {
-        // These commands inspect/adopt the storage contract themselves. Requiring
-        // current storage before reaching upgrade would make recovery impossible.
-        return { contract: undefined, verifiedStore: undefined };
-    }
     await assertRuntimeCoherence({ actualHome: home }, {
         checkController: !(expectedRoleKind === "operator" && operatorOfflineCommand(args))
     });

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

@@ -1535,8 +1535,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 +1549,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]);