@hasna/loops 0.4.11 → 0.4.13

package/dist/lib/mode.js

@@ -2,7 +2,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.11",
+  version: "0.4.13",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -193,6 +193,50 @@ function sourceOfTruthForMode(mode) {
     return "self_hosted_control_plane";
   return "cloud_control_plane";
 }
+var ROUTE_ADMISSION_GATES = [
+  "max_dispatch",
+  "max_active",
+  "max_active_per_project",
+  "max_active_per_project_group",
+  "max_active_scope",
+  "max_per_profile"
+];
+function remoteSchedulerBackendForMode(mode, config) {
+  if (mode === "local")
+    return "none";
+  if (mode === "cloud")
+    return config.cloudApiUrl ? "hosted_control_plane_contract" : "unconfigured";
+  if (config.databaseUrlPresent)
+    return "postgres_contract";
+  if (config.apiUrl)
+    return "api_control_plane_contract";
+  return "unconfigured";
+}
+function schedulerStateForMode(args) {
+  const nonLocal = args.deploymentMode !== "local";
+  return {
+    authority: args.sourceOfTruth,
+    localStore: {
+      backend: "sqlite",
+      role: args.localRole,
+      runArtifacts: "local_files",
+      routeAdmissionState: "workflow_work_items"
+    },
+    remoteStore: {
+      backend: remoteSchedulerBackendForMode(args.deploymentMode, args.config),
+      configured: nonLocal && args.controlPlaneConfigured,
+      applySupported: false,
+      objectArtifacts: nonLocal ? "object_store_contract" : "none",
+      mutatesAws: false
+    },
+    routeAdmission: {
+      stateStore: nonLocal ? "control_plane_contract" : "local_sqlite",
+      activeStatuses: ["admitted", "running"],
+      gates: ROUTE_ADMISSION_GATES,
+      dryRunEvaluatesLiveCounts: false
+    }
+  };
+}
 function displayControlPlaneUrl(value) {
   if (!value)
     return;
@@ -218,6 +262,9 @@ function buildDeploymentStatus(opts = {}) {
   if (deploymentMode === "self_hosted" && !controlPlaneConfigured) {
     warnings.push("self_hosted mode needs LOOPS_API_URL or LOOPS_DATABASE_URL before it can become authoritative");
   }
+  if (deploymentMode === "self_hosted" && config.databaseUrlPresent && !config.apiUrl) {
+    warnings.push("LOOPS_DATABASE_URL selects the self_hosted storage contract; loops-runner still needs LOOPS_API_URL to claim remote work");
+  }
   if (deploymentMode === "cloud" && config.apiUrl && !config.cloudApiUrl) {
     warnings.push("LOOPS_API_URL selects self_hosted; cloud mode uses LOOPS_CLOUD_API_URL");
   }
@@ -251,6 +298,13 @@ function buildDeploymentStatus(opts = {}) {
       required: deploymentMode !== "local",
       role: deploymentMode === "local" ? "daemon" : "control_plane_worker"
     },
+    schedulerState: schedulerStateForMode({
+      deploymentMode,
+      sourceOfTruth: sourceOfTruthForMode(deploymentMode),
+      localRole: deploymentMode === "local" ? "authoritative" : "cache_and_spool",
+      controlPlaneConfigured,
+      config
+    }),
     warnings
   };
 }
@@ -263,6 +317,7 @@ function deploymentStatusLine(status) {
     `source=${status.deploymentModeSource}`,
     `truth=${status.sourceOfTruth}`,
     `local=${status.localStore.role}`,
+    `scheduler=${status.schedulerState.routeAdmission.stateStore}`,
     `control_plane=${configured}`
   ].join(" ");
 }

package/dist/lib/route/profile-pool.d.ts

@@ -0,0 +1,60 @@
+import type { AgentWorkflowRole } from "../template-kit.js";
+/**
+ * Least-loaded auth-profile pool selection + a `--max-per-profile` admission
+ * guard. Drain dispatch used to pick a pool member by a pure FNV-1a hash of the
+ * work-item seed (worker=pool[i], verifier=i+1, planner=i+2), with no awareness
+ * of how many runs each subscription account was already carrying. At high
+ * concurrency that stacked several concurrent workers on one ChatGPT account and
+ * tripped the provider-side 429/stream-drop wall. This module spreads work to
+ * the least-loaded account instead, and defers a route when every pool member is
+ * already saturated.
+ *
+ * The hash order is preserved as the deterministic tie-break: with equal load
+ * counts (e.g. a cold store) the selection is byte-for-byte identical to the old
+ * behaviour, so it is fully reproducible and does not perturb rendered-template
+ * snapshots.
+ */
+/** FNV-1a index into a pool of `size`. Shared by the deterministic default
+ *  (templates) and the least-loaded tie-break so the two never drift. */
+export declare function stableIndex(seed: string, size: number): number;
+/** Historical per-role offset from the worker index (worker+0, verifier+1,
+ *  planner+2, everything else +3). Kept identical to the original rolePoolValue
+ *  so equal-load selection reproduces the legacy assignment. */
+export declare function poolRoleOffset(role: AgentWorkflowRole): number;
+/**
+ * Pick the least-loaded pool member. Selection key, minimised lexicographically:
+ *   1. not in `exclude` before excluded (so verifier/planner land on a DIFFERENT
+ *      profile than the worker whenever the pool is large enough),
+ *   2. lower running-step load,
+ *   3. deterministic order starting at `anchor` (first encountered wins ties).
+ * When every member is excluded (pool smaller than the number of roles) the
+ * exclusion is ignored and pure least-loaded/tie-break applies.
+ */
+export declare function selectLeastLoadedProfile(pool: string[], loadCounts: Record<string, number>, anchor: number, exclude: ReadonlySet<string>): string;
+export interface PoolAuthProfileAssignmentInput {
+    pool: string[];
+    seed: string;
+    loadCounts: Record<string, number>;
+    /** Defer the whole route when EVERY pool member already has >= K running
+     *  steps. Undefined disables the guard (spread only, never defer). */
+    maxPerProfile?: number;
+    /** Roles present in the workflow that draw from the pool. */
+    roles: AgentWorkflowRole[];
+}
+export interface PoolAuthProfileAssignment {
+    /** Chosen auth profile per role. Empty when deferred. */
+    profiles: Partial<Record<AgentWorkflowRole, string>>;
+    /** True when the max-per-profile guard fired: every pool member is saturated. */
+    deferred: boolean;
+    reason?: string;
+    /** Minimum running-step load across the pool at decision time (attribution). */
+    minLoad: number;
+}
+/**
+ * Assign one pool member per role: the worker takes the globally least-loaded
+ * account; verifier/planner/triage each take the least-loaded account not
+ * already claimed by an earlier role (so reviews run on a different subscription
+ * than the work they review). Returns `deferred` when the max-per-profile guard
+ * fires so the caller can hold the route until an account frees up.
+ */
+export declare function assignPoolAuthProfiles(input: PoolAuthProfileAssignmentInput): PoolAuthProfileAssignment;

package/dist/lib/route/throttle.d.ts

@@ -28,6 +28,7 @@ export declare function routeProjectGroup(optsGroup: string | undefined, data: R
 export declare function routeThrottleDecision(store: Store, args: {
     projectPath: string;
     projectGroup?: string;
+    routeScope?: string;
     limits: RouteThrottleLimits;
 }): RouteThrottleDecision;
 export declare function routeThrottleDryRunPreview(args: {

package/dist/lib/route/types.d.ts

@@ -32,6 +32,8 @@ export interface TodosTaskRouteOptions {
     maxActive?: string;
     maxActivePerProject?: string;
     maxActivePerProjectGroup?: string;
+    maxActiveScope?: string;
+    maxPerProfile?: string;
     worktreeMode?: string;
     worktreeRoot?: string;
     worktreeBranchPrefix?: string;

package/dist/lib/storage/index.js

@@ -1321,6 +1321,7 @@ function rowToWorkflowWorkItem(row) {
     subjectRef: row.subject_ref,
     projectKey: row.project_key ?? undefined,
     projectGroup: row.project_group ?? undefined,
+    routeScope: row.route_scope ?? undefined,
     priority: row.priority,
     status: row.status,
     attempts: row.attempts,
@@ -1601,6 +1602,13 @@ class Store {
           this.addColumnIfMissing("loop_runs", "claim_token", "TEXT");
           this.db.exec("CREATE INDEX IF NOT EXISTS idx_runs_claim_token ON loop_runs(claim_token) WHERE claim_token IS NOT NULL");
         }
+      },
+      {
+        id: "0008_work_item_route_scope",
+        apply: () => {
+          this.addColumnIfMissing("workflow_work_items", "route_scope", "TEXT");
+          this.db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status)");
+        }
       }
     ];
   }
@@ -1748,6 +1756,7 @@ class Store {
         subject_ref TEXT NOT NULL,
         project_key TEXT,
         project_group TEXT,
+        route_scope TEXT,
         priority INTEGER NOT NULL,
         status TEXT NOT NULL,
         attempts INTEGER NOT NULL,
@@ -1765,6 +1774,13 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_project ON workflow_work_items(project_key, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_group ON workflow_work_items(project_group, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_invocation ON workflow_work_items(invocation_id);
+      -- idx_workflow_work_items_scope (route_scope, status) is created ONLY by
+      -- migration 0008_work_item_route_scope, never here: this baseline DDL
+      -- re-runs on EVERY open (0001 is not skip-guarded), and on a pre-0008
+      -- database the CREATE TABLE above is a no-op, so an index on route_scope
+      -- here would execute before the column exists and crash the open
+      -- ("no such column: route_scope"). New columns may be folded into the
+      -- CREATE TABLE (fresh-db only); their indexes must live in the migration.
 
       CREATE TABLE IF NOT EXISTS workflow_step_runs (
         id TEXT PRIMARY KEY,
@@ -2556,10 +2572,10 @@ class Store {
     const id = genId();
     const status = input.status ?? "queued";
     this.db.query(`INSERT INTO workflow_work_items (id, route_key, idempotency_key, invocation_id, source_type, source_ref,
-          subject_ref, project_key, project_group, priority, status, attempts, next_attempt_at, lease_expires_at,
+          subject_ref, project_key, project_group, route_scope, priority, status, attempts, next_attempt_at, lease_expires_at,
           workflow_id, loop_id, workflow_run_id, last_reason, created_at, updated_at)
          VALUES ($id, $routeKey, $idempotencyKey, $invocationId, $sourceType, $sourceRef, $subjectRef,
-          $projectKey, $projectGroup, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
+          $projectKey, $projectGroup, $routeScope, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
           $lastReason, $created, $updated)
          ON CONFLICT(route_key, idempotency_key) DO UPDATE SET
           invocation_id=excluded.invocation_id,
@@ -2568,6 +2584,7 @@ class Store {
           subject_ref=excluded.subject_ref,
           project_key=excluded.project_key,
           project_group=excluded.project_group,
+          route_scope=excluded.route_scope,
           priority=excluded.priority,
           status=CASE
             WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled')
@@ -2609,6 +2626,7 @@ class Store {
       $subjectRef: input.subjectRef,
       $projectKey: input.projectKey ?? null,
       $projectGroup: input.projectGroup ?? null,
+      $routeScope: input.routeScope ?? null,
       $priority: input.priority ?? 0,
       $status: status,
       $nextAttemptAt: input.nextAttemptAt ?? null,
@@ -2646,11 +2664,21 @@ class Store {
   countActiveWorkflowWorkItems(args = {}) {
     const active = ["admitted", "running"];
     const placeholders = active.map(() => "?").join(",");
-    const global = this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders})`).get(...active)?.count ?? 0;
+    const routeScope = args.routeScope?.trim() || undefined;
+    const global = routeScope ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND route_scope = ?`).get(...active, routeScope)?.count ?? 0 : this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders})`).get(...active)?.count ?? 0;
     const project = args.projectKey ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_key = ?`).get(...active, args.projectKey)?.count ?? 0 : 0;
     const projectGroup = args.projectGroup ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_group = ?`).get(...active, args.projectGroup)?.count ?? 0 : undefined;
     return { global, project, ...projectGroup !== undefined ? { projectGroup } : {} };
   }
+  countRunningWorkflowStepsByAuthProfile() {
+    const rows = this.db.query("SELECT account_profile, COUNT(*) AS count FROM workflow_step_runs WHERE status = 'running' AND account_profile IS NOT NULL GROUP BY account_profile").all();
+    const counts = {};
+    for (const row of rows) {
+      if (row.account_profile)
+        counts[row.account_profile] = row.count;
+    }
+    return counts;
+  }
   requeueWorkflowWorkItem(id, patch = {}) {
     const current = this.getWorkflowWorkItem(id);
     if (!current)
@@ -3086,6 +3114,9 @@ class Store {
       }
       input.workflow.steps.forEach((step, sequence) => {
         const account = step.account ?? step.target.account;
+        const agentTarget = step.target.type === "agent" ? step.target : undefined;
+        const resolvedProfile = account?.profile ?? agentTarget?.authProfile ?? null;
+        const resolvedTool = account?.tool ?? (agentTarget?.authProfile ? agentTarget.provider : null);
         this.db.query(`INSERT INTO workflow_step_runs (id, workflow_run_id, step_id, sequence, status, started_at, finished_at,
               exit_code, pid, duration_ms, stdout, stderr, error, account_profile, account_tool, created_at, updated_at)
              VALUES ($id, $workflowRunId, $stepId, $sequence, 'pending', NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL,
@@ -3094,8 +3125,8 @@ class Store {
           $workflowRunId: runId,
           $stepId: step.id,
           $sequence: sequence,
-          $accountProfile: account?.profile ?? null,
-          $accountTool: account?.tool ?? null,
+          $accountProfile: resolvedProfile,
+          $accountTool: resolvedTool,
           $created: now,
           $updated: now
         });
@@ -4755,6 +4786,10 @@ CREATE TABLE IF NOT EXISTS audit_events (
 );
 CREATE INDEX IF NOT EXISTS idx_audit_events_subject ON audit_events(subject_type, subject_id, created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_audit_events_action ON audit_events(action, created_at DESC);
+    `),
+  migration("0004_work_item_route_scope", `
+ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS route_scope TEXT;
+CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status);
     `)
 ]);
 

package/dist/lib/storage/postgres-schema.js

@@ -319,6 +319,10 @@ CREATE TABLE IF NOT EXISTS audit_events (
 );
 CREATE INDEX IF NOT EXISTS idx_audit_events_subject ON audit_events(subject_type, subject_id, created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_audit_events_action ON audit_events(action, created_at DESC);
+    `),
+  migration("0004_work_item_route_scope", `
+ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS route_scope TEXT;
+CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status);
     `)
 ]);
 export {

package/dist/lib/storage/postgres.js

@@ -319,6 +319,10 @@ CREATE TABLE IF NOT EXISTS audit_events (
 );
 CREATE INDEX IF NOT EXISTS idx_audit_events_subject ON audit_events(subject_type, subject_id, created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_audit_events_action ON audit_events(action, created_at DESC);
+    `),
+  migration("0004_work_item_route_scope", `
+ALTER TABLE workflow_work_items ADD COLUMN IF NOT EXISTS route_scope TEXT;
+CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status);
     `)
 ]);
 

package/dist/lib/storage/sqlite.js

@@ -1321,6 +1321,7 @@ function rowToWorkflowWorkItem(row) {
     subjectRef: row.subject_ref,
     projectKey: row.project_key ?? undefined,
     projectGroup: row.project_group ?? undefined,
+    routeScope: row.route_scope ?? undefined,
     priority: row.priority,
     status: row.status,
     attempts: row.attempts,
@@ -1601,6 +1602,13 @@ class Store {
           this.addColumnIfMissing("loop_runs", "claim_token", "TEXT");
           this.db.exec("CREATE INDEX IF NOT EXISTS idx_runs_claim_token ON loop_runs(claim_token) WHERE claim_token IS NOT NULL");
         }
+      },
+      {
+        id: "0008_work_item_route_scope",
+        apply: () => {
+          this.addColumnIfMissing("workflow_work_items", "route_scope", "TEXT");
+          this.db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status)");
+        }
       }
     ];
   }
@@ -1748,6 +1756,7 @@ class Store {
         subject_ref TEXT NOT NULL,
         project_key TEXT,
         project_group TEXT,
+        route_scope TEXT,
         priority INTEGER NOT NULL,
         status TEXT NOT NULL,
         attempts INTEGER NOT NULL,
@@ -1765,6 +1774,13 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_project ON workflow_work_items(project_key, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_group ON workflow_work_items(project_group, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_invocation ON workflow_work_items(invocation_id);
+      -- idx_workflow_work_items_scope (route_scope, status) is created ONLY by
+      -- migration 0008_work_item_route_scope, never here: this baseline DDL
+      -- re-runs on EVERY open (0001 is not skip-guarded), and on a pre-0008
+      -- database the CREATE TABLE above is a no-op, so an index on route_scope
+      -- here would execute before the column exists and crash the open
+      -- ("no such column: route_scope"). New columns may be folded into the
+      -- CREATE TABLE (fresh-db only); their indexes must live in the migration.
 
       CREATE TABLE IF NOT EXISTS workflow_step_runs (
         id TEXT PRIMARY KEY,
@@ -2556,10 +2572,10 @@ class Store {
     const id = genId();
     const status = input.status ?? "queued";
     this.db.query(`INSERT INTO workflow_work_items (id, route_key, idempotency_key, invocation_id, source_type, source_ref,
-          subject_ref, project_key, project_group, priority, status, attempts, next_attempt_at, lease_expires_at,
+          subject_ref, project_key, project_group, route_scope, priority, status, attempts, next_attempt_at, lease_expires_at,
           workflow_id, loop_id, workflow_run_id, last_reason, created_at, updated_at)
          VALUES ($id, $routeKey, $idempotencyKey, $invocationId, $sourceType, $sourceRef, $subjectRef,
-          $projectKey, $projectGroup, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
+          $projectKey, $projectGroup, $routeScope, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
           $lastReason, $created, $updated)
          ON CONFLICT(route_key, idempotency_key) DO UPDATE SET
           invocation_id=excluded.invocation_id,
@@ -2568,6 +2584,7 @@ class Store {
           subject_ref=excluded.subject_ref,
           project_key=excluded.project_key,
           project_group=excluded.project_group,
+          route_scope=excluded.route_scope,
           priority=excluded.priority,
           status=CASE
             WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled')
@@ -2609,6 +2626,7 @@ class Store {
       $subjectRef: input.subjectRef,
       $projectKey: input.projectKey ?? null,
       $projectGroup: input.projectGroup ?? null,
+      $routeScope: input.routeScope ?? null,
       $priority: input.priority ?? 0,
       $status: status,
       $nextAttemptAt: input.nextAttemptAt ?? null,
@@ -2646,11 +2664,21 @@ class Store {
   countActiveWorkflowWorkItems(args = {}) {
     const active = ["admitted", "running"];
     const placeholders = active.map(() => "?").join(",");
-    const global = this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders})`).get(...active)?.count ?? 0;
+    const routeScope = args.routeScope?.trim() || undefined;
+    const global = routeScope ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND route_scope = ?`).get(...active, routeScope)?.count ?? 0 : this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders})`).get(...active)?.count ?? 0;
     const project = args.projectKey ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_key = ?`).get(...active, args.projectKey)?.count ?? 0 : 0;
     const projectGroup = args.projectGroup ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_group = ?`).get(...active, args.projectGroup)?.count ?? 0 : undefined;
     return { global, project, ...projectGroup !== undefined ? { projectGroup } : {} };
   }
+  countRunningWorkflowStepsByAuthProfile() {
+    const rows = this.db.query("SELECT account_profile, COUNT(*) AS count FROM workflow_step_runs WHERE status = 'running' AND account_profile IS NOT NULL GROUP BY account_profile").all();
+    const counts = {};
+    for (const row of rows) {
+      if (row.account_profile)
+        counts[row.account_profile] = row.count;
+    }
+    return counts;
+  }
   requeueWorkflowWorkItem(id, patch = {}) {
     const current = this.getWorkflowWorkItem(id);
     if (!current)
@@ -3086,6 +3114,9 @@ class Store {
       }
       input.workflow.steps.forEach((step, sequence) => {
         const account = step.account ?? step.target.account;
+        const agentTarget = step.target.type === "agent" ? step.target : undefined;
+        const resolvedProfile = account?.profile ?? agentTarget?.authProfile ?? null;
+        const resolvedTool = account?.tool ?? (agentTarget?.authProfile ? agentTarget.provider : null);
         this.db.query(`INSERT INTO workflow_step_runs (id, workflow_run_id, step_id, sequence, status, started_at, finished_at,
               exit_code, pid, duration_ms, stdout, stderr, error, account_profile, account_tool, created_at, updated_at)
              VALUES ($id, $workflowRunId, $stepId, $sequence, 'pending', NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL,
@@ -3094,8 +3125,8 @@ class Store {
           $workflowRunId: runId,
           $stepId: step.id,
           $sequence: sequence,
-          $accountProfile: account?.profile ?? null,
-          $accountTool: account?.tool ?? null,
+          $accountProfile: resolvedProfile,
+          $accountTool: resolvedTool,
           $created: now,
           $updated: now
         });

package/dist/lib/store.d.ts

@@ -218,11 +218,22 @@ export declare class Store {
     countActiveWorkflowWorkItems(args?: {
         projectKey?: string;
         projectGroup?: string;
+        routeScope?: string;
     }): {
         global: number;
         project: number;
         projectGroup?: number;
     };
+    /**
+     * Number of currently-running workflow steps per resolved auth profile
+     * (account_profile). Drives least-loaded pool selection and the
+     * `--max-per-profile` guard so concurrency spreads across subscription
+     * accounts instead of stacking on one (the provider-side 429 wall). Only
+     * `running` steps are counted: within a workflow steps run sequentially, so a
+     * profile's running count is the number of concurrent workflows executing a
+     * step on that account right now — exactly the concurrency to bound.
+     */
+    countRunningWorkflowStepsByAuthProfile(): Record<string, number>;
     requeueWorkflowWorkItem(id: string, patch?: {
         reason?: string;
     }): WorkflowWorkItem;

package/dist/lib/store.js

@@ -1321,6 +1321,7 @@ function rowToWorkflowWorkItem(row) {
     subjectRef: row.subject_ref,
     projectKey: row.project_key ?? undefined,
     projectGroup: row.project_group ?? undefined,
+    routeScope: row.route_scope ?? undefined,
     priority: row.priority,
     status: row.status,
     attempts: row.attempts,
@@ -1601,6 +1602,13 @@ class Store {
           this.addColumnIfMissing("loop_runs", "claim_token", "TEXT");
           this.db.exec("CREATE INDEX IF NOT EXISTS idx_runs_claim_token ON loop_runs(claim_token) WHERE claim_token IS NOT NULL");
         }
+      },
+      {
+        id: "0008_work_item_route_scope",
+        apply: () => {
+          this.addColumnIfMissing("workflow_work_items", "route_scope", "TEXT");
+          this.db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_work_items_scope ON workflow_work_items(route_scope, status)");
+        }
       }
     ];
   }
@@ -1748,6 +1756,7 @@ class Store {
         subject_ref TEXT NOT NULL,
         project_key TEXT,
         project_group TEXT,
+        route_scope TEXT,
         priority INTEGER NOT NULL,
         status TEXT NOT NULL,
         attempts INTEGER NOT NULL,
@@ -1765,6 +1774,13 @@ class Store {
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_project ON workflow_work_items(project_key, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_group ON workflow_work_items(project_group, status);
       CREATE INDEX IF NOT EXISTS idx_workflow_work_items_invocation ON workflow_work_items(invocation_id);
+      -- idx_workflow_work_items_scope (route_scope, status) is created ONLY by
+      -- migration 0008_work_item_route_scope, never here: this baseline DDL
+      -- re-runs on EVERY open (0001 is not skip-guarded), and on a pre-0008
+      -- database the CREATE TABLE above is a no-op, so an index on route_scope
+      -- here would execute before the column exists and crash the open
+      -- ("no such column: route_scope"). New columns may be folded into the
+      -- CREATE TABLE (fresh-db only); their indexes must live in the migration.
 
       CREATE TABLE IF NOT EXISTS workflow_step_runs (
         id TEXT PRIMARY KEY,
@@ -2556,10 +2572,10 @@ class Store {
     const id = genId();
     const status = input.status ?? "queued";
     this.db.query(`INSERT INTO workflow_work_items (id, route_key, idempotency_key, invocation_id, source_type, source_ref,
-          subject_ref, project_key, project_group, priority, status, attempts, next_attempt_at, lease_expires_at,
+          subject_ref, project_key, project_group, route_scope, priority, status, attempts, next_attempt_at, lease_expires_at,
           workflow_id, loop_id, workflow_run_id, last_reason, created_at, updated_at)
          VALUES ($id, $routeKey, $idempotencyKey, $invocationId, $sourceType, $sourceRef, $subjectRef,
-          $projectKey, $projectGroup, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
+          $projectKey, $projectGroup, $routeScope, $priority, $status, 0, $nextAttemptAt, NULL, NULL, NULL, NULL,
           $lastReason, $created, $updated)
          ON CONFLICT(route_key, idempotency_key) DO UPDATE SET
           invocation_id=excluded.invocation_id,
@@ -2568,6 +2584,7 @@ class Store {
           subject_ref=excluded.subject_ref,
           project_key=excluded.project_key,
           project_group=excluded.project_group,
+          route_scope=excluded.route_scope,
           priority=excluded.priority,
           status=CASE
             WHEN workflow_work_items.status IN ('succeeded', 'admitted', 'running', 'failed', 'dead_letter', 'cancelled')
@@ -2609,6 +2626,7 @@ class Store {
       $subjectRef: input.subjectRef,
       $projectKey: input.projectKey ?? null,
       $projectGroup: input.projectGroup ?? null,
+      $routeScope: input.routeScope ?? null,
       $priority: input.priority ?? 0,
       $status: status,
       $nextAttemptAt: input.nextAttemptAt ?? null,
@@ -2646,11 +2664,21 @@ class Store {
   countActiveWorkflowWorkItems(args = {}) {
     const active = ["admitted", "running"];
     const placeholders = active.map(() => "?").join(",");
-    const global = this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders})`).get(...active)?.count ?? 0;
+    const routeScope = args.routeScope?.trim() || undefined;
+    const global = routeScope ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND route_scope = ?`).get(...active, routeScope)?.count ?? 0 : this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders})`).get(...active)?.count ?? 0;
     const project = args.projectKey ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_key = ?`).get(...active, args.projectKey)?.count ?? 0 : 0;
     const projectGroup = args.projectGroup ? this.db.query(`SELECT COUNT(*) AS count FROM workflow_work_items WHERE status IN (${placeholders}) AND project_group = ?`).get(...active, args.projectGroup)?.count ?? 0 : undefined;
     return { global, project, ...projectGroup !== undefined ? { projectGroup } : {} };
   }
+  countRunningWorkflowStepsByAuthProfile() {
+    const rows = this.db.query("SELECT account_profile, COUNT(*) AS count FROM workflow_step_runs WHERE status = 'running' AND account_profile IS NOT NULL GROUP BY account_profile").all();
+    const counts = {};
+    for (const row of rows) {
+      if (row.account_profile)
+        counts[row.account_profile] = row.count;
+    }
+    return counts;
+  }
   requeueWorkflowWorkItem(id, patch = {}) {
     const current = this.getWorkflowWorkItem(id);
     if (!current)
@@ -3086,6 +3114,9 @@ class Store {
       }
       input.workflow.steps.forEach((step, sequence) => {
         const account = step.account ?? step.target.account;
+        const agentTarget = step.target.type === "agent" ? step.target : undefined;
+        const resolvedProfile = account?.profile ?? agentTarget?.authProfile ?? null;
+        const resolvedTool = account?.tool ?? (agentTarget?.authProfile ? agentTarget.provider : null);
         this.db.query(`INSERT INTO workflow_step_runs (id, workflow_run_id, step_id, sequence, status, started_at, finished_at,
               exit_code, pid, duration_ms, stdout, stderr, error, account_profile, account_tool, created_at, updated_at)
              VALUES ($id, $workflowRunId, $stepId, $sequence, 'pending', NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL,
@@ -3094,8 +3125,8 @@ class Store {
           $workflowRunId: runId,
           $stepId: step.id,
           $sequence: sequence,
-          $accountProfile: account?.profile ?? null,
-          $accountTool: account?.tool ?? null,
+          $accountProfile: resolvedProfile,
+          $accountTool: resolvedTool,
           $created: now,
           $updated: now
         });