@zq-silk/yui 2.17.0 → 2.18.0

package/dist/controller/jobDefinitionControl.js

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

package/dist/controller/jobSupervisor.js

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

package/dist/controller/runtime.js

@@ -1,4 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
+import { ControllerDiagnosticJournal } from "./diagnosticJournal.js";
+import { monotonicMilliseconds } from "../core/controllerTelemetry.js";
 import { prepareNativeHostSteer } from "./nativeHostInput.js";
 import { archiveLeaderTask } from "../task/leaderArchive.js";
 import { TaskWorkspaceCoordinator } from "../repository/taskWorkspaceCoordinator.js";
@@ -61,7 +63,6 @@ import { authorizeJobStart } from "./jobControl.js";
 import { authorizeGlobalJobStart, createJobDefinitionControl } from "./jobDefinitionControl.js";
 import { reconcileTaskDelegation } from "./jobTaskDelegationControl.js";
 import { createScheduleControl, reconcileSchedules } from "./scheduleControl.js";
-import { reconcileProjectSync } from "../job/projectSync.js";
 import { createFileArtifactPort, createLinuxProcessPort, DurableJobSupervisor } from "./jobSupervisor.js";
 import { createProviderRetryHooks } from "./providerRetryDelivery.js";
 import { createRuntimeResourceActivityTracker } from "./resourceInventory.js";
@@ -72,8 +73,54 @@ import { AsyncRuntimeEventProcessor, createAsyncRuntimeObserver, FileRuntimeEven
 import { RuntimeLaunchCoordinator } from "./runtimeLaunchCoordinator.js";
 import { SessionOwnerReconciliation } from "./sessionOwnerReconciliation.js";
 import { readTaskAgentCapabilities } from "./agentCapabilities.js";
+import { workerSchedulerStore } from "./workerSchedulerStore.js";
+import { deserializeError } from "../core/boundedRpc.js";
 /** Production composition root for the current SQLite TaskStore + tmux Controller. */
 export async function startFileTaskControllerRuntime(home, options = {}) {
+    const diagnostics = new ControllerDiagnosticJournal(home);
+    let timer;
+    const closeDiagnostics = async () => {
+        if (timer !== undefined)
+            clearInterval(timer);
+        await diagnostics.close();
+    };
+    try {
+        const running = await createFileTaskControllerRuntime(home, {
+            ...options,
+            diagnosticMetrics: () => diagnostics.metrics(),
+            onError: error => { diagnostics.error(error); options.onError?.(error); }
+        });
+        let expectedAt = monotonicMilliseconds() + 250;
+        timer = setInterval(() => {
+            const now = monotonicMilliseconds();
+            const lagMs = Math.max(0, now - expectedAt);
+            expectedAt = now + 250;
+            diagnostics.observe({
+                ...running.runtime.runtimeMetrics(),
+                commands: {
+                    routes: running.server.commandObserver.snapshot(),
+                    eventLoopDelay: running.server.eventLoopDelay.snapshot()
+                }
+            }, lagMs);
+        }, 250);
+        timer.unref();
+        const closed = running.closed.finally(closeDiagnostics);
+        return { ...running, closed, close: async () => {
+                try {
+                    await running.close();
+                }
+                finally {
+                    await closeDiagnostics();
+                }
+            } };
+    }
+    catch (error) {
+        diagnostics.error(error);
+        await closeDiagnostics();
+        throw error;
+    }
+}
+async function createFileTaskControllerRuntime(home, options) {
     // The current Home always uses SQLite. The persistence worker is enabled by
     // default; YUI_STORE_WORKER=0/false keeps the same database in-process.
     const useWorker = resolveStoreWorkerEnabledForHome(home, options.environment ?? process.env);
@@ -111,6 +158,10 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         closeTelemetry = () => telemetry?.sink.close() ?? Promise.resolve();
         const schedulerStore = options.schedulerStore
             ?? new FileSchedulerStoreAdapter(store, telemetry);
+        // Injected stores/adapters retain their owner and semantics. Only the
+        // production SQLite adapter shares the worker's exact Home and behavior.
+        const workerMaintenance = asyncStoreClient !== undefined
+            && options.store === undefined && options.schedulerStore === undefined;
         const domainIdentity = options.domainIdentity
             ?? ephemeralDomainFromEnvironment(options.environment ?? process.env);
         const planner = options.planner ?? new FileRoleLaunchPlanner(home, store, {
@@ -532,7 +583,9 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
         const continuationReconciler = options.continuationMetadata === undefined
             ? undefined
             : new ProviderContinuationReconciliationService(store, schedulerStore, options.continuationMetadata, options.onError);
-        const running = await startFileTaskController(home, schedulerStore, delivery, (method, params) => method === "task.role-capabilities"
+        const running = await startFileTaskController(home, workerMaintenance
+            ? workerSchedulerStore(schedulerStore, asyncStoreClient)
+            : schedulerStore, delivery, (method, params) => method === "task.role-capabilities"
             ? readTaskAgentCapabilities(store, catalogs, params)
             : method === "web.start" || method === "web.stop" || method === "web.status"
                 ? web.dispatch(method, params) : lifecycleDispatcher(method, params), {
@@ -551,6 +604,7 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
                 ?? resolveRuntimeHealth(durableConfig.runtimeHealth).diagnosticAfterMs,
             now: options.now,
             onError: options.onError,
+            diagnosticMetrics: options.diagnosticMetrics,
             lifecycleHost,
             providerRetry: createProviderRetryHooks(home, store, {
                 now: options.now,
@@ -581,8 +635,12 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
             jobDefinitions: createJobDefinitionControl(store, home),
             schedules: {
                 control: createScheduleControl(store, home),
-                reconcile: now => {
-                    reconcileProjectSync(store, now, options.onError);
+                reconcile: async (now) => {
+                    const errors = workerMaintenance
+                        ? await asyncStoreClient.invokeObserver("reconcileProjectSync", [now])
+                        : schedulerStore.reconcileProjectSync(now);
+                    for (const error of errors)
+                        options.onError?.(deserializeError(error));
                     reconcileSchedules(store, home, now, options.onError);
                 }
             },
@@ -600,6 +658,10 @@ export async function startFileTaskControllerRuntime(home, options = {}) {
                 ?? (useWorker && asyncStoreClient !== undefined
                     ? new AsyncRuntimeEventProcessor(runtimeEventInbox, createAsyncRuntimeObserver((method, args) => asyncStoreClient.invokeObserver(method, args)))
                     : new FileRuntimeEventProcessor(runtimeEventInbox, schedulerStore)),
+            persistenceMetrics: () => ({
+                worker: asyncStoreClient?.observationMetrics() ?? null,
+                database: store instanceof SqliteTaskStore ? store.storageObservationMetrics() : null
+            }),
             runtimeObserver: options.runtimeObserver
                 ?? new AgentRuntimeObserver(store, runtimeEventInbox),
             domainIdentity,

package/dist/controller/workerSchedulerStore.js

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

package/dist/core/boundedRpc.js

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

package/dist/core/controllerServer.js

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

package/dist/core/controllerTelemetry.js

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

package/dist/job/globalShell.js

@@ -0,0 +1,51 @@
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { requireKnownFields } from "../domain/validation.js";
+import { validateJobExecutionConfiguration } from "./durableJob.js";
+export function validateJobScriptFiles(files) {
+    if (!Array.isArray(files) || files.length > 64)
+        throw new Error("Job supports at most 64 script files.");
+    const paths = new Set();
+    let bytes = 0;
+    for (const file of files) {
+        requireKnownFields(file, ["path", "content"], "Job script file");
+        if (typeof file.path !== "string" || file.path.length > 240
+            || !/^[a-zA-Z0-9_-][a-zA-Z0-9._/-]*$/u.test(file.path)
+            || file.path.split("/").some((part) => !part || part === "." || part === "..")) {
+            throw new Error("Script paths must be safe relative paths, for example scripts/check.sh.");
+        }
+        if (paths.has(file.path) || [...paths].some(path => path.startsWith(file.path + "/") || file.path.startsWith(path + "/"))) {
+            throw new Error("Script paths must be unique and cannot overlap directories.");
+        }
+        if (typeof file.content !== "string" || file.content.includes("\0"))
+            throw new Error("Scripts must be UTF-8 text without NUL.");
+        bytes += Buffer.byteLength(file.content);
+        if (bytes > 512 * 1024)
+            throw new Error("Job scripts exceed 512 KiB.");
+        paths.add(file.path);
+    }
+}
+export function prepareGlobalShell(configuration, workspace) {
+    requireKnownFields(configuration, ["kind", "env", "steps", "files"], "Global Shell Job");
+    if (configuration.kind !== "shell")
+        throw new Error("Not a Shell Job.");
+    validateJobScriptFiles(configuration.files);
+    // No repository applies. This hash identifies executable configuration,
+    // never a Project commit or an Integration candidate.
+    const head = createHash("sha1").update(JSON.stringify(configuration)).digest("hex");
+    const spec = { workspace, env: configuration.env, steps: configuration.steps, head };
+    validateJobExecutionConfiguration(spec);
+    return spec;
+}
+/** A fresh per-Run directory; never overwrite another run's files or follow
+ * a pre-existing workspace. The runner's exclusive ready receipt fences replay. */
+export function materializeJobScripts(workspace, files) {
+    validateJobScriptFiles(files);
+    mkdirSync(workspace, { mode: 0o700 });
+    for (const file of files) {
+        const path = join(workspace, file.path);
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, file.content, { flag: "wx", mode: 0o700 });
+    }
+}

package/dist/job/jobBusinessResult.js

@@ -62,9 +62,10 @@ export function jobRunSnapshot(run) {
         ...runReference(run), definitionId: run.definitionId, definitionRevision: run.definitionRevision,
         owner: "owner" in run ? run.owner : null,
         trigger: run.trigger, retryOf: run.retryOf ?? null,
-        executor: run.delegation ? { kind: "task", delegation: run.delegation } : "taskId" in run ? { kind: "shell" } : {
-            kind: "builtin", action: run.action, input: run.actionInput
-        },
+        executor: run.delegation ? { kind: "task", delegation: run.delegation } : "taskId" in run ? { kind: "shell" }
+            : run.action === "shell.exec" ? { kind: "shell", configuration: run.actionInput } : {
+                kind: "builtin", action: run.action, input: run.actionInput
+            },
         target: run.delegation ? { taskId: run.delegation.taskId, workItemId: run.delegation.workItemId ?? null }
             : { projectId: run.projectId ?? null, workspace: run.workspace, head: run.head },
         execution: run.delegation ? null : { env: run.env, steps: run.steps, implementation: run.operation.implementation }

package/dist/job/jobDefinition.js

@@ -2,6 +2,7 @@ import { requireIdentity, requireKnownFields, requirePositiveInteger, requireTex
 import { validateJobExecutionConfiguration, validateDurableJobOwner } from "./durableJob.js";
 import { validateAgentJobConfiguration } from "./agentJob.js";
 import { validateTaskJobConfiguration } from "./taskDelegation.js";
+import { prepareGlobalShell } from "./globalShell.js";
 export function jobScopeKey(scope) {
     if (scope.kind === "global")
         return "global";
@@ -44,6 +45,10 @@ export function validateJobDefinition(job) {
         validateTaskJobConfiguration(config);
     }
     else if (job.scope.kind === "global") {
+        if (config.kind === "shell") {
+            prepareGlobalShell(config, "/job-validation");
+            return job;
+        }
         if (config.kind !== "builtin")
             throw new Error("Global Jobs require a controlled builtin action.");
         requireKnownFields(config, ["kind", "action", "projectId", "input"], "Builtin Job");
@@ -54,7 +59,7 @@ export function validateJobDefinition(job) {
             throw new Error("Builtin Job input is required.");
     }
     else {
-        if (config.kind !== "shell")
+        if (config.kind !== "shell" || !("owner" in config))
             throw new Error("Task Jobs require a managed shell configuration.");
         requireKnownFields(config, ["kind", "owner", "projectId", "head", "workspace", "env", "steps"], "Task Job");
         requireIdentity(config.projectId, "Job Project id");

package/dist/job/jobRunner.js

@@ -13,6 +13,7 @@ import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { jobStepDirectory } from "./stepDirectory.js";
 import { prepareHttpPreview, isHttpPreview } from "./httpPreview.js";
+import { materializeJobScripts, validateJobScriptFiles } from "./globalShell.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { currentProcessStartIdentity } from "../core/fileLockOwner.js";
 const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
@@ -112,6 +113,8 @@ export async function runDurableJobRunner(specPath) {
     let failedStep;
     let preview;
     try {
+        if (spec.files !== undefined)
+            materializeJobScripts(spec.workspace, spec.files);
         for (let index = 0; index < spec.steps.length; index += 1) {
             if (cancelled || existsSync(cancelPath)) {
                 cancelled = true;
@@ -278,6 +281,12 @@ function readSpec(specPath) {
     if (typeof spec.artifactDir !== "string" || !spec.artifactDir.startsWith("/")) {
         throw new Error("DurableJob spec artifactDir must be an absolute path.");
     }
+    if (spec.files !== undefined) {
+        if (spec.scope !== "global" || spec.workspace !== join(spec.artifactDir, "workspace")) {
+            throw new Error("Job script snapshots require their own global Run workspace.");
+        }
+        validateJobScriptFiles(spec.files);
+    }
     if (typeof spec.head !== "string" || spec.head.length === 0) {
         throw new Error("DurableJob spec is missing head.");
     }

package/dist/job/scheduleService.js

@@ -4,6 +4,8 @@ import { requireProjectSyncTarget } from "./projectSync.js";
 /** Internal compiled registration, not a caller identity accepted by RPC. */
 const actions = new Set(["system.noop", "project.refresh"]);
 export function requireServiceTarget(job) {
+    if (job.scope.kind === "global" && job.configuration.kind === "shell")
+        return;
     if (job.scope.kind !== "global" || job.configuration.kind !== "builtin"
         || !actions.has(job.configuration.action))
         throw new Error("Schedule service is not registered for this scope/action.");