@hyperdrive.bot/paseo-server 0.3.41 → 0.3.43

package/dist/server/server/workflow/workflow-progress.d.ts

@@ -86,10 +86,63 @@ export declare class WorkflowCycleError extends Error {
     readonly unresolved: string[];
     constructor(unresolved: string[]);
 }
+/**
+ * A graph that is malformed *before* dependencies are even considered: it declares no
+ * tasks at all, or it declares the same task id twice.
+ *
+ * Kept separate from {@link WorkflowCycleError} because neither defect is a dependency
+ * problem, and both callers (`session.ts` RPC, `mcp-server.ts` tool) forward
+ * `error.message` verbatim to a human - telling that human "dependency cycle" when the
+ * real defect is "you sent zero tasks" is the kind of message that costs an hour.
+ * `defect` is the stable discriminator; the message is the human-facing half.
+ */
+export declare class WorkflowInvalidGraphError extends Error {
+    readonly defect: "empty-graph" | "duplicate-task-id";
+    constructor(defect: "empty-graph" | "duplicate-task-id", message: string);
+}
 /**
  * Resolve the layered execution order for a graph. Prefer the graph's declared
  * `metadata.executionLayers`; otherwise compute layers from task dependencies.
  */
 export declare function resolveExecutionLayers(graph: TaskGraph): string[][];
+/**
+ * Assert that a task graph is schedulable: it declares at least one task, no task id is
+ * declared twice, every declared dependency names a task that exists in the graph, and
+ * the dependency relation is acyclic. Throws {@link WorkflowInvalidGraphError} for the
+ * two shape defects and {@link WorkflowCycleError} for the two dependency defects, on
+ * the first violation; returns `void` on success.
+ *
+ * WHY the shape defects are rejected here rather than tolerated: both produce a workflow
+ * that can never reach a terminal status, which is the exact failure this validator
+ * exists to prevent. An empty graph makes `startWorkflow` flip to `running`, spawn zero
+ * children and return - and `settleWorkflow` is only ever reached from a child terminal
+ * event, so with no children no event ever fires and the workflow sits `running`
+ * forever. Duplicate ids are worse than useless: two children spawn for one task id and
+ * the first of them to close settles the whole workflow to `completed` while its twin is
+ * still live, recording intent as fact. Neither is stopped downstream - the wire schema
+ * (`WorkflowTaskGraphSchema.tasks`) has no `.min(1)` and no uniqueness constraint - so
+ * submission time is the only place they can be stopped. The definition layer already
+ * rejects both (`steps: z.array(...).min(1)` and `collectDuplicateStepIds` in
+ * `protocol/src/workflow/definition.ts`); this closes the same two holes on the
+ * raw-graph path, which is the one the wire and the CLI can still reach directly.
+ *
+ * Pure: no I/O, no snapshot reads, no `Date` API (see the determinism rules above).
+ *
+ * WHY this cannot delegate to `resolveExecutionLayers`: that function (above) returns
+ * `graph.metadata.executionLayers` verbatim and unvalidated whenever it is non-empty,
+ * and `WorkflowTaskGraphSchema.metadata.executionLayers` is a REQUIRED wire field
+ * (`packages/protocol/src/messages.ts`), so every real graph carries declared layers and
+ * takes that branch. The Kahn check inside `computeLayersFromDependencies` therefore
+ * never runs for real traffic. This validator reads `TaskNode.dependencies` only and
+ * ignores the declared layering entirely, so a graph that *claims* to be layerable is
+ * still rejected when its dependencies say otherwise.
+ *
+ * It also deliberately does NOT share `computeLayersFromDependencies`' escape hatch
+ * (`|| !byId.has(dep)`, which treats an out-of-graph dependency as already satisfied).
+ * That clause is correct for the projection, which must keep layering graphs stored
+ * before this validator existed, and wrong for scheduling, where an out-of-graph
+ * dependency can never be met. Rejecting is done here, one level up, instead.
+ */
+export declare function assertSchedulableGraph(graph: TaskGraph): void;
 export {};
 //# sourceMappingURL=workflow-progress.d.ts.map

package/dist/server/server/workflow/workflow-progress.js

@@ -138,6 +138,23 @@ export class WorkflowCycleError extends Error {
         this.name = "WorkflowCycleError";
     }
 }
+/**
+ * A graph that is malformed *before* dependencies are even considered: it declares no
+ * tasks at all, or it declares the same task id twice.
+ *
+ * Kept separate from {@link WorkflowCycleError} because neither defect is a dependency
+ * problem, and both callers (`session.ts` RPC, `mcp-server.ts` tool) forward
+ * `error.message` verbatim to a human - telling that human "dependency cycle" when the
+ * real defect is "you sent zero tasks" is the kind of message that costs an hour.
+ * `defect` is the stable discriminator; the message is the human-facing half.
+ */
+export class WorkflowInvalidGraphError extends Error {
+    constructor(defect, message) {
+        super(message);
+        this.defect = defect;
+        this.name = "WorkflowInvalidGraphError";
+    }
+}
 /**
  * Resolve the layered execution order for a graph. Prefer the graph's declared
  * `metadata.executionLayers`; otherwise compute layers from task dependencies.
@@ -175,4 +192,83 @@ function computeLayersFromDependencies(tasks) {
     }
     return layers;
 }
+/**
+ * Assert that a task graph is schedulable: it declares at least one task, no task id is
+ * declared twice, every declared dependency names a task that exists in the graph, and
+ * the dependency relation is acyclic. Throws {@link WorkflowInvalidGraphError} for the
+ * two shape defects and {@link WorkflowCycleError} for the two dependency defects, on
+ * the first violation; returns `void` on success.
+ *
+ * WHY the shape defects are rejected here rather than tolerated: both produce a workflow
+ * that can never reach a terminal status, which is the exact failure this validator
+ * exists to prevent. An empty graph makes `startWorkflow` flip to `running`, spawn zero
+ * children and return - and `settleWorkflow` is only ever reached from a child terminal
+ * event, so with no children no event ever fires and the workflow sits `running`
+ * forever. Duplicate ids are worse than useless: two children spawn for one task id and
+ * the first of them to close settles the whole workflow to `completed` while its twin is
+ * still live, recording intent as fact. Neither is stopped downstream - the wire schema
+ * (`WorkflowTaskGraphSchema.tasks`) has no `.min(1)` and no uniqueness constraint - so
+ * submission time is the only place they can be stopped. The definition layer already
+ * rejects both (`steps: z.array(...).min(1)` and `collectDuplicateStepIds` in
+ * `protocol/src/workflow/definition.ts`); this closes the same two holes on the
+ * raw-graph path, which is the one the wire and the CLI can still reach directly.
+ *
+ * Pure: no I/O, no snapshot reads, no `Date` API (see the determinism rules above).
+ *
+ * WHY this cannot delegate to `resolveExecutionLayers`: that function (above) returns
+ * `graph.metadata.executionLayers` verbatim and unvalidated whenever it is non-empty,
+ * and `WorkflowTaskGraphSchema.metadata.executionLayers` is a REQUIRED wire field
+ * (`packages/protocol/src/messages.ts`), so every real graph carries declared layers and
+ * takes that branch. The Kahn check inside `computeLayersFromDependencies` therefore
+ * never runs for real traffic. This validator reads `TaskNode.dependencies` only and
+ * ignores the declared layering entirely, so a graph that *claims* to be layerable is
+ * still rejected when its dependencies say otherwise.
+ *
+ * It also deliberately does NOT share `computeLayersFromDependencies`' escape hatch
+ * (`|| !byId.has(dep)`, which treats an out-of-graph dependency as already satisfied).
+ * That clause is correct for the projection, which must keep layering graphs stored
+ * before this validator existed, and wrong for scheduling, where an out-of-graph
+ * dependency can never be met. Rejecting is done here, one level up, instead.
+ */
+export function assertSchedulableGraph(graph) {
+    // Pass 0 - shape. Runs before anything reads `dependencies`, because a graph this
+    // malformed has no dependency verdict worth reporting.
+    if (graph.tasks.length === 0) {
+        throw new WorkflowInvalidGraphError("empty-graph", "Workflow task graph declares no tasks: a workflow must declare at least one task.");
+    }
+    // Built by hand rather than `new Map(graph.tasks.map(...))` precisely so the collision
+    // is observable: the Map constructor silently keeps the LAST entry for a repeated key,
+    // which is how a duplicate id survives every downstream check.
+    const byId = new Map();
+    for (const task of graph.tasks) {
+        if (byId.has(task.id)) {
+            throw new WorkflowInvalidGraphError("duplicate-task-id", `Workflow task graph declares duplicate task id: ${task.id}`);
+        }
+        byId.set(task.id, task);
+    }
+    // Pass 1 - dangling dependencies. Runs FIRST so a dependency on a task that does not
+    // exist is never misreported as a cycle. First offender in graph order, for a
+    // deterministic message.
+    for (const task of graph.tasks) {
+        for (const dep of task.dependencies) {
+            if (!byId.has(dep)) {
+                throw new WorkflowCycleError([`${task.id} -> ${dep}`]);
+            }
+        }
+    }
+    // Pass 2 - cycles. Kahn-style sweep over `dependencies` only; no out-of-graph escape,
+    // which is safe precisely because pass 1 proved every dependency is in-graph.
+    const resolved = new Set();
+    let remaining = graph.tasks;
+    while (remaining.length > 0) {
+        const layer = remaining.filter((task) => task.dependencies.every((dep) => resolved.has(dep)));
+        if (layer.length === 0) {
+            throw new WorkflowCycleError(remaining.map((task) => task.id));
+        }
+        for (const task of layer) {
+            resolved.add(task.id);
+        }
+        remaining = remaining.filter((task) => !resolved.has(task.id));
+    }
+}
 //# sourceMappingURL=workflow-progress.js.map

package/dist/server/server/workspace-directory.js

@@ -44,6 +44,28 @@ export function workspaceIdsOnCheckout(workspaces, cwd) {
         .filter((workspace) => !workspace.archivedAt && resolve(workspace.cwd) === resolvedCwd)
         .map((workspace) => workspace.workspaceId);
 }
+/**
+ * Build the bucket-derivation input for one agent snapshot.
+ *
+ * Exists so every call site in this file feeds `deriveAgentStateBucket` the
+ * SAME shape. It previously did not: two call sites hand-built the object and
+ * both omitted `activeChildCount`, so server-derived workspace buckets could
+ * never see armed background work while the app-side derivation could. The same
+ * agent then bucketed as "done" in the workspace list and "running" on its
+ * kanban card. One helper, one shape, no drift.
+ */
+function toBucketInput(agent) {
+    return {
+        status: agent.status,
+        pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
+        requiresAttention: agent.requiresAttention,
+        attentionReason: agent.attentionReason ?? null,
+        // Monitors, crons and backgrounded shells still alive on this agent. Live
+        // SUBAGENTS are not counted here — they arrive as their own snapshots and
+        // are attributed to the delegation root in applyAgentBucketContributions.
+        activeChildCount: agent.activeBackgroundTaskCount ?? 0,
+    };
+}
 export class WorkspaceDirectory {
     constructor(deps) {
         this.deps = deps;
@@ -166,15 +188,13 @@ export class WorkspaceDirectory {
                     continue;
                 }
                 workspaceAgent = parentAgent;
-                bucket = "running";
+                // A live subagent means the ROOT's own turn is not in flight — it is
+                // waiting on delegated work that will hand control back by itself.
+                // That is "pending", not "running"; see agent-state-bucket.ts.
+                bucket = "pending";
             }
             else {
-                bucket = deriveAgentStateBucket({
-                    status: agent.status,
-                    pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
-                    requiresAttention: agent.requiresAttention,
-                    attentionReason: agent.attentionReason ?? null,
-                });
+                bucket = deriveAgentStateBucket(toBucketInput(agent));
             }
             const workspaceId = workspaceAgent.workspaceId;
             if (!workspaceId) {
@@ -210,7 +230,10 @@ export class WorkspaceDirectory {
                 existing.status = bucket;
             }
             const entries = terminalEntriesByWorkspaceId.get(workspaceId) ?? [];
-            entries.push({ bucket, changedAtIso: new Date(activity.changedAt).toISOString() });
+            entries.push({
+                bucket,
+                changedAtIso: new Date(activity.changedAt).toISOString(),
+            });
             terminalEntriesByWorkspaceId.set(workspaceId, entries);
         }
         return terminalEntriesByWorkspaceId;
@@ -271,12 +294,7 @@ export class WorkspaceDirectory {
     findNewestTimestampInBucket(contributingAgents, terminalEntries, winningBucket) {
         const agentTimestamps = contributingAgents
             .filter((agent) => {
-            const derived = deriveAgentStateBucket({
-                status: agent.status,
-                pendingPermissionCount: agent.pendingPermissions?.length ?? 0,
-                requiresAttention: agent.requiresAttention,
-                attentionReason: agent.attentionReason ?? null,
-            });
+            const derived = deriveAgentStateBucket(toBucketInput(agent));
             return derived === winningBucket;
         })
             .map((agent) => {