@hasna/loops 0.3.60 → 0.4.1

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

@@ -0,0 +1,27 @@
+import type { EventEnvelope } from "@hasna/events";
+/** Deep field extraction over Hasna event envelopes and todos task records. */
+export declare function eventData(event: EventEnvelope): Record<string, unknown>;
+export declare function eventMetadata(event: EventEnvelope): Record<string, unknown>;
+export declare function stringField(value: unknown): string | undefined;
+export declare function slugSegment(value: string, fallback?: string): string;
+export declare function stableSuffix(value: string): string;
+export declare function stableHash(parts: unknown[]): string;
+export declare function taskEventField(data: Record<string, unknown>, keys: string[]): string | undefined;
+export declare function objectField(value: unknown): Record<string, unknown> | undefined;
+export declare function taskEventRecords(data: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>[];
+export declare function booleanLike(value: unknown): boolean;
+export declare function hasTruthyField(records: Record<string, unknown>[], keys: string[]): boolean;
+export declare function firstTruthyField(records: Record<string, unknown>[], keys: string[]): string | undefined;
+export declare function automationRecords(data: Record<string, unknown>, metadata: Record<string, unknown>): Record<string, unknown>[];
+export declare function tagsFromValue(value: unknown): string[];
+export declare function taskEventTags(records: Record<string, unknown>[]): string[];
+export declare function taskRouteEligibility(data: Record<string, unknown>, metadata: Record<string, unknown>): {
+    eligible: boolean;
+    reason?: string;
+    tags: string[];
+};
+export declare function canonicalRouteField(value: string): string;
+export declare function recordFieldValues(record: Record<string, unknown>, field: string): string[];
+export declare function routeFieldValues(records: Record<string, unknown>[], field: string): string[];
+export declare function firstRouteField(records: Record<string, unknown>[], fields: string[]): string | undefined;
+export declare function routeFieldList(records: Record<string, unknown>[], fields: string[]): string[] | undefined;

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

@@ -0,0 +1,26 @@
+import type { CreateWorkflowInput, LoopTarget, WorkflowSpec } from "../../types.js";
+import { CodedError } from "../errors.js";
+import { preflightTarget } from "../executor.js";
+import { preflightWorkflow } from "../workflow-runner.js";
+/**
+ * Validation/preflight gates shared by CLI commands and route engines. Failures
+ * throw a `GateError` carrying the gate kind and structured context so the CLI
+ * error runner can render the stable `{ok:false, created:false, ...}` JSON shape.
+ */
+export declare class GateError extends CodedError {
+    readonly gate: "validation" | "preflight";
+    readonly context: Record<string, unknown>;
+    constructor(gate: "validation" | "preflight", message: string, context: Record<string, unknown>);
+}
+export declare function normalizeLoopTargetForStorage(target: unknown, context: Record<string, unknown>, opts?: {
+    baseDir?: string;
+}): Exclude<LoopTarget, {
+    type: "workflow";
+}>;
+export declare function normalizeWorkflowForStorage(body: CreateWorkflowInput, context: Record<string, unknown>): CreateWorkflowInput;
+export declare function workflowBodyFromFile(file: string, fallbackName: string | undefined, context: Record<string, unknown>): CreateWorkflowInput;
+export declare function preflightLoopTarget(target: Exclude<LoopTarget, {
+    type: "workflow";
+}>, context: Record<string, unknown>, metadata: Parameters<typeof preflightTarget>[1], opts: Parameters<typeof preflightTarget>[2]): ReturnType<typeof preflightTarget>;
+export declare function preflightStoredWorkflow(workflow: Parameters<typeof preflightWorkflow>[0], context: Record<string, unknown>, opts: Parameters<typeof preflightWorkflow>[1]): ReturnType<typeof preflightWorkflow>;
+export declare function workflowSpecForPreflight(body: CreateWorkflowInput, id?: string): WorkflowSpec;

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

@@ -0,0 +1,18 @@
+/**
+ * Route engine: turns Hasna events, todos ready queues, and health/hygiene
+ * findings into deduped, throttled OpenLoops workflow loops and todos tasks.
+ * Extracted from the CLI so commands stay thin and the SDK/daemon can reuse it.
+ */
+export * from "./types.js";
+export * from "./parse.js";
+export { eventData, eventMetadata, objectField, slugSegment, stableHash, stableSuffix, stringField, tagsFromValue, taskEventField, taskEventTags, taskRouteEligibility, } from "./fields.js";
+export { routeCursorKey, selectRouteItems, writeRouteCursor, writeRouteEvidence, type RouteSelection } from "./cursors.js";
+export { GateError, normalizeLoopTargetForStorage, normalizeWorkflowForStorage, preflightLoopTarget, preflightStoredWorkflow, workflowBodyFromFile, workflowSpecForPreflight, } from "./gates.js";
+export { accountPoolFromOpts, normalizeAgentProvider, permissionModeFromOpts, providerAuthProfileFromOpts, providerRoutingPublic, resolveProviderRouting, roleAccountFromOpts, sandboxFromOpts, SUPPORTED_AGENT_PROVIDERS, type ProviderRoutingDecision, } from "./provider.js";
+export { prReviewRoutingDecision, type PrReviewRoutingDecision } from "./pr-review.js";
+export { hasThrottleLimits, normalizeRoutePath, routeThrottleDecision, routeThrottleLimitsFromOpts, type RouteThrottleDecision, type RouteThrottleLimits, } from "./throttle.js";
+export { generatedRouteSandboxPreflight, readEventEnvelopeInput, routeEventByKind, routeGenericEvent, routeTodosTaskEvent, todosTaskRouteTemplateId, } from "./route-event.js";
+export { drainTodosTaskRoutes, type DrainResult } from "./drain.js";
+export { buildHygieneRouteTasks, parseHygieneChecks, taskAutoRoute, upsertRouteTasks, type HygieneCheckKind, type HygieneRouteTask, type RouteTaskSpec, type UpsertRouteTasksOptions, } from "./route-tasks.js";
+export { defaultLoopsProject, ensureTodosTaskList, runLocalCommand, runLocalCommandWithStdoutFile } from "./todos-cli.js";
+export { addAgentRoutingOptions, addRouteEventOptions, addTodosDrainOptions, routeDrainArgs, type AgentRoutingOptionConfig } from "./options.js";

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

@@ -0,0 +1,31 @@
+import type { Command } from "commander";
+import type { TodosDrainOptions } from "./types.js";
+export interface AgentRoutingOptionConfig {
+    /** Include event input options (--event-file/--event-json). */
+    eventInput?: boolean;
+    /** Include todos-task-only options (template, triage/planner roles, PR gating). */
+    todosTask?: boolean;
+    /** Default for --provider; when set the option description drops the codewith hint. */
+    providerDefault?: string;
+    /** Default for --name-prefix. */
+    namePrefixDefault?: string;
+    /** Override the --preflight help text. */
+    preflightDescription?: string;
+    /** Include --dry-run with this help text; omit the flag entirely when absent. */
+    dryRunDescription?: string;
+}
+/** Compose the shared agent-routing flag block onto a route command. */
+export declare function addAgentRoutingOptions(command: Command, config?: AgentRoutingOptionConfig): Command;
+/** Options for `routes create/preview <kind>` and the deprecated `events handle` aliases. */
+export declare function addRouteEventOptions(command: Command, config?: AgentRoutingOptionConfig): Command;
+/** Options for `routes drain/schedule todos-task` and the deprecated `events drain` alias. */
+export declare function addTodosDrainOptions(command: Command, opts?: {
+    includeDryRun?: boolean;
+    preflightDescription?: string;
+}): Command;
+/**
+ * Rebuild the argv for a scheduled route drain loop from the same option specs
+ * used to declare the flags, so scheduled drains replay exactly the options the
+ * operator passed to `routes schedule`.
+ */
+export declare function routeDrainArgs(opts: TodosDrainOptions): string[];

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

@@ -0,0 +1,8 @@
+export declare function positiveInteger(raw: string | undefined, label: string): number | undefined;
+export declare function nonNegativeInteger(raw: string | undefined, label: string): number | undefined;
+export declare function positiveDuration(raw: string | undefined, label: string): number | undefined;
+export declare function timeoutDuration(raw: string | undefined, label: string): number | null | undefined;
+export declare function idleTimeoutDuration(raw: string | undefined, label: string): number | undefined;
+export declare function splitList(value: string | undefined): string[] | undefined;
+export declare function listFromRepeatedOpts(value: string[] | undefined): string[] | undefined;
+export declare function collectValues(value: string, previous?: string[]): string[];

package/dist/lib/route/pr-review.d.ts

@@ -0,0 +1,11 @@
+import type { TodosTaskRouteOptions } from "./types.js";
+export interface PrReviewRoutingDecision {
+    required: boolean;
+    allowed: boolean;
+    reason?: string;
+    author?: string;
+    reviewers: string[];
+    selectedReviewer?: string;
+    signals: string[];
+}
+export declare function prReviewRoutingDecision(data: Record<string, unknown>, metadata: Record<string, unknown>, opts: TodosTaskRouteOptions): PrReviewRoutingDecision;

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

@@ -0,0 +1,41 @@
+import type { AccountRef, AgentPermissionMode, AgentProvider, AgentSandbox } from "../../types.js";
+import type { TodosTaskRouteOptions } from "./types.js";
+export declare const SUPPORTED_AGENT_PROVIDERS: Set<AgentProvider>;
+export type ProviderRoutingSource = "default" | "option" | "rule" | "metadata";
+export interface ProviderRoutingRule {
+    raw: string;
+    field: string;
+    value: string;
+    provider: AgentProvider;
+    profiles?: string[];
+}
+export interface ProviderRoutingDecision {
+    provider: AgentProvider;
+    source: ProviderRoutingSource;
+    reason: string;
+    rule?: Pick<ProviderRoutingRule, "raw" | "field" | "value" | "provider" | "profiles">;
+    authProfile?: string;
+    authProfilePool?: string[];
+    account?: AccountRef;
+    accountPool?: AccountRef[];
+}
+export declare function normalizeAgentProvider(value: string | undefined, source: string): AgentProvider;
+export declare function parseProviderRoutingRule(raw: string): ProviderRoutingRule;
+export declare function accountPoolFromOpts(opts: {
+    accountPool?: string;
+    accountTool?: string;
+}): AccountRef[] | undefined;
+export declare function roleAccountFromOpts(opts: {
+    accountTool?: string;
+}, profile: string | undefined): AccountRef | undefined;
+export declare function providerRoutingPublic(decision: ProviderRoutingDecision): Record<string, unknown>;
+export declare function resolveProviderRouting(data: Record<string, unknown>, metadata: Record<string, unknown>, opts: TodosTaskRouteOptions): ProviderRoutingDecision;
+export declare function providerAuthProfileFromOpts(opts: {
+    authProfile?: string;
+}, provider: AgentProvider): string | undefined;
+export declare function sandboxFromOpts(opts: {
+    sandbox?: string;
+}, provider: AgentProvider): AgentSandbox | undefined;
+export declare function permissionModeFromOpts(opts: {
+    permissionMode?: string;
+}, provider: AgentProvider): AgentPermissionMode | undefined;

package/dist/lib/route/route-event.d.ts

@@ -0,0 +1,23 @@
+import type { EventEnvelope } from "@hasna/events";
+import type { AgentProvider, AgentSandbox, CreateWorkflowInput } from "../../types.js";
+import type { TodosTaskRouteOptions, TodosTaskRoutePrint } from "./types.js";
+/** Shared event-to-workflow route engine behind `routes create/preview` and the deprecated `events handle` aliases. */
+interface RouteSandboxPreflight {
+    stepId: string;
+    provider: AgentProvider;
+    sandbox?: AgentSandbox;
+    worktreeEnabled?: boolean;
+    method: "provider-native-sandbox" | "isolated-worktree" | "manual-break-glass";
+}
+export declare function generatedRouteSandboxPreflight(workflow: CreateWorkflowInput): RouteSandboxPreflight[];
+export declare function todosTaskRouteTemplateId(opts: {
+    template?: string;
+}): string;
+export declare function readEventEnvelopeInput(opts?: {
+    eventJson?: string;
+    eventFile?: string;
+}): Promise<EventEnvelope>;
+export declare function routeTodosTaskEvent(event: EventEnvelope, opts: TodosTaskRouteOptions): TodosTaskRoutePrint;
+export declare function routeGenericEvent(event: EventEnvelope, opts: TodosTaskRouteOptions): TodosTaskRoutePrint;
+export declare function routeEventByKind(kind: string, event: EventEnvelope, opts: TodosTaskRouteOptions): TodosTaskRoutePrint;
+export {};

package/dist/lib/route/route-tasks.d.ts

@@ -0,0 +1,75 @@
+import type { Store } from "../store.js";
+/** Deduped todos task upserts shared by `health route-tasks` and `hygiene route-tasks`. */
+export interface TaskRouteOptions {
+    autoRoute?: boolean;
+    routeProjectPath?: string;
+    source: string;
+}
+export declare function taskAutoRoute(tags: string[], base: Record<string, unknown>, opts: TaskRouteOptions): {
+    tags: string[];
+    metadata: Record<string, unknown>;
+    autoRoute: {
+        requested: boolean;
+        enabled: boolean;
+        skippedReason?: string;
+    };
+};
+export interface RouteTaskSpec {
+    title: string;
+    description: string;
+    priority: string;
+    tags: string[];
+    fingerprint: string;
+    /** Base metadata handed to taskAutoRoute (before route flags are merged in). */
+    metadata: Record<string, unknown>;
+    /** Extra fields copied onto every action record for this task (e.g. hygiene `check`). */
+    extra?: Record<string, unknown>;
+}
+export interface UpsertRouteTasksOptions {
+    project: string;
+    taskList: {
+        slug: string;
+        name: string;
+        description: string;
+    };
+    cursorKey: string;
+    maxActions: number;
+    dryRun?: boolean;
+    autoRoute?: boolean;
+    routeProjectPath?: string;
+    source: string;
+    evidence: {
+        kind: string;
+        dir?: string;
+    };
+    /** Command-specific summary fields merged into the output before routing/actions. */
+    summary: Record<string, unknown>;
+    tasks: RouteTaskSpec[];
+}
+export interface UpsertRouteTasksResult {
+    ok: boolean;
+    output: Record<string, unknown>;
+    evidencePath?: string;
+}
+export declare function upsertRouteTasks(opts: UpsertRouteTasksOptions): UpsertRouteTasksResult;
+export type HygieneCheckKind = "names" | "duplicates" | "scripts";
+export interface HygieneRouteTask {
+    check: HygieneCheckKind;
+    title: string;
+    description: string;
+    priority: "critical" | "high" | "medium" | "low";
+    tags: string[];
+    fingerprint: string;
+    metadata: Record<string, unknown>;
+}
+export declare function parseHygieneChecks(value: string | undefined): HygieneCheckKind[];
+export declare function buildHygieneRouteTasks(store: Store, opts: {
+    checks: HygieneCheckKind[];
+    includeInactive?: boolean;
+    limit?: number;
+    scriptsDir?: string;
+}): {
+    checked: Record<HygieneCheckKind, number>;
+    findings: number;
+    tasks: HygieneRouteTask[];
+};

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

@@ -0,0 +1,47 @@
+import type { Store } from "../store.js";
+/** Active-workflow admission throttles and canonical project-path handling. */
+export interface RouteThrottleLimits {
+    maxActive?: number;
+    maxActivePerProject?: number;
+    maxActivePerProjectGroup?: number;
+}
+export interface RouteThrottleDecision {
+    allowed: boolean;
+    reason?: string;
+    projectPath: string;
+    projectGroup?: string;
+    limits: RouteThrottleLimits;
+    counts: {
+        global: number;
+        project: number;
+        projectGroup?: number;
+    };
+}
+export declare function routeThrottleLimitsFromOpts(opts: {
+    maxActive?: string;
+    maxActivePerProject?: string;
+    maxActivePerProjectGroup?: string;
+}): RouteThrottleLimits;
+export declare function hasThrottleLimits(limits: RouteThrottleLimits): boolean;
+export declare function normalizeRoutePath(value: string | undefined): string | undefined;
+export declare function routeProjectGroup(optsGroup: string | undefined, data: Record<string, unknown>, metadata: Record<string, unknown>): string | undefined;
+export declare function routeThrottleDecision(store: Store, args: {
+    projectPath: string;
+    projectGroup?: string;
+    limits: RouteThrottleLimits;
+}): RouteThrottleDecision;
+export declare function routeThrottleDryRunPreview(args: {
+    projectPath: string;
+    projectGroup?: string;
+    limits: RouteThrottleLimits;
+}): {
+    limits: RouteThrottleLimits;
+    projectGroup?: string | undefined;
+    evaluated: boolean;
+    reason: string;
+    projectPath: string;
+};
+export declare function isExistingGitProjectPath(path: string): boolean;
+export declare function validateRequiredRouteWorktreeProjectPath(opts: {
+    worktreeMode?: string;
+}, projectPath: string): void;

package/dist/lib/route/todos-cli.d.ts

@@ -0,0 +1,21 @@
+/** Local `todos` CLI transport used by route drains and route-tasks commands. */
+export declare function defaultLoopsProject(): string;
+export interface LocalCommandResult {
+    ok: boolean;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error: string;
+}
+export declare function runLocalCommand(command: string, args: string[], opts?: {
+    input?: string;
+    timeoutMs?: number;
+    maxBuffer?: number;
+}): LocalCommandResult;
+export declare function runLocalCommandWithStdoutFile(command: string, args: string[], opts?: {
+    input?: string;
+    timeoutMs?: number;
+    maxBuffer?: number;
+}): LocalCommandResult;
+export declare function ensureTodosTaskList(project: string, slug: string, name: string, description: string): string;
+export declare function todosMutationSummary(result: LocalCommandResult): Record<string, unknown>;

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

@@ -0,0 +1,88 @@
+/** Typed option bags shared by the route engine, drain engine, and CLI commands. */
+export interface TodosTaskRouteOptions {
+    eventFile?: string;
+    eventJson?: string;
+    template?: string;
+    provider?: string;
+    providerRule?: string[];
+    authProfile?: string;
+    authProfilePool?: string;
+    triageAuthProfile?: string;
+    plannerAuthProfile?: string;
+    workerAuthProfile?: string;
+    verifierAuthProfile?: string;
+    account?: string;
+    accountPool?: string;
+    triageAccount?: string;
+    plannerAccount?: string;
+    workerAccount?: string;
+    verifierAccount?: string;
+    accountTool?: string;
+    model?: string;
+    variant?: string;
+    agent?: string;
+    addDir?: string[];
+    timeout?: string;
+    verifierIdleTimeout?: string;
+    permissionMode?: string;
+    sandbox?: string;
+    manualBreakGlass?: boolean;
+    projectPath?: string;
+    projectGroup?: string;
+    maxActive?: string;
+    maxActivePerProject?: string;
+    maxActivePerProjectGroup?: string;
+    worktreeMode?: string;
+    worktreeRoot?: string;
+    worktreeBranchPrefix?: string;
+    prHandoff?: boolean;
+    githubReviewer?: string;
+    githubReviewerPool?: string;
+    namePrefix?: string;
+    preflight?: boolean;
+    dryRun?: boolean;
+    todosProject?: string;
+}
+export interface TodosReadyTask {
+    id?: string;
+    task_id?: string;
+    taskId?: string;
+    title?: string;
+    description?: string;
+    body?: string;
+    status?: string;
+    working_dir?: string;
+    workingDir?: string;
+    project_path?: string;
+    projectPath?: string;
+    cwd?: string;
+    tags?: string[] | string;
+    metadata?: Record<string, unknown>;
+    project_id?: string;
+    projectId?: string;
+    task_list_id?: string;
+    taskListId?: string;
+    task_list?: {
+        id?: string;
+        slug?: string;
+    };
+    [key: string]: unknown;
+}
+export interface TodosDrainOptions extends TodosTaskRouteOptions {
+    todosProject?: string;
+    todosProjectId?: string;
+    taskList?: string;
+    tags?: string;
+    tag?: string;
+    projectPathPrefix?: string;
+    limit?: string;
+    scanLimit?: string;
+    maxDispatch?: string;
+    evidenceDir?: string;
+    compact?: boolean;
+}
+export interface TodosTaskRoutePrint {
+    kind: "skipped" | "deduped" | "throttled" | "created";
+    value: Record<string, unknown>;
+    human: string;
+}

package/dist/lib/run-artifacts.d.ts

@@ -1,7 +1,7 @@
 export declare function safeRunPathSlug(value: string | undefined, fallback: string): string;
 export declare function workflowRunSubjectKey(kind: string | undefined, rawSubjectRef: string | undefined): string;
 export declare function workflowRunProjectSlug(projectKey: string | undefined): string;
-export declare function writeWorkflowRunManifest(args: {
+export interface WorkflowRunManifestArgs {
     loopsDataDir: string;
     workflowRunId: string;
     workflowId: string;
@@ -12,4 +12,19 @@ export declare function writeWorkflowRunManifest(args: {
     subjectKind?: string;
     rawSubjectRef?: string;
     payload: Record<string, unknown>;
-}): string;
+}
+export interface StagedWorkflowRunManifest {
+    /** Final manifest.json location, valid only after {@link commitWorkflowRunManifest}. */
+    manifestPath: string;
+    /** Temp file holding the staged manifest content. */
+    tmpPath: string;
+}
+/**
+ * Write the manifest to `manifest.json.tmp` so callers can stage the
+ * filesystem side effect before opening a database transaction and promote it
+ * with {@link commitWorkflowRunManifest} only after COMMIT succeeds.
+ */
+export declare function stageWorkflowRunManifest(args: WorkflowRunManifestArgs): StagedWorkflowRunManifest;
+export declare function commitWorkflowRunManifest(staged: StagedWorkflowRunManifest): string;
+export declare function discardWorkflowRunManifest(staged: StagedWorkflowRunManifest): void;
+export declare function writeWorkflowRunManifest(args: WorkflowRunManifestArgs): string;

package/dist/lib/run-envelope.d.ts

@@ -0,0 +1,41 @@
+import type { ExecutorResult, WorkflowRun, WorkflowStepRun, WorkflowStepRunStatus } from "../types.js";
+/** Maximum characters kept from each end of a child output when building parent envelopes. */
+export declare const ENVELOPE_EXCERPT_CHARS = 2048;
+/** Stable marker prefix recorded on skipped step runs that were blocked by policy exit codes. */
+export declare const BLOCKED_STEP_ERROR_PREFIX = "blocked:";
+/**
+ * Excerpts scrub BEFORE truncating: cutting raw output at fixed character
+ * boundaries can bisect a credential (e.g. an `sk-ant-…` key whose prefix
+ * falls in the omitted middle), leaving a fragment no scrub pattern matches.
+ * scrubSecrets is idempotent, so store-time re-scrubbing stays safe.
+ */
+export declare function boundedExcerpt(text: string | undefined, limit?: number): string | undefined;
+export interface OutputSummary {
+    stdoutBytes: number;
+    stderrBytes: number;
+    stdoutExcerpt?: string;
+    stderrExcerpt?: string;
+}
+export declare function summarizeOutput(stdout: string | undefined, stderr: string | undefined): OutputSummary;
+export interface ExecutorResultSummary extends OutputSummary {
+    status: ExecutorResult["status"];
+    exitCode?: number;
+    durationMs: number;
+    error?: string;
+}
+export declare function summarizeExecutorResult(result: Pick<ExecutorResult, "status" | "exitCode" | "durationMs" | "stdout" | "stderr" | "error">): ExecutorResultSummary;
+export interface WorkflowStepRunSummary extends OutputSummary {
+    stepId: string;
+    status: WorkflowStepRunStatus;
+    exitCode?: number;
+    durationMs?: number;
+    error?: string;
+    blocked: boolean;
+}
+export declare function isBlockedStepRun(step: Pick<WorkflowStepRun, "status" | "error"> | undefined): boolean;
+export declare function summarizeWorkflowStepRun(step: WorkflowStepRun): WorkflowStepRunSummary;
+/**
+ * Parent-run result envelope: per-step summaries only. Full child output stays on the
+ * workflow step run rows; duplicating it here bloated the database and propagated secrets.
+ */
+export declare function workflowRunEnvelope(run: WorkflowRun, steps: WorkflowStepRun[]): string;

package/dist/lib/scheduler.d.ts

@@ -10,6 +10,10 @@ export interface SchedulerDeps {
     execute?: (loop: Loop, run: LoopRun) => Promise<ExecutorResult>;
     onError?: (loop: Loop, error: unknown) => void;
     onRun?: (run: LoopRun) => void;
+    /** randomness source for retry jitter; injectable for deterministic tests */
+    random?: () => number;
+    /** consecutive-final-failure count that trips the circuit breaker; number, per-loop resolver, or <= 0 to disable */
+    circuitBreakerThreshold?: number | ((loop: Loop) => number | undefined);
 }
 export interface TickResult {
     claimed: LoopRun[];
@@ -29,9 +33,81 @@ export declare function manualRunScheduledFor(loop: Loop, now?: Date): string;
 export declare function shouldAdvanceManualRun(loop: Loop, scheduledFor: string, now?: Date): boolean;
 export type ManualRunSource = "ad_hoc" | "due_slot" | "retry_slot";
 export declare function manualRunSource(loop: Loop, scheduledFor: string, now?: Date): ManualRunSource;
-export declare function advanceLoop(store: Store, loop: Loop, run: LoopRun, finishedAt: Date, succeeded: boolean, opts?: {
+/**
+ * Inline (non-daemon) runners claim runs as `<surface>:<pid>`: `manual:<pid>`
+ * (CLI run-now), `manual-tick:<pid>` (CLI tick), `sdk:<pid>` (LoopsClient
+ * default), and caller-supplied SDK runner ids following the same convention.
+ * The daemon claims as `${hostname}:${pid}:${leaseId}` (three segments) and
+ * MCP run-now uses schedule mode, so neither ever matches. Centralized here so
+ * the daemon's "spare runs owned by a live inline runner" check cannot drift
+ * from the surfaces that share runLoopNow/executeClaimedRun semantics.
+ */
+export declare const INLINE_RUNNER_ID_PATTERN: RegExp;
+/** Owner pid of an inline runner claim, or undefined for daemon/unknown claims. */
+export declare function inlineRunnerOwnerPid(claimedBy: string | undefined): number | undefined;
+export type RunLoopNowMode = "inline" | "schedule";
+export interface RunLoopNowDeps {
+    store: Store;
+    /** loop id or exact loop name */
+    idOrName: string;
+    runnerId: string;
+    /**
+     * "inline" claims and executes the run in this process (CLI/SDK semantics);
+     * "schedule" only marks the loop due now for daemon pickup (MCP semantics).
+     */
+    mode?: RunLoopNowMode;
+    now?: () => Date;
+    execute?: (loop: Loop, run: LoopRun) => Promise<ExecutorResult>;
+}
+export interface RunLoopNowScheduled {
+    mode: "schedule";
+    loop: Loop;
+    scheduledFor: string;
+}
+export interface RunLoopNowExecuted {
+    mode: "inline";
+    loop: Loop;
+    run: LoopRun;
+    source: ManualRunSource;
+    advancedLoop: boolean;
+}
+export type RunLoopNowResult = RunLoopNowScheduled | RunLoopNowExecuted;
+export declare function runLoopNow(deps: RunLoopNowDeps & {
+    mode: "schedule";
+}): Promise<RunLoopNowScheduled>;
+export declare function runLoopNow(deps: RunLoopNowDeps & {
+    mode?: "inline";
+}): Promise<RunLoopNowExecuted>;
+export declare const MAX_RETRY_DELAY_MS: number;
+export declare const DEFAULT_CIRCUIT_BREAKER_THRESHOLD = 5;
+export declare const CIRCUIT_BREAKER_REASON_PREFIX = "circuit breaker open";
+export declare const MAX_SKIPS_PER_LOOP_PER_TICK = 10;
+/**
+ * Exponential retry backoff with jitter:
+ * delay = retryDelayMs * 2^(attempt-1) * (0.5 + random), capped at 6h.
+ * Failures classified as rate_limit/auth back off 4x harder, since hammering
+ * a throttled or misconfigured provider only makes things worse.
+ */
+export declare function retryBackoffDelayMs(loop: Loop, run: LoopRun, random?: () => number): number;
+export interface AdvanceLoopOptions {
     daemonLeaseId?: string;
-}): void;
+    random?: () => number;
+    circuitBreakerThreshold?: number | ((loop: Loop) => number | undefined);
+    onRun?: (run: LoopRun) => void;
+}
+/**
+ * Count consecutive final failures (failed/timed_out/abandoned) in recent run
+ * history. Skipped bookkeeping runs and in-flight runs are neutral; a success
+ * resets the streak. Failed runs with attempts remaining (attempt <
+ * maxAttempts) are pending retries by the scheduler's own semantics, so they
+ * are neutral too — only exhausted slots count as final failures. A previous
+ * circuit-breaker marker acts as a watermark (compared via scheduledFor, which
+ * shares the scheduler clock with run slots, unlike the marker's wall-clock
+ * createdAt): only failures after it count, so a manual resume requires a
+ * fresh streak before the breaker can trip again.
+ */
+export declare function consecutiveFailureCount(store: Store, loopId: string, maxAttempts?: number, scanLimit?: number): number;
+export declare function advanceLoop(store: Store, loop: Loop, run: LoopRun, finishedAt: Date, succeeded: boolean, opts?: AdvanceLoopOptions): void;
 export declare function executeClaimedRun(deps: {
     store: Store;
     runnerId: string;