@zq-silk/yui 2.11.0 → 2.12.0

package/dist/job/agentRoleScope.js

@@ -0,0 +1,33 @@
+/** A Job execution role is not a second Operator. Normal global Roles retain
+ * their contract; this narrows only explicitly Job-owned managed CLI callers.
+ * Job RPCs still authorize exact scope/Run and current native identity. */
+export function assertJobAgentCommand(role, args) {
+    if (!role.jobOwner)
+        return;
+    const [command, action, operation, target] = args;
+    const allowed = command === "job" && ["show", "runs", "run-get", "run-result", "run-context",
+        "run-claim", "run-report", "run-evidence", "run-confirm", "artifact-save", "artifact-list",
+        "artifact-read", "artifact-preview", "artifact-register"].includes(action ?? "")
+        || command === "session" && (action === "skills" || action === "context" && operation === role.name)
+        || command === "role" && action === "message" && ["list", "show"].includes(operation ?? "") && target === role.name
+        || command === "inbox" && ["list", "show", "claim", "ack"].includes(action ?? "")
+        || ["help", "version"].includes(command ?? "");
+    if (!allowed)
+        throw new Error("Job Agent authority is limited to its own context, inbox and exact Job execution; management requires its owner.");
+}
+/** Global runtime transport does not give a Job's execution Role global authority. */
+export function assertJobRoleRunnable(store, role) {
+    const owner = role.jobOwner;
+    if (!owner)
+        return;
+    const job = store.getJobDefinition(owner.scope, owner.jobId);
+    if (!job || job.configuration.kind !== "agent" || job.configuration.target.kind !== "job"
+        || job.configuration.target.agentId !== role.activeAgentId)
+        throw new Error("Job-owned Role configuration changed; inspect the original Job and pending input.");
+    if (owner.scope.kind === "task") {
+        const task = store.getTask(owner.scope.taskId);
+        if (task?.status !== "active" || task.executionGate.state !== "enabled") {
+            throw new Error("Job-owned Role cannot execute while its owning Task is stopped or terminal.");
+        }
+    }
+}

package/dist/job/durableJob.js

@@ -1,5 +1,8 @@
 import { createHash } from "node:crypto";
-import { requireIdentity, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
+import { artifactsAppendOnly, validateRunArtifacts } from "../artifacts/jobArtifact.js";
+import { processBusinessResult, runReference, validateBusinessResult } from "./jobBusinessResult.js";
+import { validateTaskDelegation } from "./taskDelegation.js";
+import { requireIdentity, requireKnownFields, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 import { recordOperationEvidence, validateOperationFacts } from "../kernel/operationFacts.js";
 export const CURRENT_DURABLE_JOB_SCHEMA_VERSION = 1;
@@ -82,7 +85,7 @@ export function touchDurableJobHeartbeat(job, now) {
         updatedAt: now.toISOString()
     });
 }
-export function completeDurableJob(job, result, now) {
+export function completeDurableJob(job, result, now, businessResult = processBusinessResult(job, result)) {
     validateDurableJob(job);
     if (job.status !== "running") {
         throw new Error(`DurableJob can only complete from running: ${job.status}.`);
@@ -93,13 +96,14 @@ export function completeDurableJob(job, result, now) {
     const timestamp = now.toISOString();
     return validateDurableJob({
         ...job,
-        status: result.outcome,
+        status: businessResult.outcome,
         operation: recordOperationEvidence(job.operation, {
             partialResultRefs: result.steps.map((step) => step.logPath),
             receiptRefs: result.evidenceSource === undefined ? []
                 : [`${job.artifactsLocator}/${result.evidenceSource === "checkpoint" ? "checkpoint.json" : "exit.json"}`]
         }),
         result: normalizeDurableJobResult(result),
+        businessResult: validateBusinessResult(businessResult, runReference(job)),
         terminalAt: timestamp,
         updatedAt: timestamp
     });
@@ -111,13 +115,14 @@ export function rejectQueuedDurableJob(job, reason, now) {
         throw new Error("Only an unattempted queued Job can be rejected.");
     }
     const timestamp = now.toISOString();
+    const result = {
+        outcome: "failed", exitCode: null, signal: null,
+        unknownReason: requireText(reason, "DurableJob rejection reason"), steps: []
+    };
     return validateDurableJob({
         ...job,
         status: "failed",
-        result: {
-            outcome: "failed", exitCode: null, signal: null,
-            unknownReason: requireText(reason, "DurableJob rejection reason"), steps: []
-        },
+        result, businessResult: processBusinessResult(job, result),
         terminalAt: timestamp,
         updatedAt: timestamp
     });
@@ -128,19 +133,18 @@ export function markDurableJobUnknown(job, unknownReason, completedSteps, now) {
         throw new Error(`DurableJob can only be marked unknown after an attempted effect: ${job.status}.`);
     }
     const timestamp = now.toISOString();
+    const result = {
+        outcome: "unknown-needs-attention", exitCode: null, signal: null,
+        unknownReason: requireText(unknownReason, "DurableJob unknown reason"),
+        steps: completedSteps.map(step => ({ ...step }))
+    };
     return validateDurableJob({
         ...job,
         status: "unknown-needs-attention",
         operation: recordOperationEvidence(job.operation, {
             partialResultRefs: completedSteps.map((step) => step.logPath)
         }),
-        result: {
-            outcome: "unknown-needs-attention",
-            exitCode: null,
-            signal: null,
-            unknownReason: requireText(unknownReason, "DurableJob unknown reason"),
-            steps: completedSteps.map((step) => ({ ...step }))
-        },
+        result, businessResult: processBusinessResult(job, result),
         terminalAt: timestamp,
         updatedAt: timestamp
     });
@@ -173,15 +177,11 @@ export function cancelQueuedDurableJob(job, now) {
         throw new Error(`DurableJob can only cancel-queued from queued: ${job.status}.`);
     }
     const timestamp = now.toISOString();
+    const result = { outcome: "cancelled", exitCode: null, signal: null, steps: [] };
     return validateDurableJob({
         ...job,
         status: "cancelled",
-        result: {
-            outcome: "cancelled",
-            exitCode: null,
-            signal: null,
-            steps: []
-        },
+        result, businessResult: processBusinessResult(job, result),
         terminalAt: timestamp,
         updatedAt: timestamp
     });
@@ -235,6 +235,23 @@ export function retryDurableJobIdempotencyKey(previousKey, previousJobId) {
         .digest("hex");
 }
 export function validateDurableJob(job) {
+    if (job.delegation !== undefined) {
+        validateTaskDelegation(job.delegation);
+        if (job.process !== undefined || job.result !== undefined || job.status === "queued") {
+            throw new Error("Task delegation cannot carry process execution/result evidence.");
+        }
+        if (job.steps !== undefined || job.env !== undefined || job.workspace !== undefined
+            || job.head !== undefined || job.projectId !== undefined || job.checkpoint !== undefined
+            || ("action" in job && job.action !== undefined)
+            || ("actionInput" in job && job.actionInput !== undefined)
+            || ("serviceAuthorization" in job && job.serviceAuthorization !== undefined)) {
+            throw new Error("Task delegation cannot contain a process specification.");
+        }
+        if (job.businessResult?.outcome === "succeeded" && !job.businessResult.evidence.some(ref => (ref.kind === "task-result" || ref.kind === "work-item-result") && ref.owner.taskId === job.delegation.taskId)) {
+            throw new Error("Successful delegation requires exact target delivery evidence.");
+        }
+    }
+    validateRunArtifacts(job);
     if (job.schemaVersion !== CURRENT_DURABLE_JOB_SCHEMA_VERSION) {
         throw new Error(`DurableJob must use schemaVersion ${CURRENT_DURABLE_JOB_SCHEMA_VERSION}.`);
     }
@@ -248,17 +265,25 @@ export function validateDurableJob(job) {
     if ("taskId" in job) {
         validateTaskRecordReference({ taskId: job.taskId, localId: job.id }, "durableJob");
         validateDurableJobOwner(job.owner, job.taskId);
-        requireIdentity(job.projectId, "DurableJob project id");
+        if (!job.delegation)
+            requireIdentity(job.projectId, "DurableJob project id");
     }
     else {
         if (job.scope !== "global")
             throw new Error("Invalid global JobRun scope.");
         requireIdentity(job.id, "JobRun id");
-        requireText(job.action, "JobRun builtin action");
+        if (!job.delegation)
+            requireText(job.action, "JobRun builtin action");
+        if (job.serviceAuthorization !== undefined) {
+            requireKnownFields(job.serviceAuthorization, ["scheduleId", "grantId"], "Job Schedule service reference");
+            requireText(job.serviceAuthorization.scheduleId, "Schedule id");
+            requireText(job.serviceAuthorization.grantId, "Schedule grant id");
+        }
         if (job.projectId !== undefined)
             requireIdentity(job.projectId, "JobRun Project id");
     }
-    validateJobExecutionConfiguration(job);
+    if (!job.delegation)
+        validateJobExecutionConfiguration(job);
     requireText(job.idempotencyKey, "DurableJob idempotency key");
     if (!/^[a-f0-9]{64}$/u.test(job.idempotencyKey)) {
         throw new Error("DurableJob idempotency key is invalid.");
@@ -302,6 +327,11 @@ export function validateDurableJob(job) {
     if (job.result !== undefined) {
         normalizeDurableJobResult(job.result);
     }
+    if (job.businessResult !== undefined) {
+        validateBusinessResult(job.businessResult, runReference(job));
+        if (job.status !== job.businessResult.outcome)
+            throw new Error("Job status must match its business outcome.");
+    }
     if (job.retryOf !== undefined) {
         if ("taskId" in job)
             validateTaskRecordReference({ taskId: job.taskId, localId: job.retryOf }, "durableJob");
@@ -329,7 +359,10 @@ export function validateDurableJob(job) {
     return job;
 }
 export function validDurableJobTransition(before, after) {
-    if (before.id !== after.id
+    if (!isDeepStrictEqual(before.delegation, after.delegation)
+        ||
+            !artifactsAppendOnly(before, after)
+        || before.id !== after.id
         || before.definitionId !== after.definitionId
         || before.definitionRevision !== after.definitionRevision
         || !isDeepStrictEqual(before.trigger, after.trigger)
@@ -341,7 +374,7 @@ export function validDurableJobTransition(before, after) {
         || before.idempotencyKey !== after.idempotencyKey
         || before.artifactsLocator !== after.artifactsLocator
         || before.createdAt !== after.createdAt
-        || !isDeepStrictEqual("owner" in before ? before.owner : [before.action, before.actionInput], "owner" in after ? after.owner : [after.action, after.actionInput])
+        || !isDeepStrictEqual("owner" in before ? before.owner : [before.action, before.actionInput, before.serviceAuthorization], "owner" in after ? after.owner : [after.action, after.actionInput, after.serviceAuthorization])
         || !isDeepStrictEqual(before.env, after.env)
         || !isDeepStrictEqual(before.steps, after.steps)
         || before.operation.requestId !== after.operation.requestId
@@ -354,7 +387,9 @@ export function validDurableJobTransition(before, after) {
         || !isDeepStrictEqual(recordOperationEvidence(before.operation, after.operation), after.operation))
         return false;
     if (isDurableJobTerminal(before.status)) {
-        // A terminal job is immutable except for two one-way flags:
+        // A terminal job's outcome is immutable. Artifact references can only append,
+        // permitting exact post-execution collection without rerunning business work.
+        // The two existing one-way flags remain:
         // wakeupNotified (set by the supervisor after enqueuing the Leader
         // wakeup) and acknowledgedAt (set by the Leader on an unknown job so
         // Task lifecycle gates can proceed). Without these exceptions the
@@ -363,8 +398,8 @@ export function validDurableJobTransition(before, after) {
         const wakeupFlip = before.wakeupNotified !== true && after.wakeupNotified === true;
         const acknowledgeFlip = before.acknowledgedAt === undefined
             && after.acknowledgedAt !== undefined;
-        const { wakeupNotified: _beforeWake, acknowledgedAt: _beforeAck, updatedAt: _beforeTime, ...beforeFacts } = before;
-        const { wakeupNotified: _afterWake, acknowledgedAt: _afterAck, updatedAt: _afterTime, ...afterFacts } = after;
+        const { artifacts: _beforeArtifacts, wakeupNotified: _beforeWake, acknowledgedAt: _beforeAck, updatedAt: _beforeTime, ...beforeFacts } = before;
+        const { artifacts: _afterArtifacts, wakeupNotified: _afterWake, acknowledgedAt: _afterAck, updatedAt: _afterTime, ...afterFacts } = after;
         return isDeepStrictEqual(beforeFacts, afterFacts)
             && before.status === after.status
             && isDeepStrictEqual(before.result, after.result)

package/dist/job/jobAssignmentScope.js

@@ -13,6 +13,7 @@ export function assertJobAssignmentScope(store, target, caller) {
     if (run?.status !== "active" || run.reviewRoundId !== undefined
         || target.owner.kind !== "work-item" || target.owner.workItemId !== run.workItemId
         || item?.status !== "open" || item.assignee !== caller.role
+        || target.projectId === undefined || target.workspace === undefined
         || !item.writeProjectIds.includes(target.projectId)
         || !run.effective.writeProjectIds.includes(target.projectId)
         || workspace === undefined || resolve(workspace.root) !== resolve(target.workspace)

package/dist/job/jobBusinessResult.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { requireKnownFields, requireText } from "../domain/validation.js";
+export function runReference(run) {
+    if ("executor" in run)
+        return { scope: run.scope, runId: run.id };
+    return { scope: "taskId" in run ? { kind: "task", taskId: run.taskId } : { kind: "global" }, runId: run.id };
+}
+export function resultDigest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function validateBusinessResult(result, run) {
+    requireKnownFields(result, ["schemaVersion", "sourceRun", "outcome", "summary", "data", "evidence"], "Job business result");
+    const matches = (ref) => {
+        requireKnownFields(ref, ["scope", "runId"], "Job result Run reference");
+        requireKnownFields(ref.scope, ref.scope?.kind === "task" ? ["kind", "taskId"] : ["kind"], "Job result scope");
+        return ref.runId === run.runId && ref.scope.kind === run.scope.kind
+            && (run.scope.kind !== "task" || (ref.scope.kind === "task" && ref.scope.taskId === run.scope.taskId));
+    };
+    if (result.schemaVersion !== 1 || !matches(result.sourceRun))
+        throw new Error("Job result source Run mismatch.");
+    if (!["succeeded", "failed", "cancelled", "timed-out", "unknown-needs-attention"].includes(result.outcome)) {
+        throw new Error("Invalid Job business outcome.");
+    }
+    requireText(result.summary, "Job result summary");
+    if (Buffer.byteLength(JSON.stringify(result)) > 256 * 1024)
+        throw new Error("Job business result exceeds 256 KiB.");
+    if (!Array.isArray(result.evidence))
+        throw new Error("Job result evidence must be an array.");
+    for (const ref of result.evidence) {
+        requireKnownFields(ref, ["kind", "owner", "sourceRun", "version", "locator"], "Job result reference");
+        const taskEvidence = ref.kind === "task-result" || ref.kind === "work-item-result";
+        const ownerMatches = taskEvidence
+            ? (requireKnownFields(ref.owner, ["kind", "taskId"], "Task result owner"),
+                ref.owner.kind === "task" && /^task-\d+$/u.test(ref.owner.taskId))
+            : matches(ref.owner);
+        if (!["run-record", "execution-evidence", "task-result", "work-item-result"].includes(ref.kind) || !ownerMatches || !matches(ref.sourceRun)
+            || !/^[a-f0-9]{64}$/u.test(ref.version))
+            throw new Error("Invalid Job result evidence identity/version.");
+        requireText(ref.locator, "Job result evidence locator");
+        if (ref.locator.startsWith("/") || ref.locator.split("/").includes(".."))
+            throw new Error("Invalid Job evidence locator.");
+    }
+    return result;
+}
+/** Shell and historical results describe only what the saved process evidence proves. */
+export function processBusinessResult(run, result) {
+    const sourceRun = runReference(run);
+    const summary = result.unknownReason ?? `Execution ${result.outcome}${result.failedStep ? ` at ${result.failedStep}` : ""}.`;
+    return {
+        schemaVersion: 1, sourceRun, outcome: result.outcome,
+        summary: summary.length <= 4096 ? summary : `${summary.slice(0, 4096)}… (see original execution evidence)`,
+        evidence: [{
+                kind: "run-record", owner: sourceRun, sourceRun,
+                version: resultDigest(JSON.stringify(result)),
+                locator: `job-runs/${"taskId" in run ? run.taskId : "global"}/${run.id}/result`
+            }]
+    };
+}
+/** Derived only from the admitted Run; never read a mutable definition here. */
+export function jobRunSnapshot(run) {
+    return {
+        ...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
+        },
+        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/jobCleanupInspection.js

@@ -12,6 +12,10 @@ export function jobCleanupBlocker(job, home, phase = "before-removal") {
     if (job.status === "unknown-needs-attention" && job.acknowledgedAt === undefined) {
         return "Unknown Job result requires explicit acknowledgement.";
     }
+    // A settled delegation owns no runner/workspace. Its target Task retains
+    // independent resource ownership and must pass its own cleanup inspection.
+    if (job.delegation)
+        return undefined;
     if (job.status !== "unknown-needs-attention" && job.startedAt === undefined
         && job.process === undefined && job.operation.effect === "none")
         return undefined;

package/dist/job/jobDefinition.js

@@ -1,5 +1,7 @@
 import { requireIdentity, requireKnownFields, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
 import { validateJobExecutionConfiguration, validateDurableJobOwner } from "./durableJob.js";
+import { validateAgentJobConfiguration } from "./agentJob.js";
+import { validateTaskJobConfiguration } from "./taskDelegation.js";
 export function jobScopeKey(scope) {
     if (scope.kind === "global")
         return "global";
@@ -9,7 +11,7 @@ export function jobScopeKey(scope) {
     return scope.taskId;
 }
 export function validateJobDefinition(job) {
-    requireKnownFields(job, ["schemaVersion", "id", "scope", "title", "revision", "configuration", "createdAt", "updatedAt"], "Job");
+    requireKnownFields(job, ["schemaVersion", "id", "scope", "title", "revision", "configuration", "builtin", "instantiation", "createdAt", "updatedAt"], "Job");
     if (job.schemaVersion !== 1)
         throw new Error("Job schemaVersion must be 1.");
     requireIdentity(job.id, "Job id");
@@ -19,12 +21,29 @@ export function validateJobDefinition(job) {
     requirePositiveInteger(job.revision, "Job revision");
     requireTimestamp(job.createdAt, "Job createdAt");
     requireTimestamp(job.updatedAt, "Job updatedAt");
+    if (job.instantiation !== undefined) {
+        requireKnownFields(job.instantiation, ["sourceId", "sourceRevision", "key"], "Job instantiation");
+        requireIdentity(job.instantiation.sourceId, "Job source id");
+        requirePositiveInteger(job.instantiation.sourceRevision, "Job source revision");
+        requireText(job.instantiation.key, "Job instantiation key");
+    }
     if (job.scope.kind !== "task" && job.scope.kind !== "global")
         throw new Error("Invalid Job scope.");
     requireKnownFields(job.scope, job.scope.kind === "task" ? ["kind", "taskId"] : ["kind"], "Job scope");
     jobScopeKey(job.scope);
     const config = job.configuration;
-    if (job.scope.kind === "global") {
+    if (job.builtin !== undefined && (job.builtin !== "project-sync" || job.scope.kind !== "global"
+        || config.kind !== "builtin" || config.action !== "project.refresh"
+        || job.id !== `project-sync-${config.projectId}` || job.instantiation !== undefined)) {
+        throw new Error("Invalid builtin Project sync definition.");
+    }
+    if (config.kind === "agent") {
+        validateAgentJobConfiguration(config);
+    }
+    else if (config.kind === "task") {
+        validateTaskJobConfiguration(config);
+    }
+    else if (job.scope.kind === "global") {
         if (config.kind !== "builtin")
             throw new Error("Global Jobs require a controlled builtin action.");
         requireKnownFields(config, ["kind", "action", "projectId", "input"], "Builtin Job");
@@ -51,6 +70,9 @@ export function createJobDefinition(input, now) {
     });
 }
 export function reviseJobDefinition(job, input, now) {
+    if (job.configuration.kind !== input.configuration.kind) {
+        throw new Error("Changing Job executor kind requires a new Job id; preserve the original execution history.");
+    }
     return validateJobDefinition({
         ...job, title: input.title, configuration: structuredClone(input.configuration),
         revision: job.revision + 1, updatedAt: now.toISOString()
@@ -58,6 +80,8 @@ export function reviseJobDefinition(job, input, now) {
 }
 /** Old execution IDs are preserved one-to-one; command equality never merges history. */
 export function definitionFromTaskRun(run) {
+    if (run.delegation)
+        throw new Error("Task delegation already requires a Job definition.");
     return createJobDefinition({
         id: run.definitionId, scope: { kind: "task", taskId: run.taskId }, title: run.steps[0].name,
         configuration: {

package/dist/job/jobRunner.js

@@ -14,7 +14,7 @@ import { fileURLToPath } from "node:url";
 import { jobStepDirectory } from "./stepDirectory.js";
 import { prepareHttpPreview, isHttpPreview } from "./httpPreview.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
-import { readLinuxProcessStartIdentity } from "../controller/domainIdentity.js";
+import { currentProcessStartIdentity } from "../core/fileLockOwner.js";
 const DEFAULT_STEP_TIMEOUT_MS = 30 * 60_000;
 const HEARTBEAT_INTERVAL_MS = 5_000;
 const SIGKILL_GRACE_MS = 2_000;
@@ -46,14 +46,15 @@ export async function runDurableJobRunner(specPath) {
     // reads this file to adopt a queued job after a Controller crash.
     //
     // rr4/finding-4: The runner writes its own OS startIdentity so the
-    // supervisor can adopt without re-reading /proc (which could return a
+    // supervisor can adopt without re-reading the OS (which could return a
     // reused PID's identity after the original runner exited).
     const readyPath = join(artifactDir, "ready.json");
+    const startIdentity = currentProcessStartIdentity();
     try {
         const readyFd = openSync(readyPath, "wx", 0o600);
         writeFileSync(readyFd, JSON.stringify({
             pid: process.pid,
-            startIdentity: readLinuxProcessStartIdentity(process.pid) ?? String(process.pid),
+            startIdentity,
             startedAt: new Date().toISOString()
         }, null, 2) + "\n");
         closeSync(readyFd);

package/dist/job/projectRefreshRunner.js

@@ -2,38 +2,74 @@
  * Controlled Project domain action invoked by the artifact-only Job runner.
  * Its catalog connection is read-only; only the shared domain service writes Git.
  */
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { SqliteTaskStore } from "../storage/sqliteStore.js";
 import { authorizeGlobalJobStart } from "../controller/jobDefinitionControl.js";
 import { refreshRegisteredProject } from "../repository/projectRefresh.js";
 import { projectRefreshDigest } from "./builtinJob.js";
 import { CliError } from "../errors/cliError.js";
+import { writeTextFileAtomically } from "../storage/durableFile.js";
+import { runReference } from "./jobBusinessResult.js";
+import { requireProjectSyncCheckout } from "./projectSync.js";
 export async function runProjectRefresh(home, runId) {
     const store = new SqliteTaskStore(home, { readonly: true });
     try {
         const run = store.getGlobalJobRun(runId);
-        if (!run || run.action !== "project.refresh" || !["queued", "running"].includes(run.status)
-            || run.operation.effect !== "possible" || run.cancelRequestedAt) {
+        if (!run || run.action !== "project.refresh"
+            || !((run.status === "queued" && run.operation.effect === "possible")
+                || (run.status === "running" && run.operation.effect === "confirmed"))
+            || run.cancelRequestedAt) {
             throw new Error("No active admitted project.refresh Run.");
         }
-        authorizeGlobalJobStart(store, run);
-        const result = await refreshRegisteredProject(store, run.projectId, {
-            automatic: true,
-            expectedDigest: projectRefreshDigest({
-                kind: "builtin", action: run.action, projectId: run.projectId, input: run.actionInput
-            }),
-            beforeRefresh: () => {
-                const current = store.getGlobalJobRun(runId);
-                if (!current || !["queued", "running"].includes(current.status) || current.cancelRequestedAt) {
-                    throw new Error("Project refresh Run stopped while waiting for maintenance.");
+        let result;
+        try {
+            // A revoked/stale grant before Git is a known refusal. Persist its
+            // business receipt just like a refusal after waiting for maintenance.
+            authorizeGlobalJobStart(store, run);
+            result = await refreshRegisteredProject(store, run.projectId, {
+                automatic: true,
+                expectedDigest: projectRefreshDigest({
+                    kind: "builtin", action: run.action, projectId: run.projectId, input: run.actionInput
+                }),
+                beforeRefresh: () => {
+                    const current = store.getGlobalJobRun(runId);
+                    if (!current || !["queued", "running"].includes(current.status) || current.cancelRequestedAt) {
+                        throw new Error("Project refresh Run stopped while waiting for maintenance.");
+                    }
+                    authorizeGlobalJobStart(store, current);
+                    const job = store.getJobDefinition({ kind: "global" }, current.definitionId);
+                    if (job?.builtin)
+                        requireProjectSyncCheckout(store, job);
                 }
-                authorizeGlobalJobStart(store, current);
-            }
-        });
-        process.stdout.write(JSON.stringify({ action: run.action, projectId: run.projectId,
+            });
+        }
+        catch (error) {
+            const details = error instanceof CliError ? error.details : {};
+            const partial = details.refresh;
+            const business = {
+                schemaVersion: 1, sourceRun: runReference(run),
+                outcome: partial?.changed === null ? "unknown-needs-attention" : "failed",
+                summary: error instanceof Error ? error.message : String(error),
+                data: JSON.parse(JSON.stringify({ action: run.action, projectId: run.projectId,
+                    target: run.actionInput, observedAt: new Date().toISOString(), details })),
+                evidence: []
+            };
+            writeTextFileAtomically(join(home, run.artifactsLocator, "business-result.json"), JSON.stringify(business) + "\n");
+            throw error;
+        }
+        const data = { action: run.action, projectId: run.projectId,
             trigger: run.trigger, outcome: "succeeded", observedAt: new Date().toISOString(),
-            remoteCheck: { status: "verified", commit: result.toCommit }, refresh: result }) + "\n");
+            remoteCheck: { status: "verified", commit: result.toCommit }, refresh: result };
+        const business = {
+            schemaVersion: 1, sourceRun: runReference(run), outcome: "succeeded",
+            summary: `Project ${run.projectId} refreshed to ${result.toCommit}.`,
+            data: JSON.parse(JSON.stringify(data)), evidence: []
+        };
+        // Persist separately from stdout. If this write fails after Git effects,
+        // the collector reports unknown, never a safely retryable failed action.
+        writeTextFileAtomically(join(home, run.artifactsLocator, "business-result.json"), JSON.stringify(business) + "\n");
+        process.stdout.write(JSON.stringify(data) + "\n");
     }
     finally {
         store.close();