@zq-silk/yui 0.10.0 → 0.11.0

package/dist/commands/taskContextCommand.js

@@ -8,6 +8,7 @@ import { inspectTaskRoleSessionRecovery } from "./taskRoleRuntimeStatus.js";
 import { summarizeExecutionGroup } from "../execution/executionGroup.js";
 import { currentWorkItemExecutionGroup } from "../workItem/workItem.js";
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
+import { projectExecutionLaneRunRecoveries } from "../run/recoveryProjection.js";
 const RECENT_RECORD_LIMIT = 5;
 const RELATED_RECORD_LIMIT = 5;
 const SUMMARY_TEXT_LIMIT = 400;
@@ -21,6 +22,7 @@ export function runTaskContextCommand(args, store) {
         throw usageError("Task context usage: yui task context <task>.");
     }
     const taskId = args[0].trim();
+    const now = new Date();
     const data = store.transaction((reader) => {
         const task = reader.getTask(taskId);
         if (task === null)
@@ -28,7 +30,7 @@ export function runTaskContextCommand(args, store) {
         const workItems = reader.listWorkItems(task.id);
         const inputRequests = reader.listInputRequests(task.id);
         const roles = reader.listRoles(task.id);
-        const execution = buildTaskExecutionProjection(reader, task.id, task);
+        const execution = buildTaskExecutionProjection(reader, task.id, task, now);
         if (execution === null) {
             throw new Error(`Task execution projection disappeared: ${task.id}.`);
         }
@@ -74,7 +76,11 @@ export function runTaskContextCommand(args, store) {
             openInputRequests: inputRequests.filter((request) => request.status === "open"),
             resolvedInputRequests: inputRequests.filter((request) => request.status !== "open"),
             events,
-            nextAction: projectNextAction(nextActionFacts)
+            nextAction: projectNextAction({
+                ...nextActionFacts,
+                executionGroups: execution.executionGroups,
+                runRecoveries: projectExecutionLaneRunRecoveries(reader, task.id, execution.executionGroups)
+            })
         };
     });
     const { task, execution, reviewConfig, brief, activeDecisions, milestones, roles, managedWorkspaces, roleSessionSets, coordinationMailboxes, roleSessionRecoveries, workItems, agentRuns, reviewRounds, changeSets, integrations, publications, messages, openInputRequests, resolvedInputRequests, events, nextAction } = data;
@@ -86,6 +92,11 @@ export function runTaskContextCommand(args, store) {
     const displayedExecutionCarriers = execution.monitoring === "active"
         ? execution.activeRuns
         : [];
+    const executionGroupsById = new Map(execution.executionGroups.map((group) => [
+        group.groupId,
+        group
+    ]));
+    const observability = execution.observability;
     const lines = [
         `Task context: ${task.id}`,
         `Title: ${compactText(task.title)}`,
@@ -128,6 +139,10 @@ export function runTaskContextCommand(args, store) {
         ...(displayedExecutionCarriers.length === 0
             ? ["    None."]
             : displayedExecutionCarriers.map((run) => (`    ${run.roleName}: ${run.id} [${run.status}; ${run.delivered ? "accepted" : "delivery-pending"}]`))),
+        "Observability:",
+        `  DAG: ${observability.dag.nodes.length} node(s), ${observability.dag.edges.length} edge(s); ready=${observability.dag.readyIds.join(", ") || "none"}; blocked=${observability.dag.blockedIds.join(", ") || "none"}`,
+        `  Cost: tokens=${resourceUsageLabel(observability.cost.tokens, undefined, observability.cost.tokensObservable)}; tools=${resourceUsageLabel(observability.cost.toolCalls, undefined, observability.cost.toolCallsObservable)}; wall=${observability.cost.wallClockSeconds}s; lanes=${observability.cost.laneCount}; groups=${observability.cost.groupCount}; retries=${observability.cost.retryCount}; marginal-value=unavailable`,
+        `  Context: snapshots=${observability.context.snapshotCount}; bytes=${observability.context.totalBytes === null ? "partial" : observability.context.totalBytes}; peak-input=${observability.context.observedInputPeakTokens}; compression=unavailable`,
         ...(task.projectBindings.length === 0
             ? []
             : [
@@ -232,9 +247,12 @@ export function runTaskContextCommand(args, store) {
                     `    Writable Projects: ${item.writeProjectIds.length === 0
                         ? "none"
                         : item.writeProjectIds.join(", ")}`,
+                    ...(observability.workItems.find(({ workItemId }) => workItemId === item.id) === undefined
+                        ? []
+                        : [renderWorkItemObservability(observability.workItems.find(({ workItemId }) => workItemId === item.id))]),
                     ...(currentWorkItemExecutionGroup(item) === undefined
                         ? []
-                        : renderExecutionGroup(currentWorkItemExecutionGroup(item))),
+                        : renderExecutionGroup(currentWorkItemExecutionGroup(item), executionGroupsById.get(currentWorkItemExecutionGroup(item).id))),
                     ...(item.acceptance.length === 0
                         ? []
                         : [`    Acceptance: ${item.acceptance.map(compactText).join("; ")}`]),
@@ -260,12 +278,12 @@ export function runTaskContextCommand(args, store) {
                                 ? []
                                 : [`      Summary: ${compactText(latestRun.summary)}`])
                         ]),
-                    ...renderReviewRounds(reviewRounds.filter((round) => round.workItemId === item.id))
+                    ...renderReviewRounds(reviewRounds.filter((round) => round.workItemId === item.id), executionGroupsById)
                 ];
             })),
         "",
         "Task-final reviews:",
-        ...renderReviewRounds(reviewRounds.filter((round) => (round.scope ?? "work-item") === "task")),
+        ...renderReviewRounds(reviewRounds.filter((round) => (round.scope ?? "work-item") === "task"), executionGroupsById),
         "",
         ...recentSection("AgentRuns", agentRuns, (run) => [
             `  ${run.id} [${run.status}/${run.purpose}] ${run.roleName} via ${run.effective.agentId}/${run.effective.adapterId}`,
@@ -362,7 +380,7 @@ function latestStallKind(events, runId) {
         .sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))[0];
     return event?.payload.kind ?? "workflow-not-progressing";
 }
-function renderReviewRounds(rounds) {
+function renderReviewRounds(rounds, executionGroupsById = new Map()) {
     const latest = rounds.at(-1);
     if (latest === undefined)
         return ["    ReviewRounds: none."];
@@ -406,7 +424,7 @@ function renderReviewRounds(rounds) {
             : [`      Review summary: ${compactText(latest.summary)}`]),
         ...(latest.executionGroup === undefined
             ? []
-            : renderExecutionGroup(latest.executionGroup).map((line) => `    ${line.trimStart()}`))
+            : renderExecutionGroup(latest.executionGroup, executionGroupsById.get(latest.executionGroup.id)).map((line) => `    ${line.trimStart()}`))
     ];
 }
 function renderResolvedInputRequest(request, timeZone) {
@@ -499,27 +517,51 @@ function managedWorkspaceLabel(workspace) {
             return `execution-lane ${workspace.owner.executionGroupId}/${workspace.owner.executionLaneId}`;
     }
 }
-function renderExecutionGroup(group) {
-    const summary = summarizeExecutionGroup(group);
+function renderExecutionGroup(group, projected) {
+    const summary = projected
+        ?? summarizeExecutionGroup(group);
+    const health = projected?.health;
+    const resources = projected?.resources;
     return [
-        `    Execution Group ${summary.groupId} [${summary.purpose}/${summary.strategy.mode}]: ${summary.activeLaneCount} active / ${summary.terminalLaneCount} terminal; ${summary.failedLaneCount} failed`,
-        ...summary.laneSummaries.flatMap((lane) => [
-            `      Lane ${lane.laneId} (#${lane.ordinal}, ${lane.roleName}) [${lane.status}]${lane.summary === undefined ? "" : `: ${compactText(lane.summary)}`}`,
-            ...(lane.report === undefined ? [] : [`        Report: ${compactText(lane.report)}`]),
-            ...(lane.checks === undefined || lane.checks.length === 0
-                ? []
-                : [`        Checks: ${lane.checks.map(({ name, outcome }) => `${name}:${outcome}`).join(", ")}`]),
-            ...(lane.findings === undefined || lane.findings.length === 0
-                ? []
-                : [`        Findings: ${lane.findings.map(({ id, severity, status }) => `${id}:${severity}/${status}`).join(", ")}`]),
-            ...(lane.evidence === undefined || lane.evidence.length === 0
-                ? []
-                : [`        Evidence: ${lane.evidence.length} item(s)`]),
-            ...(lane.evidenceCommit === undefined
-                ? []
-                : [`        Evidence commit: ${lane.evidenceCommit}`]),
-            ...(lane.decision === undefined ? [] : [`        Decision: ${lane.decision}`])
-        ]),
+        `    Execution Group ${summary.groupId} [${summary.purpose}/${summary.strategy.mode}]: ${summary.activeLaneCount} active / ${summary.terminalLaneCount} terminal; ${summary.failedLaneCount} failed; ${summary.skippedLaneCount} skipped`,
+        ...(health === undefined
+            ? []
+            : [
+                `      Health: active=${health.activeLaneCount}, silent=${health.silentLaneCount}, suspected-stalled=${health.suspectedStalledLaneCount}, confirmed-dead=${health.confirmedDeadLaneCount}`,
+                `      Recovery: reusable=${health.reusableLaneIds.length}, retryable=${health.retryableLaneIds.length}`
+            ]),
+        ...(resources === undefined
+            ? []
+            : [
+                `      Resources: tokens=${resourceUsageLabel(resources.tokens, resources.tokensRemaining, resources.tokensObservable)}; tools=${resourceUsageLabel(resources.toolCalls, resources.toolCallsRemaining, resources.toolCallsObservable)}; wall=${resources.wallClockSeconds}s${resources.wallClockSecondsRemaining === undefined ? "" : `, remaining=${resources.wallClockSecondsRemaining}s`}`,
+                `      Completion: usable=${resources.usableLaneCount}/${group.stage?.resources?.quorum ?? "legacy"}; quorum=${resources.quorumMet ? "met" : "open"}; deadline=${resources.deadlineReached ? "reached" : "open"}; budgets=${resources.exhaustedBudgets.join(",") || "open"}; queued=${resources.pendingLaneIds.length}; stragglers=${resources.stragglerLaneIds.length}`
+            ]),
+        ...summary.laneSummaries.flatMap((lane) => {
+            const laneHealth = projected?.laneSummaries.find(({ laneId }) => laneId === lane.laneId);
+            return [
+                `      Lane ${lane.laneId} (#${lane.ordinal}, ${lane.roleName}${lane.runId === undefined ? "" : `, run ${lane.runId}`}) [${lane.status}${laneHealth?.runtimeHealth === undefined ? "" : `/${laneHealth.runtimeHealth}`}]${lane.summary === undefined ? "" : `: ${compactText(lane.summary)}`}`,
+                ...(lane.effective === undefined
+                    ? []
+                    : [`        Config: ${lane.effective.adapterId}/${lane.effective.model ?? "default"}/${lane.effective.effort ?? "default"}; profile=${lane.effective.profileAccess}`]),
+                ...(laneHealth !== undefined && laneHealth.recovery !== "none"
+                    ? [`        Recovery: ${laneHealth.recovery}; ${compactText(laneHealth.reason)}`]
+                    : []),
+                ...(lane.report === undefined ? [] : [`        Report: ${compactText(lane.report)}`]),
+                ...(lane.checks === undefined || lane.checks.length === 0
+                    ? []
+                    : [`        Checks: ${lane.checks.map(({ name, outcome }) => `${name}:${outcome}`).join(", ")}`]),
+                ...(lane.findings === undefined || lane.findings.length === 0
+                    ? []
+                    : [`        Findings: ${lane.findings.map(({ id, severity, status }) => `${id}:${severity}/${status}`).join(", ")}`]),
+                ...(lane.evidence === undefined || lane.evidence.length === 0
+                    ? []
+                    : [`        Evidence: ${lane.evidence.length} item(s)`]),
+                ...(lane.evidenceCommit === undefined
+                    ? []
+                    : [`        Evidence commit: ${lane.evidenceCommit}`]),
+                ...(lane.decision === undefined ? [] : [`        Decision: ${lane.decision}`])
+            ];
+        }),
         ...(summary.openHighPriorityFindingIds.length === 0
             ? []
             : [`      Open high findings: ${summary.openHighPriorityFindingIds.join(", ")}`]),
@@ -528,3 +570,12 @@ function renderExecutionGroup(group) {
             : [`      Resolution: ${summary.resolution.decision} — ${compactText(summary.resolution.summary)}`])
     ];
 }
+function resourceUsageLabel(used, remaining, observable) {
+    if (!observable)
+        return `${used} observed (partial)`;
+    return `${used}${remaining === undefined ? "" : `, remaining=${remaining}`}`;
+}
+function renderWorkItemObservability(item) {
+    const stages = item.stages.map((stage) => (`${stage.stage ?? "single"}${stage.round === undefined ? "" : `#${stage.round}`}${stage.stageAttempt === undefined ? "" : `/a${stage.stageAttempt}`}`)).join(", ");
+    return `    Observability: stages=${stages || "none"}; tokens=${item.cost.tokens}; tools=${item.cost.toolCalls}; wall=${item.cost.wallClockSeconds}s; retries=${item.cost.retryCount}; snapshots=${item.context.snapshotCount}; peak-input=${item.context.observedInputPeakTokens}; evidence=${item.evidenceCount}; open-findings=${item.openFindingCount}; compression=${item.context.compressionStatus}`;
+}

package/dist/commands/taskNextActionCommand.js

@@ -4,6 +4,8 @@ import { projectCompletionReadiness } from "../task/completionReadiness.js";
 import { extractReviewFindings, planRepairWave } from "../task/repairWave.js";
 import { projectTaskOrchestration } from "../observability/orchestrationMetrics.js";
 import { operationalTaskRecords } from "../task/taskRecordRetirement.js";
+import { buildTaskExecutionProjection } from "../scheduler/taskExecutionProjection.js";
+import { projectExecutionLaneRunRecoveries } from "../run/recoveryProjection.js";
 /**
  * Issue 07 (Leader convergence): read-only `yui task next-action <task>`.
  * Folds the existing durable records into exactly one protocol-level next
@@ -24,6 +26,7 @@ export function runTaskNextActionCommand(args, store) {
         throw usageError(usage);
     }
     const taskId = positionals[0].trim();
+    const now = new Date();
     const data = store.transaction((reader) => {
         // Issue 06: the lightweight facts drive the action on every call; the
         // heavier readiness facts (full event fold, workspaces, jobs, ledger) are
@@ -32,8 +35,16 @@ export function runTaskNextActionCommand(args, store) {
         const facts = reader.readNextActionFacts(taskId);
         if (facts === null)
             throw taskNotFound(taskId);
-        const action = projectNextAction(facts);
-        const repairWave = repairWaveFor(action, facts);
+        const execution = buildTaskExecutionProjection(reader, taskId, undefined, now);
+        if (execution === null)
+            throw taskNotFound(taskId);
+        const actionFacts = {
+            ...facts,
+            executionGroups: execution.executionGroups,
+            runRecoveries: projectExecutionLaneRunRecoveries(reader, taskId, execution.executionGroups)
+        };
+        const action = projectNextAction(actionFacts);
+        const repairWave = repairWaveFor(action, actionFacts);
         // Issue 12: surface pending Knowledge promotion proposals for the Task's
         // bound Projects as a non-blocking advisory. The proposals are workflow
         // state, not completion blockers: an Operator reviews them separately.

package/dist/commands/taskOverviewCommand.js

@@ -4,6 +4,7 @@ import { formatTimestamp } from "../output/timePresentation.js";
 import { pendingWakeupProjection } from "../storage/taskStore.js";
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { projectTaskExecutionFromFacts } from "../scheduler/taskExecutionProjection.js";
+import { resolveRuntimeHealth } from "../config/yuiConfig.js";
 export function parseTaskListOptions(args) {
     const allowed = new Set(["--all", "--verbose"]);
     if (args.some((argument) => !allowed.has(argument))
@@ -15,10 +16,11 @@ export function parseTaskListOptions(args) {
         verbose: args.includes("--verbose")
     };
 }
-export function buildTaskOverview(store, options) {
+export function buildTaskOverview(store, options, now = new Date()) {
+    const runtimeHealthPolicy = resolveRuntimeHealth(store.getConfig().runtimeHealth);
     const tasks = store.listTasks()
         .filter((task) => options.all || task.status !== "archived")
-        .map((task) => buildTaskOverviewEntry(task, store));
+        .map((task) => buildTaskOverviewEntry(task, store, now, runtimeHealthPolicy));
     return { tasks };
 }
 export function renderTaskOverview(result, options, timeZone, width = defaultTableWidth()) {
@@ -52,7 +54,7 @@ export function renderTaskOverview(result, options, timeZone, width = defaultTab
         return `${output}\n`;
     return `${output}\n\n${renderVerboseDetails(result.tasks, timeZone)}\n`;
 }
-function buildTaskOverviewEntry(task, store) {
+function buildTaskOverviewEntry(task, store, now, runtimeHealthPolicy) {
     const brief = store.getTaskBrief(task.id);
     const roles = store.listRoles(task.id);
     const leaderRole = roles.find((role) => role.name === "leader") ?? null;
@@ -74,7 +76,7 @@ function buildTaskOverviewEntry(task, store) {
     });
     const attention = collectAttention(task, agentRuns, events, leaderFailure, operatorNotification);
     const blockers = collectBlockers(workItems, openInputRequests, attention);
-    const next = deriveNextAction(task, brief, workItems, openInputRequests, blockers, pendingWakeup);
+    const legacyNext = deriveNextAction(task, brief, workItems, openInputRequests, blockers, pendingWakeup);
     const leader = {
         role: "leader",
         roleStatus: leaderRole?.status ?? "missing",
@@ -118,8 +120,19 @@ function buildTaskOverviewEntry(task, store) {
         leaderMailbox,
         leaderFailure,
         operatorNotification,
-        roleSessions
+        roleSessions,
+        contextSnapshots: store.listContextSnapshots(task.id),
+        now,
+        runtimeHealthPolicy
     });
+    const next = execution.action === "recover-execution"
+        ? {
+            action: execution.action,
+            owner: execution.owner,
+            kind: "execution",
+            summary: execution.summary
+        }
+        : legacyNext;
     return {
         ...task,
         brief,
@@ -384,6 +397,9 @@ function renderVerboseDetails(tasks, timeZone) {
                 : formatTimestamp(task.summaryUpdatedAt, timeZone)}`,
             `  Execution: ${task.execution.status} (${task.execution.owner}); ${task.execution.summary}`,
             `  Monitoring: ${task.execution.monitoring}; attention: ${task.execution.attention.length}`,
+            `  DAG: ${task.execution.observability.dag.nodes.length} nodes, ${task.execution.observability.dag.edges.length} edges; ready=${task.execution.observability.dag.readyIds.join(", ") || "none"}; blocked=${task.execution.observability.dag.blockedIds.join(", ") || "none"}`,
+            `  Cost: tokens=${task.execution.observability.cost.tokens}${task.execution.observability.cost.tokensObservable ? "" : " (partial)"}; tools=${task.execution.observability.cost.toolCalls}${task.execution.observability.cost.toolCallsObservable ? "" : " (partial)"}; wall=${task.execution.observability.cost.wallClockSeconds}s; retries=${task.execution.observability.cost.retryCount}`,
+            `  Context: snapshots=${task.execution.observability.context.snapshotCount}; bytes=${task.execution.observability.context.totalBytes ?? "partial"}; peak-input=${task.execution.observability.context.observedInputPeakTokens}; compression=unavailable`,
             `  Projects: ${task.projectBindings.length === 0
                 ? "none"
                 : task.projectBindings.map(({ directory, projectId, baseRef }) => (`${directory} (${projectId} @ ${baseRef})`)).join(", ")}`

package/dist/commands/taskUpstreamCommands.js

@@ -0,0 +1,136 @@
+import { usageError } from "../errors/cliError.js";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { NodeGitWorkspace } from "../repository/gitWorkspace.js";
+import { acquireProjectMaintenanceLock } from "../repository/projectMaintenanceLock.js";
+import { workspaceProjectEntry } from "../worktree/managedWorkspace.js";
+export async function runTaskUpstreamCommand(args, store, options = {}) {
+    const [command, ...rest] = args;
+    if (command === "integrate") {
+        return integrateUpstream(rest, store, options);
+    }
+    throw usageError(command === undefined
+        ? "Task upstream command is required."
+        : `Unknown command: task upstream ${command}`);
+}
+async function integrateUpstream(args, store, options) {
+    const usage = "Task upstream integrate usage: yui task upstream integrate <task> [--latest] [--project <project>].";
+    const taskId = args[0];
+    if (taskId === undefined)
+        throw usageError(usage);
+    const flags = new Set(args.slice(1));
+    if (flags.size !== args.length - 1) {
+        throw usageError(usage);
+    }
+    const latest = flags.has("--latest");
+    const projectFlag = args.find((arg) => arg.startsWith("--project="));
+    const projectRef = projectFlag?.slice("--project=".length);
+    if (!latest && projectRef === undefined) {
+        throw usageError("Specify --latest to integrate the remote development head, or --project=<project> to target one Project.");
+    }
+    if (latest && projectRef !== undefined) {
+        throw usageError("--latest and --project are mutually exclusive.");
+    }
+    for (const flag of flags) {
+        if (flag !== "--latest" && !flag.startsWith("--project=")) {
+            throw usageError(usage);
+        }
+    }
+    const task = store.getTask(taskId);
+    if (task === null)
+        throw usageError(`Task not found: ${taskId}.`);
+    if (task.status !== "active") {
+        throw usageError(`Task must be active to integrate upstream: ${taskId}/${task.status}.`);
+    }
+    // RFC Phase 4: integrating upstream rewrites the Task worktree HEAD. Refuse
+    // while the Leader has an active Run so the merge never lands under a
+    // running Session.
+    const activeLeaderRun = store.getActiveAgentRun(taskId, "leader");
+    if (activeLeaderRun !== null) {
+        throw usageError(`Task has an active Leader Run (${activeLeaderRun.id}); stop it before integrating upstream: ${taskId}.`);
+    }
+    const workspace = store.getTaskWorkspace(taskId);
+    if (workspace === null) {
+        throw usageError(`Task has no workspace: ${taskId}. Activate it first.`);
+    }
+    const git = options.git ?? new NodeGitWorkspace();
+    const now = options.now ?? (() => new Date());
+    const results = [];
+    for (const binding of task.projectBindings) {
+        if (projectRef !== undefined && binding.projectId !== projectRef)
+            continue;
+        const project = store.getProject(binding.projectId);
+        if (project === null) {
+            throw usageError(`Project not found: ${binding.projectId}.`);
+        }
+        if (project.remoteUrl === undefined) {
+            throw usageError(`Project has no remote URL: ${project.id}.`);
+        }
+        const entry = workspaceProjectEntry(workspace, project.id);
+        if (entry === undefined) {
+            throw usageError(`Task workspace has no entry for Project: ${project.id}.`);
+        }
+        // Hold the per-Project maintenance fence while resolving the remote
+        // baseline so a concurrent `project refresh` cannot interleave with the
+        // fetch.
+        const releaseMaintenance = acquireProjectMaintenanceLock(store.rootDirectory(), project.id);
+        let oldHead;
+        let newHead;
+        let upstreamCommit;
+        try {
+            // Resolve the exact upstream commit.
+            const upstream = await git.resolveRemoteBaseline({
+                repositoryPath: project.path,
+                remoteUrl: project.remoteUrl,
+                developmentRef: project.developmentBranch
+            });
+            upstreamCommit = upstream.commit;
+            // Record the current HEAD as a backup before merging.
+            const current = await git.inspect(entry.path, "HEAD");
+            oldHead = current.baseCommit;
+            try {
+                // mergeWorktree always creates a merge commit (--no-ff); record the
+                // actual resulting HEAD rather than assuming a fast-forward.
+                await git.mergeWorktree({
+                    targetPath: entry.path,
+                    sourceRefs: [upstream.commit]
+                });
+            }
+            catch (error) {
+                // Restore the original HEAD on failure.  mergeWorktree already aborts
+                // a conflicted merge, so HEAD is usually already at oldHead; reset
+                // only when the merge left HEAD moved or the tree dirty.
+                let restoreNote;
+                try {
+                    await git.resetWorktree({
+                        targetPath: entry.path,
+                        expectedHead: oldHead,
+                        restoreHead: oldHead
+                    });
+                    restoreNote = ` The workspace has been restored to ${oldHead}.`;
+                }
+                catch {
+                    restoreNote = ` The workspace may be left in a conflicted state; inspect ${entry.path} manually.`;
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`Upstream integration failed for Project ${project.id}: ${message}.` + restoreNote);
+            }
+            const after = await git.inspect(entry.path, "HEAD");
+            newHead = after.baseCommit;
+        }
+        finally {
+            releaseMaintenance();
+        }
+        // Record the integration event immediately so a later Project's failure
+        // does not lose this Project's audit trail.
+        const result = { projectId: project.id, oldHead, newHead, upstreamCommit };
+        store.transaction((tx) => {
+            tx.saveEvent(task.id, createTaskEvent(tx.nextEventId(task.id), task.id, "task.upstream-integrated", result, now()));
+        });
+        results.push(result);
+    }
+    const lines = results.map((r) => `  ${r.projectId}: ${r.oldHead.slice(0, 12)} -> ${r.newHead.slice(0, 12)} (upstream: ${r.upstreamCommit.slice(0, 12)})`);
+    return {
+        output: `Integrated upstream for Task ${taskId}:\n${lines.join("\n")}\n`,
+        data: { taskId, integrations: results }
+    };
+}