@zq-silk/yui 0.10.1 → 0.11.0

package/README.md

@@ -532,6 +532,59 @@ yui task work isolate <task-id>/<work-item-id>
 yui task work dispatch <task-id>/<work-item-id> --input "Implement and run focused tests"
 ```
 
+Dispatch remains `single` by default. A Leader can explicitly enable bounded
+multi-route exploration on a fresh WorkItem; each accepted stage advances
+`Plan → Generate → Compare → Synthesize → Verify → Resolve`, and only the
+accepted Resolve stage materializes the existing single Candidate:
+
+```sh
+yui task work dispatch <task-id>/<work-item-id> \
+  --mode parallel-diverse --max-rounds 2 --stage-max-attempts 2 \
+  --strategy fixed:2 --lane-role critic \
+  --stage-max-tokens 240000 --stage-max-tool-calls 200 \
+  --stage-max-seconds 1800 --stage-quorum 2
+yui task work group resolve <task-id>/<work-item-id> \
+  --decision accept --summary "Plan evidence is sufficient"
+```
+
+Every stage is a new immutable ExecutionGroup. Its ContextSnapshot and selected
+parent Lane results are durable references; `retry` repeats a stage within its
+attempt budget, while `retry` at Resolve begins the next bounded round.
+
+Each new stage also freezes one Resource Broker contract: token, tool-call and
+wall-clock budgets; quorum and deadline; a straggler window; and the minimum
+marginal value for more Lane spend. Omitted values reuse the existing context
+budget and runtime-health windows; stage retries share the original cumulative
+spend and absolute deadline. Execution, Lane retry, and Reviewer-panel
+admission all count active Lanes at Home, Task, WorkItem, Group, Provider,
+Agent, and model scopes. Capacity pressure keeps the excess Lane durably
+pending instead of failing the Group. Capacity release or deadline arrival
+wakes the Leader through the existing actionability path; rerunning the same
+dispatch resumes the frozen input. Released capacity is reserved for the
+oldest currently admissible waiter, while a Provider- or Agent-blocked queue
+head does not prevent independent scopes from making progress. Provider rate
+limits still use the existing in-place retry window and therefore never fan
+out into sibling failures.
+
+The Leader may add `--early-stop <0-100>` to an accepting Group resolution.
+Yui permits it only after quorum and T5's passed Verify/Resolve evidence prove
+sufficiency. It may skip Lanes that never started; active stragglers are
+reported and retained, never killed automatically for cost. If evidence is
+insufficient, budget or deadline exhaustion blocks the stage for Leader
+judgment instead of turning thin evidence into success.
+
+New exploration histories also freeze the structured candidate-convergence
+contract. Yui appends the exact stage-local JSON shape to every Lane assignment
+and validates selected reports before the Leader can advance: Compare must
+partition duplicate clusters and justify each selected route with a direct
+source, executable check, or frozen artifact; Synthesize uses a claim/evidence
+table for research, a decision matrix for architecture, and one frozen Git
+snapshot for code. Verify must use a Role independent from the selected
+Synthesize author. Only complete criterion evidence can produce `passed` and
+an accepted Resolve Candidate; explicit gaps produce `next-round` and can only
+continue through bounded Resolve `retry`. Votes and derived analysis remain
+reportable context, but never substitute for direct evidence.
+
 Permission is one adapter-specific enum configuration on each Agent binding:
 `default` follows the provider, `bypass` compiles the provider's supported
 bypass flag, and `configured` retains whichever native options are explicitly

package/dist/cli/commandCatalog.js

@@ -343,6 +343,19 @@ const taskChildren = [
         usage: "yui task rebuild <task> [--latest]",
         options: ["--latest"]
     },
+    {
+        name: "upstream",
+        summary: "Integrate upstream changes into an Active Task workspace.",
+        sections: [{ id: "manage", title: "Commands", entries: ["integrate"] }],
+        children: [
+            {
+                name: "integrate",
+                summary: "Merge the remote development head into the Task workspace.",
+                usage: "yui task upstream integrate <task> [--latest] [--project <project>]",
+                options: ["--latest", "--project"]
+            }
+        ]
+    },
     {
         name: "history",
         summary: "Inspect and archive legacy Task refs in the Home repository.",
@@ -619,8 +632,11 @@ const taskChildren = [
             {
                 name: "dispatch",
                 summary: "Dispatch a work item to its Role.",
-                usage: "yui task work dispatch <task>/<work> [--input <text>] [--strategy fixed:<count>|adaptive:<max>] [--lane-role <role> ...]",
-                options: ["--input", "--strategy", "--lane-role"]
+                usage: "yui task work dispatch <task>/<work> [--input <text>] [--strategy fixed:<count>|adaptive:<max>] [--lane-role <role> ...] [--mode <single|parallel-diverse|ensemble-replicated|adversarial|adaptive-exploration>] [--max-rounds <count>] [--stage-max-attempts <count>] [--stage-max-tokens <count>] [--stage-max-tool-calls <count>] [--stage-max-seconds <count>] [--stage-quorum <count>] [--stage-straggler-seconds <count>] [--stage-min-marginal-value <0-100>]",
+                options: ["--input", "--strategy", "--lane-role", "--mode", "--max-rounds", "--stage-max-attempts", "--stage-max-tokens", "--stage-max-tool-calls", "--stage-max-seconds", "--stage-quorum", "--stage-straggler-seconds", "--stage-min-marginal-value"],
+                optionValues: {
+                    "--mode": ["single", "parallel-diverse", "ensemble-replicated", "adversarial", "adaptive-exploration"]
+                }
             },
             {
                 name: "group",
@@ -630,9 +646,9 @@ const taskChildren = [
                 children: [{
                         name: "resolve",
                         summary: "Select Lane outputs and resolve the Worker group.",
-                        usage: "yui task work group resolve <task>/<work> --decision <accept|reject|blocked> --summary <text> [--lane <lane-id> ...]",
-                        options: ["--decision", "--summary", "--lane"],
-                        optionValues: { "--decision": ["accept", "reject", "blocked"] }
+                        usage: "yui task work group resolve <task>/<work> --decision <accept|reject|retry|blocked> --summary <text> [--lane <lane-id> ...] [--early-stop <marginal-value-percent>]",
+                        options: ["--decision", "--summary", "--lane", "--early-stop"],
+                        optionValues: { "--decision": ["accept", "reject", "retry", "blocked"] }
                     }]
             },
             {
@@ -1244,7 +1260,7 @@ export const ROOT_COMMAND = buildNode({
         {
             name: "project",
             summary: "Manage Projects, stable checkouts, branches, and Yui knowledge.",
-            sections: [{ id: "manage", title: "Commands", entries: ["add", "clone", "refresh", "migrate", "update", "discover", "list", "show", "knowledge"] }],
+            sections: [{ id: "manage", title: "Commands", entries: ["add", "clone", "refresh", "diagnose", "migrate", "update", "discover", "list", "show", "knowledge"] }],
             children: [
                 {
                     name: "add",
@@ -1264,6 +1280,11 @@ export const ROOT_COMMAND = buildNode({
                     summary: "Fast-forward a clean stable checkout from its configured remote.",
                     usage: "yui project refresh <project>"
                 },
+                {
+                    name: "diagnose",
+                    summary: "Show canonical HEAD vs remote head without mutating the checkout.",
+                    usage: "yui project diagnose <project>"
+                },
                 {
                     name: "migrate",
                     summary: "Move an external Project into a Home-managed repository.",
@@ -1381,7 +1402,7 @@ export const ROOT_COMMAND = buildNode({
             name: "task",
             summary: "Manage Tasks, WorkItems, Agent Runs, and integration.",
             sections: [
-                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "next-action", "archive", "rebuild", "history", "replace", "reconcile"] },
+                { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "next-action", "archive", "rebuild", "history", "replace", "reconcile", "upstream"] },
                 { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "overlap", "change-set"] },
                 { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event", "continuation", "wake"] }
             ],

package/dist/cli.js

@@ -37,7 +37,7 @@ import { runResourcesCommand } from "./commands/resourcesCommands.js";
 import { applyOperatorSessionControl, runOperatorCommand } from "./commands/operatorCommands.js";
 import { runProjectCommand } from "./commands/projectCommands.js";
 import { runProfileCommand } from "./commands/profileCommands.js";
-import { dispatchPreparedReviewRound, failPendingReviewRound, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, parseTaskFinalReviewContractRebindRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, validateTaskArchiveRequest } from "./commands/taskCommands.js";
+import { dispatchPreparedReviewRound, failPendingReviewRound, RESUMED_PENDING_FINAL_REVIEW, TERMINALIZED_LEADER_BEFORE_FINAL_REVIEW, TaskFinalReviewDispatchDriftError, preserveReviewRoundWorkspace, parseTaskCompletionRequest, parseTaskFinalReviewContractRebindRequest, preflightTaskCompletion, runTaskCommand, normalizedExecutionLanePlan, resolvedExecutionStageRetryGroup, validateTaskArchiveRequest } from "./commands/taskCommands.js";
 import { taskActor } from "./commands/taskActor.js";
 import { isCurrentGlobalOperator } from "./commands/taskInputCommands.js";
 import { runTaskIntegrationCommand } from "./commands/taskIntegrationCommands.js";
@@ -52,6 +52,7 @@ import { acquireHandoverLock, readRuntimeIdentity } from "./release/runtimeRelea
 import { renderReleaseActivateResult, renderReleaseInstallResult, renderReleaseList, resolveReleaseActivationDriver, runReleaseActivate, runReleaseInstall, runReleaseList } from "./commands/releaseCommands.js";
 import { reconcileTaskRemoteBaselines, verifyTaskCompletionPublishedTree } from "./commands/taskCompletionGate.js";
 import { runTaskBaseStatusCommand } from "./commands/taskBaseCommands.js";
+import { runTaskUpstreamCommand } from "./commands/taskUpstreamCommands.js";
 import { assertTaskBaseFreshnessForCompletion, inspectTaskBaseFreshness } from "./repository/taskBaseFreshness.js";
 import { FileCompletionManager, resolveCliIdentity } from "./completion/fileCompletionManager.js";
 import { assertFileTaskControllerStorageCompatible, ensureFileTaskController, FileTaskWorkflowRuntime, refreshRunningFileTaskControllerConfiguration, refreshRunningFileTaskControllerEnvironment, restartFileTaskController, stopFileTaskController } from "./controller/clientRuntime.js";
@@ -1005,6 +1006,11 @@ export async function main() {
             emit(result.output, false, result.data);
             return;
         }
+        if (resolved[1] === "upstream") {
+            const result = await runTaskUpstreamCommand(resolved.slice(2), store);
+            emit(result.output, false, result.data);
+            return;
+        }
         if (resolved[1] === "complete" && resolved[2] !== undefined) {
             const completionRequest = parseTaskCompletionRequest(resolved.slice(2));
             completionSummary = completionRequest.summary;
@@ -1117,6 +1123,16 @@ export async function main() {
             const laneSnapshotPreflight = executionLaneGitSnapshot === undefined
                 ? undefined
                 : executionLaneGitSnapshot;
+            // RFC Phase 3: prepare the Task workspace before activation so a
+            // preparation failure keeps the Task in Draft instead of leaving it
+            // Active without a workspace.
+            if (resolved[1] === "activate") {
+                const taskId = resolved[2];
+                const task = taskId === undefined ? null : store.getTask(taskId);
+                if (task !== null && task.status === "draft") {
+                    await workspacePreparer.prepareTaskWorkspace(task.id);
+                }
+            }
             const result = runTaskCommand(resolved.slice(1), store, {
                 runtime,
                 environment: process.env,
@@ -1166,10 +1182,12 @@ export async function main() {
                     : store.getReviewRound(requestedRound.taskId, requestedRound.id);
                 let reviewOutput = "";
                 let reviewData;
+                const resumesReviewDispatch = (resolved[1] === "review" && resolved[2] === "request")
+                    || (resolved[1] === "work" && resolved[2] === "review")
+                    || (resolved[1] === "run" && resolved[2] === "retry");
                 const reviewDispatchNeeded = requestedRound?.status === "pending"
                     || (requestedRound?.status === "running"
-                        && resolved[1] === "review"
-                        && resolved[2] === "request"
+                        && resumesReviewDispatch
                         && persistedRequestedRound?.executionGroup?.lanes.some((lane) => (lane.status === "pending" && lane.runId === undefined)) === true);
                 if (reviewDispatchNeeded) {
                     try {
@@ -1203,10 +1221,12 @@ export async function main() {
                                 ? {}
                                 : { deltaRecheckDiff: deltaRecheckPreflight.diffByProject })
                         });
-                        reviewOutput = `Review queued as ${requestedRound.id} (${run.id})\n`;
+                        reviewOutput = run === null
+                            ? `Review ${requestedRound.id} retained pending by Resource Broker\n`
+                            : `Review queued as ${requestedRound.id} (${run.id})\n`;
                         reviewData = {
                             reviewRound: store.getReviewRound(requestedRound.taskId, requestedRound.id),
-                            reviewRun: run,
+                            ...(run === null ? {} : { reviewRun: run }),
                             workspace
                         };
                     }
@@ -1226,45 +1246,6 @@ export async function main() {
                         reviewData = { reviewRound: failed };
                     }
                 }
-                if (resolved[1] === "create") {
-                    const created = result.data;
-                    if (created?.task?.id !== undefined) {
-                        let workspace;
-                        try {
-                            workspace = await workspacePreparer.prepareTaskWorkspace(created.task.id);
-                        }
-                        catch (error) {
-                            const message = error instanceof Error ? error.message : String(error);
-                            workspace = {
-                                taskId: created.task.id,
-                                status: "failed",
-                                error: message
-                            };
-                        }
-                        const latest = store.getTask(created.task.id);
-                        const leader = store.getRole(created.task.id, "leader");
-                        if (latest !== null && leader !== null) {
-                            const warning = workspace.status === "failed"
-                                ? `Main worktree is not ready: ${workspace.error ?? "unknown error"}.\n`
-                                    + `After correcting the Git problem, run yui task reconcile ${created.task.id}.\n`
-                                : "";
-                            emit(`${result.output}${warning}`, false, {
-                                ...created,
-                                task: latest,
-                                leader,
-                                workspace
-                            });
-                            return;
-                        }
-                    }
-                }
-                if (resolved[1] === "activate") {
-                    const taskId = resolved[2];
-                    const task = taskId === undefined ? null : store.getTask(taskId);
-                    if (task?.status === "active") {
-                        await workspacePreparer.prepareTaskWorkspace(task.id);
-                    }
-                }
                 if (resolved[1] === "project" && resolved[2] === "add") {
                     const taskId = resolved[3];
                     const task = taskId === undefined ? null : store.getTask(taskId);
@@ -1683,6 +1664,7 @@ async function candidateSnapshotForTaskCommand(args, store, preparer, environmen
             const fixedSingleLane = group?.strategy.mode === "fixed"
                 && group.strategy.count === 1
                 && group.lanes.length === 1
+                && group.stage === undefined
                 && run.workspace.owner.type === "work-item";
             if (fixedSingleLane)
                 return preparer.snapshotCandidateWorkspace(run.workspace);
@@ -1725,9 +1707,28 @@ async function candidateMaterializationForTaskCommand(args, store, preparer, env
         : currentWorkItemExecutionGroup(item);
     if (item === null || item === undefined || group === undefined)
         return undefined;
+    if (group.stage !== undefined && group.stage.stage !== "resolve")
+        return undefined;
+    // Early termination first stops never-started spend. Active stragglers are
+    // deliberately retained, so the command records that stop and leaves the
+    // group unresolved. Do not merge Lane output into the WorkItem Candidate
+    // until those active Lanes settle and the Leader resolves the group again.
+    if (args.includes("--early-stop")
+        && group.lanes.some(({ status }) => status === "running"))
+        return undefined;
     const selected = args.flatMap((value, index) => value === "--lane" && args[index + 1] !== undefined ? [args[index + 1]] : []);
+    const materializedLaneIds = selected.length === 0
+        ? group.lanes
+            .filter((lane) => lane.status === "yielded" || lane.status === "completed")
+            .map(({ id }) => id)
+        : selected;
+    if (group.stage?.convergence !== undefined
+        && group.stage.stage === "resolve"
+        && materializedLaneIds.length !== 1) {
+        throw usageError("Candidate convergence Resolve must select exactly one Lane before materialization.");
+    }
     try {
-        return await preparer.materializeExecutionGroupCandidate(item.taskId, item.id, group.id, selected);
+        return await preparer.materializeExecutionGroupCandidate(item.taskId, item.id, group.id, materializedLaneIds);
     }
     catch (error) {
         throw usageError(error instanceof Error ? error.message : String(error));
@@ -1781,6 +1782,9 @@ async function prepareExecutionLaneWorkspacesForCommand(args, store, preparer, e
         requestedRoles: roles,
         requestedStrategy,
         existingGroup: group === undefined ? undefined : group,
+        resolvedRetryGroup: isDispatch
+            ? resolvedExecutionStageRetryGroup(currentGroup)
+            : undefined,
         status: item.status,
         nextGroupId: `execution-group-${store.peekNextAgentRunId(item.taskId)}`,
         retryLaneId,
@@ -1799,8 +1803,7 @@ async function prepareExecutionLaneWorkspacesForCommand(args, store, preparer, e
             throw usageError(`ExecutionGroup strategy is frozen: ${group.id}.`);
     }
     const laneCount = plan.requestedCount;
-    const strategyArg = args.find((value) => value.startsWith("adaptive:") || value.startsWith("fixed:"));
-    const adaptive = strategyArg?.startsWith("adaptive:") === true || group?.strategy.mode === "adaptive";
+    const adaptive = plan.strategy.mode === "adaptive";
     const needsIsolation = adaptive || laneCount > 1 || (group?.lanes.length ?? 0) > 1;
     if (!needsIsolation)
         return undefined;

package/dist/commands/projectCommands.js

@@ -27,6 +27,9 @@ export async function runProjectCommand(args, store, options = {}) {
             data: refreshed
         };
     }
+    if (command === "diagnose") {
+        return diagnoseProject(rest, store, options);
+    }
     if (command === "migrate") {
         const migrated = await migrateProject(rest, store, options);
         return {
@@ -80,12 +83,72 @@ async function refreshProject(args, store, options) {
     if (project.stableBranch !== project.developmentBranch) {
         throw usageError(`Project refresh requires matching stable and development branches: ${project.id}.`);
     }
-    const refreshed = await (options.git ?? new NodeGitWorkspace()).refresh({
-        repositoryPath: project.path,
-        remoteUrl: project.remoteUrl,
-        stableRef: project.stableBranch
-    });
-    return { project, ...refreshed };
+    // 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);
+    try {
+        const refreshed = await (options.git ?? new NodeGitWorkspace()).refresh({
+            repositoryPath: project.path,
+            remoteUrl: project.remoteUrl,
+            stableRef: project.stableBranch
+        });
+        return { project, ...refreshed };
+    }
+    finally {
+        releaseMaintenance();
+    }
+}
+/**
+ * RFC Phase 1: diagnose a managed Project's divergence without mutating it.
+ * Shows the canonical HEAD, remote advertised SHA, and whether the checkout
+ * can be fast-forwarded. Does not auto-reset or rebase.
+ */
+async function diagnoseProject(args, store, options) {
+    if (args.length !== 1) {
+        throw usageError("Project diagnose usage: yui project diagnose <project>.");
+    }
+    const project = requireProject(store, args[0]);
+    if (project.remoteUrl === undefined) {
+        return {
+            output: `Project ${project.id} has no remote URL; nothing to diagnose.\n`,
+            data: { project, diagnosis: "no-remote" }
+        };
+    }
+    const git = options.git ?? new NodeGitWorkspace();
+    const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+    try {
+        const current = await git.inspect(project.path, "HEAD");
+        const remote = await git.resolveRemoteBaseline({
+            repositoryPath: project.path,
+            remoteUrl: project.remoteUrl,
+            developmentRef: project.developmentBranch
+        });
+        const isAncestor = await git.isAncestor(project.path, current.baseCommit, remote.commit);
+        const diverged = !isAncestor && current.baseCommit !== remote.commit;
+        const lines = [
+            `Project: ${project.id}`,
+            `  canonical HEAD: ${current.baseCommit}`,
+            `  remote ${project.developmentBranch}: ${remote.commit}`,
+            `  status: ${current.baseCommit === remote.commit ? "up-to-date" : diverged ? "diverged" : "behind"}`,
+            ...(diverged
+                ? ["  The canonical checkout has local commits not on the remote.",
+                    "  Use `yui project refresh` only after resolving the divergence manually."]
+                : [])
+        ];
+        return {
+            output: lines.join("\n") + "\n",
+            data: {
+                project,
+                diagnosis: diverged ? "diverged" : current.baseCommit === remote.commit ? "up-to-date" : "behind",
+                canonicalHead: current.baseCommit,
+                remoteHead: remote.commit
+            }
+        };
+    }
+    finally {
+        releaseMaintenance();
+    }
 }
 async function discoverProjects(args, store, options) {
     if (args.length > 1) {