pi-ultracode 0.1.3 → 0.3.0

package/src/workflow/admission.ts

@@ -0,0 +1,318 @@
+export const DEFAULT_MAX_AGENTS = 128;
+export const ABSOLUTE_MAX_AGENTS = 1024;
+export const MAX_ACTIVE_WORKFLOWS_PER_SESSION = 4;
+
+export const WORKFLOW_POLICY_ERROR_CODE = "WORKFLOW_POLICY_ERROR";
+export const WORKFLOW_ABORT_ERROR_CODE = "WORKFLOW_ABORTED";
+export const WORKFLOW_STALL_ERROR_CODE = "WORKFLOW_STALLED";
+export const WORKFLOW_CLEANUP_TIMEOUT_ERROR_CODE = "WORKFLOW_CLEANUP_TIMEOUT";
+
+export class WorkflowPolicyError extends Error {
+  readonly code = WORKFLOW_POLICY_ERROR_CODE;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowPolicyError";
+  }
+}
+
+export class WorkflowAbortError extends Error {
+  readonly code = WORKFLOW_ABORT_ERROR_CODE;
+
+  constructor(message = "workflow aborted") {
+    super(message);
+    this.name = "WorkflowAbortError";
+  }
+}
+
+export class WorkflowStallError extends Error {
+  readonly code = WORKFLOW_STALL_ERROR_CODE;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowStallError";
+  }
+}
+
+export class WorkflowCleanupTimeoutError extends Error {
+  readonly code = WORKFLOW_CLEANUP_TIMEOUT_ERROR_CODE;
+
+  constructor(timeoutMs: number) {
+    super(`workflow cleanup did not drain within ${timeoutMs}ms`);
+    this.name = "WorkflowCleanupTimeoutError";
+  }
+}
+
+export function isWorkflowPolicyError(error: unknown): error is WorkflowPolicyError {
+  return !!error && typeof error === "object" && (error as any).code === WORKFLOW_POLICY_ERROR_CODE;
+}
+
+export function isWorkflowAbortError(error: unknown): error is WorkflowAbortError {
+  return !!error && typeof error === "object" && (error as any).code === WORKFLOW_ABORT_ERROR_CODE;
+}
+
+export function isWorkflowStallError(error: unknown): error is WorkflowStallError {
+  return !!error && typeof error === "object" && (error as any).code === WORKFLOW_STALL_ERROR_CODE;
+}
+
+export function isWorkflowCleanupTimeoutError(error: unknown): error is WorkflowCleanupTimeoutError {
+  return !!error && typeof error === "object" && (error as any).code === WORKFLOW_CLEANUP_TIMEOUT_ERROR_CODE;
+}
+
+export function normalizeMaxAgents(value: unknown, name = "maxAgents"): number {
+  if (value === undefined || value === null) return DEFAULT_MAX_AGENTS;
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    throw new WorkflowPolicyError(`workflow ${name} must be an integer between 1 and ${ABSOLUTE_MAX_AGENTS}`);
+  }
+  if (value < 1 || value > ABSOLUTE_MAX_AGENTS) {
+    throw new WorkflowPolicyError(`workflow ${name} must be between 1 and ${ABSOLUTE_MAX_AGENTS} (got ${value})`);
+  }
+  return value;
+}
+
+export function normalizeReservationSize(value: unknown, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > ABSOLUTE_MAX_AGENTS) {
+    throw new WorkflowPolicyError(`parallel reserveAgents must be an integer between 0 and ${ABSOLUTE_MAX_AGENTS}`);
+  }
+  return value;
+}
+
+interface SlotEntry {
+  /**
+   * Return path for an unused slot. The first live reservation in this stack gets
+   * the slot back; if none remain, the slot returns to root capacity. This lets a
+   * nested panel transfer a sibling's branch slot without permanently stealing it
+   * from its immediate parent, while still preserving the parent's own upstream
+   * return path when that parent is released later.
+   */
+  returnStack: string[];
+}
+
+interface Reservation {
+  id: string;
+  slots: SlotEntry[];
+  contingentSlots: number;
+  contingentParentIds: string[];
+  released: boolean;
+}
+
+export interface PanelReservation {
+  panelReservationId: string;
+  branchReservationIds: string[];
+}
+
+export class AgentAdmission {
+  readonly maxAgents: number;
+  private rootFree: number;
+  private consumed = 0;
+  private nextReservation = 0;
+  private readonly reservations = new Map<string, Reservation>();
+
+  constructor(maxAgents: number, usedAgents = 0) {
+    this.maxAgents = normalizeMaxAgents(maxAgents);
+    if (!Number.isInteger(usedAgents) || usedAgents < 0 || usedAgents > this.maxAgents) {
+      throw new WorkflowPolicyError(
+        `workflow usedAgents must be an integer between 0 and maxAgents=${this.maxAgents}`,
+      );
+    }
+    this.consumed = usedAgents;
+    this.rootFree = this.maxAgents - usedAgents;
+  }
+
+  get usedAgents(): number {
+    return this.consumed;
+  }
+
+  get availableAgents(): number {
+    return this.rootFree;
+  }
+
+  reservePanel(requestedSlots: number, parentReservationIds: string[] = []): string {
+    const slots = normalizeReservationSize(requestedSlots, requestedSlots);
+    const parents = this.uniqueReservations(parentReservationIds);
+    const parentFree = parents.reduce((sum, reservation) => sum + reservation.slots.length, 0);
+    const totalFree = parentFree + this.rootFree;
+    if (totalFree < slots) {
+      throw new WorkflowPolicyError(
+        `parallel() needs ${slots} agent slot(s), but only ${totalFree} remain under maxAgents=${this.maxAgents}`,
+      );
+    }
+
+    const entries: SlotEntry[] = [];
+    let remaining = slots;
+    for (const parent of parents) {
+      while (remaining > 0 && parent.slots.length > 0) {
+        const slot = parent.slots.shift()!;
+        entries.push({ returnStack: [parent.id, ...slot.returnStack] });
+        remaining--;
+      }
+      if (remaining === 0) break;
+    }
+    if (remaining > 0) {
+      this.rootFree -= remaining;
+      for (let i = 0; i < remaining; i++) entries.push({ returnStack: [] });
+    }
+
+    return this.createReservation(entries).id;
+  }
+
+  reservePanelWithBranchNeeds(
+    requestedSlots: number,
+    branchNeedsSlot: boolean[],
+    parentReservationIds: string[] = [],
+    contingentSlots = 0,
+  ): PanelReservation {
+    const branchCount = branchNeedsSlot.length;
+    const requiredBranches = branchNeedsSlot.filter(Boolean).length;
+    const slots = normalizeReservationSize(requestedSlots, requestedSlots);
+    if (branchCount > ABSOLUTE_MAX_AGENTS) {
+      throw new WorkflowPolicyError(`parallel branch count must be at most ${ABSOLUTE_MAX_AGENTS}`);
+    }
+    if (slots < requiredBranches) {
+      throw new WorkflowPolicyError(
+        `parallel replay needs at least ${requiredBranches} live branch slot(s); got ${slots}`,
+      );
+    }
+    const contingent = normalizeReservationSize(contingentSlots, contingentSlots);
+    const panelReservationId = this.reservePanel(slots, parentReservationIds);
+    const panelReservation = this.requireReservation(panelReservationId);
+    panelReservation.contingentSlots = contingent;
+    panelReservation.contingentParentIds = [...parentReservationIds];
+    const branchReservationIds: string[] = [];
+    try {
+      for (const needsSlot of branchNeedsSlot) {
+        branchReservationIds.push(this.reservePanel(needsSlot ? 1 : 0, [panelReservationId]));
+      }
+      return { panelReservationId, branchReservationIds };
+    } catch (error) {
+      for (const id of branchReservationIds) this.releasePanel(id);
+      this.releasePanel(panelReservationId);
+      throw error;
+    }
+  }
+
+  reservePanelWithBranches(
+    requestedSlots: number,
+    branchCount: number,
+    parentReservationIds: string[] = [],
+  ): PanelReservation {
+    const slots = normalizeReservationSize(requestedSlots, requestedSlots);
+    if (!Number.isInteger(branchCount) || branchCount < 0 || branchCount > ABSOLUTE_MAX_AGENTS) {
+      throw new WorkflowPolicyError(`parallel branch count must be an integer between 0 and ${ABSOLUTE_MAX_AGENTS}`);
+    }
+    if (slots < branchCount) {
+      throw new WorkflowPolicyError(
+        `parallel reserveAgents must be at least the number of thunks (${branchCount}); got ${slots}`,
+      );
+    }
+
+    const panelReservationId = this.reservePanel(slots, parentReservationIds);
+    const branchReservationIds: string[] = [];
+    try {
+      for (let i = 0; i < branchCount; i++) {
+        branchReservationIds.push(this.reservePanel(1, [panelReservationId]));
+      }
+      return { panelReservationId, branchReservationIds };
+    } catch (error) {
+      for (const id of branchReservationIds) this.releasePanel(id);
+      this.releasePanel(panelReservationId);
+      throw error;
+    }
+  }
+
+  releasePanel(id: string): void {
+    const reservation = this.reservations.get(id);
+    if (!reservation || reservation.released) return;
+    reservation.released = true;
+    for (const slot of reservation.slots) this.returnSlot(slot);
+    reservation.slots = [];
+    this.reservations.delete(id);
+  }
+
+  consumeAgent(reservationIds: string[] = []): number {
+    const reservations = this.uniqueReservations(reservationIds);
+    for (const reservation of reservations) {
+      if (reservation.slots.length > 0) {
+        reservation.slots.shift();
+        this.consumed++;
+        return this.consumed;
+      }
+    }
+    for (const reservation of reservations) {
+      if (reservation.contingentSlots > 0 && this.acquireContingentSlot(reservation)) {
+        reservation.contingentSlots--;
+        this.consumed++;
+        return this.consumed;
+      }
+    }
+    if (reservationIds.length > 0) {
+      throw new WorkflowPolicyError(
+        "parallel() reservation has no agent slots left; increase reserveAgents for this panel or lower fan-out",
+      );
+    }
+    if (this.rootFree < 1) {
+      throw new WorkflowPolicyError(`workflow exceeded maxAgents=${this.maxAgents} (no agent slots remain)`);
+    }
+    this.rootFree--;
+    this.consumed++;
+    return this.consumed;
+  }
+
+  private createReservation(slots: SlotEntry[]): Reservation {
+    const id = `res_${++this.nextReservation}`;
+    const reservation: Reservation = {
+      id,
+      slots,
+      contingentSlots: 0,
+      contingentParentIds: [],
+      released: false,
+    };
+    this.reservations.set(id, reservation);
+    return reservation;
+  }
+
+  private uniqueReservations(ids: string[]): Reservation[] {
+    const out: Reservation[] = [];
+    const seen = new Set<string>();
+    for (const id of ids) {
+      if (!id || seen.has(id)) continue;
+      seen.add(id);
+      out.push(this.requireReservation(id));
+    }
+    return out;
+  }
+
+  private requireReservation(id: string): Reservation {
+    const reservation = this.reservations.get(id);
+    if (!reservation || reservation.released) {
+      throw new WorkflowPolicyError(`unknown or expired parallel reservation: ${id}`);
+    }
+    return reservation;
+  }
+
+  private acquireContingentSlot(reservation: Reservation): boolean {
+    for (const parent of this.uniqueReservations(reservation.contingentParentIds)) {
+      if (parent.slots.length === 0) continue;
+      parent.slots.shift();
+      return true;
+    }
+    if (this.rootFree < 1) return false;
+    this.rootFree--;
+    return true;
+  }
+
+  private returnSlot(slot: SlotEntry): void {
+    const [targetId, ...rest] = slot.returnStack;
+    if (!targetId) {
+      this.rootFree++;
+      return;
+    }
+    const target = this.reservations.get(targetId);
+    if (target && !target.released) {
+      target.slots.push({ returnStack: rest });
+      return;
+    }
+    this.returnSlot({ returnStack: rest });
+  }
+}

package/src/workflow/agent-runner.ts

@@ -310,6 +310,7 @@ export class WorkflowAgentRunner {
       sessionManager: SessionManager.inMemory(cwd),
       settingsManager: SettingsManager.create(cwd, agentDir),
       customTools,
+      excludeTools: ["workflow"],
       ...(model ? { model: model as any } : {}),
       ...(level ? { thinkingLevel: level as any } : {}),
       ...(toolAllowlist ? { tools: toolAllowlist } : {}),

package/src/workflow/display.ts

@@ -31,6 +31,8 @@ export interface WorkflowAgentUsageSnapshot {
 
 export interface WorkflowAgentSnapshot {
   id: number;
+  /** Stable orchestration identity; display order continues to use id. */
+  callPath?: string;
   label: string;
   phase?: string;
   workflowPath?: string[];
@@ -84,16 +86,19 @@ export interface WorkflowSnapshot {
   spentTokens: number;
   newTokens: number;
   replayedTokens: number;
+  /** Effective logical agent-slot cap for this run; usage-only, not a token budget. */
+  maxAgents?: number;
+  /** Lifetime live-agent admissions across resume generations. */
+  agentsUsed?: number;
   /** Sanitized session-scoped workflow detail manifest for headless consumers. */
   detailsManifestPath?: string;
-  budgetTotal: number | null;
   durationMs?: number;
   result?: unknown;
   status: "running" | "completed" | "aborted" | "failed";
 }
 
 export interface RenderOptions {
-  maxAgents?: number;
+  maxAgentRows?: number;
   maxLogs?: number;
   showResultPreviews?: boolean;
   /** @deprecated No-op retained for source compatibility. */
@@ -102,7 +107,7 @@ export interface RenderOptions {
   now?: number;
 }
 
-export function createSnapshot(meta: WorkflowMeta, runId: string, budgetTotal: number | null): WorkflowSnapshot {
+export function createSnapshot(meta: WorkflowMeta, runId: string): WorkflowSnapshot {
   return {
     runId,
     name: safeDisplayText(meta.name, 120) || "workflow",
@@ -119,7 +124,6 @@ export function createSnapshot(meta: WorkflowMeta, runId: string, budgetTotal: n
     spentTokens: 0,
     newTokens: 0,
     replayedTokens: 0,
-    budgetTotal,
     status: "running",
   };
 }
@@ -134,7 +138,7 @@ export function recompute(snapshot: WorkflowSnapshot): WorkflowSnapshot {
 }
 
 export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: RenderOptions = {}): string[] {
-  const maxAgents = options.maxAgents ?? 6;
+  const maxAgentRows = options.maxAgentRows ?? 6;
   const maxLogs = options.maxLogs ?? 2;
   const showResultPreviews = options.showResultPreviews ?? false;
   const now = options.now ?? Date.now();
@@ -145,9 +149,6 @@ export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: RenderO
     : snapshot.spentTokens
       ? ` · ${formatTokens(snapshot.spentTokens)} output token`
       : "";
-  const budget = snapshot.budgetTotal
-    ? ` · ${formatTokens(snapshot.spentTokens)}/${formatTokens(snapshot.budgetTotal)} out`
-    : "";
   const stateParts = [
     snapshot.runningCount > 0 ? `${snapshot.runningCount} running` : undefined,
     snapshot.errorCount > 0 ? `${snapshot.errorCount} errors` : undefined,
@@ -155,7 +156,10 @@ export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: RenderO
   ].filter(Boolean);
   const state = stateParts.length ? `, ${stateParts.join(", ")}` : "";
   const cached = snapshot.cachedCount ? ` · ${snapshot.cachedCount} cached` : "";
-  const header = `◆ ${statusMark(snapshot.status)} ${shorten(snapshot.name, 60)} (${snapshot.doneCount}/${snapshot.agentCount} done${state})${cached}${tokens}${budget}`;
+  const agentSlots = snapshot.maxAgents
+    ? ` · agents ${snapshot.agentsUsed ?? snapshot.agentCount}/${snapshot.maxAgents}`
+    : "";
+  const header = `◆ ${statusMark(snapshot.status)} ${shorten(snapshot.name, 60)} (${snapshot.doneCount}/${snapshot.agentCount} done${state})${cached}${agentSlots}${tokens}`;
   const lines = [header];
 
   const phaseNames = unique([
@@ -186,19 +190,19 @@ export function renderWorkflowLines(snapshot: WorkflowSnapshot, options: RenderO
     lines.push(
       `  ${marker} ${shorten(phase, 60)} ${done}/${agents.length}${running ? ` · ${running} running` : ""}${errors ? ` · ${errors} errors` : ""}${cancelled ? ` · ${cancelled} cancelled` : ""}`,
     );
-    for (const agent of agents.slice(-maxAgents)) {
+    for (const agent of agents.slice(-maxAgentRows)) {
       lines.push(...renderAgentLines(agent, { showResultPreviews, now }));
     }
-    if (agents.length > maxAgents) lines.push(`    … ${agents.length - maxAgents} earlier agents`);
+    if (agents.length > maxAgentRows) lines.push(`    … ${agents.length - maxAgentRows} earlier agents`);
   }
 
   const unphased = snapshot.agents.filter((a) => !rendered.has(a));
   if (unphased.length) {
     lines.push("  (unphased)");
-    for (const agent of unphased.slice(-maxAgents)) {
+    for (const agent of unphased.slice(-maxAgentRows)) {
       lines.push(...renderAgentLines(agent, { showResultPreviews, now }));
     }
-    if (unphased.length > maxAgents) lines.push(`    … ${unphased.length - maxAgents} earlier agents`);
+    if (unphased.length > maxAgentRows) lines.push(`    … ${unphased.length - maxAgentRows} earlier agents`);
   }
 
   for (const log of snapshot.logs.slice(-maxLogs)) lines.push(`  log: ${shorten(log, 100)}`);

package/src/workflow/json-schema.ts

@@ -3,15 +3,21 @@
  * `agent(prompt, { schema })`) into a TypeBox `TSchema` so Pi can both validate
  * the subagent's structured output and serialize a faithful tool schema to the model.
  *
- * Covers the common JSON Schema subset; anything unrecognized falls back to
- * `Type.Unsafe`, which preserves the raw schema for the model without crashing.
+ * Covers the explicitly validated workflow JSON Schema subset. Unsupported
+ * keywords are rejected before conversion rather than silently weakened.
  */
 
 import { Type, type TSchema } from "typebox";
+import { assertWorkflowSchemaLimit } from "./value-limits.ts";
 
 type Json = Record<string, any>;
 
 export function jsonSchemaToTypeBox(schema: unknown): TSchema {
+  assertWorkflowSchemaLimit(schema);
+  return convertJsonSchema(schema);
+}
+
+function convertJsonSchema(schema: unknown): TSchema {
   if (!schema || typeof schema !== "object") {
     // No constraints -> accept anything.
     return Type.Unsafe<unknown>({});
@@ -21,27 +27,29 @@ export function jsonSchemaToTypeBox(schema: unknown): TSchema {
 
   // Composite keywords first.
   if (Array.isArray(node.enum)) {
-    const literals = node.enum.map((value: unknown) => Type.Literal(value as any));
-    return withAnnotations(literals.length === 1 ? literals[0] : Type.Union(literals), annotations);
+    return withAnnotations(Type.Unsafe<unknown>({
+      ...(node.type !== undefined ? { type: node.type } : {}),
+      enum: node.enum,
+    }), annotations);
   }
   if ("const" in node) {
-    return withAnnotations(Type.Literal(node.const), annotations);
+    return withAnnotations(Type.Unsafe<unknown>({
+      ...(node.type !== undefined ? { type: node.type } : {}),
+      const: node.const,
+    }), annotations);
   }
   if (Array.isArray(node.anyOf)) {
-    return withAnnotations(Type.Union(node.anyOf.map(jsonSchemaToTypeBox)), annotations);
-  }
-  if (Array.isArray(node.oneOf)) {
-    return withAnnotations(Type.Union(node.oneOf.map(jsonSchemaToTypeBox)), annotations);
+    return withAnnotations(Type.Union(node.anyOf.map(convertJsonSchema)), annotations);
   }
   if (Array.isArray(node.allOf)) {
-    return withAnnotations(Type.Intersect(node.allOf.map(jsonSchemaToTypeBox)), annotations);
+    return withAnnotations(Type.Intersect(node.allOf.map(convertJsonSchema)), annotations);
   }
 
   const type = node.type;
   if (Array.isArray(type)) {
     // e.g. ["string", "null"]
     return withAnnotations(
-      Type.Union(type.map((t: string) => jsonSchemaToTypeBox({ ...node, type: t, enum: undefined }))),
+      Type.Union(type.map((t: string) => convertJsonSchema({ ...node, type: t, enum: undefined }))),
       annotations,
     );
   }
@@ -70,33 +78,47 @@ export function jsonSchemaToTypeBox(schema: unknown): TSchema {
 }
 
 function objectSchema(node: Json): TSchema {
-  const properties: Record<string, TSchema> = {};
+  const properties: Record<string, TSchema> = Object.create(null);
   const required: string[] = Array.isArray(node.required) ? node.required : [];
   const props = (node.properties ?? {}) as Json;
   for (const [key, value] of Object.entries(props)) {
-    const child = jsonSchemaToTypeBox(value);
+    const child = convertJsonSchema(value);
     properties[key] = required.includes(key) ? child : Type.Optional(child);
   }
   const options: Json = {};
   if (node.additionalProperties === false) options.additionalProperties = false;
   else if (node.additionalProperties && typeof node.additionalProperties === "object") {
-    options.additionalProperties = jsonSchemaToTypeBox(node.additionalProperties);
+    options.additionalProperties = convertJsonSchema(node.additionalProperties);
   }
   return Type.Object(properties, options);
 }
 
 function arraySchema(node: Json): TSchema {
-  const items = node.items ? jsonSchemaToTypeBox(Array.isArray(node.items) ? node.items[0] : node.items) : Type.Unknown();
   const options: Json = {};
   if (typeof node.minItems === "number") options.minItems = node.minItems;
   if (typeof node.maxItems === "number") options.maxItems = node.maxItems;
   if (node.uniqueItems === true) options.uniqueItems = true;
-  return Type.Array(items, options);
+  if (Array.isArray(node.items)) {
+    return Type.Tuple(node.items.map(convertJsonSchema), {
+      ...options,
+      additionalItems: true,
+      minItems: options.minItems ?? 0,
+    });
+  }
+  return Type.Array(node.items ? convertJsonSchema(node.items) : Type.Unknown(), options);
 }
 
 function numericAndStringConstraints(node: Json): Json {
   const out: Json = {};
-  for (const key of ["minimum", "maximum", "minLength", "maxLength", "pattern", "format"]) {
+  for (const key of [
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "multipleOf",
+    "minLength",
+    "maxLength",
+  ]) {
     if (node[key] !== undefined) out[key] = node[key];
   }
   return out;

package/src/workflow/leases.ts

@@ -0,0 +1,60 @@
+import * as path from "node:path";
+import { MAX_ACTIVE_WORKFLOWS_PER_SESSION, WorkflowPolicyError } from "./admission.ts";
+
+interface ScopeState {
+  activeRunIds: Set<string>;
+}
+
+const scopes = new Map<string, ScopeState>();
+
+export interface WorkflowLease {
+  readonly runsDir: string;
+  readonly runId: string;
+  release(): void;
+}
+
+export function acquireWorkflowLease(runsDir: string, runId: string): WorkflowLease {
+  const key = normalizeScope(runsDir);
+  let state = scopes.get(key);
+  if (!state) {
+    state = { activeRunIds: new Set() };
+    scopes.set(key, state);
+  }
+  if (state.activeRunIds.has(runId)) {
+    throw new WorkflowPolicyError(`workflow runId ${runId} is already active in this session`);
+  }
+  if (state.activeRunIds.size >= MAX_ACTIVE_WORKFLOWS_PER_SESSION) {
+    throw new WorkflowPolicyError(
+      `too many active workflows in this session (${state.activeRunIds.size}/${MAX_ACTIVE_WORKFLOWS_PER_SESSION}); wait for one to finish`,
+    );
+  }
+  state.activeRunIds.add(runId);
+  let released = false;
+  return {
+    runsDir: key,
+    runId,
+    release() {
+      if (released) return;
+      released = true;
+      const current = scopes.get(key);
+      current?.activeRunIds.delete(runId);
+      if (current && current.activeRunIds.size === 0) scopes.delete(key);
+    },
+  };
+}
+
+export function activeWorkflowCount(runsDir: string): number {
+  return scopes.get(normalizeScope(runsDir))?.activeRunIds.size ?? 0;
+}
+
+export function clearWorkflowLeasesForTests(): void {
+  scopes.clear();
+}
+
+function normalizeScope(runsDir: string): string {
+  try {
+    return path.resolve(runsDir);
+  } catch {
+    return runsDir;
+  }
+}