@zq-silk/yui 2.8.1 → 2.10.0

package/dist/controller/jobDefinitionControl.js

@@ -0,0 +1,304 @@
+import { createHash, randomUUID } from "node:crypto";
+import { openSync, closeSync, fstatSync, readSync, realpathSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+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 { projectRefreshTargetDigest, requireRefreshProject } from "../repository/projectRefresh.js";
+import { assertCallerAuthorized, assertNonSecretJobInput, createDurableJobControl, jobAuthorityBinding, validateStartParams, requireJobAssignment, parseDurableJobCaller } from "./jobControl.js";
+import { createFileArtifactPort } from "./jobSupervisor.js";
+export function authorizeScope(store, scope, caller) {
+    parseDurableJobCaller(caller);
+    jobScopeKey(scope);
+    // Match Task Context's Operator-only boundary for global callers as well
+    // as excluding Task callers from global Jobs. Session identity alone is not
+    // permission for a custom GlobalRole to read or manage Task definitions.
+    if ((scope.kind === "global" && caller.scope !== "global")
+        || (caller.scope === "global" && caller.role !== "operator")) {
+        throw Object.assign(new Error("Only the current Operator Session may access Jobs across global scope."), { name: "CoreApplicationError", code: "UNAUTHORIZED" });
+    }
+    assertCallerAuthorized(store, caller, scope.kind === "task" ? scope.taskId : "");
+}
+function taskParams(job, caller, requestId) {
+    if (job.scope.kind !== "task" || job.configuration.kind !== "shell")
+        throw new Error("Not a Task Job.");
+    return { ...job.configuration, taskId: job.scope.taskId, caller, requestId };
+}
+export function authorizeDefinition(store, job, caller, write) {
+    authorizeScope(store, job.scope, caller);
+    if (job.scope.kind === "task") {
+        const params = taskParams(job, caller, "definition-validation");
+        // A definition must not reveal another Assignment's commands/environment.
+        requireJobAssignment(store, params, caller);
+        if (write)
+            validateStartParams(store, params);
+        if (write)
+            assertNonSecretJobInput(params);
+    }
+    else if (write) {
+        if (job.configuration.kind !== "builtin")
+            throw new Error("Global Jobs require builtin actions.");
+        prepareBuiltinJob(job.configuration, "/");
+        if (job.configuration.action === "project.refresh") {
+            const project = requireRefreshProject(store, job.configuration.projectId, true);
+            if (projectRefreshDigest(job.configuration) !== projectRefreshTargetDigest(project)) {
+                throw new Error("Project refresh target changed; inspect the Project and explicitly update the Job.");
+            }
+            const duplicate = store.listJobDefinitions({ kind: "global" }).find(other => other.id !== job.id && other.configuration.kind === "builtin"
+                && other.configuration.action === "project.refresh" && other.configuration.projectId === project.id);
+            if (duplicate)
+                throw new Error(`Project refresh Job already exists: ${duplicate.id}.`);
+        }
+    }
+}
+export function listJobRuns(store, job) {
+    return (job.scope.kind === "task" ? store.listDurableJobs(job.scope.taskId) : store.listGlobalJobRuns())
+        .filter(run => run.definitionId === job.id);
+}
+/** Read-only presentation; attempts/results remain owned by exact JobRuns. */
+function presentDefinition(store, job) {
+    if (job.configuration.kind !== "builtin" || job.configuration.action !== "project.refresh")
+        return job;
+    const projectId = job.configuration.projectId;
+    const targetDigest = projectRefreshDigest(job.configuration);
+    const runs = listJobRuns(store, job).filter(run => !("taskId" in run)
+        && run.action === "project.refresh" && run.projectId === projectId
+        && projectRefreshDigest({ kind: "builtin", action: run.action,
+            projectId: run.projectId, input: run.actionInput }) === targetDigest)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+    const summarize = (run) => run === undefined ? null : {
+        runId: run.id, definitionRevision: run.definitionRevision, trigger: run.trigger,
+        status: run.status, attemptedAt: run.createdAt, finishedAt: run.terminalAt ?? null
+    };
+    return { ...job, refresh: {
+            projectId, lastAttempt: summarize(runs[0]),
+            lastSuccessfulRefresh: summarize(runs.find(run => run.status === "succeeded"))
+        } };
+}
+function authorizeRunRead(store, run, caller) {
+    // A revised definition's Assignment does not grant access to earlier Runs.
+    if ("taskId" in run)
+        createDurableJobControl(store).getJob(run.taskId, run.id, caller);
+}
+/**
+ * The narrow Schedule seam: call inside the SAME TaskStore transaction as
+ * schedule advancement. No external effects occur here; rollback removes the
+ * admission as well. The caller must be freshly authenticated on every call.
+ */
+export function admitJobRun(store, home, scope, definitionId, caller, trigger, now, retryOf) {
+    return store.transaction(tx => {
+        const job = tx.getJobDefinition(scope, definitionId);
+        if (job === null)
+            throw new Error("Job definition not found.");
+        authorizeDefinition(tx, job, caller, false);
+        if (!trigger.key.trim() || !["manual", "retry", "schedule", "integration"].includes(trigger.source)) {
+            throw new Error("Invalid JobRun trigger.");
+        }
+        const runs = listJobRuns(tx, job);
+        const same = runs.find(run => run.trigger.key === trigger.key && run.trigger.source === trigger.source);
+        if (same !== undefined) {
+            authorizeRunRead(tx, same, caller);
+            if (same.definitionRevision !== job.revision || same.retryOf !== retryOf) {
+                throw new Error(`JobRun trigger conflicts with its original snapshot: ${same.id}.`);
+            }
+            return { run: same, created: false };
+        }
+        authorizeDefinition(tx, job, caller, true);
+        const occupied = runs.find(run => run.status === "queued" || run.status === "running"
+            || run.status === "unknown-needs-attention");
+        if (occupied !== undefined) {
+            authorizeRunRead(tx, occupied, caller);
+            return { run: occupied, created: false, reason: "overlap" };
+        }
+        if (retryOf !== undefined && !runs.some(run => run.id === retryOf
+            && ["failed", "cancelled", "timed-out"].includes(run.status))) {
+            throw new Error("Retry requires an exact failed/cancelled/timed-out Run of this Job.");
+        }
+        const requestId = `job:${job.id}:${trigger.source}:${trigger.key}`;
+        if (scope.kind === "task") {
+            const result = createDurableJobControl(tx).startJob({
+                ...taskParams(job, caller, requestId), definitionId, trigger, retryOf
+            }, now);
+            return { run: result.job, created: result.created };
+        }
+        if (job.configuration.kind !== "builtin")
+            throw new Error("Global Jobs require builtin actions.");
+        const id = `job-${randomUUID()}`;
+        const locator = `artifacts/jobs/global/${id}`;
+        const spec = prepareBuiltinJob(job.configuration, join(home, locator), { home, runId: id });
+        const actorId = `global:${caller.role}`;
+        const run = validateDurableJob({
+            schemaVersion: 1, scope: "global", id, definitionId: job.id, definitionRevision: job.revision,
+            trigger: structuredClone(trigger), action: job.configuration.action,
+            actionInput: structuredClone(job.configuration.input),
+            ...(job.configuration.projectId === undefined ? {} : { projectId: job.configuration.projectId }),
+            ...spec, status: "queued", artifactsLocator: locator,
+            idempotencyKey: createHash("sha256").update(JSON.stringify([actorId, requestId])).digest("hex"),
+            operation: {
+                requestId, actorId, authorityRef: jobAuthorityBinding(tx, "global", caller.role, ""),
+                targetId: job.id, capability: "job.run", implementation: JOB_RUNNER_IMPLEMENTATION,
+                inputDigest: createHash("sha256").update(JSON.stringify([job, trigger, retryOf])).digest("hex"),
+                effect: "none", receiptRefs: [], partialResultRefs: []
+            },
+            ...(retryOf === undefined ? {} : { retryOf }),
+            createdAt: now.toISOString(), updatedAt: now.toISOString()
+        });
+        tx.saveGlobalJobRun(run);
+        return { run, created: true };
+    });
+}
+export function authorizeGlobalJobStart(store, run) {
+    if (run.operation.actorId !== "global:operator"
+        || jobAuthorityBinding(store, "global", "operator", "") !== run.operation.authorityRef) {
+        throw Object.assign(new Error("Global JobRun caller binding was revoked; no execution was started."), { name: "CoreJobError" });
+    }
+    // Storage failures are not domain refusals or proof of no execution.
+    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 });
+        if (run.action === "project.refresh") {
+            const project = requireRefreshProject({ listProjects: () => projects, rootDirectory: () => home }, run.projectId, true);
+            if (projectRefreshTargetDigest(project) !== projectRefreshDigest({
+                kind: "builtin", action: run.action, projectId: run.projectId, input: run.actionInput
+            }))
+                throw new Error("Project refresh target changed before execution.");
+            if (run.workspace !== join(home, "artifacts/jobs/global", run.id)) {
+                throw new Error("Project refresh Run workspace does not match its artifact directory.");
+            }
+        }
+        if (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.");
+        }
+    }
+    catch (error) {
+        throw Object.assign(new Error(error instanceof Error ? error.message : String(error), { cause: error }), { name: "CoreJobError" });
+    }
+}
+/** One bounded RPC surface; legacy job.start/get/cancel remain exact-run APIs. */
+export function createJobDefinitionControl(store, home) {
+    return (value, now) => {
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error("Invalid Job request.");
+        requireKnownFields(value, ["op", "scope", "caller", "id", "title", "configuration", "expectedRevision", "trigger", "retryOf", "runId"], "Job request");
+        const input = value;
+        authorizeScope(store, input.scope, input.caller);
+        return store.transaction(tx => {
+            if (input.op === "list") {
+                return tx.listJobDefinitions(input.scope).filter(job => {
+                    try {
+                        authorizeDefinition(tx, job, input.caller, false);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                }).map(job => presentDefinition(tx, job));
+            }
+            if (typeof input.id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u.test(input.id))
+                throw new Error("An explicit safe Job id is required.");
+            const existing = tx.getJobDefinition(input.scope, input.id);
+            if (input.op === "define" || input.op === "update") {
+                let configuration = input.configuration;
+                // Empty input is an explicit request to bind the current catalog target.
+                // A saved digest is never silently refreshed on run/retry.
+                if (input.scope.kind === "global" && configuration?.kind === "builtin"
+                    && configuration.action === "project.refresh" && JSON.stringify(configuration.input) === "{}") {
+                    const project = requireRefreshProject(tx, configuration.projectId, true);
+                    configuration = { ...configuration, input: { targetDigest: projectRefreshTargetDigest(project) } };
+                }
+                const fields = { title: input.title, configuration };
+                if (input.op === "define") {
+                    const next = createJobDefinition({ id: input.id, scope: input.scope, ...fields }, now);
+                    authorizeDefinition(tx, next, input.caller, true);
+                    if (existing !== null) {
+                        if (JSON.stringify(existing.configuration) !== JSON.stringify(next.configuration) || existing.title !== next.title) {
+                            throw new Error("Job id already exists with different configuration; use update with its revision.");
+                        }
+                        return existing;
+                    }
+                    tx.saveJobDefinition(next);
+                    return next;
+                }
+                if (existing === null || existing.revision !== input.expectedRevision)
+                    throw new Error("Job revision changed or Job missing.");
+                // The old snapshot may no longer be runnable (for example HEAD moved).
+                // Check its ownership before validating the replacement for execution.
+                authorizeDefinition(tx, existing, input.caller, false);
+                const next = reviseJobDefinition(existing, fields, now);
+                authorizeDefinition(tx, next, input.caller, true);
+                tx.saveJobDefinition(next);
+                return next;
+            }
+            if (existing === null)
+                throw new Error("Job definition not found.");
+            validateJobDefinition(existing);
+            authorizeDefinition(tx, existing, input.caller, false);
+            if (input.op === "show")
+                return presentDefinition(tx, existing);
+            if (input.op === "runs")
+                return listJobRuns(tx, existing).filter(run => {
+                    try {
+                        authorizeRunRead(tx, run, input.caller);
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+            if (input.op === "run") {
+                if (input.trigger === undefined)
+                    throw new Error("A trigger identity is required.");
+                // Schedule is an internal transactional caller, not a manual RPC claim.
+                if (!["manual", "retry"].includes(input.trigger.source))
+                    throw new Error("RPC triggers must be manual or retry.");
+                return admitJobRun(tx, home, input.scope, input.id, input.caller, input.trigger, now, input.retryOf);
+            }
+            const run = listJobRuns(tx, existing).find(candidate => candidate.id === input.runId);
+            if (run === undefined)
+                throw new Error("Exact JobRun not found.");
+            authorizeRunRead(tx, run, input.caller);
+            if (input.op === "run-get")
+                return run;
+            if (input.op === "logs") {
+                const steps = run.result?.steps ?? createFileArtifactPort(home)
+                    .readCheckpoint(executionNamespace(run), run.id)?.completedSteps ?? run.checkpoint?.completedSteps ?? [];
+                if (steps.length === 0)
+                    return [];
+                const root = realpathSync(resolve(home, run.artifactsLocator, "logs"));
+                return steps.map(step => {
+                    const path = realpathSync(resolve(root, step.logPath));
+                    if (!path.startsWith(root + sep))
+                        throw new Error("JobRun log escaped its artifact directory.");
+                    const fd = openSync(path, "r");
+                    try {
+                        const size = fstatSync(fd).size;
+                        const bytes = Buffer.alloc(Math.min(size, 65536));
+                        const count = readSync(fd, bytes, 0, bytes.length, Math.max(0, size - bytes.length));
+                        return { step: step.name, path, text: bytes.subarray(0, count).toString("utf8"), truncated: size > bytes.length };
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                });
+            }
+            if (input.op === "run-cancel" || input.op === "run-acknowledge") {
+                if ("taskId" in run) {
+                    const control = createDurableJobControl(tx);
+                    return input.op === "run-cancel"
+                        ? control.cancelJob(run.taskId, run.id, now, input.caller)
+                        : control.acknowledgeJob(run.taskId, run.id, now, input.caller);
+                }
+                const next = input.op === "run-cancel" ? requestDurableJobCancel(run, now) : acknowledgeUnknownDurableJob(run, now);
+                tx.saveGlobalJobRun(next);
+                return next;
+            }
+            throw new Error(`Unknown Job operation: ${input.op}.`);
+        });
+    };
+}

package/dist/controller/jobSupervisor.js

@@ -15,7 +15,7 @@ import { spawn } from "node:child_process";
 import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { cancelQueuedDurableJob, completeDurableJob, isDurableJobTerminal, markDurableJobUnknown, markDurableJobWakeupNotified, rejectQueuedDurableJob, startDurableJob, touchDurableJobHeartbeat } from "../job/durableJob.js";
+import { cancelQueuedDurableJob, completeDurableJob, isDurableJobTerminal, markDurableJobUnknown, markDurableJobWakeupNotified, rejectQueuedDurableJob, startDurableJob, touchDurableJobHeartbeat, executionNamespace } from "../job/durableJob.js";
 import { recordOperationEvidence } from "../kernel/operationFacts.js";
 import { wakeReason } from "../scheduler/wakeReason.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
@@ -45,12 +45,23 @@ export class DurableJobSupervisor {
     }
     reconcile(now) {
         const jobs = this.#store.listActiveDurableJobs();
-        for (const job of jobs) {
+        const refresh = (job) => !("taskId" in job) && job.action === "project.refresh";
+        const waiting = (job) => refresh(job) && job.status === "queued"
+            && job.operation.effect === "none" && !job.cancelRequestedAt;
+        // Harvest/recover existing attempts first. Network operations remain in
+        // detached runners, with at most four outstanding Project refreshes.
+        const ordered = [...jobs.filter(job => !waiting(job)), ...jobs.filter(waiting)];
+        for (const job of ordered) {
             try {
+                if (waiting(job)) {
+                    const occupied = this.#store.listActiveDurableJobs().filter(candidate => refresh(candidate) && (candidate.status === "running" || candidate.operation.effect !== "none"));
+                    if (occupied.length >= 4)
+                        break;
+                }
                 this.#reconcileJob(job, now);
             }
             catch (error) {
-                this.#onError(new Error(`DurableJob supervision failed for ${job.taskId}/${job.id}: `
+                this.#onError(new Error(`DurableJob supervision failed for ${executionNamespace(job)}/${job.id}: `
                     + `${error instanceof Error ? error.message : String(error)}. `
                     + "Inspect retained process/artifact evidence before retry or cancellation; effects remain unconfirmed.", { cause: error }));
             }
@@ -68,14 +79,14 @@ export class DurableJobSupervisor {
     }
     /** Composite key for the SIGKILL deadline map. */
     #sigkillKey(job) {
-        return `${job.taskId}/${job.id}`;
+        return `${executionNamespace(job)}/${job.id}`;
     }
     /** Adopt observed execution, preserve unknown, or start an unattempted request. */
     #reconcileQueued(job, now) {
-        const marker = this.#artifacts.readStartMarker(job.taskId, job.id);
+        const marker = this.#artifacts.readStartMarker(executionNamespace(job), job.id);
         const spawned = this.#spawnedProcessFromEvidence(job, marker);
         if (job.cancelRequestedAt !== undefined) {
-            this.#artifacts.writeCancelFence(job.taskId, job.id);
+            this.#artifacts.writeCancelFence(executionNamespace(job), job.id);
             if (spawned !== null) {
                 this.#process.signalIfOwned(spawned.pid, spawned.startIdentity, "SIGTERM");
             }
@@ -87,13 +98,13 @@ export class DurableJobSupervisor {
         if (job.operation.effect !== "none") {
             // A send intent was committed but no acceptance can be proved. Absence
             // of a file is not proof of no external effect. Never respawn unknown.
-            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(markDurableJobUnknown(current, "runner acceptance is unknown; inspect the original request", current.checkpoint?.completedSteps ?? [], now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => markDurableJobWakeupNotified(markDurableJobUnknown(current, "runner acceptance is unknown; inspect the original request", current.checkpoint?.completedSteps ?? [], now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
             return;
         }
         if (job.cancelRequestedAt !== undefined) {
             // No effect attempted. Cancellation and its wake commit atomically.
-            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(cancelQueuedDurableJob(current, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => markDurableJobWakeupNotified(cancelQueuedDurableJob(current, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
             return;
         }
@@ -112,7 +123,7 @@ export class DurableJobSupervisor {
         // around the spawn), while ready.json is written by the runner itself
         // before any side effect. A disagreement (PID reuse, spawn retry, stale
         // /proc read) is resolved in favor of ready.json.
-        const ready = this.#artifacts.readReadyFile(job.taskId, job.id);
+        const ready = this.#artifacts.readReadyFile(executionNamespace(job), job.id);
         if (ready !== null) {
             return { pid: ready.pid, startIdentity: ready.startIdentity };
         }
@@ -128,9 +139,9 @@ export class DurableJobSupervisor {
      * process. A request with unobserved acceptance instead stays unknown.
      */
     #adoptAndContinue(job, process, now) {
-        this.#store.transitionDurableJob(job.taskId, job.id, (current) => startDurableJob(current, process, now), now);
+        this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => startDurableJob(current, process, now), now);
         // The runner may already have finished while the Controller was down.
-        const exit = this.#artifacts.readExitJson(job.taskId, job.id);
+        const exit = this.#artifacts.readExitJson(executionNamespace(job), job.id);
         if (exit !== null) {
             this.#harvestExit(job, exit, now);
             return;
@@ -153,18 +164,18 @@ export class DurableJobSupervisor {
         }
         const spec = {
             jobId: job.id,
-            taskId: job.taskId,
+            ...("taskId" in job ? { taskId: job.taskId } : { scope: "global" }),
             workspace: job.workspace,
             env: job.env,
             steps: job.steps,
             defaultStepTimeoutMs: DEFAULT_STEP_TIMEOUT_MS,
-            artifactDir: this.#artifacts.artifactDir(job.taskId, job.id),
+            artifactDir: this.#artifacts.artifactDir(executionNamespace(job), job.id),
             head: job.head
         };
-        const specPath = this.#artifacts.writeSpec(job.taskId, job.id, spec);
+        const specPath = this.#artifacts.writeSpec(executionNamespace(job), job.id, spec);
         let attempted;
         try {
-            attempted = this.#store.transitionDurableJob(job.taskId, job.id, (current) => {
+            attempted = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => {
                 if (current.status !== "queued" || current.operation.effect !== "none") {
                     throw new Error("Job already attempted; inspect the original request.");
                 }
@@ -184,7 +195,7 @@ export class DurableJobSupervisor {
             return;
         // Both the request and possible-effect boundary precede spawn. A missing
         // acceptance after this point is unknown, never permission to respawn.
-        this.#artifacts.writeStartMarker(job.taskId, job.id, {
+        this.#artifacts.writeStartMarker(executionNamespace(job), job.id, {
             pid: 0,
             startIdentity: "pending",
             spawnedAt: now.toISOString()
@@ -194,7 +205,7 @@ export class DurableJobSupervisor {
         // the runner's own ready.json is the fallback: the next reconcile reads
         // ready and adopts. The runner checks ready with O_EXCL and exits if it
         // already exists, preventing duplicate execution.
-        this.#artifacts.writeStartMarker(job.taskId, job.id, {
+        this.#artifacts.writeStartMarker(executionNamespace(job), job.id, {
             pid: spawned.pid,
             startIdentity: spawned.startIdentity ?? String(spawned.pid),
             spawnedAt: now.toISOString()
@@ -206,27 +217,27 @@ export class DurableJobSupervisor {
         // terminalized or no longer exists; the recovery interval stays the
         // cross-restart fallback. No new timer is pinned while the Controller is
         // idle — each wake is a single event-driven signal.
-        spawned.onExit?.(() => this.#wake(job.taskId));
-        this.#wake(job.taskId);
+        spawned.onExit?.(() => this.#wake(executionNamespace(job)));
+        this.#wake(executionNamespace(job));
     }
     #rejectStart(job, error, now) {
         // Only an explicit domain refusal is a known failure. Storage/CAS/runtime
         // errors still propagate; never infer rejection from an unavailable read.
         if (!(error instanceof Error) || error.name !== "CoreJobError")
             throw error;
-        const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(rejectQueuedDurableJob(current, error.message, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
+        const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => markDurableJobWakeupNotified(rejectQueuedDurableJob(current, error.message, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
         this.#deliverTerminalEvent(terminal);
     }
     #superviseRunning(job, now) {
         // 1. Harvest exit.json if present.
-        const exit = this.#artifacts.readExitJson(job.taskId, job.id);
+        const exit = this.#artifacts.readExitJson(executionNamespace(job), job.id);
         if (exit !== null) {
             this.#harvestExit(job, exit, now);
             return;
         }
         // 2. Cancel requested: write fence + SIGTERM.
         if (job.cancelRequestedAt !== undefined && job.process !== undefined) {
-            this.#artifacts.writeCancelFence(job.taskId, job.id);
+            this.#artifacts.writeCancelFence(executionNamespace(job), job.id);
             this.#process.signalIfOwned(job.process.pid, job.process.startIdentity, "SIGTERM");
         }
         // 3. Process liveness via pid + startIdentity.
@@ -241,7 +252,7 @@ export class DurableJobSupervisor {
             }
         }
         // 4. Heartbeat freshness.
-        const heartbeatMtime = this.#artifacts.heartbeatMtime(job.taskId, job.id);
+        const heartbeatMtime = this.#artifacts.heartbeatMtime(executionNamespace(job), job.id);
         if (heartbeatMtime !== null) {
             const staleMs = now.getTime() - heartbeatMtime;
             if (staleMs > HEARTBEAT_STALE_MS && job.process !== undefined) {
@@ -255,7 +266,7 @@ export class DurableJobSupervisor {
                 ? Date.parse(job.heartbeatAt)
                 : 0;
             if (heartbeatMtime > recordHeartbeat) {
-                this.#store.transitionDurableJob(job.taskId, job.id, (current) => touchDurableJobHeartbeat(current, new Date(heartbeatMtime)), now);
+                this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => touchDurableJobHeartbeat(current, new Date(heartbeatMtime)), now);
             }
         }
         // 5. SIGKILL escalation.
@@ -268,7 +279,7 @@ export class DurableJobSupervisor {
     #harvestExit(job, exit, now) {
         // Persist the original receipt locator before interpreting its output.
         // A bad schema cannot erase evidence of an already executed runner.
-        this.#store.transitionDurableJob(job.taskId, job.id, (current) => ({
+        this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => ({
             ...current,
             operation: recordOperationEvidence(current.operation, {
                 effect: "confirmed",
@@ -292,7 +303,7 @@ export class DurableJobSupervisor {
         // the adapter enqueues the Leader mailbox entry in the same transaction.
         // A separate #notifyWakeup pass would lose the wakeup if the Controller
         // died between the terminal write and the flag flip.
-        const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => {
+        const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => {
             let completed;
             try {
                 completed = completeDurableJob(current, result, now);
@@ -310,7 +321,7 @@ export class DurableJobSupervisor {
         this.#sigkillAt.delete(this.#sigkillKey(job));
     }
     #handleDeadProcess(job, now) {
-        const checkpoint = this.#artifacts.readCheckpoint(job.taskId, job.id);
+        const checkpoint = this.#artifacts.readCheckpoint(executionNamespace(job), job.id);
         const proven = checkpoint === null ? null : proveOutcomeFromCheckpoint(job, checkpoint);
         // rr4/finding-7: Same atomic wakeup composition as #harvestExit — the
         // terminal transition and the Leader wakeup commit together.
@@ -318,12 +329,12 @@ export class DurableJobSupervisor {
             // The runner died without exit.json, but its step checkpoint covered
             // every planned step: the outcome is still provable from durable
             // evidence. No false pass — the checkpoint is the runner's own record.
-            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, { ...proven, evidenceSource: "checkpoint" }, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => markDurableJobWakeupNotified(completeDurableJob(current, { ...proven, evidenceSource: "checkpoint" }, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
         }
         else {
             const completedSteps = checkpoint?.completedSteps ?? [];
-            const terminal = this.#store.transitionDurableJob(job.taskId, job.id, (current) => markDurableJobWakeupNotified(markDurableJobUnknown(current, "runner process exited without writing exit.json", completedSteps, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
+            const terminal = this.#store.transitionDurableJob(executionNamespace(job), job.id, (current) => markDurableJobWakeupNotified(markDurableJobUnknown(current, "runner process exited without writing exit.json", completedSteps, now), now), now, { reason: wakeReason("job-finished"), refs: wakeupRefs(job) });
             this.#deliverTerminalEvent(terminal);
         }
         this.#sigkillAt.delete(this.#sigkillKey(job));
@@ -339,8 +350,10 @@ export class DurableJobSupervisor {
     #deliverTerminalEvent(job) {
         if (job === null || !isDurableJobTerminal(job.status))
             return;
+        if (!("taskId" in job))
+            return; // The durable Operator mailbox owns global notices.
         this.#terminalEvents?.deliverTerminalEvent({
-            taskId: job.taskId,
+            taskId: executionNamespace(job),
             jobId: job.id,
             status: job.status,
             outcome: job.result?.outcome ?? job.status
@@ -348,9 +361,11 @@ export class DurableJobSupervisor {
     }
 }
 function wakeupRefs(job) {
-    const refs = [{ type: "task", id: job.taskId }];
+    if (!("taskId" in job))
+        return [];
+    const refs = [{ type: "task", id: executionNamespace(job) }];
     if (job.owner.kind === "work-item") {
-        refs.push({ type: "work-item", taskId: job.taskId, id: job.owner.workItemId });
+        refs.push({ type: "work-item", taskId: executionNamespace(job), id: job.owner.workItemId });
     }
     return refs;
 }

package/dist/controller/providerRetryAdmission.js

@@ -2,6 +2,7 @@ import { admitProviderRetry, cancelProviderRetry, providerRetryAttemptId, provid
 import { blockingProviderContinuations } from "../runtime/runtimeContinuationProjection.js";
 import { validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
 import { isDeepStrictEqual } from "node:util";
+import { isHandlingReminder } from "../message/inboxTurn.js";
 export function ownedProviderInput(input) {
     if (input.runId !== undefined && input.taskId !== undefined) {
         return { kind: "run", taskId: input.taskId, runId: input.runId };
@@ -26,6 +27,7 @@ export function retryIntentBlocker(store, input, retry) {
             return "role-configuration-changed";
         if (store.listGlobalRoleMessages(input.roleName).some(message => (message.kind === "user" || message.kind === "operator"
             || message.inputControl !== undefined || message.interruptThen !== undefined)
+            && !isHandlingReminder(message)
             && Date.parse(message.createdAt) > Date.parse(retry.intentAt)
             && message.delivery === undefined && message.notDelivered === undefined))
             return "new-user-input";

package/dist/controller/runtime.js

@@ -45,6 +45,7 @@ import { archiveOrdinaryTask } from "../task/ordinaryArchive.js";
 import { createWebSettings } from "../web/webSettings.js";
 import { createModelManagement } from "../models/modelManagement.js";
 import { createWebSkills } from "../web/webSkills.js";
+import { createWebJobs } from "../web/webJobs.js";
 import { isTaskOwnedWorkspace, sameManagedWorkspaceIdentity } from "../worktree/managedWorkspace.js";
 import { AgentRuntimeObserver } from "./agentRuntimeObserver.js";
 import { createCapabilityDispatcher } from "./capabilityBridge.js";
@@ -55,6 +56,8 @@ import { createEphemeralResourceReaper } from "./ephemeralResourceReaper.js";
 import { AgentHostProviderSessionBusyError, AgentHostProviderTurnFenceError, FileSchedulerStoreAdapter } from "./fileSchedulerStoreAdapter.js";
 import { deliverGlobalInputs } from "./globalInputDelivery.js";
 import { authorizeJobStart } from "./jobControl.js";
+import { authorizeGlobalJobStart, createJobDefinitionControl } from "./jobDefinitionControl.js";
+import { createScheduleControl, reconcileSchedules } from "./scheduleControl.js";
 import { createFileArtifactPort, createLinuxProcessPort, DurableJobSupervisor } from "./jobSupervisor.js";
 import { createProviderRetryHooks } from "./providerRetryDelivery.js";
 import { createRuntimeResourceActivityTracker } from "./resourceInventory.js";
@@ -412,6 +415,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         const web = createControllerWeb(store, {
             previews: () => createTaskPreviews(store, home),
             skills: createWebSkills(store),
+            jobs: createWebJobs(store, home),
             models: createModelManagement(store),
             settings: createWebSettings(store, {
                 environment: options.environment ?? process.env, catalogs,
@@ -483,7 +487,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             store: schedulerStore,
             process: kernel.runner,
             artifacts: createFileArtifactPort(home),
-            authorizeStart: (job) => authorizeJobStart(store, job),
+            authorizeStart: (job) => "taskId" in job ? authorizeJobStart(store, job) : authorizeGlobalJobStart(store, job),
             // rr6/f1: Bounded supervision wake. The supervisor signals the Controller
             // after spawning a runner (queued→running adoption) and when a runner
             // exits (terminal harvest), so a quick job converges without waiting for
@@ -492,7 +496,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             // no-op. The recovery interval stays the cross-restart fallback.
             wake: (taskId) => {
                 try {
-                    runningRuntime?.signal(`task:${taskId}`);
+                    runningRuntime?.signal(taskId === "global" ? "operator" : `task:${taskId}`);
                 }
                 catch {
                     // Controller stopped; the recovery interval remains the fallback.
@@ -568,6 +572,11 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
                 await lifecycleDispatcher("runtime.ensure-role-session", { scope: "global", roleName });
             }, options.onError ?? (() => undefined), deliveryOptions),
             jobControl,
+            jobDefinitions: createJobDefinitionControl(store, home),
+            schedules: {
+                control: createScheduleControl(store, home),
+                reconcile: now => reconcileSchedules(store, home, now, options.onError)
+            },
             capabilityDispatcher: createCapabilityDispatcher(kernel.capabilities),
             ...(continuationReconciler === undefined ? {} : { continuationReconciler }),
             ...(resourceReaper === undefined ? {} : { resourceReaper }),