@zq-silk/yui 2.11.0 → 2.12.0

package/dist/job/projectSync.js

@@ -0,0 +1,162 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, realpathSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import { join, resolve } from "node:path";
+import { managedProjectPath } from "../repository/project.js";
+import { requireRefreshProject, projectRefreshTargetDigest } from "../repository/projectRefresh.js";
+import { createJobDefinition, reviseJobDefinition, validateJobDefinition } from "./jobDefinition.js";
+import { nextScheduleDue, validateScheduleRule } from "../schedule/schedule.js";
+import { scheduleServiceBinding } from "./scheduleService.js";
+const scope = { kind: "global" };
+const unavailable = "Project sync unavailable: ";
+export const PROJECT_SYNC_INTERVAL_MS = 6 * 60 * 60_000;
+/** Called under the maintenance lock immediately before Git, not a timer probe. */
+export function requireProjectSyncCheckout(store, job) {
+    requireProjectSyncTarget(store, job);
+    const path = managedProjectPath(store.rootDirectory(), job.configuration.kind === "builtin" ? job.configuration.projectId : "");
+    if (realpathSync(path) !== path || !lstatSync(join(path, ".git")).isDirectory()
+        || lstatSync(join(path, ".git")).isSymbolicLink()) {
+        throw new Error("Builtin sync requires its own canonical checkout, not a linked or shared worktree.");
+    }
+}
+/** Current registry and maintenance source, not the builtin label, bound authority. */
+export function requireProjectSyncTarget(store, job) {
+    if (job.builtin !== "project-sync" || job.configuration.kind !== "builtin")
+        throw new Error("Not a builtin Project sync.");
+    validateJobDefinition(job);
+    const project = requireRefreshProject(store, job.configuration.projectId, true);
+    if (resolve(project.path) !== managedProjectPath(store.rootDirectory(), project.id)) {
+        throw new Error("Project sync requires its canonical managed checkout.");
+    }
+    if (!isDeepStrictEqual(job.configuration.input, { targetDigest: projectRefreshTargetDigest(project) })) {
+        throw new Error("Project sync target changed; await registry reconciliation.");
+    }
+    const custom = store.listJobDefinitions(scope).find(other => !other.builtin && !other.instantiation
+        && other.configuration.kind === "builtin" && other.configuration.action === "project.refresh"
+        && other.configuration.projectId === project.id);
+    if (custom)
+        throw new Error(`Existing custom maintenance Job ${custom.id}; builtin sync does not take it over. Explicitly retarget that Job before enabling builtin sync.`);
+}
+function grant(store, plan, job, now) {
+    requireProjectSyncTarget(store, job);
+    const grantId = randomUUID();
+    return { kind: "service", service: "schedule", grantId, revoked: false, jobRevision: job.revision,
+        grantedBy: { scope: "service", service: "project-sync" }, grantedAt: now.toISOString(),
+        binding: scheduleServiceBinding(store, plan, job, grantId) };
+}
+/** Called by the existing Controller Schedule pass, with no timer or Git effects. */
+export function reconcileProjectSync(store, now, onError = () => { }) {
+    const ids = new Set([...store.listProjects().map(p => p.id),
+        ...store.listSchedules(scope).flatMap(s => s.builtin ? [s.builtin.projectId] : [])]);
+    for (const projectId of ids) {
+        try {
+            store.transaction(tx => {
+                const id = `project-sync-${projectId}`;
+                const project = tx.listProjects().find(p => p.id === projectId);
+                let job = tx.getJobDefinition(scope, id);
+                let plan = tx.getSchedule(scope, id);
+                if ((job && job.builtin !== "project-sync") || (plan && !plan.builtin)) {
+                    throw new Error(`Reserved builtin identity ${id} is occupied; existing records were not adopted.`);
+                }
+                if (!job && !project)
+                    return;
+                let changed = false;
+                if (project) {
+                    const configuration = { kind: "builtin", action: "project.refresh", projectId,
+                        input: { targetDigest: projectRefreshTargetDigest(project) } };
+                    if (!job) {
+                        job = validateJobDefinition({ ...createJobDefinition({ id, scope, title: `Project sync · ${project.name}`, configuration }, now),
+                            builtin: "project-sync" });
+                        tx.saveJobDefinition(job);
+                        changed = true;
+                    }
+                    else if (!isDeepStrictEqual(job.configuration, configuration)) {
+                        job = reviseJobDefinition(job, { title: job.title, configuration }, now);
+                        tx.saveJobDefinition(job);
+                        changed = true;
+                    }
+                }
+                if (!job)
+                    throw new Error(`Builtin Project sync definition missing: ${id}.`);
+                let reason;
+                try {
+                    requireProjectSyncTarget(tx, job);
+                }
+                catch (error) {
+                    reason = unavailable + (error instanceof Error ? error.message : String(error));
+                }
+                if (!plan) {
+                    const rule = { kind: "interval", anchor: new Date(now.getTime() + PROJECT_SYNC_INTERVAL_MS).toISOString(),
+                        everyMs: PROJECT_SYNC_INTERVAL_MS };
+                    const grantId = randomUUID();
+                    plan = { schemaVersion: 1, id, scope, jobId: id, target: { kind: "existing-job" }, rule,
+                        builtin: { projectId, enabled: true }, revision: 1, generation: 1,
+                        state: reason ? "needs-attention" : "enabled", nextDue: nextScheduleDue(rule, now),
+                        authorization: { kind: "service", service: "schedule", grantId, revoked: true, jobRevision: job.revision,
+                            grantedBy: { scope: "service", service: "project-sync" }, grantedAt: now.toISOString(),
+                            binding: scheduleServiceBinding(tx, { id, scope, jobId: id, target: { kind: "existing-job" } }, job, grantId) },
+                        ...(reason ? { reason } : {}), createdAt: now.toISOString(), updatedAt: now.toISOString() };
+                    if (!reason)
+                        plan = { ...plan, authorization: grant(tx, plan, job, now) };
+                    tx.saveSchedule(plan);
+                    return;
+                }
+                const original = plan;
+                if (plan.authorization.kind !== "service")
+                    throw new Error("Builtin Schedule requires service authority.");
+                if (reason || !plan.builtin.enabled) {
+                    plan = { ...plan, state: plan.builtin.enabled ? "needs-attention" : "disabled",
+                        reason: reason ?? "Project sync disabled by user.",
+                        authorization: { ...plan.authorization, revoked: true } };
+                }
+                else if (changed || plan.reason?.startsWith(unavailable)) {
+                    const { reason: _reason, ...rest } = plan;
+                    const after = new Date(Math.max(now.getTime(), Date.parse(plan.processedThrough ?? "") || 0));
+                    plan = { ...rest, state: "enabled", nextDue: nextScheduleDue(plan.rule, after),
+                        processedThrough: after.toISOString(), generation: plan.generation + 1,
+                        authorization: grant(tx, plan, job, now) };
+                }
+                // Unchanged dispatch failures are visible, not automatically retried/re-authorized.
+                if (!isDeepStrictEqual(original, plan))
+                    tx.saveSchedule({
+                        ...plan, revision: original.revision + 1, updatedAt: now.toISOString()
+                    });
+            });
+        }
+        catch (error) {
+            onError(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+}
+/** Narrow user override. No alternative writable target or authorization surface. */
+export function updateProjectSync(store, previous, op, rule, now) {
+    if (!previous.builtin || previous.authorization.kind !== "service")
+        throw new Error("Not a builtin Schedule.");
+    if (!["enable", "disable", "revoke", "update"].includes(op))
+        throw new Error("Unsupported builtin Schedule operation.");
+    const nextRule = rule ?? previous.rule;
+    validateScheduleRule(nextRule);
+    if (nextRule.kind === "once" || (nextRule.kind === "interval" && nextRule.everyMs < 60_000)) {
+        throw new Error("Builtin sync requires a recurring rule (interval at least 60000ms, or five-field cron).");
+    }
+    const enabled = op === "enable" ? true : ["disable", "revoke"].includes(op) ? false : previous.builtin.enabled;
+    const after = new Date(Math.max(now.getTime(), Date.parse(previous.processedThrough ?? "") || 0));
+    const { reason: _reason, ...rest } = previous;
+    let next = { ...rest, builtin: { ...previous.builtin, enabled }, rule: structuredClone(nextRule),
+        state: enabled ? "enabled" : "disabled", revision: previous.revision + 1,
+        generation: previous.generation + (op === "update" ? 1 : 0), updatedAt: now.toISOString(),
+        nextDue: nextScheduleDue(nextRule, after), processedThrough: after.toISOString() };
+    if (!enabled)
+        next = { ...next, reason: "Project sync disabled by user.",
+            authorization: { ...previous.authorization, revoked: true } };
+    else {
+        const job = store.getJobDefinition(scope, previous.jobId);
+        if (!job)
+            throw new Error("Builtin definition missing.");
+        requireProjectSyncTarget(store, job);
+        next = { ...next, authorization: previous.authorization.revoked || op === "enable"
+                ? grant(store, next, job, now) : previous.authorization };
+    }
+    store.saveSchedule(next);
+    return next;
+}

package/dist/job/scheduleService.js

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+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 !== "builtin"
+        || !actions.has(job.configuration.action))
+        throw new Error("Schedule service is not registered for this scope/action.");
+}
+export function scheduleServiceBinding(store, schedule, job, grantId) {
+    requireServiceTarget(job);
+    return createHash("sha256").update(JSON.stringify([
+        "schedule-service/v1", store.getHomeIdentity().homeId, grantId,
+        schedule.id, schedule.scope, schedule.jobId, schedule.target, job
+    ])).digest("hex");
+}
+export function requireScheduleService(store, ref) {
+    const schedule = store.getSchedule({ kind: "global" }, ref.scheduleId);
+    const auth = schedule?.authorization;
+    if (!schedule || auth?.kind !== "service" || auth.revoked || auth.grantId !== ref.grantId) {
+        throw new Error("Schedule service authority was revoked; no execution was started.");
+    }
+    const source = store.getJobDefinition(schedule.scope, schedule.jobId);
+    if (!source || source.revision !== auth.jobRevision
+        || scheduleServiceBinding(store, schedule, source, auth.grantId) !== auth.binding) {
+        throw new Error("Schedule service target or authority changed; explicitly reauthorize.");
+    }
+    if (schedule.builtin) {
+        if (!schedule.builtin.enabled)
+            throw new Error("Builtin Project sync was disabled.");
+        requireProjectSyncTarget(store, source);
+    }
+    return schedule;
+}
+/** Bind each immutable Run to its exact stored grant, definition and input. */
+export function serviceRunBinding(store, run, schedule) {
+    return createHash("sha256").update(JSON.stringify([
+        "schedule-service-run/v1", store.getHomeIdentity().homeId, schedule.authorization.binding,
+        run.serviceAuthorization, run.id, run.definitionId, run.definitionRevision,
+        run.action, run.projectId, run.actionInput, run.trigger, run.operation.requestId
+    ])).digest("hex");
+}
+export function authorizeServiceJob(store, job, ref, key) {
+    const schedule = requireScheduleService(store, ref);
+    const source = store.getJobDefinition(schedule.scope, schedule.jobId);
+    const matches = schedule.target.kind === "existing-job" ? job.id === source.id
+        : job.instantiation?.sourceId === source.id && job.instantiation.sourceRevision === source.revision
+            && job.instantiation.key === key;
+    if (!matches || !key.startsWith(`${schedule.id}:`)
+        || !isDeepStrictEqual(job.configuration, source.configuration)) {
+        throw new Error("Job is outside the Schedule service authority target.");
+    }
+    return schedule;
+}

package/dist/job/taskDelegation.js

@@ -0,0 +1,48 @@
+import { requireIdentity, requireKnownFields, requireText } from "../domain/validation.js";
+import { createTask, validateTask } from "../task/task.js";
+import { createHash } from "node:crypto";
+/** WorkItem revision also advances on execution/candidate submission. Freeze
+ * requirements, not that mutable progress counter, as the delegated scope. */
+export function workItemDefinitionDigest(work) {
+    return createHash("sha256").update(JSON.stringify([work.title, work.objective, work.acceptance,
+        work.dependsOn, work.writeProjectIds, work.baseRefs ?? null])).digest("hex");
+}
+export function validateTaskJobConfiguration(config) {
+    requireKnownFields(config, ["kind", "goal", "target"], "Task Job");
+    if (config.target.kind === "new") {
+        requireKnownFields(config.target, ["kind", "title", "description", "type", "projectBindings"], "New Task target");
+        if (!["delivery", "task-created"].includes(config.goal))
+            throw new Error("New Task requires a delivery or explicit task-created goal.");
+        requireText(config.target.description, "Task requirements");
+        if (!Array.isArray(config.target.projectBindings))
+            throw new Error("Explicit Task Project bindings required.");
+        for (const binding of config.target.projectBindings) {
+            requireKnownFields(binding, ["projectId", "directory", "baseRef"], "Draft Project binding");
+        }
+        validateTask(createTask("task-1", config.target.title, new Date(0), config.target));
+    }
+    else if (config.target.kind === "work-item" && config.goal === "work-item") {
+        requireKnownFields(config.target, ["kind", "taskId", "workItemId", "revision"], "WorkItem target");
+        requireIdentity(config.target.taskId, "Target Task");
+        requireIdentity(config.target.workItemId, "Target WorkItem");
+        if (!/^task-\d+$/u.test(config.target.taskId) || !/^work-item-\d+$/u.test(config.target.workItemId)
+            || !Number.isSafeInteger(config.target.revision) || config.target.revision < 1)
+            throw new Error("Exact WorkItem scope and revision required.");
+    }
+    else
+        throw new Error("Invalid Task delegation target/goal.");
+}
+export function validateTaskDelegation(value) {
+    requireKnownFields(value, ["taskId", "goal", "workItemId", "workItemRevision", "workItemDefinitionDigest"], "Task delegation");
+    if (!/^task-\d+$/u.test(value.taskId))
+        throw new Error("Invalid delegated Task.");
+    if (value.goal === "work-item") {
+        if (!/^work-item-\d+$/u.test(value.workItemId ?? "")
+            || !Number.isSafeInteger(value.workItemRevision) || value.workItemRevision < 1
+            || !/^[a-f0-9]{64}$/u.test(value.workItemDefinitionDigest ?? ""))
+            throw new Error("Exact delegated WorkItem required.");
+    }
+    else if (!["delivery", "task-created"].includes(value.goal) || value.workItemId !== undefined
+        || value.workItemRevision !== undefined || value.workItemDefinitionDigest !== undefined)
+        throw new Error("Invalid delegated goal.");
+}

package/dist/message/messageContinuation.js

@@ -32,7 +32,7 @@ export function resolveMessageRecipient(store, taskId, roleName, scope) {
 /** Current Assignment authority, independent of eligibility to start a new Run.
  * A Reviewer still owns its frozen clarification when Task main advances. */
 export function messageAssignmentBlocker(store, message) {
-    if (isTaskRecordRetired(store.listEvents(message.taskId), "message", message.id))
+    if (message.id !== undefined && isTaskRecordRetired(store.listEvents(message.taskId), "message", message.id))
         return "message-retired";
     const target = message.recipient;
     if (target?.ownerRunId === undefined)

package/dist/resources/projectResourceService.js

@@ -308,7 +308,7 @@ export function createProjectResources(store, now = () => new Date()) {
                             || (run.workspace && overlaps(run.workspace.root, value.directory.path))))
                         || sessionSets.some((set) => [...Object.values(set.sessions), ...(set.history ?? [])].some((session) => session.status === "active" && references(session.effective.executionEnvironment)))
                         || tx.listDurableJobs(taskId).some((job) => ["queued", "running", "unknown-needs-attention"].includes(job.status)
-                            && overlaps(job.workspace, value.directory.path))))
+                            && !job.delegation && overlaps(job.workspace, value.directory.path))))
                         throw new Error("Environment still has a live or unknown execution reference.");
                 }
                 if (value.directory?.ownership === "preparation") {

package/dist/resources/resourceGc.js

@@ -43,7 +43,7 @@ export function readResourceGcState(store) {
                 }),
                 ...reader.listDurableJobs(task.id).filter(job => job.status === "queued" || job.status === "running"
                     || (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined))
-                    .map(job => job.workspace)
+                    .flatMap(job => job.delegation ? [] : [job.workspace])
             ])
         };
     });

package/dist/role/role.js

@@ -1,4 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
+import { requireKnownFields } from "../domain/validation.js";
+import { jobScopeKey } from "../job/jobDefinition.js";
 import { validateExecutionEnvironmentSnapshot } from "../resources/projectResource.js";
 import { isAgentAdapterId } from "../agent/adapterCatalog.js";
 import { adapterIdForExecutionComponent, resolveAgentExecutionComponent } from "../agent/executionComponents.js";
@@ -189,6 +191,16 @@ export function unbindRoleAgent(role, sessions, agentId, now) {
 export function validateGlobalRole(role) {
     if (Object.hasOwn(role, "taskId"))
         throw new Error("Global Role cannot carry a Task identity.");
+    if (role.jobOwner !== undefined) {
+        requireKnownFields(role.jobOwner, ["scope", "jobId", "runId"], "Job Role owner");
+        requireKnownFields(role.jobOwner.scope, role.jobOwner.scope.kind === "task" ? ["kind", "taskId"] : ["kind"], "Job Role scope");
+        if (!["task", "global"].includes(role.jobOwner.scope.kind) || role.name === "operator")
+            throw new Error("Invalid Job Role owner.");
+        jobScopeKey(role.jobOwner.scope);
+        requireSafeIdentity(role.jobOwner.jobId, "Job Role owner id");
+        if (role.jobOwner.runId !== undefined)
+            requireSafeIdentity(role.jobOwner.runId, "Job Role Run id");
+    }
     return validateRoleOwner(role);
 }
 export function validateTaskRole(role) {

package/dist/schedule/schedule.js

@@ -1,6 +1,7 @@
 import { CronExpressionParser } from "cron-parser";
 import { requireKnownFields, requirePositiveInteger, requireTimestamp, requireText } from "../domain/validation.js";
 import { jobScopeKey } from "../job/jobDefinition.js";
+import { parseDurableJobCaller } from "../controller/jobControl.js";
 export function scheduleId(id) {
     if (typeof id !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u.test(id)) {
         throw new Error("An explicit safe Schedule/Job id is required.");
@@ -49,16 +50,25 @@ export function nextScheduleDue(rule, after) {
     return CronExpressionParser.parse(rule.expression, { currentDate: after, tz: rule.timezone }).next().toISOString();
 }
 export function validateSchedule(value) {
-    requireKnownFields(value, ["schemaVersion", "id", "scope", "jobId", "rule", "revision", "generation",
-        "state", "nextDue", "processedThrough", "authorization", "lastAttempt", "reason", "createdAt", "updatedAt"], "Schedule");
+    requireKnownFields(value, ["schemaVersion", "id", "scope", "jobId", "target", "rule", "revision", "generation",
+        "state", "nextDue", "processedThrough", "authorization", "builtin", "lastAttempt", "reason", "createdAt", "updatedAt"], "Schedule");
     if (value.schemaVersion !== 1)
         throw new Error("Invalid Schedule schema.");
     scheduleId(value.id);
     scheduleId(value.jobId);
+    validateScheduleTarget(value.target);
     if (!["task", "global"].includes(value.scope.kind))
         throw new Error("Invalid Schedule scope.");
     requireKnownFields(value.scope, value.scope.kind === "task" ? ["kind", "taskId"] : ["kind"], "Schedule scope");
     jobScopeKey(value.scope);
+    if (value.builtin !== undefined) {
+        requireKnownFields(value.builtin, ["projectId", "enabled"], "Builtin Schedule");
+        if (!/^project-\d+$/u.test(value.builtin.projectId) || typeof value.builtin.enabled !== "boolean"
+            || value.scope.kind !== "global" || value.id !== `project-sync-${value.builtin.projectId}`
+            || value.jobId !== value.id || value.target.kind !== "existing-job"
+            || value.authorization.kind !== "service")
+            throw new Error("Invalid builtin Schedule.");
+    }
     validateScheduleRule(value.rule);
     requirePositiveInteger(value.revision, "Schedule revision");
     requirePositiveInteger(value.generation, "Schedule generation");
@@ -74,35 +84,75 @@ export function validateSchedule(value) {
         instant(value.processedThrough);
     instant(value.createdAt);
     instant(value.updatedAt);
-    requireKnownFields(value.authorization, ["caller", "binding", "jobRevision"], "Schedule authorization");
     requirePositiveInteger(value.authorization.jobRevision, "Schedule Job revision");
     if (typeof value.authorization.binding !== "string" || !/^[a-f0-9]{64}$/u.test(value.authorization.binding))
         throw new Error("Invalid Schedule authority binding.");
-    const caller = value.authorization.caller;
-    requireKnownFields(caller, ["scope", "taskId", "role", "agentId", "adapterId", "nativeSessionId", "runId"], "Schedule caller");
-    if (typeof caller.role !== "string" || typeof caller.nativeSessionId !== "string")
-        throw new Error("Schedule authority requires a Role and Session.");
-    requireText(caller.role, "Schedule caller role");
-    requireText(caller.nativeSessionId, "Schedule caller Session");
-    if (caller.scope === "global") {
-        if (caller.role !== "operator")
-            throw new Error("Global Schedule authority requires Operator.");
+    if (value.authorization.kind === "service") {
+        requireKnownFields(value.authorization, ["kind", "service", "grantId", "revoked", "binding", "jobRevision", "grantedBy", "grantedAt"], "Schedule service authorization");
+        if (value.scope.kind !== "global" || value.authorization.service !== "schedule"
+            || typeof value.authorization.revoked !== "boolean")
+            throw new Error("Invalid Schedule service scope or registration.");
+        scheduleId(value.authorization.grantId);
+        instant(value.authorization.grantedAt);
+        if (value.authorization.grantedBy.scope === "service") {
+            requireKnownFields(value.authorization.grantedBy, ["scope", "service"], "Builtin service issuer");
+            if (value.authorization.grantedBy.service !== "project-sync" || value.builtin === undefined) {
+                throw new Error("Invalid builtin service issuer.");
+            }
+        }
+        else {
+            const manager = parseDurableJobCaller(value.authorization.grantedBy);
+            if ((manager.scope === "user" && Object.keys(manager).length !== 1)
+                || (manager.scope !== "user" && (manager.scope !== "global" || manager.role !== "operator" || !manager.nativeSessionId))) {
+                throw new Error("Invalid service grant issuer.");
+            }
+        }
     }
-    else if (caller.scope !== "task" || value.scope.kind !== "task" || caller.taskId !== value.scope.taskId) {
-        throw new Error("Schedule caller must belong to its scope.");
+    else {
+        requireKnownFields(value.authorization, ["kind", "caller", "binding", "jobRevision"], "Schedule authorization");
+        if (value.authorization.kind !== "session")
+            throw new Error("Explicit Schedule authorization kind is required.");
+        const caller = value.authorization.caller;
+        requireKnownFields(caller, ["scope", "taskId", "role", "agentId", "adapterId", "nativeSessionId", "runId"], "Schedule caller");
+        if (typeof caller.role !== "string" || typeof caller.nativeSessionId !== "string")
+            throw new Error("Schedule authority requires a Role and Session.");
+        requireText(caller.role, "Schedule caller role");
+        requireText(caller.nativeSessionId, "Schedule caller Session");
+        if (caller.scope === "global") {
+            if (caller.role !== "operator")
+                throw new Error("Global Schedule authority requires Operator.");
+        }
+        else if (caller.scope !== "task" || value.scope.kind !== "task" || caller.taskId !== value.scope.taskId) {
+            throw new Error("Schedule caller must belong to its scope.");
+        }
     }
     if (value.reason !== undefined)
         requireText(value.reason, "Schedule reason");
     if (value.lastAttempt !== undefined) {
-        requireKnownFields(value.lastAttempt, ["at", "dueAt", "outcome", "runId", "reason"], "Schedule attempt");
+        requireKnownFields(value.lastAttempt, ["at", "dueAt", "outcome", "runId", "jobId", "generation", "reason"], "Schedule attempt");
         instant(value.lastAttempt.at);
         instant(value.lastAttempt.dueAt);
         if (!["admitted", "overlap", "blocked"].includes(value.lastAttempt.outcome))
             throw new Error("Invalid Schedule attempt.");
         if (value.lastAttempt.runId !== undefined)
             requireText(value.lastAttempt.runId, "Schedule Run id");
+        if (value.lastAttempt.jobId !== undefined)
+            scheduleId(value.lastAttempt.jobId);
+        if (value.lastAttempt.generation !== undefined)
+            requirePositiveInteger(value.lastAttempt.generation, "Schedule attempt generation");
         if (value.lastAttempt.reason !== undefined)
             requireText(value.lastAttempt.reason, "Schedule attempt reason");
     }
     return value;
 }
+export function validateScheduleTarget(target) {
+    if (target?.kind === "existing-job")
+        requireKnownFields(target, ["kind"], "Schedule target");
+    else if (target?.kind === "new-job") {
+        requireKnownFields(target, ["kind", "definitionRevision"], "Schedule target");
+        requirePositiveInteger(target.definitionRevision, "Schedule source definition revision");
+    }
+    else
+        throw new Error("Invalid Schedule target.");
+    return target;
+}

package/dist/scheduler/wakeReason.js

@@ -24,6 +24,7 @@ export const WAKE_REASON_KINDS = Object.freeze([
     "leader-turn-failed",
     "role-turn-failed",
     "job-finished",
+    "job-agent-input",
     "published-tree-authorized",
     "notification-retry",
     "force-wake"
@@ -31,6 +32,9 @@ export const WAKE_REASON_KINDS = Object.freeze([
 const IMMEDIATE_KINDS = new Set([
     "operator-input",
     "user-message",
+    // An explicitly admitted Agent Job is new input, not a background result
+    // to debounce. All existing busy/ownership/delivery checks still apply.
+    "job-agent-input",
     "task-created",
     "execution-started",
     "session-replaced",

package/dist/storage/agentJobSchema.js

@@ -0,0 +1,10 @@
+/** Storage 1.18: Agent Runs are not shell runs with fabricated Task/workspace fields. */
+export const AGENT_JOB_SCHEMA_SQL = `
+CREATE TABLE agent_job_runs (
+  run_id TEXT PRIMARY KEY,
+  scope_key TEXT NOT NULL,
+  definition_id TEXT NOT NULL,
+  payload TEXT NOT NULL
+);
+CREATE INDEX idx_agent_job_runs_owner ON agent_job_runs(scope_key, definition_id);
+`;

package/dist/storage/recordValidation.js

@@ -9,6 +9,7 @@ import { validateChangeSet } from "../integration/changeSet.js";
 import { validateIntegrationAttempt } from "../integration/integrationAttempt.js";
 import { validateDurableJob } from "../job/durableJob.js";
 import { validateJobDefinition } from "../job/jobDefinition.js";
+import { validateAgentJobRun } from "../job/agentJob.js";
 import { validateSchedule } from "../schedule/schedule.js";
 import { validateGlobalRoleMessage, validateTaskMessage } from "../message/message.js";
 import { validateMilestone } from "../milestone/milestone.js";
@@ -57,6 +58,7 @@ const validators = {
     integration_attempts: check(validateIntegrationAttempt),
     durable_jobs: check(validateDurableJob),
     job_definitions: check(validateJobDefinition),
+    agent_job_runs: check(validateAgentJobRun),
     schedules: check(validateSchedule),
     global_job_runs: check(validateDurableJob),
     context_snapshots: check(validateContextSnapshot),

package/dist/storage/sqliteSchema.js

@@ -4,12 +4,15 @@ import { BASELINE_SCHEMA_SQL, SQLITE_SCHEMA_TABLES as BASELINE_SCHEMA_TABLES } f
 import { migrateTaskMainWorkspaces } from "./upgrade/taskMainWorkspaceMigration.js";
 import { migrateProjectKnowledge } from "./upgrade/projectKnowledgeMigration.js";
 import { JOB_SCHEMA_SQL } from "./jobSchema.js";
+import { AGENT_JOB_SCHEMA_SQL } from "./agentJobSchema.js";
 import { SCHEDULE_SCHEMA_SQL } from "./scheduleSchema.js";
 import { GLOBAL_SESSION_TABLE_SQL, SESSION_HISTORY_UPGRADE_SQL } from "./sessionHistorySchema.js";
 import { migrateJobDefinitions } from "./upgrade/jobDefinitionMigration.js";
+import { migrateJobBusinessResults } from "./upgrade/jobBusinessResultMigration.js";
+import { migrateScheduleDispatch } from "./upgrade/scheduleDispatchMigration.js";
 import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION, STORAGE_FORMAT, isMinorStorageUpgrade, isStorageVersion, storageVersionParts } from "./storageVersions.js";
 export { BASELINE_SCHEMA_SQL };
-export const SQLITE_SCHEMA_TABLES = [...BASELINE_SCHEMA_TABLES, "job_definitions", "global_job_runs", "schedules"];
+export const SQLITE_SCHEMA_TABLES = [...BASELINE_SCHEMA_TABLES, "job_definitions", "global_job_runs", "schedules", "agent_job_runs"];
 export const TELEMETRY_KEEP_PER_RUN = 200;
 export const TELEMETRY_RUN_CAP = 50_000;
 export const BASELINE_SCHEMA_CHECKSUM = createHash("sha256").update(BASELINE_SCHEMA_SQL).digest("hex");
@@ -17,7 +20,9 @@ export const JOB_SCHEMA_CHECKSUM = createHash("sha256").update(BASELINE_SCHEMA_S
 export const SCHEDULE_SCHEMA_SQL_COMPLETE = BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL + SCHEDULE_SCHEMA_SQL;
 export const SCHEDULE_SCHEMA_CHECKSUM = createHash("sha256").update(SCHEDULE_SCHEMA_SQL_COMPLETE).digest("hex");
 // Fresh Homes create the final layout directly; published baseline SQL stays immutable.
-export const CURRENT_SCHEMA_SQL = SCHEDULE_SCHEMA_SQL_COMPLETE.replace(/CREATE TABLE global_role_session_sets \([\s\S]*?\n\);/, GLOBAL_SESSION_TABLE_SQL);
+const SESSION_SCHEMA_SQL = SCHEDULE_SCHEMA_SQL_COMPLETE.replace(/CREATE TABLE global_role_session_sets \([\s\S]*?\n\);/, GLOBAL_SESSION_TABLE_SQL);
+const SESSION_SCHEMA_CHECKSUM = createHash("sha256").update(SESSION_SCHEMA_SQL).digest("hex");
+export const CURRENT_SCHEMA_SQL = SESSION_SCHEMA_SQL + AGENT_JOB_SCHEMA_SQL;
 export const CURRENT_SCHEMA_CHECKSUM = createHash("sha256").update(CURRENT_SCHEMA_SQL).digest("hex");
 export class SqliteSchemaError extends Error {
     code;
@@ -164,9 +169,70 @@ const MINOR_UPGRADES = Object.freeze([{
         name: "retained-session-identity",
         introducedIn: "next",
         sourceChecksum: SCHEDULE_SCHEMA_CHECKSUM,
-        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: SESSION_SCHEMA_CHECKSUM,
         // Preserve every payload byte. No identity or authorization is inferred.
         sql: SESSION_HISTORY_UPGRADE_SQL
+    }, {
+        fromVersion: "1.14",
+        toVersion: "1.15",
+        name: "job-business-results",
+        introducedIn: "next",
+        sourceChecksum: SESSION_SCHEMA_CHECKSUM,
+        targetChecksum: SESSION_SCHEMA_CHECKSUM,
+        sql: "",
+        dataMigration: "job-business-results"
+    }, {
+        fromVersion: "1.15",
+        toVersion: "1.16",
+        name: "schedule-dispatch",
+        introducedIn: "next",
+        sourceChecksum: SESSION_SCHEMA_CHECKSUM,
+        targetChecksum: SESSION_SCHEMA_CHECKSUM,
+        sql: "",
+        dataMigration: "schedule-dispatch"
+    }, {
+        fromVersion: "1.16",
+        toVersion: "1.17",
+        name: "job-owned-artifacts",
+        introducedIn: "next",
+        sourceChecksum: SESSION_SCHEMA_CHECKSUM,
+        targetChecksum: SESSION_SCHEMA_CHECKSUM,
+        // New optional append-only Run artifact references and Home-owned per-Run
+        // repositories. Existing payloads, Task repositories and frozen Git refs are
+        // unchanged. No files are moved and no historical provenance is invented.
+        sql: ""
+    }, {
+        fromVersion: "1.17",
+        toVersion: "1.18",
+        name: "builtin-project-sync",
+        introducedIn: "next",
+        sourceChecksum: SESSION_SCHEMA_CHECKSUM,
+        targetChecksum: SESSION_SCHEMA_CHECKSUM,
+        // Additive installer provenance, explicit compiled service issuer and user
+        // intent on new definitions/plans. Do not adopt or rewrite historical Jobs,
+        // grants, time overrides or Runs. Installation is a separate runtime action.
+        sql: ""
+    }, {
+        fromVersion: "1.18",
+        toVersion: "1.19",
+        name: "job-task-delegation",
+        introducedIn: "next",
+        sourceChecksum: SESSION_SCHEMA_CHECKSUM,
+        targetChecksum: SESSION_SCHEMA_CHECKSUM,
+        // Optional immutable Task creation source and Run delegation. Existing
+        // ordinary Tasks retain absence of source; all historical payload bytes,
+        // references and unknown effects remain unchanged.
+        sql: ""
+    }, {
+        fromVersion: "1.19",
+        toVersion: "1.20",
+        name: "job-agent-execution",
+        introducedIn: "next",
+        sourceChecksum: SESSION_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // Existing records and immutable artifacts remain byte-for-byte unchanged.
+        // Declares Agent definitions/Runs and optional Job ownership of a non-Task Role.
+        sql: AGENT_JOB_SCHEMA_SQL
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)
@@ -196,9 +262,10 @@ export function validateSqliteSchemaObjects(db, version = CURRENT_STORAGE_VERSIO
     const checksum = version === CURRENT_STORAGE_VERSION
         ? CURRENT_SCHEMA_CHECKSUM : storageMinorUpgradePlan(version)?.[0]?.sourceChecksum;
     const sql = checksum === CURRENT_SCHEMA_CHECKSUM ? CURRENT_SCHEMA_SQL
-        : checksum === SCHEDULE_SCHEMA_CHECKSUM ? SCHEDULE_SCHEMA_SQL_COMPLETE
-            : checksum === JOB_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL
-                : checksum === BASELINE_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL : undefined;
+        : checksum === SESSION_SCHEMA_CHECKSUM ? SESSION_SCHEMA_SQL
+            : checksum === SCHEDULE_SCHEMA_CHECKSUM ? SCHEDULE_SCHEMA_SQL_COMPLETE
+                : checksum === JOB_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL + JOB_SCHEMA_SQL
+                    : checksum === BASELINE_SCHEMA_CHECKSUM ? BASELINE_SCHEMA_SQL : undefined;
     if (sql === undefined || checksum === undefined)
         throw new SqliteSchemaError(`unsupported schema definition for storage ${version}.`);
     let expectedObjects = schemaObjectsByChecksum.get(checksum);
@@ -292,6 +359,10 @@ export function applySqliteMinorUpgrades(db, home, createdRoots = []) {
                 migrateProjectKnowledge(db);
             if (step.dataMigration === "job-definitions")
                 migrateJobDefinitions(db);
+            if (step.dataMigration === "job-business-results")
+                migrateJobBusinessResults(db);
+            if (step.dataMigration === "schedule-dispatch")
+                migrateScheduleDispatch(db);
             const { major, minor } = storageVersionParts(step.toVersion);
             db.prepare("UPDATE storage_schema SET major=?,minor=?,checksum=? WHERE id=1")
                 .run(major, minor, step.targetChecksum);