@zq-silk/yui 0.6.13 → 0.6.14

package/dist/scheduler/leaderWakeupProcessor.js

@@ -3,9 +3,10 @@ import { markYuiRunInput } from "../run/runIdentity.js";
 import { taskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { formatAgentRunReceiptId } from "../task/taskRecordReference.js";
 import { effectiveLaunchSnapshotsCompatible, effectiveLaunchSnapshotsCompatibleForTaskMain } from "../executor/effectiveLaunch.js";
-import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
+import { hasRuntimeLifecycleWork, RuntimeLifecycleBusyError, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 import { recordLeaderFailure } from "./leaderFailure.js";
 import { createLeaderRecoveryNotification } from "./operatorNotification.js";
+import { evaluateSessionContextBudget } from "../context/sessionContextBudget.js";
 import { isSchedulerTaskWorkspaceReady } from "./ports.js";
 import { RuntimeLaunchError } from "../runtime/ports.js";
 export async function processLeaderWakeups(store, delivery, now, selection) {
@@ -49,8 +50,22 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
             results.push({ taskId: task.id, status: "skipped", reason: "busy" });
             continue;
         }
+        // Single-flight: a Role runtime lifecycle lane that already holds a
+        // launch reservation or cleanup obligation must not be entered by a
+        // second wake. The wake stays durable (pendingWakeup is not consumed) and
+        // is retried after the lane settles; the suppression is recorded for the
+        // audit instead of manufacturing a failed Run.
+        if (hasRuntimeLifecycleWork(store.getWorkMailbox(runtimeLifecycleTarget({
+            scope: "task",
+            taskId: task.id,
+            roleName: role.name
+        })))) {
+            store.recordWakeSuppression?.(task.id, "lifecycle-busy", now);
+            results.push({ taskId: task.id, status: "skipped", reason: "recovery-blocked" });
+            continue;
+        }
         const reopening = wakeup.reasons.includes("task-reopened");
-        const existingSession = store.getRoleSession(task.id, role.name, reopening ? undefined : role.effective.agentId);
+        let existingSession = store.getRoleSession(task.id, role.name, reopening ? undefined : role.effective.agentId);
         let effectiveSession = existingSession;
         let claimed = false;
         let deliveryAttempted = false;
@@ -107,9 +122,51 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                 && existingSession.status !== "stopped" && existingSession.status !== "broken") {
                 throw new Error(`Leader Session is incompatible with desired effective launch: ${task.id}/${role.name}.`);
             }
+            // Issue 04: a native Session generation whose observed per-request
+            // input peak crossed the hard context budget is retired before dispatch
+            // so the wake starts a fresh generation instead of waiting for
+            // provider-side auto-compaction. Durable Task records are the checkpoint;
+            // the bounded snapshot below re-establishes working context.
+            let contextBudgetAdvisory;
+            if (hasNativeSession(existingSession)
+                && compatibleSession
+                && existingSession.status !== "stopped"
+                && existingSession.status !== "broken"
+                && typeof store.listEvents === "function"
+                && typeof store.getContextBudget === "function"
+                && typeof store.rolloverTaskRoleSessionForContextBudget === "function") {
+                const budget = evaluateSessionContextBudget(store.listEvents(task.id), {
+                    taskId: task.id,
+                    roleName: role.name,
+                    ...(existingSession.nativeSessionId === undefined
+                        ? {}
+                        : { nativeSessionId: existingSession.nativeSessionId }),
+                    ...(existingSession.launchId === undefined
+                        ? {}
+                        : { launchId: existingSession.launchId })
+                }, store.getContextBudget());
+                if (budget.state === "hard") {
+                    const rollover = store.rolloverTaskRoleSessionForContextBudget({
+                        taskId: task.id,
+                        roleName: role.name,
+                        peakTokens: budget.peakTokens,
+                        hardTokens: budget.budget.hardTokens,
+                        now
+                    });
+                    if (rollover !== null) {
+                        existingSession = null;
+                        effectiveSession = null;
+                        contextBudgetAdvisory = `Previous Session generation ${rollover.retiredNativeSessionId ?? "unknown"} was retired at the hard context budget (peak ${budget.peakTokens} >= ${budget.budget.hardTokens} tokens). This wake starts a fresh generation; durable Task records preserve all state.`;
+                    }
+                }
+                else if (budget.state === "soft") {
+                    contextBudgetAdvisory = `Session context budget advisory: observed per-request input peak ${budget.peakTokens} tokens crossed the soft threshold (${budget.budget.softTokens}). Durable Yui records are the checkpoint; a fresh generation starts automatically at the hard threshold (${budget.budget.hardTokens}).`;
+                }
+            }
             const mode = hasNativeSession(existingSession) && compatibleSession ? "resume" : "new";
             const runId = store.peekNextAgentRunId(task.id);
-            const input = markYuiRunInput(leaderWakeupInput(task.id, runId, wakeup.reasons, task.projectBindings), runId, taskRoleSessionTitle(task, role.name));
+            const wakeEnvelope = resolveLeaderWakeEnvelope(store, task.id);
+            const input = markYuiRunInput(leaderWakeupInput(task.id, runId, wakeEnvelope, contextBudgetAdvisory), runId, taskRoleSessionTitle(task, role.name));
             run = createAgentRun(runId, task.id, role.name, mode, input, now, {
                 ...(role.managedWorkspace === undefined
                     ? {}
@@ -126,6 +183,10 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
                 // durable, retryable recovery obligation before any provider call.
                 session: reopenIdentityDrift ? null : existingSession,
                 wakeup,
+                ...(wakeEnvelope === null ? {} : {
+                    wakeId: wakeEnvelope.wakeId,
+                    wakeFromCursor: wakeEnvelope.fromCursor
+                }),
                 now
             });
             if (claim !== "claimed") {
@@ -266,6 +327,26 @@ export async function processLeaderWakeups(store, delivery, now, selection) {
             const detail = error instanceof Error ? error.message : String(error);
             const message = `Leader dispatch failed: ${detail}`;
             if (claimed && run !== null) {
+                // Scheduler single-flight backpressure: the Role runtime lifecycle
+                // lane was busy when the launch was reserved. The claimed Run stays
+                // active-unpushed; the active-Run delivery path retries it after the
+                // lane settles. This is contention before any semantic launch, not a
+                // Run failure and not grounds for a Leader failure record.
+                if (error instanceof RuntimeLifecycleBusyError) {
+                    delivery.forgetPrepared?.({
+                        taskId: task.id,
+                        roleName: role.name,
+                        runId: run.id
+                    });
+                    results.push({
+                        taskId: task.id,
+                        runId: run.id,
+                        status: "skipped",
+                        reason: "not-ready",
+                        error: message
+                    });
+                    continue;
+                }
                 // A finite managed provider from the preceding Run may still be
                 // exiting after its durable yield. Keep this newly-claimed Run as the
                 // sole owner of the Role mailbox; active-Run delivery will retry it
@@ -396,22 +477,31 @@ function hasNativeSession(session) {
         typeof session.nativeSessionId === "string" &&
         session.nativeSessionId.trim().length > 0;
 }
-function leaderWakeupInput(taskId, runId, reasons, projectBindings) {
+/**
+ * Issue 04 (long-term design): resolves the minimal wake envelope for a
+ * Leader wake. The envelope carries only the aggregated reason tags, the
+ * delta window, and read pointers; the Agent reads delta content on demand
+ * with `yui task wake show`. Returns null when the adapter lacks the
+ * projection, so the wake falls back to the full `yui task context`
+ * instruction.
+ */
+function resolveLeaderWakeEnvelope(store, taskId) {
+    if (typeof store.getTaskWakeEnvelope !== "function")
+        return null;
+    return store.getTaskWakeEnvelope(taskId);
+}
+function leaderWakeupInput(taskId, runId, wakeEnvelope, contextBudgetAdvisory) {
     const lines = [
         "Follow the injected yui-leader Skill for this Yui wakeup.",
         `Current Leader Run: ${runId}.`,
         `For every Leader decision, milestone, or Work Item lifecycle command that is meaningful progress, carry this exact current-turn assertion on that command: YUI_LEADER_ACTION_RUN_ID=${runId} YUI_LEADER_ACTION_RECEIPT_ID=${formatAgentRunReceiptId(taskId, runId)}. The native Session environment may retain an older YUI_RUN_ID/launch; never copy those values, and never reuse this assertion after the turn changes.`,
-        `Yui wakeup reasons: ${reasons.join(", ")}.`,
-        `Read the authoritative context with yui task context ${taskId}.`,
-        "Keep the context layers separate: Yui Core owns durable identity, lifecycle, access, workspace, and exact-yield safety; the generic role Skill owns portable collaboration behavior; Project Policy/Knowledge owns project-specific build, test, migration, release, and review rules; the Task Contract owns this Task's objective, scope, acceptance, and evidence.",
-        "For role-run-stalled or runtime-health attention, diagnose from the exact Run/Event/Session and related WorkItem/Review/Integration records. Preserve the current fence and write a Task Message only for a new root cause, impact, recovery action, acceptance decision, or user-relevant conclusion; an unchanged healthy wait is zero Message.",
-        projectBindings.length === 0
-            ? "This Task has no bound Project Policy; do not invent repository-specific rules."
-            : `Project Policy references: ${projectBindings.map((binding) => `${binding.directory} (${binding.projectId})`).join(", ")}. Read each with yui project show <project>, then yui project knowledge list <project> and yui project knowledge show <project> <knowledge>.`,
-        "Use narrower Task message, WorkItem, decision, milestone, and input commands only when a specific record needs closer inspection.",
-        `When the requested outcome is finished and there are no active Worker Runs or unresolved inputs, complete the Task with yui task complete ${taskId} --summary-file - and a quoted heredoc containing the final outcome and evidence.`,
-        "Provider-native subagents remain inside this Leader AgentRun. Yui observes their structured lifecycle and keeps the Run active across intermediate provider Turn boundaries while children remain active; let the provider deliver completion notifications and continue synthesis without polling or yielding merely for that native wait.",
-        `A Provider Turn ending does not end this Yui Run. Leave the Run active when later native-subagent results, managed Role results, reviewer results, or user corrections still belong to the same objective; Yui will aggregate those durable events and resume this Session with another Turn. Use yui task run yield ${runId} --summary-file - only for a deliberate Yui-level handoff that should close this Run rather than for ordinary waiting. If used, the yield command must be the final tool action: after it succeeds, stop immediately.`
+        ...(contextBudgetAdvisory === undefined ? [] : [contextBudgetAdvisory]),
+        ...(wakeEnvelope === null
+            ? [`Read the authoritative context with yui task context ${taskId}.`]
+            : [
+                "Wake envelope (Issue 04):",
+                wakeEnvelope.text
+            ]),
     ];
     return lines.join("\n");
 }

package/dist/scheduler/roleRunLiveness.js

@@ -1,6 +1,7 @@
 import { selectedSchedulerRoles, selectedActiveSchedulerTasks } from "./ports.js";
 import { formatTaskRecordReference } from "../task/taskRecordReference.js";
 import { queueLeaderWakeup } from "./wakeupQueue.js";
+import { wakeReason } from "./wakeReason.js";
 import { currentRoleRunProgressAt, DEFAULT_WORKFLOW_STALL_CANDIDATE_AGE_MS } from "./roleRunStall.js";
 export const EXITED_ROLE_RUN_SUMMARY = "The role's tmux session exited before the run yielded.";
 /**
@@ -109,7 +110,7 @@ export async function reconcileExitedRoleRuns(store, delivery, now, selection, e
         // adapter's atomic failure+wake transition. Production returns
         // "failed" and already enqueued this wake in the same transaction.
         if (persisted === undefined && task.status === "active") {
-            queueLeaderWakeup(store, task.id, role.name === "leader" ? "leader-run-failed" : "role-run-failed", now);
+            queueLeaderWakeup(store, task.id, wakeReason(role.name === "leader" ? "leader-run-failed" : "role-run-failed"), now);
         }
     }
     return failed;

package/dist/scheduler/roleRunStall.js

@@ -1,13 +1,14 @@
 import { selectedSchedulerRoles, selectedActiveSchedulerTasks } from "./ports.js";
 import { nextPendingBatch } from "../coordination/workMailbox.js";
+import { RUNTIME_DIAGNOSTIC_AFTER_MS, SEMANTIC_STALL_WINDOW_MS } from "../runtime/runtimeHealthPolicy.js";
 /**
  * Default window of no durable progress before a live-but-idle Run becomes a
  * traceable needs-attention signal. It is deliberately long: a healthy Run that
  * is simply slow keeps its structured checkpoint fresh and never crosses it.
  */
-export const DEFAULT_STALL_WINDOW_MS = 30 * 60_000;
+export const DEFAULT_STALL_WINDOW_MS = SEMANTIC_STALL_WINDOW_MS;
 /** Cheap workflow-stall candidate filter; the real threshold remains 30m. */
-export const DEFAULT_WORKFLOW_STALL_CANDIDATE_AGE_MS = 10 * 60_000;
+export const DEFAULT_WORKFLOW_STALL_CANDIDATE_AGE_MS = RUNTIME_DIAGNOSTIC_AFTER_MS;
 export const RUN_PROGRESS_EVENT = "run.progress";
 export const RUN_STALLED_EVENT = "run.stalled";
 export const RUN_RECOVERED_EVENT = "run.recovered";

package/dist/scheduler/taskWake.js

@@ -0,0 +1,72 @@
+import { requireIdentity, requirePositiveInteger, requireText, requireTimestamp } from "../domain/validation.js";
+import { TASK_RECORD_ID_PREFIXES } from "../task/taskRecordReference.js";
+export const CURRENT_TASK_WAKE_SCHEMA_VERSION = 1;
+export function createTaskWake(input) {
+    const wake = {
+        schemaVersion: CURRENT_TASK_WAKE_SCHEMA_VERSION,
+        id: requireIdentity(input.id, "Task wake id"),
+        taskId: requireIdentity(input.taskId, "Task id"),
+        seq: wakeSequence(input.id),
+        reasons: Object.freeze(input.reasons.map((reason) => requireText(reason, "Wake reason"))),
+        fromCursor: requireTimestamp(input.fromCursor, "Wake fromCursor"),
+        toCursor: requireTimestamp(input.toCursor, "Wake toCursor"),
+        status: "dispatched",
+        runId: requireIdentity(input.runId, "Wake run id"),
+        createdAt: input.now.toISOString()
+    };
+    validateTaskWake(wake);
+    return wake;
+}
+export function validateTaskWake(wake) {
+    if (wake.schemaVersion !== CURRENT_TASK_WAKE_SCHEMA_VERSION) {
+        throw new Error(`Task wake ${wake.id} must use schemaVersion ${CURRENT_TASK_WAKE_SCHEMA_VERSION}.`);
+    }
+    if (wake.seq !== wakeSequence(wake.id)) {
+        throw new Error(`Task wake id/seq mismatch: ${wake.id} vs ${wake.seq}.`);
+    }
+    if (wake.reasons.length === 0) {
+        throw new Error(`Task wake ${wake.id} must carry at least one reason.`);
+    }
+    if (Date.parse(wake.fromCursor) > Date.parse(wake.toCursor)) {
+        throw new Error(`Task wake ${wake.id} cursor window is inverted.`);
+    }
+    if (wake.status !== "dispatched" && wake.status !== "consumed") {
+        throw new Error(`Task wake ${wake.id} has invalid status: ${String(wake.status)}.`);
+    }
+    if (wake.status === "consumed" && wake.consumedAt === undefined) {
+        throw new Error(`Task wake ${wake.id} is consumed without consumedAt.`);
+    }
+    if (wake.status === "dispatched" && wake.consumedAt !== undefined) {
+        throw new Error(`Task wake ${wake.id} is dispatched but carries consumedAt.`);
+    }
+}
+export function markTaskWakeConsumed(wake, now) {
+    if (wake.status === "consumed")
+        return wake;
+    return Object.freeze({ ...wake, status: "consumed", consumedAt: now.toISOString() });
+}
+/** Latest wake by sequence, or null when the ledger is empty. */
+export function latestTaskWake(wakes) {
+    let latest = null;
+    for (const wake of wakes) {
+        if (latest === null || wake.seq > latest.seq)
+            latest = wake;
+    }
+    return latest;
+}
+/**
+ * The delta lower bound for a Task's first wake: the last Leader Run's
+ * creation time, preserving the pre-ledger watermark semantics. When no
+ * Leader Run exists, the Task's own creation time bounds the window.
+ */
+export function fallbackWakeCursor(input) {
+    return input.leaderRunCreatedAt ?? input.taskCreatedAt;
+}
+function wakeSequence(id) {
+    const prefix = `${TASK_RECORD_ID_PREFIXES.taskWake}-`;
+    if (!id.startsWith(prefix)) {
+        throw new Error(`Task wake id is invalid: ${id}.`);
+    }
+    const seq = Number(id.slice(prefix.length));
+    return requirePositiveInteger(seq, "Task wake seq");
+}

package/dist/scheduler/wakeReason.js

@@ -0,0 +1,64 @@
+/**
+ * Canonical taxonomy for Leader wake reasons.
+ *
+ * The leader-role WorkMailbox pending batch is the durable aggregation bucket;
+ * it stores reason tags as strings. This module is the single taxonomy that
+ * producers use to build those tags and that the wake envelope uses to render
+ * them together with their record references. The mailbox stays a generic
+ * queue — the wake layer owns the meaning of its tags.
+ *
+ * Tag wire format: `<kind>` or `<kind>:<ref>`. The ref is an exact record
+ * identifier (InputRequest id, AgentRun id, ...) or, for `force-wake`, the
+ * operator-supplied text. Unknown kinds parse losslessly so a newer producer
+ * can never wedge an older reader.
+ */
+export const WAKE_REASON_KINDS = Object.freeze([
+    "role-result",
+    "task-orphaned",
+    "input-timeout",
+    "role-run-stalled",
+    "review-failed",
+    "task-reopened",
+    "leader-run-failed",
+    "role-run-failed",
+    "job-finished",
+    "force-wake"
+]);
+const IMMEDIATE_KINDS = new Set([
+    "task-reopened",
+    "leader-run-failed",
+    "role-run-failed"
+]);
+export function wakeReason(kind, ref) {
+    if (ref === undefined)
+        return kind;
+    const normalized = ref.trim();
+    if (normalized.length === 0)
+        throw new Error(`Wake reason ref is required: ${kind}.`);
+    if (normalized.includes(":")) {
+        throw new Error(`Wake reason ref must not contain ':': ${normalized}.`);
+    }
+    return `${kind}:${normalized}`;
+}
+export function parseWakeReason(tag) {
+    const normalized = tag.trim();
+    if (normalized.length === 0)
+        throw new Error("Wake reason tag is required.");
+    const separator = normalized.indexOf(":");
+    const kind = separator < 0 ? normalized : normalized.slice(0, separator);
+    const ref = separator < 0 ? undefined : normalized.slice(separator + 1);
+    return {
+        kind,
+        ...(ref === undefined || ref.length === 0 ? {} : { ref }),
+        immediate: IMMEDIATE_KINDS.has(kind)
+    };
+}
+/** One-line rendering for the wake envelope: `kind (ref)` or `kind`. */
+export function renderWakeReason(tag) {
+    const reason = parseWakeReason(tag);
+    return reason.ref === undefined ? reason.kind : `${reason.kind} (${reason.ref})`;
+}
+/** True when any aggregated reason demands prompt dispatch. */
+export function hasImmediateWakeReason(tags) {
+    return tags.some((tag) => parseWakeReason(tag).immediate);
+}

package/dist/scheduler/wakeupQueue.js

@@ -1,4 +1,5 @@
 import { mergePendingWakeup } from "./pendingWakeup.js";
+import { wakeReason } from "./wakeReason.js";
 export function queueLeaderWakeup(store, taskId, reason, now) {
     if (store.enqueueLeaderWakeup !== undefined) {
         return store.enqueueLeaderWakeup(taskId, reason, now);
@@ -12,5 +13,5 @@ export function queueLeaderWakeupAfterYield(store, task, run, now) {
         throw new Error(`AgentRun belongs to another Task: ${run.taskId}.`);
     if (task.status !== "active" || run.roleName === "leader")
         return null;
-    return queueLeaderWakeup(store, task.id, "role-result", now);
+    return queueLeaderWakeup(store, task.id, wakeReason("role-result"), now);
 }

package/dist/setup/setupCommand.js

@@ -518,7 +518,7 @@ function parseSetupOptions(args) {
     throw usageError("Setup usage: yui setup [tmux]");
 }
 async function setupTmux(env, executor, question) {
-    const command = env.YUI_TMUX_BIN ?? "tmux";
+    const command = "tmux";
     if (hasExecutable(command, ["-V"], executor))
         return ["Tmux already installed."];
     const plan = detectTmuxInstallPlan(env, executor);