@zq-silk/yui 0.15.9 → 0.15.12

package/dist/commands/executionAuditCommands.js

@@ -7,6 +7,7 @@
  */
 import { usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
+import { formatUsageMetric } from "../runtime/taskUsageMetrics.js";
 import { runExecutionAudit } from "../observability/executionAudit.js";
 export function parseExecutionAuditOptions(args) {
     const options = {};
@@ -246,6 +247,15 @@ export function renderExecutionAudit(report, width = defaultTableWidth()) {
     else {
         lines.push("", ...sectionError("orchestration", report));
     }
+    if (report.usage.status === "ok" && report.usage.data !== undefined) {
+        lines.push("", "Observed usage — Task lifetime, observed sources only (audit time window not applied):");
+        for (const usage of report.usage.data) {
+            lines.push(`  ${usage.taskId}: tokens=${formatUsageMetric(usage.tokens)}; tools=${formatUsageMetric(usage.toolCalls)}; elapsed=${formatUsageMetric(usage.elapsedSeconds, "s")}; native execution sum=${formatUsageMetric(usage.executionSeconds, "s")}`);
+        }
+    }
+    else {
+        lines.push("", ...sectionError("usage", report));
+    }
     if (report.storage.status === "ok" && report.storage.data !== undefined) {
         const storage = report.storage.data;
         lines.push("", `Storage: backend ${storage.backend} · state.json ${formatBytes(storage.stateJsonBytes)} · yui.db ${formatBytes(storage.databaseBytes)}`

package/dist/commands/globalRoleCommands.js

@@ -1,6 +1,12 @@
 import { roleNotFound, usageError } from "../errors/cliError.js";
+import { controlProviderRetry, providerRetryProjection, renderProviderRetry } from "../runtime/providerRetry.js";
+import { settleGlobalRetryInput } from "../message/globalProviderRetry.js";
 import { createRoleSessionSet, recordRoleAgentSession } from "../executor/agentExecutor.js";
 import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
+import { managedGlobalRoleWorkspace } from "../storage/homeLayout.js";
+import { createGlobalRoleMessage, claimGlobalRoleMessageInterruptThen } from "../message/message.js";
+import { resolveGlobalInputControl } from "../message/inputControlResolution.js";
+import { readCommandText } from "./textInput.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { activeRoleSummary, renderRoleDetails } from "../output/rolePresentation.js";
 import { activeRoleAgentBinding, createGlobalRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateGlobalRole } from "../role/role.js";
@@ -10,6 +16,28 @@ import { hasRoleLaunchContextOptions, validateConfiguredRoleSkills } from "./rol
 import { assertLiveRoleSessionAcknowledged, assertRoleRuntimeMutationAllowed, LIVE_SESSION_ACKNOWLEDGEMENT_OPTION } from "./roleRuntimeGuard.js";
 export function runGlobalRoleCommand(args, store, options = {}) {
     const [command, ...rest] = args;
+    if (command === "message" || command === "interrupt" || command === "session" && rest[0] === "retry") {
+        const env = options.env ?? process.env;
+        const target = command === "message" || command === "session" ? rest[1] : rest[0];
+        if (env.YUI_SESSION_SCOPE !== undefined && env.YUI_SESSION_SCOPE !== "global"
+            || env.YUI_SESSION_SCOPE === "global" && env.YUI_ROLE !== "operator"
+                && env.YUI_ROLE !== target) {
+            throw usageError("Global input mutation is outside the exact Session authority.");
+        }
+        if (env.YUI_SESSION_SCOPE === "global") {
+            const caller = store.getGlobalRoleSessionSet(env.YUI_ROLE ?? "");
+            const session = caller?.sessions[caller.activeAgentId];
+            if (session === undefined || session.status !== "active" || env.YUI_AGENT_ID !== session.agentId
+                || env.YUI_ADAPTER_ID !== session.adapterId
+                || (env.CODEX_THREAD_ID ?? env.YUI_NATIVE_SESSION_ID) !== session.nativeSessionId) {
+                throw usageError("Global input mutation requires the current native caller Session.");
+            }
+        }
+        else if (env.YUI_ROLE !== undefined || env.YUI_AGENT_ID !== undefined
+            || env.YUI_NATIVE_SESSION_ID !== undefined) {
+            throw usageError("Incomplete managed identity cannot acquire user authority.");
+        }
+    }
     switch (command) {
         case "add": return addRole(rest, store, options);
         case "list": return listRoles(rest, store);
@@ -21,6 +49,8 @@ export function runGlobalRoleCommand(args, store, options = {}) {
         case "unbind": return unbindRole(rest, store);
         case "enter": return enterRole(rest, store);
         case "session": return roleSession(rest, store, options);
+        case "message": return globalRoleMessage(rest, store, options);
+        case "interrupt": return globalRoleInterrupt(rest, store, options);
         default:
             throw usageError(command === undefined
                 ? "Role command is required."
@@ -32,7 +62,9 @@ function roleContext(args, store, options) {
     const name = roleName(rawName);
     assertNoArguments(rest, "Session context usage: yui session context <role>");
     const environment = options.env ?? process.env;
-    if (environment.YUI_SESSION_SCOPE !== undefined) {
+    // Context reads expose durable input and runtime facts without delivering it.
+    const selfRead = environment.YUI_SESSION_SCOPE !== undefined;
+    if (selfRead) {
         if (environment.YUI_SESSION_SCOPE !== "global" || environment.YUI_ROLE !== name) {
             throw usageError("Managed GlobalRole context is outside the exact Session authority.");
         }
@@ -45,6 +77,19 @@ function roleContext(args, store, options) {
     const effective = resolveEffectiveLaunch({ role, purpose: "execution" });
     const sessions = store.getGlobalRoleSessionSet(name);
     const session = sessions?.sessions[role.activeAgentId];
+    // Only the controlled Endpoint's accepted receipt consumes a queued Message.
+    const queued = store.listGlobalRoleMessages(name).filter((message) => message.delivery === undefined
+        && message.notDelivered === undefined
+        && (message.interruptThen !== undefined || message.inputControl?.action === "queue"));
+    const pendingQueue = queued.map((message) => ({
+        id: message.id,
+        requestId: message.interruptThen?.requestId ?? message.inputControl?.requestId,
+        body: message.body,
+        ...(message.control === undefined ? {} : { control: message.control }),
+        ...(message.deliveryTarget === undefined ? {} : { deliveryTarget: message.deliveryTarget }),
+        ...(message.interruptThen === undefined ? {} : { interruptThen: true }),
+        ...(message.delivery === undefined ? {} : { deliveredAt: message.delivery.deliveredAt })
+    }));
     const context = Object.freeze({
         schemaVersion: 1,
         protocol: "yui-managed-context/v1",
@@ -79,6 +124,12 @@ function roleContext(args, store, options) {
                 ? ["route-request", "inspect-catalog", "answer-user-boundary"]
                 : ["perform-global-role-request"]
         },
+        // Reading pending input is neither delivery nor implementation.
+        pendingMessages: pendingQueue,
+        messages: store.listGlobalRoleMessages(name),
+        nativeTurn: sessions?.providerBinding?.run ?? null,
+        retry: providerRetryProjection(sessions?.providerBinding),
+        interrupts: sessions?.interrupts ?? {},
         sessionManifestPath: environment.YUI_SESSION_MANIFEST,
         cliCommand: "yui"
     });
@@ -92,6 +143,8 @@ function roleContext(args, store, options) {
         `Effective revision: ${role.launchRevision}`,
         `Skills: ${context.profile.skillIds.join(", ") || "none"}`,
         `Authority: ${context.authority.view}; Task implementation: no`,
+        `Pending messages: ${pendingQueue.length === 0 ? "none"
+            : pendingQueue.map((message) => message.id).join(", ")}`,
         ""
     ].join("\n");
 }
@@ -109,9 +162,16 @@ function addRole(args, store, options) {
     const created = store.transaction((tx) => {
         assertRoleRuntimeMutationAllowed(tx, { scope: "global", roleName: name }, "creation");
         const agent = requireAgent(agentId, tx);
-        const workspace = trimmed(parsed.one("--workspace"))
-            ?? tx.getConfig().defaultWorkspace
-            ?? process.cwd();
+        // An explicit --workspace is a user-chosen cwd and keeps its own semantics
+        // (external roots stay external). When none is given, default to a
+        // Home-internal Global Role working directory rather than the external
+        // `defaultWorkspace` or the ambient process.cwd(), so Yui-auto-created
+        // scratch never lands outside the canonical Home.
+        const explicitWorkspace = trimmed(parsed.one("--workspace"));
+        const workspace = explicitWorkspace
+            ?? (options.yuiHome !== undefined
+                ? managedGlobalRoleWorkspace(options.yuiHome)
+                : tx.getConfig().defaultWorkspace ?? process.cwd());
         const binding = patchRoleAgentBinding(createRoleAgentBinding(definition(agent)), parsed);
         const profile = roleProfileFrom(parsed);
         validateConfiguredRoleSkills(options.yuiHome, profile.skills ?? []);
@@ -325,6 +385,28 @@ function enterRole(args, store) {
 }
 function roleSession(args, store, options) {
     const [command, rawName, ...tail] = args;
+    if (command === "retry") {
+        const name = roleName(rawName);
+        const [action = "show", ...extra] = tail;
+        if (extra.length > 0 || !["show", "cancel", "disable", "enable"].includes(action)) {
+            throw usageError("Usage: yui session retry <role> [show|cancel|disable|enable]");
+        }
+        return store.transaction(tx => {
+            requireRole(name, tx);
+            const sessions = tx.getGlobalRoleSessionSet(name);
+            let binding = sessions?.providerBinding ?? null;
+            if (action !== "show") {
+                if (sessions === null || binding === null)
+                    throw usageError("No current Provider Session.");
+                binding = controlProviderRetry(binding, action, Date.now());
+                tx.saveGlobalRoleSessionSet({ ...sessions, providerBinding: binding });
+                settleGlobalRetryInput(tx, name, binding, new Date());
+            }
+            return options.jsonOutput ? JSON.stringify({
+                roleName: name, retry: providerRetryProjection(binding), disabled: binding?.retryDisabled ?? false
+            }) + "\n" : renderProviderRetry(binding) + "\n";
+        });
+    }
     if (command !== "record" && command !== "replace") {
         throw usageError("Session usage: yui session record|replace <role> --native-id <id> [--reason <reason>].");
     }
@@ -404,6 +486,259 @@ function assertSessionProvenance(command, role, nativeSessionId, environment) {
         throw usageError("Native session id does not match CODEX_THREAD_ID.");
     }
 }
+/**
+ * The shared application-layer primitive for a durable Global Role input
+ * (decision-3 §7: CLI and Web/API share one entry, not per-surface fallbacks).
+ * It persists the Global-owned Message with an explicit owner (the Role name)
+ * and a stable requestId, idempotent exactly like a Task input: an exact repeat
+ * of the same requestId returns the original Message, and any different body,
+ * action, or expectedTarget under the same id is a conflicting reuse, never a
+ * silent second input (decision-3 §6). It never fabricates a Task or a native
+ * Turn; it only records intent.
+ */
+export function sendGlobalRoleMessageCommand(store, roleName, body, author, inputControl, now) {
+    if (!body.trim())
+        throw usageError("Message body is required.");
+    const existing = store.listGlobalRoleMessages(roleName).find((entry) => (entry.inputControl ?? entry.interruptThen?.reusedInput)?.requestId === inputControl.requestId);
+    if (existing !== undefined) {
+        const original = existing.inputControl ?? existing.interruptThen?.reusedInput;
+        if (original?.action !== inputControl.action
+            || existing.body !== body
+            || original.expectedTarget !== inputControl.expectedTarget) {
+            throw usageError(`Input requestId ${inputControl.requestId} was already used with different content or target; use a new requestId for a new input.`);
+        }
+        return { message: existing, idempotentReplay: true };
+    }
+    const kind = author.type;
+    let message = createGlobalRoleMessage(store.nextGlobalRoleMessageId(), roleName, body, kind, author, now, { inputControl });
+    const sessions = store.getGlobalRoleSessionSet(roleName);
+    const session = sessions?.sessions[sessions.activeAgentId];
+    if (session !== undefined)
+        message = { ...message,
+            deliveryTarget: { agentId: session.agentId, nativeSessionId: session.nativeSessionId } };
+    store.saveGlobalRoleMessage(message);
+    return { message, idempotentReplay: false };
+}
+/**
+ * `yui role message queue|steer <role> ...` — the durable Global input actions.
+ * `queue` persists and returns queued (delivered at the Role's next legal
+ * execution opportunity by the existing global-role-runtime mailbox, never a new
+ * private queue). `steer` persists then resolves the exact current native Turn
+ * from durable state; on a ready resolution it returns a structured live intent
+ * the CLI performs against the Agent Host with scope "global", and on any
+ * explicit failure it returns the saved Message plus the exact code and never
+ * falls back to interrupt or queue (decision-3 §1/§5).
+ */
+function globalRoleMessage(args, store, options) {
+    const [action, rawName, ...tail] = args;
+    if (action !== "queue" && action !== "steer") {
+        throw usageError("Role message usage: yui role message queue|steer <role> (<body>|--body-file <path|->) --request-id <id> [--expected-target <turn>].");
+    }
+    const usage = action === "queue"
+        ? "Role message queue usage: yui role message queue <role> (<body>|--body-file <path|->) --request-id <id>."
+        : "Role message steer usage: yui role message steer <role> (<body>|--body-file <path|->) --request-id <id> --expected-target <turn>.";
+    const name = roleName(rawName);
+    // A leading positional before the flags is the inline body; the rest are flags.
+    const positionalBody = tail.length > 0 && !tail[0].startsWith("--") ? tail[0] : undefined;
+    const flags = positionalBody === undefined ? tail : tail.slice(1);
+    const parsed = parseOptions(flags, new Map([
+        ["--body-file", false],
+        ["--request-id", false],
+        ...(action === "steer" ? [["--expected-target", false]] : [])
+    ]));
+    const body = readCommandText(positionalBody, parsed.one("--body-file"), "--body", usage);
+    const requestId = required(parsed.one("--request-id"), "--request-id");
+    const expectedTarget = action === "steer"
+        ? required(parsed.one("--expected-target"), "--expected-target")
+        : undefined;
+    const now = new Date();
+    // The durable Global input is authored as an operator input: a Global Role has
+    // no Task Leader, and the operator is the human authority over Global Roles.
+    const environment = options.env ?? process.env;
+    const author = { type: environment.YUI_SESSION_SCOPE === "global"
+            ? environment.YUI_ROLE === "operator" ? "operator" : "agent" : "user" };
+    const persisted = store.transaction((tx) => {
+        requireRole(name, tx);
+        return sendGlobalRoleMessageCommand(tx, name, body, author, { action, requestId, ...(expectedTarget === undefined ? {} : { expectedTarget }) }, now);
+    });
+    if (action === "queue") {
+        const state = persisted.idempotentReplay ? "idempotent-replay" : "queued";
+        return jsonOrText(options, `Queued Global message ${persisted.message.id} to ${name} (${state}).\n`, { roleName: name, message: persisted.message, delivery: { state } });
+    }
+    if (persisted.idempotentReplay) {
+        return jsonOrText(options, `Steer Global message ${persisted.message.id} already recorded (idempotent-replay).\n`, { roleName: name, message: persisted.message, steer: { state: "idempotent-replay" } });
+    }
+    const resolution = resolveGlobalInputControl(store, name, "steer", expectedTarget);
+    if (resolution.outcome !== "ready") {
+        return jsonOrText(options, `Steer Global message ${persisted.message.id} saved but not delivered (${resolution.code}: ${resolution.detail}).\n`, { roleName: name, message: persisted.message,
+            steer: { state: "not-steered", code: resolution.code, detail: resolution.detail } });
+    }
+    store.updateGlobalRoleMessage({ ...persisted.message, control: {
+            requestId, receiptId: `steer:${name}/${persisted.message.id}`,
+            outcome: "pending", observedAt: now.toISOString()
+        } });
+    return {
+        kind: "input-steer",
+        roleName: name,
+        messageId: persisted.message.id,
+        target: resolution.target,
+        receiptId: `steer:${name}/${persisted.message.id}`,
+        text: body,
+        output: `Steering ${name} at Turn ${resolution.target.nativeTurnId ?? resolution.target.attemptId} with message ${persisted.message.id}.\n`
+    };
+}
+/**
+ * `yui role interrupt <role> --expected-target <turn> [--then-message <ref>]` —
+ * a live interrupt of a Global Role's exact current native Turn. A bare
+ * interrupt persists no Message (it is pure control); a `--then-message` names
+ * an already-persisted durable Global Message to deliver once after a proven
+ * terminal — the ordered composition of interrupt and an existing queue, not a
+ * fourth action and not an auto-fallback (decision-3 §4).
+ */
+function globalRoleInterrupt(args, store, options) {
+    const usage = "Role interrupt usage: yui role interrupt <role> --expected-target <turn> [--then-message <global-message-id>] [--request-id <id>].";
+    const [rawName, ...tail] = args;
+    const name = roleName(rawName);
+    const parsed = parseOptions(tail, new Map([
+        ["--expected-target", false],
+        ["--then-message", false],
+        ["--request-id", false]
+    ]));
+    const expectedTarget = required(parsed.one("--expected-target"), "--expected-target");
+    const thenMessageId = trimmed(parsed.one("--then-message"));
+    const requestId = trimmed(parsed.one("--request-id")) ?? `cancel:${encodeURIComponent(expectedTarget)}`;
+    const fingerprint = JSON.stringify({ expectedTarget, thenMessageId });
+    const prior = store.getGlobalRoleSessionSet(name)?.interrupts?.[requestId];
+    if (prior !== undefined) {
+        if (prior.fingerprint !== fingerprint)
+            throw usageError("Interrupt requestId already names another control.");
+        return jsonOrText(options, `Interrupt ${requestId} already recorded; no native control repeated.\n`, { roleName: name, interrupt: prior.receipt ?? { state: "interrupt-unknown" }, idempotentReplay: true });
+    }
+    const resolved = store.transaction((tx) => {
+        requireRole(name, tx);
+        const resolution = resolveGlobalInputControl(tx, name, "interrupt", expectedTarget);
+        if (resolution.outcome !== "ready")
+            return resolution;
+        const sessions = tx.getGlobalRoleSessionSet(name);
+        if (Object.values(sessions.interrupts ?? {}).some(entry => entry.attemptId === resolution.target.attemptId
+            && entry.nativeSessionId === resolution.target.nativeSessionId
+            && !(entry.receipt?.state === "interrupt-unavailable" && entry.receipt.outcome === "rejected"))) {
+            return { outcome: "then-conflict", code: "TARGET_CHANGED",
+                detail: "This exact native Turn already has a recorded cancel request; inspect it instead of repeating the control." };
+        }
+        // decision-3 §4: before the live cancel, register the continuation claim on
+        // the already-persisted durable Global Message in one short transaction, so
+        // the handoff relationship, its target Turn, and its stable requestId are
+        // durable independent of the cancel outcome. An explicit then-Message must be
+        // an already-persisted durable Global Message owned by this exact Role; it is
+        // never created here and never a Task record (decision-3 §4/§9).
+        if (thenMessageId !== undefined) {
+            const claim = registerGlobalInterruptThen(tx, name, thenMessageId, resolution.target.attemptId, resolution.target.nativeTurnId, requestId, resolution.target);
+            if (claim !== "claimed")
+                return { outcome: "then-conflict", ...claim };
+        }
+        tx.saveGlobalRoleSessionSet({ ...sessions, interrupts: { ...sessions.interrupts,
+                [requestId]: { fingerprint, attemptId: resolution.target.attemptId,
+                    nativeSessionId: resolution.target.nativeSessionId,
+                    receiptId: `interrupt:${name}/${requestId}` }
+            } });
+        return resolution;
+    });
+    if (resolved.outcome === "then-conflict") {
+        return jsonOrText(options, `Interrupt not delivered (${resolved.code}: ${resolved.detail}).\n`, { roleName: name, interrupt: { state: "not-interrupted", code: resolved.code, detail: resolved.detail } });
+    }
+    if (resolved.outcome !== "ready") {
+        return jsonOrText(options, `Interrupt not delivered (${resolved.code}: ${resolved.detail}).\n`, { roleName: name, interrupt: { state: "not-interrupted", code: resolved.code, detail: resolved.detail } });
+    }
+    return {
+        kind: "input-interrupt",
+        roleName: name,
+        target: resolved.target,
+        receiptId: `interrupt:${name}/${requestId}`,
+        ...(thenMessageId === undefined ? {} : { thenMessageId }),
+        output: `Interrupting ${name} at Turn ${resolved.target.nativeTurnId ?? resolved.target.attemptId}`
+            + `${thenMessageId === undefined ? "" : `, then delivering ${thenMessageId} once after a proven terminal`}.\n`
+    };
+}
+/**
+ * Bind a saved durable Global Message as the single interrupt-then continuation
+ * of an exact interrupted native Turn (decision-3 §4). The Global twin of the
+ * Task `registerInterruptThen`: a Global Role has no AgentRun, so the
+ * target is proven by the exact native Turn's attemptId under the Role's own
+ * writer fence, never by a fabricated Task Run. Idempotent per interrupt
+ * requestId; only one continuation may claim a given target Turn; a Message that
+ * was already delivered or already claims another target is refused, never
+ * silently dropped or duplicated.
+ */
+function registerGlobalInterruptThen(store, roleName, thenMessageId, targetAttemptId, targetNativeTurnId, requestId, target) {
+    const message = store.listGlobalRoleMessages(roleName).find((entry) => entry.id === thenMessageId);
+    if (message === undefined) {
+        throw usageError(`Then-Message ${thenMessageId} is not a durable Global Message owned by ${roleName}.`);
+    }
+    if (message.notDelivered !== undefined) {
+        return { code: "TARGET_CHANGED", detail: `The saved input is already settled not-delivered (${message.notDelivered.reason}).` };
+    }
+    if (message.control !== undefined && message.control.outcome !== "rejected") {
+        return { code: "TARGET_CHANGED", detail: "The saved input is already accepted or its delivery remains unconfirmed." };
+    }
+    if (message.deliveryTarget !== undefined
+        && (message.deliveryTarget.nativeSessionId !== target.nativeSessionId
+            || message.deliveryTarget.agentId !== target.agentId)) {
+        return { code: "TARGET_CHANGED", detail: "The saved input belongs to another native Session." };
+    }
+    // A synthesized fallback id is an opaque idempotency key (compared only for
+    // equality, never parsed), so it must satisfy the same safe-identity rule as a
+    // caller-supplied requestId: no path separators. Use `:` as the field joiner —
+    // the receiptId carries the `/`-shaped human receipt, this key stays slash-free.
+    const claimRequestId = requestId ?? `interrupt:${roleName}:${encodeURIComponent(targetAttemptId)}`;
+    // Idempotent per interrupt requestId: an exact repeat of the same claim is a
+    // no-op that still authorizes the live cancel.
+    if (message.interruptThen !== undefined) {
+        const claim = message.interruptThen;
+        const prior = store.getGlobalRoleSessionSet(roleName)?.interrupts?.[claim.requestId];
+        const canReferenceClaim = claim.requestId === claimRequestId
+            || (prior?.receipt?.state === "interrupt-unavailable" && prior.receipt.outcome === "rejected");
+        if (canReferenceClaim && message.delivery === undefined && message.notDelivered === undefined
+            && claim.targetAttemptId === targetAttemptId
+            && claim.targetAgentId === target.agentId && claim.targetNativeSessionId === target.nativeSessionId
+            && claim.targetAuthorityEpoch === target.authority.epoch
+            && claim.targetAuthorityHolderId === target.authority.holderId)
+            return "claimed";
+        return { code: "TARGET_CHANGED",
+            detail: `Message ${thenMessageId} already claims a continuation of Turn ${message.interruptThen.targetAttemptId}.` };
+    }
+    // A Message that already delivered is a settled fact, not a fresh input to
+    // reuse; reusing it would replay a consumed queue entry.
+    if (message.delivery !== undefined) {
+        return { code: "TARGET_CHANGED",
+            detail: `Message ${thenMessageId} was already delivered at ${message.delivery.deliveredAt}.` };
+    }
+    // Only one continuation may claim a given target Turn.
+    const existing = store.listGlobalRoleMessages(roleName).find((entry) => entry.interruptThen?.targetAttemptId === targetAttemptId && entry.id !== message.id);
+    if (existing !== undefined) {
+        return { code: "TARGET_CHANGED",
+            detail: `Turn ${targetAttemptId} is already the terminal target of Message ${existing.id}.` };
+    }
+    store.updateGlobalRoleMessage(claimGlobalRoleMessageInterruptThen(message, {
+        requestId: claimRequestId, targetAttemptId,
+        targetNativeSessionId: target.nativeSessionId, targetAgentId: target.agentId,
+        targetAuthorityEpoch: target.authority.epoch,
+        targetAuthorityHolderId: target.authority.holderId,
+        ...(targetNativeTurnId === undefined ? {} : { targetNativeTurnId })
+    }));
+    return "claimed";
+}
+/** Emit a plain string or, under --json, a JSON envelope, matching the Global
+ * Role command surface's existing string/JSON split. */
+function jsonOrText(options, text, data) {
+    const record = data;
+    const failure = record.steer?.code === undefined ? record.interrupt : record.steer;
+    if (failure?.code !== undefined)
+        options.onInputFailure?.({
+            code: failure.code, detail: failure.detail ?? failure.code, data
+        });
+    return options.jsonOutput === true ? JSON.stringify(data) : text;
+}
 function parseOptions(args, specs) {
     const values = new Map();
     const seen = new Set();

package/dist/commands/projectCommands.js

@@ -1,12 +1,13 @@
 import { existsSync } from "node:fs";
 import { readdir, rename, rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { usageError } from "../errors/cliError.js";
+import { CliError, usageError } from "../errors/cliError.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { healCheckoutSwap, restoreCheckoutSwap, swapManagedCheckout } from "../repository/checkoutSwap.js";
-import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
+import { GitWorkspaceRefreshError, NodeGitWorkspace } from "../repository/gitWorkspace.js";
 import { acquireProjectMaintenanceLock } from "../repository/projectMaintenanceLock.js";
 import { addProjectKnowledge, addKnowledgeProposal, assertProjectActive, decideKnowledgeProposal, createProject, findKnowledgeProposal, findKnowledgeProposalByFingerprint, knowledgeEvidenceDigest, knowledgeProposalFingerprint, managedProjectPath, planKnowledgeAcceptance, retireProject, retireProjectKnowledge, resolveProject, updateProjectKnowledge, updateProjectMetadata, validateProject, validateProjectName } from "../repository/project.js";
+import { managedWorkspacesRoot } from "../storage/homeLayout.js";
 import { projectActor } from "./taskActor.js";
 export async function runProjectCommand(args, store, options = {}) {
     const [command, ...rest] = args;
@@ -21,10 +22,14 @@ export async function runProjectCommand(args, store, options = {}) {
     }
     if (command === "refresh") {
         const refreshed = await refreshProject(rest, store, options);
+        const head = refreshed.changed
+            ? `Refreshed project ${refreshed.project.id}: ${refreshed.fromCommit} -> ${refreshed.toCommit}`
+            : `Project ${refreshed.project.id} HEAD is already current at ${refreshed.toCommit}`;
+        const tracking = refreshed.tracking;
         return {
-            output: refreshed.changed
-                ? `Refreshed project ${refreshed.project.id}: ${refreshed.fromCommit} -> ${refreshed.toCommit}\n`
-                : `Project ${refreshed.project.id} is already current at ${refreshed.toCommit}\n`,
+            output: `${head}\n` + (tracking.status === "unmanaged"
+                ? `Tracking unmanaged: ${tracking.reason}\n`
+                : `Tracking ${tracking.status}: ${tracking.ref} at ${tracking.toCommit}\n`),
             data: refreshed
         };
     }
@@ -100,14 +105,23 @@ async function refreshProject(args, store, options) {
     // RFC Phase 1: hold the per-Project maintenance fence for the whole refresh
     // so Task workspace preparation and other maintenance cannot interleave
     // with the canonical branch/working-tree move.
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
+        const current = requireUnchangedMaintenanceProject(store, project, "refresh");
         const refreshed = await (options.git ?? new NodeGitWorkspace()).refresh({
-            repositoryPath: project.path,
-            remoteUrl: project.remoteUrl,
-            stableRef: project.stableBranch
+            repositoryPath: current.path,
+            remoteUrl: current.remoteUrl,
+            stableRef: current.stableBranch
         });
-        return { project, ...refreshed };
+        return { project: current, ...refreshed };
+    }
+    catch (error) {
+        if (error instanceof GitWorkspaceRefreshError) {
+            throw new CliError("RUNTIME_ERROR", error.message, undefined, {
+                projectId: project.id, refresh: error.result
+            });
+        }
+        throw error;
     }
     finally {
         releaseMaintenance();
@@ -130,8 +144,9 @@ async function diagnoseProject(args, store, options) {
         };
     }
     const git = options.git ?? new NodeGitWorkspace();
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
+        requireUnchangedMaintenanceProject(store, project, "diagnose");
         const current = await git.inspect(project.path, "HEAD");
         const remote = await git.resolveRemoteBaseline({
             repositoryPath: project.path,
@@ -235,7 +250,7 @@ async function cloneProject(args, store, options) {
         if (dirname(destination) !== workspaceRoot) {
             throw usageError("Project clone destination must be directly inside the configured workspace.");
         }
-        assertOutsideManagedWorktrees(destination, workspace);
+        assertOutsideManagedWorktrees(destination, store.rootDirectory());
         ownership = "external";
     }
     else {
@@ -306,13 +321,14 @@ async function migrateProject(args, store, options) {
     // Migration rewrites the Project's Git repository: hold the per-Project
     // maintenance fence so no rebuild/archive/cleanup (or a second migrate)
     // interleaves, and the Controller defers worktree preparation meanwhile.
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         // Re-read the Project under the fence. A concurrent migration may have
         // completed and switched the catalog to the Home-managed repo since the
         // record was resolved above; the stale snapshot must not drive any Git
         // effect (in particular it must not delete the now-canonical repo).
         const current = requireProject(store, project.id);
+        assertProjectActive(current, "migrate");
         if (current.ownership === "managed") {
             throw usageError(`Project is already Home-managed: ${project.id}.`);
         }
@@ -461,10 +477,10 @@ async function assertRemoteBranchesVerified(git, repositoryPath, remoteUrl, bran
 async function addProject(args, store, options) {
     const usage = "Project add usage: yui project add <name> <path> [--alias <name> ...] [--remote <url>] [--stable <ref>] [--development <ref>].";
     const parsed = parseAddArguments(args, usage);
-    assertOutsideManagedWorktrees(parsed.path, store.getConfig().defaultWorkspace);
+    assertOutsideManagedWorktrees(parsed.path, store.rootDirectory());
     const git = options.git ?? new NodeGitWorkspace();
     const head = await git.inspect(parsed.path, "HEAD");
-    assertOutsideManagedWorktrees(head.root, store.getConfig().defaultWorkspace);
+    assertOutsideManagedWorktrees(head.root, store.rootDirectory());
     if (!await git.isClean(head.root)) {
         throw usageError("Project checkout must be clean before it can be registered.");
     }
@@ -587,7 +603,7 @@ async function resetProject(args, store, options) {
         throw usageError(`Project reset requires matching stable and development branches: ${project.id}.`);
     }
     const git = options.git ?? new NodeGitWorkspace();
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         // Re-read under the fence so a concurrent catalog change can never drive
         // a destructive Git effect from a stale snapshot.
@@ -712,7 +728,7 @@ async function replaceProject(args, store, options) {
             + "Re-run with --discard-local to acknowledge that the checkout and any uncommitted state will be discarded.");
     }
     const git = options.git ?? new NodeGitWorkspace();
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
         const current = requireProject(store, project.id);
         assertProjectActive(current, "replace");
@@ -921,8 +937,9 @@ async function deleteProjectCommand(args, store, options) {
     // every failure restores it, so the catalog never loses its recoverable
     // entry while a live checkout (or its failure) is still in play.
     const tombstone = join(store.rootDirectory(), "projects", `.delete-${project.id}`);
-    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    const releaseMaintenance = await acquireProjectMaintenanceLock(store.rootDirectory(), project.id, { signal: options.signal });
     try {
+        requireUnchangedMaintenanceProject(store, project, "delete");
         // Heal a crashed earlier attempt before the prechecks turn.
         await healCheckoutSwap({ currentPath: project.path, backupPath: tombstone });
         if (existsSync(project.path)) {
@@ -1097,10 +1114,8 @@ function assertProjectAvailable(store, project, exceptId) {
         }
     }
 }
-function assertOutsideManagedWorktrees(path, workspace) {
-    if (workspace === undefined)
-        return;
-    const managedRoot = join(resolve(workspace), "worktree");
+function assertOutsideManagedWorktrees(path, home) {
+    const managedRoot = managedWorkspacesRoot(home);
     const candidate = resolve(path);
     const fromManagedRoot = relative(managedRoot, candidate);
     const toManagedRoot = relative(candidate, managedRoot);
@@ -1290,6 +1305,19 @@ function projectKnowledge(args, store, options) {
         ? "Project knowledge command is required."
         : `Unknown command: project knowledge ${command}`);
 }
+/** Waiting yields to catalog writers too; never apply stale Git/lifecycle inputs. */
+function requireUnchangedMaintenanceProject(store, expected, action) {
+    const current = requireProject(store, expected.id);
+    if (current.path !== expected.path
+        || current.remoteUrl !== expected.remoteUrl
+        || current.stableBranch !== expected.stableBranch
+        || current.developmentBranch !== expected.developmentBranch
+        || current.ownership !== expected.ownership
+        || current.status !== expected.status) {
+        throw new Error(`Project changed while waiting to ${action}: ${expected.id}; read current state before retrying.`);
+    }
+    return current;
+}
 function requireProject(store, reference) {
     const project = resolveProject(store.listProjects(), reference);
     if (project === null)

package/dist/commands/releaseCommands.js

@@ -373,6 +373,24 @@ export function createReleaseActivatePorts(overrides = {}) {
             if (failed.length > 0) {
                 throw new Error(`Release preflight storage compatibility checks failed: ${failed.join(", ")}.`);
             }
+            // Doctor proves the target's storage, not the pinned code in existing
+            // Hosts. Ask the target's upgrade boundary for its independent Host
+            // protocol proof as well; release activation itself still never migrates.
+            const hostCheck = spawnSync(process.execPath, [cli, "--json", "upgrade", "--update-preflight"], {
+                env: { ...process.env, YUI_HOME: home, NO_COLOR: "1" },
+                encoding: "utf8", timeout: 60_000
+            });
+            let preflight;
+            try {
+                preflight = JSON.parse(hostCheck.stdout).data;
+            }
+            catch {
+                throw new Error(`Release Host preflight produced no JSON: ${hostCheck.stderr.trim()}`);
+            }
+            if (hostCheck.status !== 0 || preflight?.outcome !== "update-preflight"
+                || preflight.status !== "already-current") {
+                throw new Error(`Release Host compatibility preflight failed: ${preflight?.message ?? preflight?.status ?? "unknown"}. ${preflight?.action ?? ""}`);
+            }
         }),
         killOwnedProcess: overrides.killOwnedProcess ?? ((owner) => {
             if (readLinuxProcessStartIdentity(owner.pid) !== owner.processStartIdentity)