@zq-silk/yui 0.13.7 → 0.13.8

package/ARCHITECTURE.md

@@ -1,9 +1,33 @@
 # Yui Architecture
 
-Yui is a local control plane for durable work across Projects and native Agent
-runtimes. The user talks to one Operator. The Operator routes each request to
-the right Project and Task; that Task's Leader owns decomposition, execution
-choice, review, integration, and completion.
+Yui is a local control plane for intelligent Agents doing durable work across
+Projects and native runtimes. The user talks to one Operator. The Operator
+routes each request to the right Project and Task; that Task's Leader owns
+decomposition, execution choice, review, integration, and completion.
+
+## Design principles
+
+- **Agents own judgment.** Yui exposes current durable context and atomic
+  capabilities; the Operator, Leader, and Workers choose plans, execution
+  topology, sequencing, retry, and recovery from that context.
+- **Core provides primitives, not a prescribed workflow.** Reads, messages,
+  bounded record transitions, workspace ownership, Session lifecycle, and
+  acceptance are composable operations. Project Skills and Knowledge provide
+  project-specific policy without adding core branches.
+- **Durable intent outranks runtime continuity.** Tasks, WorkItems, Messages,
+  Decisions, results, Project Knowledge, and managed workspaces are authority.
+  Provider Sessions, transcripts, processes, and observations are execution
+  aids that may be resumed or replaced.
+- **Trust explicit Agent actions.** Once identity, authority, and scope are
+  established, a valid Agent command is a semantic declaration. Core should not
+  reconstruct the same judgment through another status protocol.
+- **Fail visibly and let the Agent adapt.** Preserve pending intent and return
+  actionable state. Add automated retry, recovery, leases, or fallback only for
+  a normal product path, a hard safety or data-integrity boundary, or a proven
+  failure whose cost justifies the machinery.
+- **One question has one authority.** Projections and indexes may summarize
+  state, but scheduling and lifecycle decisions must not depend on independently
+  writable copies of the same fact.
 
 ## One outcome, Leader-chosen execution topology
 
@@ -254,6 +278,18 @@ Yui's current attachment, not exclusive ownership of the Provider thread. One
 Turn identifies one provider-native execution. Yui's authority epoch fences
 only Yui's own submissions and retries.
 
+`AgentRun` is the single durable scheduling authority for a Role. Provider
+runtime persistence has no independently writable current-Run field; a Turn's
+Run id is correlation evidence for receipts and terminal observations only.
+`TaskRole` likewise stores configuration and identity, not a writable runtime
+status. CLI and Web status views derive activity from the active AgentRun and
+add Session/Driver facts only as lifecycle and diagnostic detail.
+`AgentHost` is the serialized consumer: while a native Turn is active, the next
+AgentRun and mailbox batch remain durable and unsubmitted. When that Turn ends,
+the Host makes the Conversation ready and the retained delivery continues.
+This remains true when the Agent declared the old Run's semantic outcome before
+the Provider emitted its terminal event.
+
 Codex Task threads remain ordinary native sessions and can be opened and used
 directly in Desktop. If a direct user Turn is active, Yui keeps its pending
 Run/message until that Turn settles. Global interactive entry remains a native

package/README.md

@@ -2,7 +2,16 @@
 
 # Yui
 
-Yui is a local control plane for durable Codex and Claude work. It keeps control state and Project knowledge in inspectable JSON, lets tmux own native Agent terminals, and combines reusable Worker Profiles, Leader-owned delegation, explicit acceptance, and isolated Git worktrees for Project-backed Tasks.
+Yui is a local control plane for intelligent Codex and Claude Agents. It keeps
+user intent, Project knowledge, Tasks, handoffs, and results durable and
+inspectable, while exposing small atomic capabilities for context, messaging,
+delegation, workspaces, Sessions, review, and integration. Agents compose those
+capabilities and decide how to plan, sequence, delegate, retry, and recover.
+
+Yui deliberately does not turn Agent judgment into a deterministic workflow
+engine. Its core owns durable identity, user authority, workspace isolation,
+and atomic state changes. Provider Sessions and runtime observations support
+execution and continuity, but they are not competing sources of Task truth.
 
 The current implementation restores the useful Role/Agent/session and CLI framework without restoring the later data-maintenance, lease, schedule, and recovery-ledger systems.
 
@@ -900,6 +909,15 @@ supported human-control boundary. A Codex Role uses an ordinary shared thread
 and may be operated directly in Desktop; an active Desktop Turn creates bounded
 backpressure for Yui rather than a failed Run.
 
+AgentRun is the only durable Role scheduling state. Conversation state does not
+carry a second current-Run pointer; each Provider Turn records a Run id only to
+correlate its receipt and terminal event. If an Agent finishes a Yui Run before
+the native Turn terminal arrives, the next mailbox batch may already become a
+new AgentRun, but Agent Host keeps its input pending and submits it only after
+the old Turn settles. TaskRole itself stores identity and desired launch
+configuration, not runtime status; Role status shown by CLI/Web is derived from
+the active AgentRun plus Session/Driver lifecycle facts.
+
 Global Operator and global Role sessions remain native interactive CLIs:
 
 ```sh

package/dist/cli/updatePorts.js

@@ -226,10 +226,10 @@ export function createUpdatePorts(environment, spawn = spawnSync, stagingRoot =
                     + `but the staged/verified artifact was ${staged.version}. Refusing to trust a `
                     + "different build than the one that passed preflight.");
             }
-            // Existing managed Sessions may have been created by a release that
-            // embedded an exact CLI path/version in its wrapper. Convert those
-            // authenticated, Manifest-referenced wrappers before the replacement
-            // Controller starts so the update cannot strand a live Session.
+            // Existing managed Sessions may have been created by an earlier release.
+            // Retarget those authenticated, Manifest-referenced wrappers to the
+            // activated control plane before the replacement Controller starts so
+            // the update cannot strand a live Session.
             const sessionCliRefresh = run(activeBinary, ["--json", "internal", "session-cli-refresh"], { cwd: process.cwd(), env: { ...environment, YUI_HOME: home }, shell: false });
             assertSpawnOk(sessionCliRefresh, "refresh managed Session CLI wrappers");
             // Retain the exact path used by both doctor and version verification. The

package/dist/cli.js

@@ -348,7 +348,7 @@ export async function main() {
                 || (process.env.YUI_SESSION_SCOPE === "global" && process.env.YUI_ROLE !== "operator")) {
                 throw usageError("Managed Session CLI refresh may be run only by the user or global Operator.");
             }
-            const result = refreshManagedSessionCliWrappers(home);
+            const result = refreshManagedSessionCliWrappers(home, currentInvocationControlPlane(home));
             emit(`Refreshed ${result.refreshed} legacy Session CLI wrapper(s); `
                 + `${result.current} already current, ${result.skipped} skipped.`, false, result);
             return;

package/dist/commands/taskCommands.js

@@ -19,7 +19,7 @@ import { renderRoleDetails } from "../output/rolePresentation.js";
 import { createTaskMessage, taskMessageAuthorLabel } from "../message/message.js";
 import { cancelInputRequest } from "../input/inputRequest.js";
 import { retireExactActiveAgentRun, terminalizeExactTaskRun, validateExactRunReviewRound } from "../lifecycle/exactRunTerminalization.js";
-import { activeRoleAgentBinding, copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole, updateRoleStatus } from "../role/role.js";
+import { activeRoleAgentBinding, copyGlobalRoleToTaskRole, createRole, createRoleAgentBinding, switchActiveRoleAgent, unbindRoleAgent, updateRole } from "../role/role.js";
 import { agentRunDeliveryReceiptId, createAgentRun, failAgentRun, withAgentRunContextSnapshot, yieldAgentRun } from "../run/agentRun.js";
 import { matchYieldReceipt } from "../run/yieldReceipt.js";
 import { createRejectedYieldAttempt, rejectedYieldAttemptEventPayload, rejectedYieldAttemptFromTaskEvent, RUN_YIELD_REJECTED_EVENT } from "../run/rejectedYieldAttempt.js";
@@ -987,11 +987,6 @@ function retireTaskCommand(args, store, options) {
                 tx.saveInputRequest(task.id, cancelInputRequest(request, `Task retired: ${summary}`, now));
             }
         }
-        for (const role of tx.listRoles(task.id)) {
-            if (role.status !== "idle") {
-                tx.saveRole(task.id, updateRoleStatus(role, "idle", now));
-            }
-        }
         for (const mailbox of tx.listWorkMailboxes()) {
             if ((mailbox.target.kind === "task"
                 || mailbox.target.kind === "role")
@@ -2374,7 +2369,6 @@ function dispatchWork(args, store, options) {
             const role = requireRole(tx, task.id, unboundRun.roleName);
             tx.saveAgentRun(runWithLineage);
             tx.saveActiveAgentRun(runWithLineage);
-            tx.saveRole(task.id, updateRoleStatus(role, "running", now));
             enqueueWork(tx, roleMailbox(task.id, role.name), "run-dispatched", now, [
                 runRef(task.id, runWithLineage.id),
                 workItemRef(task.id, item.id)
@@ -4499,7 +4493,6 @@ function retryRun(args, store, options) {
         });
         tx.saveAgentRun(created);
         tx.saveActiveAgentRun(created);
-        tx.saveRole(task.id, updateRoleStatus(role, "running", now));
         if (previous.workItemId !== undefined && retriedItemWithGroup !== null) {
             const item = retriedItemWithGroup;
             const workspace = tx.getWorkItemWorkspace(task.id, item.id);
@@ -6072,7 +6065,6 @@ export function dispatchPreparedReviewRound(taskId, reviewRoundId, store, option
             const laneReviewer = requireRole(tx, taskId, unboundRun.roleName);
             tx.saveAgentRun(created);
             tx.saveActiveAgentRun(created);
-            tx.saveRole(taskId, updateRoleStatus(laneReviewer, "running", now));
             enqueueWork(tx, roleMailbox(taskId, laneReviewer.name), "review-requested", now, [
                 runRef(taskId, created.id),
                 ...(item === undefined ? [] : [workItemRef(taskId, item.id)])
@@ -7175,9 +7167,6 @@ function settleTaskExecutionForCompletion(store, taskId, roles, summary, now) {
             }
             store.saveTaskRoleSessionSet(sessions);
         }
-        if (role.status !== "idle") {
-            store.saveRole(taskId, updateRoleStatus(role, "idle", now));
-        }
         if (!cleanupRequired)
             continue;
         const target = runtimeLifecycleTarget({

package/dist/commands/taskContextCommand.js

@@ -249,7 +249,7 @@ export function runTaskContextCommand(args, store, currentTaskReviewCandidate =
                 const effectiveSource = activeRun === undefined ? "Session" : "Run";
                 const creation = [...events].reverse().find((event) => (event.type === "role.added" && event.payload.role === role.name));
                 return [
-                    `  ${role.name} [${role.status}]: ${role.activeAgentId}/${binding.adapterId}`,
+                    `  ${role.name} [${activeRun === undefined ? "idle" : "running"}]: ${role.activeAgentId}/${binding.adapterId}`,
                     `    Desired: r${role.launchRevision}; Profile intent: ${role.defaultAccess}; Model: ${binding.config.model ?? "default"}; effort: ${binding.config.effort ?? "default"}; permission: ${binding.config.permission.strategy}`,
                     `    Effective: ${effective === undefined
                         ? "not started"

package/dist/commands/taskExecutionCommands.js

@@ -4,7 +4,6 @@ import { recordExecutionLaneResult } from "../execution/executionGroup.js";
 import { usageError } from "../errors/cliError.js";
 import { requestDurableJobCancel } from "../job/durableJob.js";
 import { finishReviewRound, updateReviewExecutionGroup } from "../review/reviewRound.js";
-import { updateRoleStatus } from "../role/role.js";
 import { failAgentRun } from "../run/agentRun.js";
 import { queueLeaderWakeup } from "../scheduler/wakeupQueue.js";
 import { startTaskExecution, stopTaskExecution } from "../task/task.js";
@@ -83,10 +82,6 @@ export function stopTaskExecutionCommand(request, store, options = {}) {
             if (sessions !== null && sessions.inFlight !== null) {
                 tx.saveTaskRoleSessionSet(terminalizeCurrentRun(sessions, now));
             }
-            const role = tx.getRole(task.id, roleName);
-            if (role !== null && role.status !== "idle") {
-                tx.saveRole(task.id, updateRoleStatus(role, "idle", now));
-            }
         }
         // A stop is allowed to discard stale pointer projections even when their
         // historical Runs are already terminal.

package/dist/commands/taskOverviewCommand.js

@@ -78,7 +78,11 @@ function buildTaskOverviewEntry(task, store, now, runtimeHealthPolicy) {
     const legacyNext = deriveNextAction(task, brief, workItems, openInputRequests, blockers, pendingWakeup);
     const leader = {
         role: "leader",
-        roleStatus: leaderRole?.status ?? "missing",
+        roleStatus: leaderRole === null
+            ? "missing"
+            : agentRuns.some((run) => run.roleName === "leader" && run.status === "active")
+                ? "running"
+                : roleSessions.find((session) => session.roleName === "leader")?.status ?? "idle",
         summary: brief?.leaderSummary ?? null,
         currentFocus: brief?.currentFocus ?? null,
         updatedAt: brief?.updatedAt ?? null,

package/dist/commands/taskRoleRuntimeStatus.js

@@ -85,7 +85,6 @@ export function renderTaskRoleRuntimeStatus(status) {
             ? "-"
             : status.launchDrift ? "pending next launch" : "none"}`,
         `  Run/session      ${status.runSessionDrift ? "snapshot mismatch" : "snapshot consistent"}`,
-        `  Role state       ${status.role.status}`,
         `  Active work      ${activeWork}`,
         `  Active run       ${activeRun}`,
         ...(lastRun === undefined ? [] : [`  Last run         ${lastRun}`]),
@@ -254,9 +253,6 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
             healthReason: "the native Session is unbound; verified runtime cleanup is pending"
         };
     }
-    if (role.status === "failed" || role.status === "exited") {
-        return { health: "failed", healthReason: `persisted Role state is ${role.status}` };
-    }
     if (nativeSession?.status === "broken") {
         // Issue 09: a broken Session only fails a live Run. When the last Run
         // already yielded, the Session death is a lifecycle event, not a Run
@@ -287,12 +283,6 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
         };
     }
     if (activeRun !== null) {
-        if (role.status !== "running") {
-            return {
-                health: "needs-attention",
-                healthReason: `the active Run conflicts with persisted Role state ${role.status}`
-            };
-        }
         if (activeRun.deliveredAt !== undefined && tmux.state !== "running") {
             return { health: "needs-attention", healthReason: "the delivered active Run has no live tmux pane" };
         }
@@ -339,9 +329,6 @@ function calculateHealth(role, activeRun, lastRun, nativeSession, runtimeCleanup
             }
         }
     }
-    if (activeRun === null && role.status === "running") {
-        return { health: "needs-attention", healthReason: "the Role is running without an active Run" };
-    }
     if (nativeSession?.status === "running" && tmux.state !== "running") {
         return { health: "needs-attention", healthReason: "the native session is running without a live tmux pane" };
     }

package/dist/context/sessionBootstrapManifest.js

@@ -1,15 +1,18 @@
 import { createHash } from "node:crypto";
 import { chmodSync, existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { exactControlPlaneDigest, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
+import { exactControlPlaneCommandPrefix, exactControlPlaneDigest, serializeExactDescriptor } from "../runtime/exactControlPlane.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
-const ORDINARY_SESSION_CLI = [
-    "#!/bin/sh",
-    "exec yui \"$@\"",
-    ""
-].join("\n");
+const ordinarySessionCli = ["#!/bin/sh", "exec yui \"$@\"", ""].join("\n");
+function renderSessionCli(controlPlane) {
+    return [
+        "#!/bin/sh",
+        `exec ${exactControlPlaneCommandPrefix(controlPlane)} \"$@\"`,
+        ""
+    ].join("\n");
+}
 /** Read back one immutable Session Manifest and verify its content digest. */
 export function readSessionBootstrapManifest(path) {
     const source = resolve(path);
@@ -84,10 +87,11 @@ export function materializeSessionBootstrap(input) {
     const controlDigest = exactControlPlaneDigest(input.controlPlane);
     const descriptorPath = resolve(join(home, "runtime", "control-plane", `${controlDigest}.json`));
     writeImmutableText(descriptorPath, `${serializeExactDescriptor(input.controlPlane)}\n`);
-    // Session identity is carried by the immutable Manifest and durable Role/
-    // Run fences. Resolve the ordinary CLI on every invocation so package or
-    // release upgrades do not invalidate a still-current native Session.
-    const sessionCliContent = ORDINARY_SESSION_CLI;
+    // Provider command runners may rebuild PATH independently of the managed
+    // process environment. Keep the Session entry point deterministic; the
+    // existing continuity preflight accepts compatible package replacement at
+    // this path without treating package version as Session identity.
+    const sessionCliContent = renderSessionCli(input.controlPlane);
     const sessionCliDigest = digest(sessionCliContent);
     const sessionCliPath = resolve(join(home, "runtime", "session-cli", `yui-${sessionCliDigest}.sh`));
     writeImmutableText(sessionCliPath, sessionCliContent);
@@ -126,11 +130,11 @@ export function materializeSessionBootstrap(input) {
         roleProfileRef: { digest: profileDigest, path: roleProfilePath },
         contextProtocol: input.owner.scope === "global"
             ? {
-                loadCommand: "yui session context \"$YUI_ROLE\" --json"
+                loadCommand: "\"$YUI_SESSION_CLI\" session context \"$YUI_ROLE\" --json"
             }
             : {
-                loadCommand: "yui task run context \"$YUI_TASK_ID/<run-id>\" --json",
-                expandCommand: "yui task run context expand \"$YUI_TASK_ID/<run-id>\" <ref-id> --store <store> --mode full --json"
+                loadCommand: "\"$YUI_SESSION_CLI\" task run context \"$YUI_TASK_ID/<run-id>\" --json",
+                expandCommand: "\"$YUI_SESSION_CLI\" task run context expand \"$YUI_TASK_ID/<run-id>\" <ref-id> --store <store> --mode full --json"
             }
     };
     const manifest = Object.freeze({ ...body, digest: digest(body) });
@@ -145,14 +149,13 @@ export function materializeSessionBootstrap(input) {
     });
 }
 /**
- * Converts wrappers produced before the protocol-compatible Session CLI to an
- * ordinary `yui` invocation. Only a valid Session Manifest may nominate a
- * wrapper, and only the exact legacy two-line wrapper shape is changed. The
- * Manifest and its frozen descriptor stay immutable and continue to
- * authenticate the Session; repeated refreshes are no-ops.
+ * Retargets known managed wrappers to the current resolved control plane after
+ * a compatible update. Only a valid Session Manifest may nominate a wrapper,
+ * and only Yui's ordinary or exact two-line wrapper shapes are changed.
  */
-export function refreshManagedSessionCliWrappers(homeInput) {
+export function refreshManagedSessionCliWrappers(homeInput, controlPlane) {
     const home = resolve(homeInput);
+    const currentSessionCli = renderSessionCli(controlPlane);
     const manifestDirectory = resolve(join(home, "runtime", "session-manifests"));
     const sessionCliDirectory = resolve(join(home, "runtime", "session-cli"));
     if (!existsSync(manifestDirectory)) {
@@ -189,21 +192,21 @@ export function refreshManagedSessionCliWrappers(homeInput) {
             continue;
         }
         const content = readFileSync(wrapperPath, "utf8");
-        if (content === ORDINARY_SESSION_CLI) {
+        if (content === currentSessionCli) {
             current += 1;
             continue;
         }
-        if (!isLegacyExactSessionCli(content)) {
+        if (content !== ordinarySessionCli && !isExactSessionCli(content)) {
             skipped += 1;
             continue;
         }
-        writeTextFileAtomically(wrapperPath, ORDINARY_SESSION_CLI);
+        writeTextFileAtomically(wrapperPath, currentSessionCli);
         chmodSync(wrapperPath, 0o700);
         refreshed += 1;
     }
     return Object.freeze({ refreshed, current, skipped });
 }
-function isLegacyExactSessionCli(content) {
+function isExactSessionCli(content) {
     return /^#!\/bin\/sh\nexec [^\n]+ '--yui-control' '[a-f0-9]{64}' "\$@"\n$/u.test(content);
 }
 function writeImmutableText(path, content) {

package/dist/controller/controller.js

@@ -96,8 +96,6 @@ export async function runControllerSchedulerPass(store, delivery, now, workspace
         }
         const newlyIdleBusyTaskIds = new Set(initialWakeupResults.flatMap((result) => (result.reason === "busy"
             && store.getActiveAgentRun(result.taskId, "leader") === null
-            && (typeof store.hasInFlightTurn !== "function"
-                || !store.hasInFlightTurn(result.taskId, "leader"))
             ? [result.taskId]
             : [])));
         // Phase-one Leader Runs did not exist at the pass's liveness boundary.