@zq-silk/yui 0.15.9 → 0.15.12

package/dist/task/archiveDiagnostics.js

@@ -0,0 +1,129 @@
+import { createTaskEvent } from "../event/taskEvent.js";
+import { StorageRecordError, StorageConflictError, StorageCancelledError } from "../storage/taskStore.js";
+import { StorageSchemaError } from "../storage/storageSchema.js";
+import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
+export class ArchiveAuditPersistenceError extends Error {
+    constructor(cause) {
+        super(`Archive audit could not be persisted: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        this.name = "ArchiveAuditPersistenceError";
+    }
+}
+export function isArchivePersistenceFailure(error) {
+    return error instanceof ArchiveAuditPersistenceError
+        || error instanceof StorageRecordError || error instanceof StorageConflictError
+        || error instanceof StorageCancelledError || error instanceof StorageSchemaError
+        || (error instanceof Error && (("code" in error && String(error.code).startsWith("SQLITE_"))
+            || (error.cause !== undefined && error.cause !== error && isArchivePersistenceFailure(error.cause))));
+}
+/** Current resource references, not another cleanup queue or writable status. */
+export function archiveRetainedResources(store, task) {
+    const workspaces = store.listManagedWorkspaces(task.id);
+    const resources = workspaces.map(workspace => ({
+        resource: managedWorkspaceKey(workspace.owner),
+        detail: "Managed workspace retained; removal has not been recorded.",
+        paths: [workspace.root, ...workspace.entries.filter(e => e.access === "write").map(e => e.path)]
+    }));
+    if (task.cwd !== undefined && !workspaces.some(w => w.owner.type === "task")) {
+        resources.push({ resource: `task:${task.id}`, detail: "Task workspace reference retained.", paths: [task.cwd] });
+    }
+    for (const run of store.listRuns(task.id).filter(r => r.status === "active")) {
+        resources.push({ resource: `run:${task.id}/${run.id}`,
+            detail: `AgentRun remains active (${run.roleName}); archive is not stop evidence.` });
+    }
+    for (const job of store.listDurableJobs(task.id).filter(j => ["queued", "running", "unknown-needs-attention"].includes(j.status))) {
+        resources.push({ resource: `job:${task.id}/${job.id}`, detail: `DurableJob remains ${job.status}.` });
+    }
+    for (const attempt of store.listIntegrationAttempts(task.id).filter(a => ["running", "blocked", "conflicted", "validating"].includes(a.status))) {
+        resources.push({ resource: `integration-attempt:${task.id}/${attempt.id}`,
+            detail: `Integration remains ${attempt.status}.` });
+    }
+    for (const item of store.listWorkItems(task.id).filter(i => i.status === "open")) {
+        resources.push({ resource: `work-item:${task.id}/${item.id}`, detail: "WorkItem remains unaccepted." });
+    }
+    for (const round of store.listReviewRounds(task.id).filter(r => !["completed", "failed"].includes(r.status))) {
+        resources.push({ resource: `review-round:${task.id}/${round.id}`, detail: `Review remains ${round.status}.` });
+    }
+    for (const input of store.listInputRequests(task.id).filter(i => i.status === "open")) {
+        resources.push({ resource: `input:${task.id}/${input.id}`, detail: "Unresolved input preserved; not answered by archive." });
+    }
+    for (const role of store.listRoles(task.id)) {
+        const sessions = store.getTaskRoleSessionSet(task.id, role.name);
+        for (const session of Object.values(sessions?.sessions ?? {})) {
+            if (session.status === "ended")
+                continue;
+            resources.push({ resource: `session:${task.id}/${role.name}/${session.agentId}/${session.nativeSessionId}`,
+                detail: `Session is ${session.status}; physical quiescence is not established by archive.` });
+        }
+        const provider = sessions?.providerBinding;
+        if (provider !== undefined && provider !== null && provider.run != null
+            && !["completed", "failed", "cancelled"].includes(provider.run.status)) {
+            resources.push({ resource: `provider-input:${task.id}/${role.name}/${provider.run.attemptId}`,
+                detail: `Provider input is ${provider.run.status}; exact input identity is retained.` });
+        }
+    }
+    for (const mailbox of store.listWorkMailboxes()) {
+        const target = mailbox.target;
+        if (!("taskId" in target) || target.taskId !== task.id)
+            continue;
+        if (mailbox.processing === null && mailbox.pending === null)
+            continue;
+        resources.push({
+            resource: `mailbox:${target.kind}:${task.id}${"roleName" in target ? `/${target.roleName}` : ""}`,
+            detail: `Original mailbox retained${mailbox.processing === null ? "" : ` (${mailbox.processing.batchId})`}; not replayed or acknowledged by archive.`
+        });
+    }
+    return resources;
+}
+export function archiveDeliveryWarnings(delivery) {
+    return delivery.projects.filter(p => p.codeDelivery !== "none" && (!p.merged || !p.verified))
+        .map(p => ({ resource: `delivery:${delivery.taskId}/${p.projectId}`,
+        detail: `${p.coverage}: ${p.reason} Merged=${p.merged}; verified=${p.verified}.` }));
+}
+/** Every completed/failed resource attempt is committed before trying the next.
+ * Do not catch storage failures: callers must not report unrecorded cleanup as success.
+ */
+export function recordArchiveCleanup(store, taskId, diagnostic, status, now = new Date()) {
+    try {
+        store.transaction(tx => {
+            if (tx.getTask(taskId)?.status !== "archived")
+                throw new Error(`Task is not archived: ${taskId}.`);
+            tx.saveEvent(taskId, createTaskEvent(tx.nextEventId(taskId), taskId, "task.archive-cleanup", {
+                resource: diagnostic.resource, detail: diagnostic.detail, status,
+                ...(diagnostic.paths === undefined ? {} : { paths: JSON.stringify(diagnostic.paths) })
+            }, now));
+        });
+    }
+    catch (error) {
+        throw new ArchiveAuditPersistenceError(error);
+    }
+}
+export function taskArchiveDiagnostics(store, task) {
+    const events = store.listEvents(task.id);
+    const archive = events.filter(e => e.type === "task.archived").at(-1);
+    const cleanup = events.filter(e => e.type === "task.archive-cleanup");
+    const warnings = archive?.payload.warnings === undefined
+        ? [] : JSON.parse(archive.payload.warnings);
+    // These are historical attempt diagnostics; current references below remain
+    // authoritative even when explicit later resource cleanup has succeeded.
+    for (const event of cleanup.filter(e => e.payload.status === "retained")) {
+        warnings.push({ resource: event.payload.resource, detail: event.payload.detail,
+            ...(event.payload.paths === undefined ? {} : { paths: JSON.parse(event.payload.paths) }) });
+    }
+    const forced = archive?.payload.force === "true";
+    const cleanupFinished = !forced || cleanup.some(e => e.payload.status === "finished");
+    if (forced && !cleanupFinished)
+        warnings.push({ resource: `task:${task.id}`,
+            detail: "Archive committed; cleanup has not finished. Retained references require explicit inspection; archive retry does not replay cleanup." });
+    return { archived: task.status === "archived", forced,
+        disposition: archive?.payload.workspaceDisposition ?? null,
+        cleanupFinished, warnings, retainedResources: archiveRetainedResources(store, task),
+        cleanupEvents: cleanup };
+}
+export function renderArchiveDiagnostics(data) {
+    return [
+        `Archived: ${data.archived}; forced: ${data.forced}; cleanup finished: ${data.cleanupFinished}`,
+        `Retained references: ${data.retainedResources.length}; a finished cleanup attempt is not physical resource release evidence.`,
+        ...data.warnings.map(w => `Warning [${w.resource}]: ${w.detail}`),
+        ...data.retainedResources.map(r => `Retained [${r.resource}]: ${r.detail}${r.paths ? ` (${r.paths.join(", ")})` : ""}`)
+    ].join("\n") + "\n";
+}

package/dist/task/archivePreflight.js

@@ -0,0 +1,124 @@
+import { readArchiveDelivery } from "../repository/workspaceCleanupInspection.js";
+import { WorkspaceCleanupBlockedError } from "../repository/taskWorkspacePreparer.js";
+import { managedWorkspaceKey } from "../worktree/managedWorkspace.js";
+import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { cleanupCheckFromError, renderCleanupCheck } from "../workspace/cleanupInspection.js";
+/** Semantic admission facts. Cleanup still has its own resource boundary. */
+export function archiveSettlementChecks(store, task) {
+    const checks = [];
+    const add = (resource, reason, detail, expected, observed, action) => checks.push({ resource, reason, status: "blocked", detail, expected, observed, sources: [resource], actions: [action] });
+    for (const input of store.listInputRequests(task.id).filter(i => i.status === "open")) {
+        add(`input:${task.id}/${input.id}`, "unresolved-input", "Open user input is not answered by archive.", "resolved input", input.status, `yui task input show ${task.id}/${input.id}`);
+    }
+    for (const item of store.listWorkItems(task.id).filter(i => i.status === "open")) {
+        add(`work-item:${task.id}/${item.id}`, "owner-unsettled", "WorkItem must be accepted or explicitly retired before archive.", ["accepted", "retired"], item.status, `yui task work show ${task.id}/${item.id}`);
+    }
+    for (const attempt of store.listIntegrationAttempts(task.id).filter(a => ["running", "blocked", "conflicted", "validating"].includes(a.status))) {
+        add(`integration-attempt:${task.id}/${attempt.id}`, "unresolved-integration", "Task has an unresolved Integration Attempt.", "terminal attempt", attempt.status, `yui task integration show ${task.id}/${attempt.id}`);
+    }
+    for (const job of store.listDurableJobs(task.id).filter(j => ["queued", "running"].includes(j.status) || (j.status === "unknown-needs-attention" && j.acknowledgedAt === undefined))) {
+        add(`job:${task.id}/${job.id}`, "active-durable-job", "Task has an active or unacknowledged DurableJob.", "settled job", job.status, `yui job get --task ${task.id} --job ${job.id}`);
+    }
+    return checks;
+}
+/** Unknown execution is never permission to remove workspaces, even after
+ * force admission. These facts are reloaded in the actual force cleanup path.
+ */
+export function archiveExecutionChecks(store, taskId) {
+    const checks = [];
+    const add = (resource, reason, detail, observed, action) => checks.push({ resource, reason, status: "unknown", detail, expected: "settled execution",
+        observed, sources: [resource], actions: [action] });
+    for (const run of store.listRuns(taskId).filter(r => r.status === "active")) {
+        add(`run:${taskId}/${run.id}`, "active-turn", "AgentRun remains active; archive is not stop evidence.", run.status, `yui task run show ${taskId}/${run.id}`);
+    }
+    for (const job of store.listDurableJobs(taskId).filter(j => ["queued", "running", "unknown-needs-attention"].includes(j.status))) {
+        add(`job:${taskId}/${job.id}`, "unresolved-execution", "DurableJob may still hold resources; acknowledgement is not physical exit evidence.", job.status, `yui job get --task ${taskId} --job ${job.id}`);
+    }
+    for (const role of store.listRoles(taskId)) {
+        const resource = `role:${taskId}/${role.name}`;
+        const action = `yui task role session inspect ${taskId} ${role.name}`;
+        const provider = store.getTaskRoleSessionSet(taskId, role.name)?.providerBinding;
+        const mailbox = store.getWorkMailbox({ kind: "role", taskId, roleName: role.name });
+        if (provider?.run != null && !["completed", "failed", "cancelled"].includes(provider.run.status)) {
+            add(resource, "unresolved-provider-input", "Original provider input outcome is unresolved; do not replay it.", { attemptId: provider.run.attemptId, status: provider.run.status }, action);
+        }
+        if (mailbox?.processing != null && (provider?.run == null
+            || !["completed", "failed", "cancelled"].includes(provider.run.status))) {
+            add(resource, "unresolved-mailbox", "Original mailbox claim has no proven terminal; archive does not acknowledge it.", { batchId: mailbox.processing.batchId }, action);
+        }
+        if (hasRuntimeLifecycleWork(store.getWorkMailbox(runtimeLifecycleTarget({ scope: "task", taskId, roleName: role.name })))) {
+            add(resource, "unresolved-runtime-lifecycle", "Role has unsettled runtime lifecycle work.", "pending", action);
+        }
+    }
+    return checks;
+}
+export async function inspectTaskArchive(coordinator, request) {
+    const { store, preparer, runtime } = coordinator;
+    const task = store.getTask(request.taskId);
+    if (task === null)
+        throw new Error(`Task not found: ${request.taskId}.`);
+    const settlement = archiveSettlementChecks(store, task);
+    const delivery = await readArchiveDelivery(store, preparer.git, task, request.force);
+    const deliveryChecks = delivery.projects.filter(p => p.codeDelivery !== "none" && (!p.merged || !p.verified))
+        .map(p => ({ resource: `delivery:${task.id}/${p.projectId}`, reason: "delivery-coverage", status: "blocked",
+        detail: p.reason, expected: { merged: true, verified: true, localCommit: p.expectedLocalCommit },
+        observed: { coverage: p.coverage, merged: p.merged, verified: p.verified, localCommit: p.publication?.localCommit ?? null },
+        sources: [`task:${task.id}`, ...(p.publication === null ? [] : [`publication:${task.id}/${p.publication.id}`])],
+        actions: [`yui task remote-delivery ${task.id}`] }));
+    const execution = archiveExecutionChecks(store, task.id);
+    const runtimeResource = `runtime:${task.id}`;
+    if (runtime.assertTaskPhysicalResourcesReleased === undefined) {
+        execution.push(...cleanupCheckFromError(null, runtimeResource, [`task:${task.id}`], [`yui task role status ${task.id}`]));
+    }
+    else {
+        try {
+            await runtime.assertTaskPhysicalResourcesReleased(task.id);
+        }
+        catch (error) {
+            execution.push({ resource: runtimeResource, reason: "physical-resources-unreleased", status: "unknown",
+                detail: error instanceof WorkspaceCleanupBlockedError ? error.message
+                    : "Exact physical resource release is not established by the runtime inspection.",
+                expected: "proven physical absence",
+                observed: error instanceof WorkspaceCleanupBlockedError ? { reason: error.reason, resource: error.resource } : "unavailable",
+                sources: [`task:${task.id}`],
+                actions: [`yui task role status ${task.id}`, `yui session reconcile --report`] });
+        }
+    }
+    const resources = [];
+    for (const workspace of store.listManagedWorkspaces(task.id)) {
+        const disposition = workspace.owner.type === "work-item"
+            && store.getWorkItem(task.id, workspace.owner.workItemId)?.status === "retired" ? "abandoned" : request.disposition;
+        let checks;
+        try {
+            checks = await preparer.inspectWorkspaceCleanup(workspace, disposition, request.force);
+        }
+        catch (error) {
+            checks = cleanupCheckFromError(error, managedWorkspaceKey(workspace.owner), [managedWorkspaceKey(workspace.owner)], [`yui task show ${task.id}`]);
+        }
+        resources.push({ resource: managedWorkspaceKey(workspace.owner), owner: workspace.owner,
+            status: checks.some(c => c.status === "unknown") ? "unknown" : checks.length > 0 ? "blocked" : "checked",
+            checks });
+    }
+    const eligible = ["completed", "cancelled", "archived"].includes(task.status);
+    return { taskId: task.id, observedAt: new Date().toISOString(), disposition: request.disposition, force: request.force,
+        readOnly: true, authorizesCleanup: false,
+        archive: { status: task.status, eligible, alreadyArchived: task.status === "archived",
+            settlement, delivery: deliveryChecks, forceBypassesSettlement: request.force,
+            requiresIndependentAuthorization: true },
+        cleanup: { execution, resources },
+        note: "Current observations only. Execution reloads the checks. Force commits archive first and retains unsafe resources; a finished attempt does not prove resource release." };
+}
+export function renderTaskArchivePreflight(data) {
+    return [
+        `Archive preflight: ${data.taskId} (${data.disposition}${data.force ? ", force" : ""}); read-only, not authorization`,
+        `Task: ${data.archive.status}; terminal eligibility: ${data.archive.eligible}`,
+        ...data.archive.settlement.map(c => `Admission${data.force ? " (force preserves)" : ""}: ${renderCleanupCheck(c)}`),
+        ...data.archive.delivery.map(c => `Delivery${data.force || data.disposition === "abandoned" ? " (advisory for admission)" : ""}: ${renderCleanupCheck(c)}`),
+        ...data.cleanup.execution.map(c => `Cleanup: ${renderCleanupCheck(c)}`),
+        ...data.cleanup.resources.flatMap(r => [
+            `Workspace [${r.resource}]: ${r.status}`,
+            ...r.checks.map(c => `  ${renderCleanupCheck(c)}`)
+        ]),
+        data.note
+    ].join("\n") + "\n";
+}

package/dist/task/nextAction.js

@@ -121,6 +121,16 @@ export function projectNextAction(facts) {
             recommendedCommand: `yui task activate ${task.id}`
         });
     }
+    const conflictedIntegration = facts.integrations.find(attempt => attempt.status === "conflicted");
+    if (conflictedIntegration !== undefined) {
+        return buildAction(facts, {
+            kind: "resolve-integration-conflicts",
+            reason: `Integration ${conflictedIntegration.id} has Git conflicts; the Leader resolves its workspace and continues without prior resolve or user approval.`,
+            refs: [ref("integration", conflictedIntegration.id)],
+            preconditions: [{ fact: "Git conflict resolution belongs to the Leader", satisfied: true }],
+            recommendedCommand: `yui task integration continue ${task.id}/${conflictedIntegration.id}`
+        });
+    }
     const checkingIntegration = facts.integrations.find(attempt => attempt.status === "running" && attempt.jobId !== undefined);
     if (checkingIntegration !== undefined) {
         const job = facts.integrationJobs?.find(job => job.id === checkingIntegration.jobId);
@@ -146,6 +156,21 @@ export function projectNextAction(facts) {
             recommendedCommand: `yui task integration continue ${task.id}/${checkingIntegration.id}`
         });
     }
+    const unfinishedIntegration = facts.integrations.find(attempt => attempt.status === "running" || attempt.status === "validating");
+    if (unfinishedIntegration !== undefined) {
+        return buildAction(facts, {
+            kind: "integrate-work-item",
+            reason: `Integration ${unfinishedIntegration.id} is unfinished. ${unfinishedIntegration.summary ?? "Continue from its persisted source and check evidence."}`,
+            refs: [ref("integration", unfinishedIntegration.id)],
+            preconditions: [{ fact: "Inspect exact Integration evidence before any retry", satisfied: true }],
+            recommendedCommand: `yui task integration continue ${task.id}/${unfinishedIntegration.id}`,
+            alternatives: [{
+                    kind: "inspect-integration",
+                    reason: "If completion cannot be proved, preserve evidence and choose formal abort and an authorized alternative.",
+                    recommendedCommand: `yui task integration show ${task.id}/${unfinishedIntegration.id}`
+                }]
+        });
+    }
     const candidateReady = facts.workItems
         .find((item) => (item.status === "open" && item.currentCandidateId !== undefined));
     if (candidateReady !== undefined) {
@@ -320,27 +345,35 @@ export function projectNextAction(facts) {
             return synthesisSelectionAction(facts, "work", item.id);
         }
         const refs = [ref("work-item", item.id)];
+        const direct = item.assignee === undefined;
         return buildAction(facts, {
             kind: "implement-current-work-item",
-            reason: `Work Item ${item.id} is ${item.status}; dispatch or continue its implementation.`,
+            reason: direct
+                ? `Work Item ${item.id} has no managed assignee; the Leader can execute it directly.`
+                : `Work Item ${item.id} is assigned to ${item.assignee}; dispatch or continue that assignment.`,
             refs,
             preconditions: [
                 { fact: `Work Item is ${item.status}`, satisfied: true, ref: refs[0] }
             ],
-            recommendedCommand: `yui task work dispatch ${task.id}/${item.id}`,
-            alternatives: [
-                {
-                    kind: "execute-directly",
-                    reason: "Execute the bounded Work Item directly when the Leader's current context and authority are sufficient.",
-                    refs
-                },
+            recommendedCommand: direct
+                ? `yui task work update ${task.id}/${item.id} running`
+                : `yui task work dispatch ${task.id}/${item.id}`,
+            alternatives: direct ? [
+                ...(item.writeProjectIds.length === 0 ? [] : [{
+                        kind: "isolate-work-item",
+                        reason: "Prepare and inspect the WorkItem-owned code workspace before direct implementation.",
+                        recommendedCommand: `yui task work isolate ${task.id}/${item.id}`,
+                        refs
+                    }]),
                 {
                     kind: "native-subagent",
-                    reason: "Use native implementer subagents when bounded work benefits from specialist attention or parallel fan-out inside the Leader Session.",
+                    reason: "Use a bounded native child only when authorized and useful within the Leader's current scope.",
                     refs
                 }
-            ],
-            judgmentRequired: "Leader must choose the execution path: direct execution, a native subagent, or managed Task Role dispatch."
+            ] : [],
+            judgmentRequired: direct
+                ? "Honor explicit execution preferences. For code, use the WorkItem-owned workspace and integrate its Candidate before acceptance; no self-dispatch is needed."
+                : "Preserve the current managed Assignment and original results; do not switch ownership merely to follow a different default."
         });
     }
     if (deliveryWorkItems.length === 0

package/dist/task/publicationAdoption.js

@@ -0,0 +1,56 @@
+import { contextContentDigest } from "../context/contextSnapshot.js";
+import { publicationExternalKey } from "./publicationReference.js";
+export const PUBLICATION_ADOPTED_EVENT = "publication.candidate-adopted";
+/**
+ * An explicit semantic decision over fixed Git endpoints, not an ancestry
+ * heuristic or a replacement completion head. Publication metadata/verification
+ * successors may retain it only while every intervening local candidate agrees.
+ */
+export function publicationAdoption(publication, completion, acceptedCommit, events, publications, integrations) {
+    const unavailable = { event: null, reason: null };
+    if (completion === undefined || acceptedCommit === null)
+        return unavailable;
+    const lineage = new Set();
+    let current = publication;
+    while (current !== undefined && !lineage.has(current.id)
+        && current.taskId === publication.taskId
+        && current.projectId === publication.projectId
+        && current.externalKind === publication.externalKind
+        && publicationExternalKey(current) === publicationExternalKey(publication)
+        && current.localCommit === publication.localCommit) {
+        lineage.add(current.id);
+        current = publications.find(p => p.id === current.supersedes);
+    }
+    const event = events.slice().reverse().find(event => {
+        const p = event.payload;
+        return event.type === PUBLICATION_ADOPTED_EVENT
+            && event.taskId === publication.taskId
+            && p.completionEventId === completion.id
+            && p.acceptedCommit === acceptedCommit
+            && p.projectId === publication.projectId
+            && p.localCommit === publication.localCommit
+            && lineage.has(p.publicationId ?? "");
+    });
+    if (event === undefined)
+        return unavailable;
+    const p = event.payload;
+    if (!p.acceptance?.trim()
+        || !["user", "operator", "leader"].includes(p.by ?? "")
+        || !/^[0-9a-f]{64}$/u.test(p.diffDigest ?? "")
+        || !/^[0-9a-f]{40}$/u.test(p.acceptedTree ?? "")
+        || !/^[0-9a-f]{40}$/u.test(p.candidateTree ?? "")) {
+        return { event: null, reason: `Adoption ${event.id} has incomplete fixed evidence.` };
+    }
+    if (p.integrationId === undefined)
+        return { event, reason: null };
+    const integration = integrations.find(i => i.id === p.integrationId);
+    const valid = integration !== undefined && integration.status === "committed"
+        && integration.taskId === publication.taskId
+        && integration.projectId === publication.projectId
+        && integration.afterCommit === publication.localCommit
+        && contextContentDigest(integration) === p.integrationDigest;
+    return valid ? { event, reason: null } : {
+        event: null,
+        reason: `Adoption ${event.id} references Integration ${p.integrationId}, whose committed candidate evidence is missing or changed (${integration?.status ?? "missing"}).`
+    };
+}

package/dist/task/publicationReference.js

@@ -35,6 +35,9 @@ export function createPublicationReference(id, taskId, input, now) {
         ...(input.localCommit === undefined ? {} : {
             localCommit: requireCommit(input.localCommit, "Publication local commit")
         }),
+        ...(input.headCommit === undefined ? {} : {
+            headCommit: requireCommit(input.headCommit, "Publication remote head")
+        }),
         ...(input.remoteCommit === undefined ? {} : {
             remoteCommit: requireCommit(input.remoteCommit, "Publication remote commit")
         }),
@@ -82,6 +85,13 @@ export function validatePublicationReference(reference) {
     if (reference.localCommit !== undefined) {
         requireCommit(reference.localCommit, "Publication local commit");
     }
+    if (reference.headCommit !== undefined) {
+        requireCommit(reference.headCommit, "Publication remote head");
+        if (reference.verification === "verified"
+            && reference.headCommit !== reference.localCommit) {
+            throw new Error("Verified publication remote head must match its local commit.");
+        }
+    }
     if (reference.remoteCommit !== undefined) {
         requireCommit(reference.remoteCommit, "Publication remote commit");
     }

package/dist/task/remoteDelivery.js

@@ -1,3 +1,4 @@
+import { publicationAdoption } from "./publicationAdoption.js";
 /**
  * One read-only delivery projection over existing Task, workspace, completion,
  * and Publication facts. It never writes a merged flag or queries a provider.
@@ -19,13 +20,19 @@ export function projectTaskRemoteDelivery(facts) {
             .filter((reference) => reference.projectId === binding.projectId);
         const matching = expectedLocalCommit === null
             ? []
-            : projectPublications.filter((reference) => reference.localCommit === expectedLocalCommit);
+            : projectPublications.filter((reference) => reference.localCommit === expectedLocalCommit
+                || publicationAdoption(reference, expected.event, expectedLocalCommit, facts.events, facts.publications, facts.integrations ?? []).event !== null);
         const publication = bestPublication(matching.length > 0 ? matching : projectPublications);
-        const coverage = projectCoverage(codeDelivery, expectedLocalCommit, publication);
+        const adoptionEvidence = publication === null ? null
+            : publicationAdoption(publication, expected.event, expectedLocalCommit, facts.events, facts.publications, facts.integrations ?? []);
+        const adoption = adoptionEvidence?.event ?? null;
+        const covers = expectedLocalCommit !== null && publication !== null
+            && (publication.localCommit === expectedLocalCommit || adoption !== null);
+        const headMatches = publication?.headCommit === undefined
+            || publication.headCommit === publication.localCommit;
+        const coverage = projectCoverage(codeDelivery, expectedLocalCommit, publication, covers, headMatches);
         const merged = codeDelivery === "none"
-            || (publication !== null
-                && expectedLocalCommit !== null
-                && publication.localCommit === expectedLocalCommit
+            || (covers && headMatches
                 && publication.state === "merged");
         const verified = codeDelivery === "none"
             || (merged && publication?.verification === "verified");
@@ -34,6 +41,8 @@ export function projectTaskRemoteDelivery(facts) {
             directory: binding.directory,
             baseCommit,
             expectedLocalCommit,
+            deliveryLocalCommit: covers ? publication.localCommit ?? null : null,
+            adoption,
             codeDelivery,
             publication,
             state: publication?.state ?? null,
@@ -42,7 +51,8 @@ export function projectTaskRemoteDelivery(facts) {
             coverage,
             merged,
             verified,
-            reason: projectCoverageReason(codeDelivery, expectedLocalCommit, publication, coverage)
+            reason: projectCoverageReason(expectedLocalCommit, publication, coverage, adoption) + (coverage === "stale" && adoptionEvidence?.reason
+                ? ` ${adoptionEvidence.reason}` : "")
         };
     });
     const codeProjects = projects.filter((project) => project.codeDelivery !== "none");
@@ -55,8 +65,9 @@ export function projectTaskRemoteDelivery(facts) {
         : codeProjects.some((project) => project.coverage === "head-unavailable")
             ? "unavailable"
             : allMerged
-                ? "merged"
-                : mergedProjectCount > 0 ? "partial" : "pending";
+                ? allVerified ? "merged" : "unverified"
+                : mergedProjectCount > 0 ? "partial"
+                    : codeProjects.some(p => p.state === "merged") ? "uncovered" : "pending";
     return {
         taskId: facts.task.id,
         source: expected.source,
@@ -111,7 +122,7 @@ function expectedDelivery(facts) {
         commits: new Map()
     };
 }
-function completionEvent(events, completedAt) {
+export function completionEvent(events, completedAt) {
     const exact = latestEvent(events, "task.completed", (event) => (event.createdAt === completedAt));
     return exact ?? latestEvent(events, "task.completed", (event) => (event.createdAt <= completedAt));
 }
@@ -154,7 +165,7 @@ function candidateCommits(candidate) {
         commit.toLowerCase()
     ]));
 }
-function commitMap(value) {
+export function commitMap(value) {
     const result = new Map();
     for (const entry of value?.split(",") ?? []) {
         const separator = entry.indexOf("@");
@@ -188,7 +199,7 @@ function publicationRank(reference) {
         return 2;
     return 1;
 }
-function projectCoverage(codeDelivery, expectedLocalCommit, publication) {
+function projectCoverage(codeDelivery, expectedLocalCommit, publication, covers, headMatches) {
     if (codeDelivery === "none")
         return "not-applicable";
     if (expectedLocalCommit === null)
@@ -197,7 +208,9 @@ function projectCoverage(codeDelivery, expectedLocalCommit, publication) {
         return "missing";
     if (publication.localCommit === undefined)
         return "missing-local-commit";
-    if (publication.localCommit !== expectedLocalCommit)
+    if (!headMatches)
+        return "head-mismatch";
+    if (!covers)
         return "stale";
     if (publication.state === "open")
         return "open";
@@ -205,7 +218,7 @@ function projectCoverage(codeDelivery, expectedLocalCommit, publication) {
         return "closed";
     return publication.verification === "verified" ? "verified" : "merged";
 }
-function projectCoverageReason(codeDelivery, expectedLocalCommit, publication, coverage) {
+function projectCoverageReason(expectedLocalCommit, publication, coverage, adoption) {
     switch (coverage) {
         case "not-applicable":
             return "Task head equals the managed workspace base; no code delivery is required.";
@@ -216,15 +229,17 @@ function projectCoverageReason(codeDelivery, expectedLocalCommit, publication, c
         case "missing-local-commit":
             return `Publication ${publication.id} does not record a local commit.`;
         case "stale":
-            return `Publication ${publication.id} covers ${publication.localCommit}, not the expected Task head ${expectedLocalCommit}.`;
+            return `Publication ${publication.id} is ${publication.state}, but its local candidate ${publication.localCommit} has no valid adoption covering accepted Task head ${expectedLocalCommit}.`;
+        case "head-mismatch":
+            return `Publication ${publication.id} is ${publication.state}, but observed remote head ${publication.headCommit} differs from local candidate ${publication.localCommit}; verification is invalid.`;
         case "open":
             return `Publication ${publication.id} covers the Task head but is still open.`;
         case "closed":
             return `Publication ${publication.id} covers the Task head but is closed without merge.`;
         case "merged":
-            return `Publication ${publication.id} reports the exact Task head as merged.`;
+            return `Publication ${publication.id} reports a covering candidate as merged, but remote verification is still required.`;
         case "verified":
-            return `Publication ${publication.id} verifies the exact Task head as merged.`;
+            return `Publication ${publication.id} verifies ${adoption === null ? "the exact Task head" : `candidate ${publication.localCommit} adopted by ${adoption.id}`} as merged.`;
     }
 }
 function compareCreated(left, right) {