@zq-silk/yui 0.15.11 → 0.16.0

package/dist/lifecycle/exactRunTerminalization.js

@@ -1,5 +1,6 @@
 import { isDeepStrictEqual } from "node:util";
 import { createTaskMessage } from "../message/message.js";
+import { providerRetryPending } from "../runtime/providerRetry.js";
 import { captureRoleRunDispatch, enqueueWork, settleRoleRunDispatch } from "../coordination/workMailboxQueue.js";
 import { finishReviewRound, updateReviewExecutionGroup } from "../review/reviewRound.js";
 import { completeRun, failRun, runPurposeAdmitsTaskState } from "../agentRun/agentRun.js";
@@ -7,7 +8,6 @@ import { boundedRunFailureDiagnostic } from "../domain/agentResultTransport.js";
 import { updateExecutionLane, updateWorkItemExecutionLane } from "../execution/workItemExecution.js";
 import { managedProviderTurnId } from "../runtime/providerRuntimeIdentity.js";
 import { latestRunDurableProgressAt } from "../scheduler/roleRunStall.js";
-import { markTaskWakeConsumed } from "../scheduler/taskWake.js";
 import { workItemExecutionGroupById, updateWorkItemExecutionGroup } from "../workItem/workItem.js";
 /**
  * Validate every immutable identity and frozen Project head needed before a
@@ -80,7 +80,7 @@ export function validateExactRunReviewRound(store, run, options = {}) {
         }
     }
     const task = store.getTask(run.taskId);
-    const taskScope = (round.scope ?? "work-item") === "task";
+    const taskScope = round.scope === "task";
     const item = taskScope || round.workItemId === undefined
         ? null
         : store.getWorkItem(run.taskId, round.workItemId);
@@ -394,7 +394,9 @@ export function terminalizeExactTaskRun(store, input, now) {
         const message = createTaskMessage(store.nextMessageId(terminal.taskId), terminal.taskId, `Execution ${terminal.id} ${terminal.status}.`, "role-result", { type: "role", roleName: terminal.roleName }, now, { resultRef: { type: "agent-run-result", runId: terminal.id }, ...(terminal.workItemId === undefined
                 ? {} : { workItemId: terminal.workItemId }) });
         store.saveMessage(terminal.taskId, message);
-        enqueueWork(store, { kind: "role", taskId: terminal.taskId, roleName: "leader" }, "role-result", now, [{ type: "message", taskId: terminal.taskId, id: message.id }], { source: "task-event", dedupeKey: `result:${terminal.taskId}/${terminal.id}` });
+        if (!providerRetryPending(store.getTaskRoleSessionSet(terminal.taskId, terminal.roleName)?.providerBinding)) {
+            enqueueWork(store, { kind: "role", taskId: terminal.taskId, roleName: "leader" }, "role-result", now, [{ type: "message", taskId: terminal.taskId, id: message.id }], { source: "task-event", dedupeKey: `result:${terminal.taskId}/${terminal.id}` });
+        }
     }
     const dispatchIdentity = {
         taskId: terminal.taskId,
@@ -407,13 +409,6 @@ export function terminalizeExactTaskRun(store, input, now) {
         roleName: terminal.roleName
     }), dispatchIdentity);
     settleRoleRunDispatch(store, dispatchIdentity, dispatchToken);
-    if (terminal.roleName === "leader") {
-        const wake = store.listTaskWakes(input.taskId)
-            .find((candidate) => candidate.runId === terminal.id && candidate.status === "dispatched");
-        if (wake !== undefined) {
-            store.saveTaskWake(input.taskId, markTaskWakeConsumed(wake, now));
-        }
-    }
     if (terminal.executionGroupId !== undefined && terminal.executionLaneId !== undefined) {
         store.clearActiveExecutionLaneRun(input.taskId, terminal.executionGroupId, terminal.executionLaneId);
     }

package/dist/message/globalProviderRetry.js

@@ -0,0 +1,15 @@
+import { markGlobalRoleMessageNotDelivered } from "./message.js";
+/** Settle the original queue entry when recovery ends with exact nondelivery.
+ * Cancellation of a submitted/unknown request is not negative Provider proof. */
+export function settleGlobalRetryInput(store, roleName, binding, now) {
+    const retry = binding?.retry;
+    if (retry === undefined || retry.input.kind !== "message" || retry.input.roleName !== roleName
+        || !["cancelled", "exhausted", "needs-attention"].includes(retry.status)
+        || binding?.run == null || ["submitting", "accepted", "delivery-unknown"].includes(binding.run.status))
+        return;
+    const messageId = retry.input.messageId;
+    const message = store.listGlobalRoleMessages(roleName).find(m => m.id === messageId);
+    if (message === undefined || message.delivery !== undefined || message.notDelivered !== undefined)
+        return;
+    store.updateGlobalRoleMessage(markGlobalRoleMessageNotDelivered(message, `provider-retry-${retry.status}: ${retry.reason ?? retry.failureRef}`, now));
+}

package/dist/message/inputControlResolution.js

@@ -36,9 +36,8 @@ function resolveInputControl(sessions, kind, expectedTarget, roleName) {
             detail: `Agent plan '${active.adapterId}' has no native interrupt; Yui will not `
                 + "stop the owned process, kill, restart, or detach it." };
     }
-    // A Global Role now carries the same optional providerBinding as a Task Role;
-    // both read it the same way. Its absence is "no current Turn", never an error.
-    const binding = "providerBinding" in sessions ? sessions.providerBinding ?? null : null;
+    // Both scopes use the same explicit null for an uncontrolled Session.
+    const binding = sessions.providerBinding;
     const turn = binding?.run ?? null;
     if (binding === null || turn === null || !PRESENT_TURN_STATUSES.has(turn.status)) {
         return { outcome: "no-active-turn", code: "NO_ACTIVE_TURN",
@@ -78,7 +77,7 @@ function resolveInputControl(sessions, kind, expectedTarget, roleName) {
             ...(turn.nativeTurnId === undefined ? {} : { nativeTurnId: turn.nativeTurnId }),
             attemptId: turn.attemptId,
             authority: { epoch: binding.authority.epoch, owner: "controller",
-                holderId: binding.authority.holderId ?? "controller" }
+                holderId: binding.authority.holderId }
         } };
 }
 /**

package/dist/message/message.js

@@ -5,7 +5,7 @@ export const TASK_MESSAGE_KINDS = ["user", "operator", "role-result", "system"];
  *
  * - `record`: save only. No Leader wake, no planning, no activation.
  * - `discuss`: save and route to planning (the default when a submission omits
- *   an intent, so an old client keeps its existing Leader-waking behaviour).
+ *   an intent).
  * - `develop`: save the requirement and its activation intent; an unplanned
  *   Draft records an activation request and queues only activation processing.
  *
@@ -30,12 +30,9 @@ export function createTaskMessage(id, taskId, body, kind, author, now, context =
         kind,
         author: normalizeAuthor(author),
         body: requireBody(body),
-        ...(context.wakePolicy === undefined
-            ? {}
-            : { wakePolicy: context.wakePolicy }),
-        ...(context.intent === undefined
-            ? {}
-            : { intent: context.intent }),
+        ...(kind === "user" || kind === "operator"
+            ? { intent: context.intent ?? "discuss" }
+            : context.intent === undefined ? {} : { intent: context.intent }),
         ...(context.submissionKey === undefined
             ? {}
             : { submissionKey: requireText(context.submissionKey, "Message submission key") }),
@@ -163,18 +160,22 @@ export function expandTaskMessageResult(message, getRun) {
     }
     return { ...message, result: run.result };
 }
-/** Replace only the mutable content of a Draft user/operator Message. */
+/** Edit unkeyed Draft context. Once an input has a request identity, its body
+ * is the retry comparison and must stay frozen, including through a handoff. */
 export function updateDraftTaskMessage(message, update) {
     validateTaskMessage(message);
     if (message.kind !== "user" && message.kind !== "operator") {
         throw new Error(`Only user/operator Task Messages can be updated: ${message.id}.`);
     }
+    const body = requireBody(update.body);
+    if (body === message.body)
+        return message;
+    if (message.submissionKey !== undefined || message.inputControl !== undefined || message.interruptThen !== undefined) {
+        throw new Error(`Message ${message.id} has a request identity; submit a new Message with a new request ID to change its content.`);
+    }
     const updated = {
         ...message,
-        body: requireBody(update.body),
-        ...(update.wakePolicy === undefined
-            ? {}
-            : { wakePolicy: update.wakePolicy })
+        body
     };
     validateTaskMessage(updated);
     return updated;
@@ -204,15 +205,11 @@ export function validateTaskMessage(message) {
     requireText(message.body, "Message body");
     validateKindAndAuthor(message.kind, message.author);
     normalizeAuthor(message.author);
-    if (message.wakePolicy !== undefined
-        && message.wakePolicy !== "leader"
-        && message.wakePolicy !== "none") {
-        throw new Error(`Message wakePolicy is invalid: ${String(message.wakePolicy)}.`);
+    if (Object.hasOwn(message, "wakePolicy")) {
+        throw new Error("Message contains a retired wake policy; use the storage upgrade boundary.");
     }
-    if (message.wakePolicy !== undefined
-        && message.kind !== "user"
-        && message.kind !== "operator") {
-        throw new Error("Message wakePolicy is only valid for user/operator messages.");
+    if ((message.kind === "user" || message.kind === "operator") && message.intent === undefined) {
+        throw new Error("User/operator Message intent is required.");
     }
     if (message.intent !== undefined
         && !TASK_SUBMISSION_INTENTS.includes(message.intent)) {

package/dist/message/messageContinuation.js

@@ -80,7 +80,7 @@ export function messageContinuationBlocker(store, message) {
         const round = store.getReviewRound(message.taskId, target.reviewRoundId);
         if (round === null)
             return "review-round-missing";
-        if ((round.scope ?? "work-item") === "task") {
+        if (round.scope === "task") {
             if (round.taskCandidate?.projects.some((project) => task.projectBindings.find((binding) => binding.projectId === project.projectId)?.currentCommit !== project.commit)) {
                 return "review-candidate-stale";
             }

package/dist/milestone/milestone.js

@@ -1,4 +1,15 @@
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+import { requireTimestamp } from "../domain/validation.js";
+export function validateMilestone(milestone) {
+    if (milestone.schemaVersion !== 2)
+        throw new Error("Milestone must use schemaVersion 2.");
+    validateTaskRecordReference({ taskId: milestone.taskId, localId: milestone.id }, "milestone");
+    requireText(milestone.title, "Milestone title");
+    requireText(milestone.summary, "Milestone summary");
+    requireTaskControlActor(milestone.createdBy);
+    requireTimestamp(milestone.createdAt, "Milestone createdAt");
+    return milestone;
+}
 export function createMilestone(id, taskId, title, summary, createdBy, now) {
     return {
         schemaVersion: 2,

package/dist/observability/executionAudit.js

@@ -15,6 +15,7 @@ import { join } from "node:path";
 import { openCurrentTaskStore } from "../storage/currentTaskStore.js";
 import { resolveTaskStoreBackendForHome } from "../storage/sqliteStore.js";
 import { runtimeObservationFromTaskEvent } from "../runtime/runtimeObservation.js";
+import { projectTaskUsageMetrics } from "../runtime/taskUsageMetrics.js";
 import { classifyRunFailure, classifyIntegrationAttempt, classifyReviewRound, countFaultClasses } from "./faultClassification.js";
 import { RUNTIME_LAUNCH_KINDS, RUNTIME_LAUNCH_PHASES } from "../runtime/launchDiagnostics.js";
 import { UNSUPPORTED } from "./runtimeIdentity.js";
@@ -192,6 +193,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
             agentErrors: section,
             workItems: section,
             orchestration: section,
+            usage: section,
             storage: section,
             runtimeProtocol: section,
             topLongRunning: section
@@ -658,6 +660,22 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
             return failed(error);
         }
     })();
+    const usage = (() => {
+        try {
+            return ok(taskIds.map((taskId) => {
+                const task = store.getTask(taskId);
+                if (task === null)
+                    throw new Error(`Task not found: ${taskId}.`);
+                return projectTaskUsageMetrics({
+                    task, events: store.listEvents(taskId), runs: store.listRuns(taskId),
+                    now: new Date(generatedAt)
+                });
+            }));
+        }
+        catch (error) {
+            return failed(error);
+        }
+    })();
     const storage = (() => {
         try {
             let stateJsonBytes = UNSUPPORTED;
@@ -796,6 +814,7 @@ export function runExecutionAudit(home, options = {}, ports = createProductionEx
         agentErrors,
         workItems,
         orchestration,
+        usage,
         storage,
         runtimeProtocol,
         topLongRunning

package/dist/observability/orchestrationMetrics.js

@@ -1,6 +1,7 @@
 import { isDeepStrictEqual } from "node:util";
 import { isCompletedReviewExecutionFromRuns } from "../review/reviewAcceptance.js";
 import { projectFirstProgressAdvisory } from "../runtime/firstProgressAdvisory.js";
+import { parseGateArtifactRef } from "../verification/gateArtifact.js";
 /** One Task's orchestration cost and advisory projection, with no writes. */
 export function projectTaskOrchestration(facts) {
     const fullRounds = facts.reviewRounds.filter((round) => round.deltaRecheck === undefined);
@@ -63,7 +64,7 @@ export function projectTaskOrchestration(facts) {
             attempts: facts.integrations.length,
             failed: facts.integrations.filter(({ status }) => status === "failed").length,
             repeatedIdentities,
-            evidenceReuses: facts.integrations.filter((attempt) => ((attempt.checks ?? []).some(({ details }) => details?.startsWith("Reused successful check evidence from ")))).length
+            evidenceReuses: facts.integrations.filter((attempt) => ((attempt.checks ?? []).some(check => check.outcome === "passed" && parseGateArtifactRef(check.name) !== undefined))).length
         },
         providerSessionsBeforeFirstProgress: firstProgress.sessionsBeforeFirstProgress,
         publicationToCompletionMs: publicationAt === undefined || facts.task.completedAt === undefined
@@ -75,6 +76,28 @@ export function projectTaskOrchestration(facts) {
 }
 function projectAdvisories(facts, fullRounds, repeatedIdentities, firstProgressAttention) {
     const result = [];
+    const scopes = new Map();
+    for (const item of facts.workItems) {
+        if (item.status !== "open")
+            continue;
+        const key = JSON.stringify([
+            item.title.trim().toLowerCase(), item.objective.trim().toLowerCase(),
+            item.acceptance.map(value => value.trim().toLowerCase()).filter(Boolean).sort(),
+            [...item.writeProjectIds].sort()
+        ]);
+        const refs = scopes.get(key) ?? [];
+        refs.push(`work-item:${item.id}`);
+        scopes.set(key, refs);
+    }
+    for (const refs of scopes.values()) {
+        if (refs.length < 2)
+            continue;
+        result.push({
+            code: "work-item-scope-overlap",
+            reason: "Open WorkItems have matching scope text. Inspect their original intent and decide whether they are independent; this advisory grants or denies no operation.",
+            refs
+        });
+    }
     if (facts.task.type === "bugfix" && facts.workItems.length > 0) {
         result.push({
             code: "bugfix-workitem-overhead",

package/dist/observability/runtimeIdentity.js

@@ -17,22 +17,6 @@ import { CURRENT_STORAGE_VERSION, MIN_SUPPORTED_STORAGE_VERSION } from "../stora
 import { inspectStorageSchema } from "../storage/storageSchema.js";
 import { resolveStoreWorkerEnabledForHome } from "../storage/storeRpc.js";
 export const UNSUPPORTED = "unsupported";
-/**
- * Feature flag for the Issue 11 read-only status/audit presentation.
- *
- * Everything behind this flag is observe-only: identity fields, storage
- * evidence, and metrics snapshots. The flag defaults ON because the fields
- * change no behavior; set `YUI_STATUS_IDENTITY=0` (or `false`) to hide the new
- * sections and the fail-closed health exit. `execution audit` is an explicit
- * command and is not gated by this flag.
- */
-export function resolveStatusIdentityEnabled(env = process.env) {
-    const value = env.YUI_STATUS_IDENTITY;
-    if (value === undefined)
-        return true;
-    const normalized = value.trim().toLowerCase();
-    return normalized !== "0" && normalized !== "false" && normalized !== "off";
-}
 export function evaluateStorageHealth(identity) {
     const contradictions = identity.findings.filter(({ severity }) => severity === "contradiction");
     const needsRepair = identity.findings.filter(({ severity }) => severity === "needs-repair");
@@ -242,7 +226,7 @@ export function collectStorageIdentity(home, ports = createProductionStorageIden
             code: "ignored-legacy-storage-manifest",
             severity: "warning",
             message: "schema.json is legacy metadata and is not a storage authority.",
-            remediation: "A successful storage upgrade removes it automatically."
+            remediation: "This file is not used. Preserve or archive it separately after inspecting its contents."
         });
     }
     if (dbPresent && dbHealth !== null && dbHealth !== "ok") {

package/dist/output/agentConfigurationPresentation.js

@@ -1,3 +1,4 @@
+import { agentModelOptionsSummary } from "../executor/agentConfigurationCatalog.js";
 import { renderAgentConfigurationResolutionNotice } from "../cli/agentConfigurationPicker.js";
 import { agentHandshakeLine } from "./agentRunConfigurationPresentation.js";
 import { defaultTableWidth, renderTable } from "./table.js";
@@ -35,6 +36,7 @@ export function renderAgentConfigurationCatalog(resolved) {
                 { header: "Default effort", minWidth: 14, maxWidth: 18 },
                 { header: "Service tiers", minWidth: 13, maxWidth: 24 }
             ], modelRows, defaultTableWidth()),
+        agentModelOptionsSummary(catalog),
         ...(fieldRows.length === 0
             ? []
             : [renderTable("Other runtime configuration", [

package/dist/output/timePresentation.js

@@ -1,17 +1,4 @@
-export const DEFAULT_TIME_ZONE = "Asia/Shanghai";
-export function resolveTimeZone(value) {
-    const timeZone = value ?? DEFAULT_TIME_ZONE;
-    if (typeof timeZone !== "string" || timeZone.trim() !== timeZone || timeZone.length === 0) {
-        throw new TypeError("timeZone must be a valid IANA timezone.");
-    }
-    try {
-        new Intl.DateTimeFormat("en", { timeZone }).format(0);
-    }
-    catch {
-        throw new TypeError("timeZone must be a valid IANA timezone.");
-    }
-    return timeZone;
-}
+import { resolveTimeZone } from "../config/timeZone.js";
 /** Formats persisted UTC/RFC 3339 timestamps for human-facing CLI output. */
 export function formatTimestamp(value, configuredTimeZone) {
     const instant = new Date(value);

package/dist/plugins/pluginService.js

@@ -354,10 +354,18 @@ export function createPluginService(store, host, registry) {
                     // recorded on the plugin's own failure channel — not a Task product
                     // artifact (product artifacts are files in the Task's Git repository).
                     try {
-                        store.recordPluginIntentFailure(taskId, retired.ref.id, intent.revision, {
-                            message: `Plugin instance cleanup failed for ${retired.ref.id}/${retired.ref.generation}: `
-                                + (error instanceof Error ? error.message : String(error)),
-                            occurredAt: new Date().toISOString()
+                        store.transaction(tx => {
+                            const current = tx.getPluginIntent(taskId, pkg.manifest.id);
+                            if (current === null)
+                                return;
+                            // A draining generation can fail after another replacement.
+                            // Attach this diagnostic to the current selection, without
+                            // changing it or treating its activation as a failure.
+                            tx.recordPluginIntentFailure(taskId, pkg.manifest.id, current.revision, {
+                                message: `Plugin instance cleanup failed for ${retired.ref.id}/${retired.ref.generation}: `
+                                    + (error instanceof Error ? error.message : String(error)),
+                                occurredAt: new Date().toISOString()
+                            });
                         });
                     }
                     catch { /* best-effort telemetry; never mask the successful activation */ }

package/dist/release/releaseWorkflowPorts.js

@@ -1,17 +1,17 @@
 import { createHash, randomBytes } from "node:crypto";
 import { chmod, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-import { releaseWorkflowScratchRoot } from "../storage/homeLayout.js";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { runUpdate } from "../cli/updateOrchestrator.js";
 import { activatedControllerEntrypoint } from "../cli/updatePorts.js";
-import { restartFileTaskController, stopFileTaskController } from "../controller/clientRuntime.js";
 import { runProjectCommand } from "../commands/projectCommands.js";
-import { createFileReleaseIdempotencyStore } from "./releaseIdempotencyStore.js";
+import { restartFileTaskController, stopFileTaskController } from "../controller/clientRuntime.js";
 import { isConcreteVersion } from "../domain/validation.js";
+import { createExecFileCommandRunner, createPinnedCommandRunner, resolveExecutable } from "../external/pinnedCommandRunner.js";
 import { resolveProject } from "../repository/project.js";
-import { resolveVerificationGate } from "../verification/verificationGateService.js";
+import { releaseWorkflowScratchRoot } from "../storage/homeLayout.js";
 import { findL2ArtifactForCommit } from "../verification/gateArtifactStore.js";
-import { createExecFileCommandRunner, createPinnedCommandRunner, resolveExecutable } from "../external/pinnedCommandRunner.js";
+import { resolveVerificationGate } from "../verification/verificationGateService.js";
+import { createFileReleaseIdempotencyStore } from "./releaseIdempotencyStore.js";
 export { resolveExecutable } from "../external/pinnedCommandRunner.js";
 const defaultRunCommand = createExecFileCommandRunner();
 /**
@@ -41,8 +41,8 @@ export function createPinnedRunner(base) {
     return createPinnedCommandRunner(base, PINNED_EXTERNAL_COMMANDS);
 }
 /**
- * The real adapter. It is NEVER exercised by the deterministic test suite
- * (fakes are); every branch dispatches to an existing atomic operation.
+ * The production adapter dispatches existing atomic operations. Deterministic
+ * tests inject command/idempotency ports and never contact release services.
  */
 export function createReleaseWorkflowPorts(deps) {
     const run = deps.runCommand !== undefined
@@ -1032,37 +1032,12 @@ export function createReleaseWorkflowPorts(deps) {
                     return { state: "unknown" };
                 }
                 case "controller-home": {
-                    // P1-2 (rr22): the identity value is a JSON envelope
-                    // {home, globalPrefix?} that pins the exact activation target;
-                    // legacy identities are bare Home path strings and re-derive the
-                    // prefix from the caller's environment.
-                    let queriedHome = deps.home;
-                    let pinnedPrefix;
+                    // Recovery uses the exact persisted activation target, never the
+                    // resume caller's current installation.
                     const parsedIdentity = parseControllerHomeIdentity(externalIdentity.value);
-                    if (parsedIdentity !== undefined) {
-                        if (parsedIdentity.globalPrefix === undefined)
-                            return { state: "unknown" };
-                        queriedHome = parsedIdentity.home;
-                        pinnedPrefix = parsedIdentity.globalPrefix;
-                    }
-                    else {
-                        queriedHome = externalIdentity.value;
-                    }
-                    // P1-3 (rr20): Query the GLOBAL install target — the same binary
-                    // `cli-update` activates via `npm install --global` — not the
-                    // current checkout module. A checkout that happens to be the target
-                    // version must not confirm a global install that is stale or never
-                    // activated. A pinned prefix is used as-is; only legacy/unpinned
-                    // identities re-derive via `npm prefix --global`, never PATH.
-                    let globalPrefix = pinnedPrefix;
-                    if (globalPrefix === undefined) {
-                        const prefixResult = await run("npm", ["prefix", "--global"]);
-                        if (prefixResult.code !== 0)
-                            return { state: "unknown" };
-                        globalPrefix = prefixResult.stdout.trim();
-                        if (globalPrefix.length === 0)
-                            return { state: "unknown" };
-                    }
+                    if (parsedIdentity === undefined)
+                        return { state: "unknown" };
+                    const { home: queriedHome, globalPrefix } = parsedIdentity;
                     const globalYui = join(globalPrefix, "bin", "yui");
                     const homeEnv = { YUI_HOME: queriedHome };
                     const checked = await run(process.execPath, [globalYui, "--json", "doctor"], undefined, homeEnv);
@@ -1092,13 +1067,6 @@ export function createReleaseWorkflowPorts(deps) {
         }
     };
 }
-/**
- * Finds the open PR for a head ref. Prefers `gh pr view --head`; older gh
- * versions that lack the flag fall back to `gh pr list --head`. A non-zero
- * exit from both commands is a failed lookup (transport error), not an
- * authoritative "no PR found". Both paths request the head object id so the
- * caller can prove the PR names the frozen source commit before reuse.
- */
 /**
  * Resolves the SHA a remote head branch currently points at, or undefined
  * when the branch cannot be resolved or the answer is not a 40-hex commit.
@@ -1122,55 +1090,40 @@ async function resolveRemoteHead(run, repo, head) {
     return /^[0-9a-f]{40}$/i.test(sha) ? sha : undefined;
 }
 async function findHeadPullRequest(run, head, repo) {
-    const viewed = await run("gh", [
-        "pr", "view", "--head", head,
-        "--repo", repo,
-        "--json", "number,headRefOid"
-    ]);
-    if (viewed.code === 0) {
-        const found = parsePrHeadEntry(viewed.stdout);
-        if (found !== undefined) {
-            return { status: "found", prNumber: found.prNumber, headSha: found.headSha };
-        }
-    }
-    // A non-zero exit from `gh pr view` may mean "no PR for head" (exit 1 with
-    // empty stdout) or a transport failure. The list fallback disambiguates.
+    // One documented query. Two matches are enough to prove ambiguity; never
+    // choose an arbitrary PR or mistake malformed output for authoritative absence.
     const listed = await run("gh", [
         "pr", "list", "--head", head,
         "--repo", repo,
         "--state", "open",
+        "--limit", "2",
         "--json", "number,headRefOid"
     ]);
-    if (listed.code === 0) {
-        const found = parsePrHeadList(listed.stdout);
-        if (found !== undefined) {
-            return { status: "found", prNumber: found.prNumber, headSha: found.headSha };
-        }
-        // Authoritative empty result: no open PR for this head.
-        return { status: "not-found" };
+    if (listed.code !== 0) {
+        return { status: "failed", error: listed.stderr.trim() || "gh PR lookup failed" };
     }
-    // Both commands failed: transport error, not "no PR found".
-    return {
-        status: "failed",
-        error: listed.stderr.trim() || viewed.stderr.trim() || "gh PR lookup failed"
-    };
-}
-/** Parses `gh pr view --json number,headRefOid` output. */
-function parsePrHeadEntry(stdout) {
+    let entries;
     try {
-        return prHeadFromJson(JSON.parse(stdout.trim()));
+        entries = JSON.parse(listed.stdout);
     }
     catch {
-        return undefined;
+        return { status: "failed", error: "gh PR list returned invalid JSON." };
     }
+    if (!Array.isArray(entries))
+        return { status: "failed", error: "gh PR list did not return an array." };
+    if (entries.length === 0)
+        return { status: "not-found" };
+    if (entries.length !== 1)
+        return { status: "failed", error: "Multiple open PRs match this head; select the intended PR explicitly." };
+    const found = prHeadFromJson(entries[0]);
+    return found === undefined
+        ? { status: "failed", error: "gh PR list returned an invalid PR identity." }
+        : { status: "found", prNumber: found.prNumber, headSha: found.headSha };
 }
-/** Parses the first entry of `gh pr list --json number,headRefOid` output. */
-function parsePrHeadList(stdout) {
+/** Parses `gh pr view --json number,headRefOid` output. */
+function parsePrHeadEntry(stdout) {
     try {
-        const parsed = JSON.parse(stdout.trim());
-        if (!Array.isArray(parsed) || parsed.length === 0)
-            return undefined;
-        return prHeadFromJson(parsed[0]);
+        return prHeadFromJson(JSON.parse(stdout.trim()));
     }
     catch {
         return undefined;
@@ -1180,9 +1133,9 @@ function prHeadFromJson(value) {
     if (typeof value !== "object" || value === null)
         return undefined;
     const record = value;
-    if (typeof record.number !== "number" || !Number.isFinite(record.number))
+    if (typeof record.number !== "number" || !Number.isSafeInteger(record.number) || record.number < 1)
         return undefined;
-    if (typeof record.headRefOid !== "string" || record.headRefOid.length === 0)
+    if (typeof record.headRefOid !== "string" || !/^[0-9a-f]{40}$/iu.test(record.headRefOid))
         return undefined;
     return { prNumber: String(record.number), headSha: record.headRefOid };
 }
@@ -1283,7 +1236,7 @@ async function queryIdentityFor(step, params, effect, source, home, run) {
  * idempotency/identity persistence). Only kinds whose identity is fully
  * determined by the immutable plan + source can be recovered this way.
  */
-function deriveIdentityFromPlan(step, source) {
+function deriveIdentityFromPlan(step, _source) {
     switch (step.kind) {
         case "version-tag": {
             const tag = step.params?.tag;
@@ -1410,11 +1363,10 @@ async function resolveGlobalPrefix(run) {
 }
 /**
  * The controller-home query identity for a cli-update effect. The value is a
- * JSON envelope carrying the Home and — when resolvable — the exact global
+ * JSON envelope carrying the Home and the exact global
  * prefix that was activated, so a resume query checks the same installation
  * instead of re-deriving the target from the caller's npm/PATH environment
- * (P1-2, rr22). Legacy identities are bare Home path strings; the query
- * accepts both shapes via {@link parseControllerHomeIdentity}.
+ * (P1-2, rr22). Without that evidence no identity is issued.
  */
 async function controllerHomeIdentity(run, home) {
     const globalPrefix = await resolveGlobalPrefix(run);
@@ -1471,7 +1423,7 @@ async function readPersistedCliUpdateIdentity(home, idempotencyKey) {
         return undefined;
     }
     const parsed = parseControllerHomeIdentity(raw);
-    if (parsed === undefined || parsed.globalPrefix === undefined)
+    if (parsed === undefined)
         return undefined;
     return { kind: "controller-home", value: JSON.stringify(parsed) };
 }
@@ -1550,22 +1502,19 @@ async function readPersistedNpmPublishTarget(home, idempotencyKey) {
     }
 }
 /**
- * Parse a controller-home identity value. Accepts the JSON envelope
- * {home, globalPrefix?} written by {@link controllerHomeIdentity}; a legacy
- * bare Home path string (or any unparseable value) yields undefined so the
- * caller treats the raw value as the Home.
+ * Read the exact activation target. Missing or malformed identity remains
+ * unknown; no alternative installation can attest the original effect.
  */
 function parseControllerHomeIdentity(value) {
     try {
         const parsed = JSON.parse(value);
-        if (!isRecord(parsed) || typeof parsed.home !== "string" || parsed.home.length === 0) {
+        if (!isRecord(parsed) || typeof parsed.home !== "string" || !isAbsolute(parsed.home)
+            || typeof parsed.globalPrefix !== "string" || !isAbsolute(parsed.globalPrefix)) {
             return undefined;
         }
         return {
             home: parsed.home,
-            ...(typeof parsed.globalPrefix === "string" && parsed.globalPrefix.length > 0
-                ? { globalPrefix: parsed.globalPrefix }
-                : {})
+            globalPrefix: parsed.globalPrefix
         };
     }
     catch {