@zq-silk/yui 0.15.9 → 0.15.11

package/dist/integration/integrationAttempt.js

@@ -52,9 +52,17 @@ export function requireResolutionDecision(attempt, report, now) {
         updatedAt: now.toISOString()
     });
 }
+export function recordIntegrationConflict(attempt, report, now) {
+    if (attempt.status !== "running" && attempt.status !== "conflicted") {
+        throw new Error(`Integration cannot record Git conflicts from ${attempt.status}.`);
+    }
+    return updateIntegrationAttempt(attempt, {
+        status: "conflicted", conflict: normalizeConflictReport(report)
+    }, now);
+}
 export function recordResolutionDecision(attempt, decision, decidedBy, now) {
     validateIntegrationAttempt(attempt);
-    if (attempt.status !== "blocked" || attempt.conflict === undefined) {
+    if (!["blocked", "conflicted"].includes(attempt.status) || attempt.conflict === undefined) {
         throw new Error("Integration has no pending semantic decision.");
     }
     if (decision.action !== "manual-resolution" && decision.action !== "reject") {
@@ -63,7 +71,7 @@ export function recordResolutionDecision(attempt, decision, decidedBy, now) {
     const timestamp = now.toISOString();
     return validateIntegrationAttempt({
         ...attempt,
-        status: decision.action === "reject" ? "failed" : "blocked",
+        status: decision.action === "reject" ? "failed" : attempt.status,
         resolution: {
             action: decision.action,
             rationale: requireText(decision.rationale, "Resolution rationale"),
@@ -138,6 +146,23 @@ export function validateIntegrationAttempt(attempt) {
     if (attempt.candidateCommit !== undefined) {
         requireCommit(attempt.candidateCommit, "Integration candidate commit");
     }
+    if (attempt.checkInputDigest !== undefined && !/^[a-f0-9]{64}$/u.test(attempt.checkInputDigest)) {
+        throw new Error("Integration check input digest is invalid.");
+    }
+    if (attempt.sourceProgress !== undefined) {
+        const progress = attempt.sourceProgress;
+        requireText(progress.workspace, "Integration source workspace");
+        requireText(progress.branch, "Integration source branch");
+        requireCommit(progress.head, "Integration source head");
+        if (!/^[a-f0-9]{64}$/u.test(progress.sourceDigest)
+            || !Number.isSafeInteger(progress.completedSteps) || progress.completedSteps < 0
+            || (progress.activeAction !== undefined
+                && !/^yui-integration-[a-f0-9]{32}$/u.test(progress.activeAction))
+            || (progress.emptyResolution !== undefined
+                && (progress.emptyResolution !== true || progress.activeAction === undefined))) {
+            throw new Error("Integration source progress is invalid.");
+        }
+    }
     if (attempt.afterCommit !== undefined) {
         requireCommit(attempt.afterCommit, "Integration after commit");
     }
@@ -160,6 +185,7 @@ export function validateIntegrationAttempt(attempt) {
     }
     if (![
         "running",
+        "conflicted",
         "blocked",
         "validating",
         "committed",
@@ -170,8 +196,8 @@ export function validateIntegrationAttempt(attempt) {
     }
     if (attempt.conflict !== undefined)
         normalizeConflictReport(attempt.conflict);
-    if (attempt.status === "blocked" && attempt.conflict === undefined) {
-        throw new Error("A blocked Integration needs a ConflictReport.");
+    if ((attempt.status === "blocked" || attempt.status === "conflicted") && attempt.conflict === undefined) {
+        throw new Error("A paused Integration needs a ConflictReport.");
     }
     if (attempt.resolution !== undefined) {
         if (attempt.resolution.action !== "manual-resolution"

package/dist/integration/integrationQueueService.js

@@ -463,9 +463,9 @@ export async function processIntegrationQueue(store, home, taskId, options = {})
             if (result.status === "committed") {
                 entry = markIntegrationQueueCommitted(entry, committedTargetAfter(result.attempt), now());
             }
-            else if (result.status === "blocked") {
+            else if (result.status === "blocked" || result.status === "conflicted") {
                 entry = markIntegrationQueueBlocked(entry, result.attempt.conflict?.summary
-                    ?? "Integration blocked without a conflict report.", now());
+                    ?? result.attempt.summary ?? "Inspect the unfinished Integration.", now());
             }
             else {
                 entry = markIntegrationQueueBlocked(entry, gateFailureSummary(result.attempt), now());
@@ -580,7 +580,7 @@ function resolveBlockedAttempt(store, taskId, entry, decision, decidedBy, now) {
     if (entry.integrationAttemptId === undefined)
         return;
     const attempt = store.getIntegrationAttempt(taskId, entry.integrationAttemptId);
-    if (attempt === null || attempt.status !== "blocked")
+    if (attempt === null || (attempt.status !== "blocked" && attempt.status !== "conflicted"))
         return;
     const rejected = recordResolutionDecision(attempt, {
         action: "reject",
@@ -601,7 +601,7 @@ function assertRecoverableAttempt(store, taskId, entry, action) {
     const attempt = store.getIntegrationAttempt(taskId, entry.integrationAttemptId);
     if (attempt === null)
         return;
-    if (attempt.status !== "blocked" && attempt.status !== "failed") {
+    if (attempt.status !== "blocked" && attempt.status !== "conflicted" && attempt.status !== "failed") {
         throw new Error(`Integration queue entry ${entry.id} is backed by ${attempt.status} `
             + `Integration Attempt ${attempt.id}; reconcile the queue entry instead `
             + `of ${action} it.`);
@@ -679,9 +679,9 @@ async function reconcileTerminalAttempts(store, taskId, git, now) {
         // it.  An Attempt still running or validating is genuinely in flight.
         if (entry.status !== "running")
             continue;
-        if (attempt.status !== "failed" && attempt.status !== "blocked")
+        if (attempt.status !== "failed" && attempt.status !== "blocked" && attempt.status !== "conflicted")
             continue;
-        const diagnosis = attempt.status === "blocked"
+        const diagnosis = attempt.status === "blocked" || attempt.status === "conflicted"
             ? attempt.conflict?.summary ?? "Integration blocked without a conflict report."
             : gateFailureSummary(attempt);
         store.saveIntegrationQueueEntry(taskId, markIntegrationQueueBlocked(entry, diagnosis, now()));
@@ -742,7 +742,7 @@ function committedTargetAfter(attempt) {
 function gateFailureSummary(attempt) {
     const failed = (attempt.checks ?? []).find((check) => check.outcome === "failed");
     return failed === undefined
-        ? "Integration failed before the target ref advanced."
+        ? attempt.summary ?? "Inspect the Integration target and preserved evidence."
         : `gate failed: ${failed.name}${failed.details === undefined ? "" : `: ${failed.details}`}`;
 }
 async function findEquivalentCommit(git, repositoryPath, sourceCommit, historyHead, baseCommit) {

package/dist/integration/integrationSourceApplication.js

@@ -0,0 +1,323 @@
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { promisify } from "node:util";
+import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
+import { recordIntegrationConflict, requireResolutionDecision, updateIntegrationAttempt } from "./integrationAttempt.js";
+const execute = promisify(execFile);
+/** Each Git ref-changing command has an attempt-owned cursor and reflog action.
+ * Re-entry consumes the exact branch ref transition, never clean HEAD alone.
+ * Git's own in-progress metadata identifies an unfinished operation. Missing
+ * evidence is a diagnosis for the Leader, not permission to replay an effect. */
+export async function applyIntegrationSource(input) {
+    let current = input.attempt;
+    const { workspace, store, now } = input;
+    const path = workspace.path;
+    const source = current.source;
+    const save = (patch) => {
+        const next = updateIntegrationAttempt(current, patch, now());
+        store.saveIntegrationAttempt(current.taskId, next);
+        current = next;
+    };
+    const pause = (affectedPaths, kind) => {
+        const pending = recordIntegrationConflict(current, {
+            affectedPaths, summary: `${kind} conflicts in ${current.targetRef}; resolve files and continue.`
+        }, now());
+        store.transaction(tx => {
+            tx.saveIntegrationAttempt(current.taskId, pending);
+            if (current.status !== "conflicted"
+                || JSON.stringify(current.conflict?.affectedPaths) !== JSON.stringify(affectedPaths)) {
+                queueLeaderWakeup(tx, current.taskId, `integration-conflicted:${current.id}`, now());
+            }
+        });
+        return pending;
+    };
+    if (source.kind === "historical-change-sets") {
+        throw new Error("Historical Integration source has no current application proof; preserve evidence and abort explicitly.");
+    }
+    if (source.kind === "work-item" && source.strategy === "manual") {
+        if (current.candidateCommit !== undefined) {
+            await assertIntegrationCandidate(path, current.candidateCommit);
+            return current;
+        }
+        if (current.resolution?.action !== "manual-resolution") {
+            const pending = requireResolutionDecision(current, {
+                affectedPaths: [], summary: "Manual WorkItem integration; apply the result and record its rationale."
+            }, now());
+            store.saveIntegrationAttempt(current.taskId, pending);
+            return pending;
+        }
+        await assertIntegrationCandidate(path);
+        save({ status: "running", candidateCommit: await line(path, "rev-parse", "HEAD") });
+        return current;
+    }
+    const sourceDigest = integrationSourceDigest(current, workspace);
+    const commits = source.kind === "work-item" && source.strategy === "cherry-pick"
+        ? (await command(path, ["rev-list", "--reverse", `${source.startCommit}..${source.resultCommit}`]))
+            .trim().split("\n").filter(Boolean)
+        : [source.kind === "upstream" ? source.remoteCommit : source.resultCommit];
+    const kind = source.kind === "upstream" ? "rebase" : source.strategy;
+    const branch = workspace.branch.startsWith("refs/") ? workspace.branch : `refs/heads/${workspace.branch}`;
+    const active = await activeGitOperation(path);
+    if (current.sourceProgress === undefined) {
+        // Historical unfinished operations can be adopted only when Git still
+        // carries their exact source/target identity. Finished old operations
+        // without a receipt are deliberately not inferred from a clean tree.
+        const head = await line(path, "rev-parse", "HEAD");
+        if (active !== undefined) {
+            if (kind === "cherry-pick") {
+                throw new Error("Historical cherry-pick has no durable completed-step cursor; preserve it and choose explicit recovery.");
+            }
+            await assertOperation(path, kind, commits[0], current.beforeCommit, branch, source);
+        }
+        else if (head !== current.beforeCommit || current.status === "conflicted") {
+            throw new Error("Integration source completion is unproven: no attempt-owned Git receipt. Preserve the candidate; do not replay.");
+        }
+        else {
+            await assertIntegrationCandidate(path, current.beforeCommit);
+        }
+        save({ sourceProgress: {
+                workspace: resolve(path), branch, sourceDigest, completedSteps: 0,
+                head: current.beforeCommit,
+                ...(active === undefined ? {} : { activeAction: actionId() })
+            } });
+    }
+    let progress = current.sourceProgress;
+    if (progress.workspace !== resolve(path) || progress.branch !== branch
+        || progress.sourceDigest !== sourceDigest || progress.completedSteps > commits.length) {
+        throw new Error("Integration source/workspace identity changed; no Git operation or check was started.");
+    }
+    if (current.candidateCommit !== undefined) {
+        if (progress.completedSteps !== commits.length || progress.activeAction !== undefined
+            || progress.head !== current.candidateCommit) {
+            throw new Error("Integration candidate does not match its source application receipt.");
+        }
+        await assertIntegrationCandidate(path, current.candidateCommit);
+        return current;
+    }
+    for (let index = progress.completedSteps; index < commits.length; index++) {
+        const commit = commits[index];
+        let fresh = false;
+        if (progress.activeAction === undefined) {
+            await assertIntegrationCandidate(path, progress.head);
+            if (await succeeds(path, ["merge-base", "--is-ancestor", commit, progress.head])) {
+                // Already-represented input is proven by ancestry, without a Git effect.
+                save({ sourceProgress: { ...progress, completedSteps: index + 1 } });
+                progress = current.sourceProgress;
+                continue;
+            }
+            if (source.kind === "upstream") {
+                if (input.remoteUrl === undefined || input.git.fetchRemoteHeadIntoWorktree === undefined) {
+                    throw new Error("Upstream Integration has no remote fetch capability.");
+                }
+                const fetched = await input.git.fetchRemoteHeadIntoWorktree({
+                    repositoryPath: path, remoteUrl: input.remoteUrl, branch: source.branch
+                });
+                if (fetched.commit !== commit) {
+                    throw new Error(`Upstream moved: ${fetched.commit}; expected ${commit}.`);
+                }
+            }
+            save({ sourceProgress: { ...progress, activeAction: actionId() } });
+            progress = current.sourceProgress;
+            fresh = true;
+        }
+        const action = progress.activeAction;
+        const operation = await activeGitOperation(path);
+        if (!fresh && operation === undefined) {
+            await assertIntegrationCandidate(path);
+            const provenEmpty = kind === "cherry-pick" && progress.emptyResolution === true
+                && await line(path, "rev-parse", "HEAD") === progress.head
+                && (await command(path, ["symbolic-ref", "HEAD"])).trim() === branch;
+            if (!provenEmpty && !await hasExactRefReceipt(path, branch, progress.head, action)) {
+                throw new Error("Git application outcome is unproven: exact attempt reflog receipt is missing; inspect or abort, never blindly replay.");
+            }
+        }
+        else {
+            if (operation !== undefined) {
+                await assertOperation(path, kind, commit, progress.head, branch, source);
+            }
+            const unresolved = await conflicts(path);
+            if (unresolved.length > 0) {
+                return pause(unresolved, kind);
+            }
+            if (!fresh && current.status !== "conflicted") {
+                throw new Error("Git operation is present but no paused conflict is recorded; inspect its execution before continuing.");
+            }
+            try {
+                if (operation !== undefined) {
+                    if (kind === "rebase") {
+                        await command(path, ["rebase", "--continue"], action);
+                    }
+                    else if (kind === "merge") {
+                        await command(path, ["commit", "--no-edit"], action);
+                    }
+                    else {
+                        const empty = await succeeds(path, ["diff", "--cached", "--quiet"]);
+                        if (empty) {
+                            save({ sourceProgress: { ...progress, emptyResolution: true } });
+                            progress = current.sourceProgress;
+                        }
+                        await command(path, ["cherry-pick", empty ? "--skip" : "--continue"], action);
+                    }
+                }
+                else if (kind === "rebase" && source.kind === "upstream") {
+                    await command(path, ["rebase", "--onto", commit, source.taskBaseCommit, workspace.branch], action);
+                }
+                else if (kind === "merge") {
+                    await command(path, ["merge", "--no-edit", "--no-ff", commit], action);
+                }
+                else if (kind === "ff") {
+                    await command(path, ["merge", "--ff-only", commit], action);
+                }
+                else {
+                    // Choose from a read, not from a failed mutating merge: a Git error
+                    // after a ref update is not proof that it is safe to cherry-pick.
+                    const fastForward = await succeeds(path, ["merge-base", "--is-ancestor", progress.head, commit]);
+                    await command(path, fastForward ? ["merge", "--ff-only", commit] : ["cherry-pick", commit], action);
+                }
+            }
+            catch (error) {
+                const affectedPaths = await conflicts(path);
+                if (affectedPaths.length > 0)
+                    return pause(affectedPaths, kind);
+                if (kind !== "cherry-pick" || await activeGitOperation(path) !== "cherry-pick"
+                    || !await succeeds(path, ["diff", "--cached", "--quiet"]))
+                    throw error;
+                await assertOperation(path, kind, commit, progress.head, branch, source);
+                save({ sourceProgress: { ...progress, emptyResolution: true } });
+                progress = current.sourceProgress;
+                await command(path, ["cherry-pick", "--skip"], action);
+            }
+        }
+        await assertIntegrationCandidate(path);
+        const head = await line(path, "rev-parse", "HEAD");
+        save({ status: "running", conflict: undefined, sourceProgress: {
+                workspace: progress.workspace, branch, sourceDigest, completedSteps: index + 1, head
+            } });
+        progress = current.sourceProgress;
+    }
+    await assertIntegrationCandidate(path, progress.head);
+    save({ status: "running", conflict: undefined, candidateCommit: progress.head });
+    return current;
+}
+export function assertRecordedSourceCandidate(attempt, workspace) {
+    if (attempt.source.kind === "work-item" && attempt.source.strategy === "manual"
+        && attempt.resolution?.action === "manual-resolution")
+        return;
+    const progress = attempt.sourceProgress;
+    const branch = workspace.branch.startsWith("refs/") ? workspace.branch : `refs/heads/${workspace.branch}`;
+    if (progress === undefined || progress.activeAction !== undefined
+        || progress.head !== attempt.candidateCommit || progress.workspace !== resolve(workspace.path)
+        || progress.branch !== branch || progress.sourceDigest !== integrationSourceDigest(attempt, workspace)) {
+        throw new Error("Integration candidate does not match its recorded source/workspace identity.");
+    }
+}
+function integrationSourceDigest(attempt, workspace) {
+    return createHash("sha256").update(JSON.stringify([
+        attempt.taskId, attempt.id, attempt.projectId, attempt.targetRef, attempt.beforeCommit,
+        attempt.source, resolve(workspace.path), workspace.branch
+    ])).digest("hex");
+}
+export async function assertIntegrationCandidate(path, expectedHead, expectedBranch) {
+    if (await activeGitOperation(path) !== undefined
+        || (await command(path, ["status", "--porcelain=v1", "--untracked-files=all"])).trim() !== "") {
+        throw new Error("Integration candidate must be clean, with no unfinished Git operation.");
+    }
+    const head = await line(path, "rev-parse", "HEAD");
+    if (expectedHead !== undefined && head !== expectedHead) {
+        throw new Error(`Integration candidate moved to ${head}; expected ${expectedHead}.`);
+    }
+    if (expectedBranch !== undefined) {
+        const branch = expectedBranch.startsWith("refs/") ? expectedBranch : `refs/heads/${expectedBranch}`;
+        if ((await command(path, ["symbolic-ref", "HEAD"])).trim() !== branch) {
+            throw new Error("Integration candidate changed its owned branch.");
+        }
+    }
+}
+async function assertOperation(path, kind, commit, before, branch, source) {
+    const active = await activeGitOperation(path);
+    if (active !== kind)
+        throw new Error(`Integration expected ${kind}, found ${active ?? "no active Git operation"}.`);
+    if (kind === "rebase") {
+        const directory = await gitPath(path, "rebase-merge");
+        // Yui invokes the merge backend explicitly. A legacy apply-backend
+        // operation cannot be silently treated as the same execution.
+        const [onto, original, headName] = await Promise.all(["onto", "orig-head", "head-name"].map(name => readFile(resolve(directory, name), "utf8")));
+        if (source.kind !== "upstream" || onto.trim() !== commit
+            || original.trim() !== before || headName.trim() !== branch) {
+            throw new Error("Active rebase does not belong to this Integration source and target.");
+        }
+    }
+    else {
+        const activeSource = await line(path, "rev-parse", kind === "merge" ? "MERGE_HEAD" : "CHERRY_PICK_HEAD");
+        if (activeSource !== commit || await line(path, "rev-parse", "HEAD") !== before
+            || (await command(path, ["symbolic-ref", "HEAD"])).trim() !== branch) {
+            throw new Error("Active Git operation does not belong to this Integration step.");
+        }
+    }
+}
+async function activeGitOperation(path) {
+    for (const dir of ["rebase-merge", "rebase-apply"]) {
+        try {
+            await readFile(resolve(await gitPath(path, dir), "head-name"));
+            return "rebase";
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    if (await succeeds(path, ["rev-parse", "--verify", "MERGE_HEAD"]))
+        return "merge";
+    if (await succeeds(path, ["rev-parse", "--verify", "CHERRY_PICK_HEAD"]))
+        return "cherry-pick";
+    // REBASE_HEAD is deliberately ignored: it can outlive a finished rebase.
+    return undefined;
+}
+async function hasExactRefReceipt(path, branch, before, action) {
+    if ((await command(path, ["symbolic-ref", "HEAD"])).trim() !== branch)
+        return false;
+    const head = await line(path, "rev-parse", "HEAD");
+    const log = await readFile(await gitPath(path, `logs/${branch}`), "utf8");
+    const last = log.trimEnd().split("\n").at(-1) ?? "";
+    const [transition, message] = last.split("\t");
+    const [oldHead, newHead] = (transition ?? "").split(" ");
+    return oldHead === before && newHead === head
+        && (message === action || message?.startsWith(`${action}:`) === true
+            || message?.startsWith(`${action} (finish):`) === true);
+}
+const actionId = () => `yui-integration-${randomBytes(16).toString("hex")}`;
+async function gitPath(path, name) {
+    const value = (await command(path, ["rev-parse", "--git-path", name])).trim();
+    return isAbsolute(value) ? value : resolve(path, value);
+}
+async function conflicts(path) {
+    return (await command(path, ["diff", "--name-only", "--diff-filter=U"])).trim().split("\n").filter(Boolean);
+}
+async function line(path, ...args) {
+    return (await command(path, args)).trim();
+}
+async function succeeds(path, args, action) {
+    try {
+        await command(path, args, action);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function command(path, args, action) {
+    try {
+        return (await execute("git", [
+            "-C", path, "-c", "user.name=Yui", "-c", "user.email=yui@local",
+            "-c", "core.editor=true", "-c", "rebase.backend=merge", ...args
+        ], {
+            encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 120_000,
+            env: { ...process.env, ...(action === undefined ? {} : { GIT_REFLOG_ACTION: action }) }
+        })).stdout;
+    }
+    catch (error) {
+        throw new Error(`Integration Git failed: ${error.stderr?.trim() ?? String(error)}`, { cause: error });
+    }
+}

package/dist/message/globalInterrupt.js

@@ -0,0 +1,33 @@
+import { markGlobalRoleMessageDelivered } from "./message.js";
+export function recordGlobalSteerResult(store, roleName, messageId, receipt) {
+    store.transaction(tx => {
+        const message = tx.listGlobalRoleMessages(roleName).find(entry => entry.id === messageId);
+        const source = message?.inputControl ?? message?.interruptThen?.reusedInput;
+        if (message === undefined || source?.action !== "steer")
+            throw new Error("Global steer has no original Message.");
+        // Conclusive native evidence outranks a lost/late transport acknowledgement.
+        if (message.control?.outcome === "accepted" || message.control?.outcome === "rejected")
+            return;
+        const now = new Date();
+        const outcome = receipt.state === "steered" ? "accepted"
+            : receipt.state === "steer-unknown" ? "delivery-unknown" : "rejected";
+        const updated = { ...message, control: {
+                requestId: source.requestId, receiptId: `steer:${roleName}/${messageId}`,
+                outcome, observedAt: now.toISOString()
+            } };
+        tx.updateGlobalRoleMessage(outcome === "accepted" ? markGlobalRoleMessageDelivered(updated, now) : updated);
+    });
+}
+export function recordGlobalInterruptResult(store, roleName, receiptId, receipt) {
+    store.transaction(tx => {
+        const sessions = tx.getGlobalRoleSessionSet(roleName);
+        const entry = Object.entries(sessions?.interrupts ?? {}).find(([, value]) => value.receiptId === receiptId);
+        if (sessions == null || entry === undefined)
+            throw new Error("Global interrupt has no original request.");
+        if (entry[1].receipt !== undefined)
+            return;
+        tx.saveGlobalRoleSessionSet({ ...sessions, interrupts: { ...sessions.interrupts,
+                [entry[0]]: { ...entry[1], receipt }
+            } });
+    });
+}

package/dist/message/inputControlResolution.js

@@ -0,0 +1,106 @@
+import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
+/**
+ * Turn statuses that mean a Turn record is present and not yet terminal. This is
+ * only "there is something here", not "it is safe to target": `submitting` is a
+ * call still in flight and `delivery-unknown` is an outbound whose acceptance was
+ * never proven. Both are separated from `accepted` below (decision-3 §3/§8) so an
+ * unconfirmed delivery is reported as DELIVERY_UNKNOWN, never silently steered or
+ * cancelled as if it were a clean active Turn.
+ */
+const PRESENT_TURN_STATUSES = new Set(["submitting", "accepted", "delivery-unknown"]);
+/**
+ * The scope-generic core. It takes an already-fetched Session set and the owner
+ * decoration for a resolved target, so Task and Global callers share the exact
+ * same capability, present-Turn, authority, and target-match logic.
+ *
+ * @param decorate Adds the owner-specific fields to a resolved target. For a
+ *   Task Role it attaches the taskId; for a Global Role it attaches nothing.
+ */
+function resolveInputControl(sessions, kind, expectedTarget, roleName) {
+    const active = sessions?.sessions[sessions.activeAgentId];
+    // Capability is read from the declared Driver of the current active Session,
+    // never hardcoded by Agent name (decision-3 §7). When there is no active
+    // Session at all there is also no current Turn to target.
+    if (sessions == null || active === undefined || active.status !== "active") {
+        return { outcome: "no-active-turn", code: "NO_ACTIVE_TURN",
+            detail: "No active native Session holds a current Turn for this Role." };
+    }
+    const capabilities = builtinAgentDriverRegistry().requireByAdapterId(active.adapterId).capabilities;
+    if (kind === "steer" && capabilities.input.steer !== "fenced") {
+        return { outcome: "unsupported", code: "STEER_UNSUPPORTED",
+            detail: `Agent plan '${active.adapterId}' cannot steer its current Turn; `
+                + "the input is saved for an explicit interrupt --then-message or a queue." };
+    }
+    if (kind === "interrupt" && capabilities.control.interruptDelivery !== "native") {
+        return { outcome: "unsupported", code: "INTERRUPT_UNSUPPORTED",
+            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;
+    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",
+            detail: "The Provider is not running a Turn now; there is nothing to steer or interrupt." };
+    }
+    // A human writer fence (an interactive takeover) owns the Turn; the Controller
+    // must not steer or cancel across it.
+    if (binding.authority.owner !== "controller") {
+        return { outcome: "target-changed", code: "TARGET_CHANGED",
+            detail: `Provider authority is ${binding.authority.owner}-held; release the takeover before a managed control.` };
+    }
+    const observedId = turn.nativeTurnId ?? turn.attemptId;
+    if (expectedTarget !== observedId
+        && !(turn.nativeTurnId !== undefined && expectedTarget === turn.attemptId)) {
+        return { outcome: "target-changed", code: "TARGET_CHANGED",
+            detail: `The current Turn is ${observedId}, not ${expectedTarget}; re-read the Session before retrying.` };
+    }
+    // The right Turn is confirmed; now report its own delivery state. decision-3
+    // §3/§8, message-3 #7: an original Turn still in flight (`submitting`) or whose
+    // acceptance was never proven (`delivery-unknown`) is not a safe target.
+    // Steering it would push a second input onto an unconfirmed one; cancelling it
+    // would guess a stop against an attempt that may not have landed. Report
+    // DELIVERY_UNKNOWN so the caller confirms the original attempt first — never a
+    // silent downgrade to another action (§10).
+    if (turn.status !== "accepted") {
+        return { outcome: "delivery-unknown", code: "DELIVERY_UNKNOWN",
+            detail: `The current Turn's own delivery is ${turn.status}; confirm the original attempt `
+                + "before steering or interrupting. Do not reissue under a new requestId or a different action." };
+    }
+    if (kind === "steer" && turn.nativeTurnId === undefined) {
+        return { outcome: "delivery-unknown", code: "DELIVERY_UNKNOWN",
+            detail: "The Provider has not supplied an exact native Turn id for steering." };
+    }
+    return { outcome: "ready", target: {
+            roleName, agentId: active.agentId, adapterId: active.adapterId,
+            nativeSessionId: active.nativeSessionId,
+            ...(turn.nativeTurnId === undefined ? {} : { nativeTurnId: turn.nativeTurnId }),
+            attemptId: turn.attemptId,
+            authority: { epoch: binding.authority.epoch, owner: "controller",
+                holderId: binding.authority.holderId ?? "controller" }
+        } };
+}
+/**
+ * Resolve a live steer/interrupt against a Task Role's current native Turn.
+ *
+ * @param expectedTarget The Leader's exact expectation for the current Turn,
+ *   as observed (its nativeTurnId, or its attemptId when no native id exists).
+ *   A steer/interrupt that no longer matches is TARGET_CHANGED, never retargeted.
+ */
+export function resolveTaskInputControl(store, taskId, roleName, kind, expectedTarget) {
+    const resolution = resolveInputControl(store.getTaskRoleSessionSet(taskId, roleName), kind, expectedTarget, roleName);
+    // A Task target carries its taskId so the live edge addresses the exact Host.
+    return resolution.outcome === "ready"
+        ? { outcome: "ready", target: { taskId, ...resolution.target } }
+        : resolution;
+}
+/**
+ * Resolve a live steer/interrupt against a Global Role's current native Turn
+ * (decision-3 §6/§9). Identical contract to the Task resolver, reading the
+ * Global Role's own Session set; the resolved target carries no taskId because a
+ * Global Role has no owning Task and never fabricates one.
+ */
+export function resolveGlobalInputControl(store, roleName, kind, expectedTarget) {
+    return resolveInputControl(store.getGlobalRoleSessionSet(roleName), kind, expectedTarget, roleName);
+}