@hasna/loops 0.3.60 → 0.4.1

package/dist/lib/accounts.d.ts

@@ -1,4 +1,9 @@
 import type { AccountRef, AgentProvider } from "../types.js";
 export declare function accountToolForProvider(provider: AgentProvider): string;
 export declare function parseAccountExportLines(output: string): Record<string, string>;
-export declare function resolveAccountEnv(account: AccountRef | undefined, toolHint?: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function resolveAccountEnv(account: AccountRef | undefined, toolHint?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, string>>;
+/**
+ * Synchronous variant reserved for the synchronous preflight path; execution
+ * paths must use the async resolveAccountEnv so the daemon event loop never blocks.
+ */
+export declare function resolveAccountEnvSync(account: AccountRef | undefined, toolHint?: string, env?: NodeJS.ProcessEnv): Record<string, string>;

package/dist/lib/agent-adapter.d.ts

@@ -0,0 +1,74 @@
+import type { AgentProvider, AgentSandbox, AgentTarget } from "../types.js";
+export type ProviderPromptChannel = "stdin" | "argv";
+export interface ProviderCapabilities {
+    /** Sandbox values the provider CLI accepts; empty when sandboxing is unsupported. */
+    sandbox: readonly AgentSandbox[];
+    /** Whether the provider runs as a durable background agent instead of a one-shot process. */
+    durable: boolean;
+    /** Whether the provider can be dispatched to a remote machine transport. */
+    remote: boolean;
+    /** How the prompt reaches the provider process. */
+    promptChannel: ProviderPromptChannel;
+}
+export interface AgentInvocation {
+    command: string;
+    args: string[];
+    /** Prompt delivered on stdin; unset only for argv-channel providers. */
+    stdin?: string;
+    /** Executables of which at least one must exist besides the command itself. */
+    preflightAnyOf?: string[];
+}
+export interface ProviderAdapter {
+    provider: AgentProvider;
+    capabilities: ProviderCapabilities;
+    validate(target: AgentTarget, label?: string): void;
+    buildInvocation(target: AgentTarget): AgentInvocation;
+}
+export declare const UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS: Set<string>;
+export declare const PROVIDER_ADAPTERS: Record<AgentProvider, ProviderAdapter>;
+export declare const AGENT_PROVIDERS: AgentProvider[];
+export declare function providerAdapter(provider: AgentProvider): ProviderAdapter;
+export interface SpawnCaptureOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs: number;
+    maxOutputBytes?: number;
+}
+export interface CapturedProcessResult {
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    error?: string;
+    timedOut: boolean;
+}
+export declare function killProcessGroup(pgid: number): void;
+/**
+ * Byte-bounded UTF-8 output accumulator shared by the capture paths
+ * (spawnCapture here, executeTarget/executeRemoteSpec in executor.ts).
+ *
+ * - Callers feed decoded strings (`stream.setEncoding("utf8")` keeps
+ *   multi-byte sequences split across pipe chunks intact); the buffer never
+ *   decodes chunks itself.
+ * - Truncation keeps at most `maxBytes` BYTES of tail, cutting at a UTF-8
+ *   sequence boundary so the retained text never starts mid-character.
+ * - The truncation marker reports the CUMULATIVE dropped byte count.
+ * - The accumulated text is scrubbed BEFORE every cut: truncation can bisect
+ *   a credential so the surviving fragment no longer matches any scrub
+ *   pattern, while scrubbing first turns the intact token into [SCRUBBED]
+ *   and the cut then slices through the marker harmlessly (scrubSecrets is
+ *   idempotent, so store-time re-scrubbing stays safe).
+ */
+export declare class BoundedOutputBuffer {
+    private readonly maxBytes;
+    private text;
+    private truncatedBytes;
+    constructor(maxBytes: number);
+    append(chunk: string): void;
+    value(): string;
+}
+/**
+ * Async replacement for short spawnSync calls: never blocks the event loop and
+ * always enforces an explicit timeout that kills the child's process group.
+ */
+export declare function spawnCapture(command: string, args: string[], opts: SpawnCaptureOptions): Promise<CapturedProcessResult>;

package/dist/lib/backup.d.ts

@@ -0,0 +1,25 @@
+export interface BackupDatabaseOptions {
+    /** Why this backup is being taken (e.g. "pre-migration", "daily"). Debounce and retention are tracked per reason. */
+    reason: string;
+    /** How many backups to retain per reason (newest first). */
+    keep?: number;
+    /** Source database file; defaults to the live store path. Tests must pass a temp path. */
+    dbFile?: string;
+    /** Directory for backup files; defaults to `<db dir>/backups`. */
+    backupsDir?: string;
+    /** Injectable clock for tests. */
+    now?: Date;
+}
+export interface BackupDatabaseResult {
+    /** Absolute path of the backup that was written (absent when skipped). */
+    path?: string;
+    skipped: boolean;
+    skipReason?: string;
+    /** Backups removed by retention pruning. */
+    prunedPaths: string[];
+}
+/**
+ * Snapshot the loops database with `VACUUM INTO`. Per-reason backups are
+ * debounced to at most one per hour and pruned to the `keep` most recent.
+ */
+export declare function backupDatabase(opts: BackupDatabaseOptions): BackupDatabaseResult;

package/dist/lib/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Coded errors thrown by the store and CLI layers. Each class carries a stable
+ * machine-readable `.code` so callers can branch on failure kind without
+ * parsing human-readable messages.
+ */
+export declare class CodedError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class LoopNotFoundError extends CodedError {
+    constructor(idOrName: string);
+}
+export declare class LoopArchivedError extends CodedError {
+    constructor(idOrName: string);
+}
+export declare class AmbiguousNameError extends CodedError {
+    constructor(name: string);
+}
+export declare class ValidationError extends CodedError {
+    constructor(message: string);
+}

package/dist/lib/executor.d.ts

@@ -1,5 +1,10 @@
 import type { LanguageModel } from "ai";
-import type { ExecutableTarget, ExecutorResult, Loop, LoopMachineRef, LoopRun, PersistGuardOptions } from "../types.js";
+import type { AgentTarget, ExecutableTarget, ExecutorResult, Loop, LoopMachineRef, LoopRun, PersistGuardOptions } from "../types.js";
+export interface SpawnedProcessInfo {
+    pid: number;
+    pgid: number;
+    processStartedAt: string;
+}
 export interface ExecuteOptions extends PersistGuardOptions {
     maxOutputBytes?: number;
     env?: NodeJS.ProcessEnv;
@@ -7,6 +12,8 @@ export interface ExecuteOptions extends PersistGuardOptions {
     log?: (message: string) => void;
     signal?: AbortSignal;
     onSpawn?: (pid: number) => void;
+    /** Children are spawned detached in their own process group, so pgid === pid. */
+    onSpawnProcess?: (info: SpawnedProcessInfo) => void;
     machine?: LoopMachineRef;
     machineResolver?: (machine: LoopMachineRef) => LoopMachineRef;
     machineCommandResolver?: (machineId: string, command: string) => MachineCommandPlan;
@@ -34,6 +41,8 @@ interface MachineCommandPlan {
     args: string[];
     source: string;
 }
+/** Exported for tests: resolves the default idle watchdog for agent targets. */
+export declare function defaultAgentIdleTimeoutMs(target: AgentTarget, opts: ExecuteOptions): number | undefined;
 export declare function preflightTarget(target: ExecutableTarget, metadata?: ExecutionMetadata, opts?: ExecuteOptions): PreflightResult;
 export declare function executeTarget(target: ExecutableTarget, metadata?: ExecutionMetadata, opts?: ExecuteOptions): Promise<ExecutorResult>;
 export declare function executeLoop(loop: Loop, run: LoopRun, opts?: ExecuteOptions): Promise<ExecutorResult>;

package/dist/lib/goal/metadata.d.ts

@@ -0,0 +1,16 @@
+import type { Loop, LoopRun, WorkflowSpec } from "../../types.js";
+import type { Goal, GoalExecutionContext, GoalPlanNode } from "./types.js";
+export interface GoalContextParts {
+    loop?: Pick<Loop, "id" | "name">;
+    loopRun?: Pick<LoopRun, "id" | "scheduledFor">;
+    scheduledFor?: string;
+    workflow?: Pick<WorkflowSpec, "id" | "name">;
+    workflowRunId?: string;
+    workflowStepId?: string;
+}
+/** Single source for the goal execution context previously copy-pasted across runners. */
+export declare function goalExecutionContext(parts: GoalContextParts): GoalExecutionContext;
+/** Executor metadata (LOOPS_* env) derived from a goal execution context; loopRunId maps to runId. */
+export declare function executionMetadata(context: GoalExecutionContext | undefined, goal?: Pick<Goal, "goalId" | "objective">, node?: Pick<GoalPlanNode, "key">): Record<string, string | undefined>;
+/** Exposes the executing plan node to child processes so command targets can honor node objectives. */
+export declare function withGoalNodeEnv(env: NodeJS.ProcessEnv | undefined, node: Pick<GoalPlanNode, "key" | "objective">): NodeJS.ProcessEnv;

package/dist/lib/goal/model-factory.d.ts

@@ -7,3 +7,4 @@ export interface ResolveGoalModelOptions {
 }
 export declare const DEFAULT_GOAL_MODEL = "openai/gpt-4o-mini";
 export declare function resolveGoalModel(opts?: ResolveGoalModelOptions): LanguageModel;
+export declare function resolveGoalVerifierModel(opts?: ResolveGoalModelOptions): LanguageModel;

package/dist/lib/goal/prompts.d.ts

@@ -1,4 +1,6 @@
+import type { ExecutableTarget } from "../../types.js";
 import type { Goal, GoalPlanNode, GoalSpec } from "./types.js";
 export declare function planPrompt(spec: GoalSpec): string;
-export declare function iterationPrompt(goal: Goal, readyNodes: GoalPlanNode[]): string;
+export declare function iterationPrompt(goal: Pick<Goal, "objective">, node: Pick<GoalPlanNode, "key" | "objective">): string;
+export declare function goalNodeTarget(target: ExecutableTarget, goal: Pick<Goal, "objective">, node: Pick<GoalPlanNode, "key" | "objective">): ExecutableTarget;
 export declare function achievementPrompt(goal: Goal, nodes: GoalPlanNode[], evidence: string[]): string;

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

@@ -11,6 +11,8 @@ export interface GoalSpec {
     objective: string;
     tokenBudget?: number;
     model?: string;
+    /** Independent model for the achievement audit; defaults to LOOPS_GOAL_VERIFIER_MODEL, then the planner model. */
+    verifierModel?: string;
     maxTurns?: number;
     maxTokens?: number;
     autoExecute?: GoalAutoExecute;
@@ -105,6 +107,7 @@ export interface GoalExecutionContext {
 export interface RunGoalOptions {
     store?: Store;
     model?: LanguageModel;
+    verifierModel?: LanguageModel;
     target?: ExecutableTarget;
     executeNode?: (node: GoalPlanNode, metadata: Record<string, string | undefined>) => Promise<ExecutorResult>;
     env?: NodeJS.ProcessEnv;

package/dist/lib/health.d.ts

@@ -1,6 +1,6 @@
 import type { Loop, LoopRun } from "../types.js";
 import type { Store } from "./store.js";
-export type RunFailureClassification = "rate_limit" | "auth" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "preflight" | "route_functional" | "timeout" | "sigsegv" | "skipped_previous_active" | "unknown";
+export type RunFailureClassification = "rate_limit" | "auth" | "model_not_found" | "context_length" | "schema_response_format" | "node_init" | "preflight" | "route_functional" | "timeout" | "sigsegv" | "skipped_previous_active" | "circuit_breaker" | "unknown";
 export interface RunFailureSignal {
     classification: RunFailureClassification;
     fingerprint: string;

package/dist/lib/ids.d.ts

@@ -1,2 +1,9 @@
-export declare function genId(length?: number): string;
+/**
+ * Generate a 128-bit, time-sortable identifier (ULID-like): a 48-bit
+ * millisecond timestamp prefix (12 lowercase hex chars) followed by 80 random
+ * bits (20 lowercase hex chars). Fixed width keeps lexicographic order aligned
+ * with creation time, and plain lowercase hex stays compatible with the
+ * existing TEXT primary keys written by earlier releases.
+ */
+export declare function genId(): string;
 export declare function nowIso(): string;

package/dist/lib/machines.d.ts

@@ -1,4 +1,9 @@
 import type { LoopMachineRef } from "../types.js";
+export interface MachineCommandPlan {
+    command: string;
+    args: string[];
+    source: string;
+}
 export interface OpenMachineSummary {
     id: string;
     hostname?: string;
@@ -13,4 +18,5 @@ export interface OpenMachineSummary {
 }
 export declare function listOpenMachines(): OpenMachineSummary[];
 export declare function resolveLoopMachine(machineId: string): LoopMachineRef;
+export declare function resolveMachineCommand(machineId: string, command: string): MachineCommandPlan;
 export declare function refreshLoopMachine(machine: LoopMachineRef): LoopMachineRef;

package/dist/lib/mode.d.ts

@@ -0,0 +1,48 @@
+export declare const LOOP_DEPLOYMENT_MODES: readonly ["local", "self_hosted", "cloud"];
+export type LoopDeploymentMode = (typeof LOOP_DEPLOYMENT_MODES)[number];
+export type LoopSourceOfTruth = "local_sqlite" | "self_hosted_control_plane" | "cloud_control_plane";
+export interface LoopModeResolution {
+    deploymentMode: LoopDeploymentMode;
+    source: string;
+}
+export interface LoopControlPlaneConfig {
+    apiUrl?: string;
+    cloudApiUrl?: string;
+    databaseUrlPresent: boolean;
+    apiAuthTokenPresent: boolean;
+    cloudAuthTokenPresent: boolean;
+    authTokenPresent: boolean;
+}
+export interface LoopDeploymentStatus {
+    packageVersion: string;
+    deploymentMode: LoopDeploymentMode;
+    activeDeploymentMode: LoopDeploymentMode;
+    active: boolean;
+    deploymentModeSource: string;
+    sourceOfTruth: LoopSourceOfTruth;
+    localStore: {
+        role: "authoritative" | "cache_and_spool";
+    };
+    controlPlane: {
+        kind: "none" | "self_hosted" | "cloud";
+        configured: boolean;
+        apiUrl?: string;
+        databaseUrlPresent: boolean;
+        authTokenPresent: boolean;
+    };
+    runner: {
+        required: boolean;
+        role: "daemon" | "control_plane_worker";
+    };
+    warnings: string[];
+}
+type Env = Record<string, string | undefined>;
+export declare function normalizeLoopDeploymentMode(value: string): LoopDeploymentMode;
+export declare function resolveLoopDeploymentMode(env?: Env): LoopModeResolution;
+export declare function loopControlPlaneConfig(env?: Env): LoopControlPlaneConfig;
+export declare function buildDeploymentStatus(opts?: {
+    env?: Env;
+    perspective?: LoopDeploymentMode;
+}): LoopDeploymentStatus;
+export declare function deploymentStatusLine(status: LoopDeploymentStatus): string;
+export {};

package/dist/lib/mode.js

@@ -0,0 +1,260 @@
+// @bun
+// package.json
+var package_default = {
+  name: "@hasna/loops",
+  version: "0.4.1",
+  description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
+  type: "module",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  bin: {
+    loops: "dist/cli/index.js",
+    "loops-daemon": "dist/daemon/index.js",
+    "loops-api": "dist/api/index.js",
+    "loops-runner": "dist/runner/index.js",
+    "loops-mcp": "dist/mcp/index.js"
+  },
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      import: "./dist/index.js"
+    },
+    "./sdk": {
+      types: "./dist/sdk/index.d.ts",
+      import: "./dist/sdk/index.js"
+    },
+    "./mcp": {
+      types: "./dist/mcp/index.d.ts",
+      import: "./dist/mcp/index.js"
+    },
+    "./api": {
+      types: "./dist/api/index.d.ts",
+      import: "./dist/api/index.js"
+    },
+    "./runner": {
+      types: "./dist/runner/index.d.ts",
+      import: "./dist/runner/index.js"
+    },
+    "./mode": {
+      types: "./dist/lib/mode.d.ts",
+      import: "./dist/lib/mode.js"
+    },
+    "./storage": {
+      types: "./dist/lib/store.d.ts",
+      import: "./dist/lib/store.js"
+    }
+  },
+  files: [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "LICENSE"
+  ],
+  scripts: {
+    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
+    typecheck: "tsc --noEmit",
+    test: "bun test",
+    "test:boundary": "bun run scripts/no-private-cloud-boundary.mjs",
+    prepare: "test -d dist || bun run build",
+    "dev:cli": "bun run src/cli/index.ts",
+    "dev:daemon": "bun run src/daemon/index.ts",
+    prepublishOnly: "bun run build && bun run test:boundary"
+  },
+  keywords: [
+    "loops",
+    "scheduler",
+    "daemon",
+    "agents",
+    "claude",
+    "cursor",
+    "codewith",
+    "opencode",
+    "cli"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/hasna/loops.git"
+  },
+  homepage: "https://github.com/hasna/loops#readme",
+  bugs: {
+    url: "https://github.com/hasna/loops/issues"
+  },
+  author: "Hasna <andrei@hasna.com>",
+  license: "Apache-2.0",
+  engines: {
+    bun: ">=1.0.0"
+  },
+  dependencies: {
+    "@hasna/events": "^0.1.9",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openrouter/ai-sdk-provider": "2.9.1",
+    ai: "6.0.204",
+    commander: "^13.1.0",
+    zod: "4.4.3"
+  },
+  optionalDependencies: {
+    "@hasna/machines": "0.0.49"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    typescript: "^5.7.3"
+  },
+  publishConfig: {
+    registry: "https://registry.npmjs.org",
+    access: "public"
+  }
+};
+
+// src/lib/version.ts
+function packageVersion() {
+  if (typeof package_default.version !== "string" || package_default.version.trim() === "")
+    throw new Error("package.json version is missing");
+  return package_default.version;
+}
+
+// src/lib/mode.ts
+var LOOP_DEPLOYMENT_MODES = ["local", "self_hosted", "cloud"];
+var MODE_ENV_KEYS = ["LOOPS_MODE", "HASNA_LOOPS_MODE"];
+var API_URL_ENV_KEYS = ["LOOPS_API_URL", "HASNA_LOOPS_API_URL"];
+var CLOUD_API_URL_ENV_KEYS = ["LOOPS_CLOUD_API_URL", "HASNA_LOOPS_CLOUD_API_URL"];
+var DATABASE_URL_ENV_KEYS = ["LOOPS_DATABASE_URL", "HASNA_LOOPS_DATABASE_URL"];
+var API_TOKEN_ENV_KEYS = ["LOOPS_API_TOKEN", "HASNA_LOOPS_API_TOKEN"];
+var CLOUD_TOKEN_ENV_KEYS = ["LOOPS_CLOUD_TOKEN", "HASNA_LOOPS_CLOUD_TOKEN"];
+var TOKEN_ENV_KEYS = [...API_TOKEN_ENV_KEYS, ...CLOUD_TOKEN_ENV_KEYS];
+function envValue(env, keys) {
+  for (const key of keys) {
+    const value = env[key]?.trim();
+    if (value)
+      return { key, value };
+  }
+  return;
+}
+function normalizeLoopDeploymentMode(value) {
+  const normalized = value.trim().toLowerCase().replace(/-/g, "_");
+  if (normalized === "local")
+    return "local";
+  if (normalized === "self_hosted" || normalized === "selfhosted")
+    return "self_hosted";
+  if (normalized === "cloud" || normalized === "saas")
+    return "cloud";
+  throw new Error(`unsupported OpenLoops deployment mode "${value}"; expected local, self_hosted, or cloud`);
+}
+function resolveLoopDeploymentMode(env = process.env) {
+  const explicitMode = envValue(env, MODE_ENV_KEYS);
+  if (explicitMode) {
+    return {
+      deploymentMode: normalizeLoopDeploymentMode(explicitMode.value),
+      source: explicitMode.key
+    };
+  }
+  const cloudApiUrl = envValue(env, CLOUD_API_URL_ENV_KEYS);
+  if (cloudApiUrl)
+    return { deploymentMode: "cloud", source: cloudApiUrl.key };
+  const apiUrl = envValue(env, API_URL_ENV_KEYS);
+  if (apiUrl)
+    return { deploymentMode: "self_hosted", source: apiUrl.key };
+  const databaseUrl = envValue(env, DATABASE_URL_ENV_KEYS);
+  if (databaseUrl)
+    return { deploymentMode: "self_hosted", source: databaseUrl.key };
+  return { deploymentMode: "local", source: "default" };
+}
+function loopControlPlaneConfig(env = process.env) {
+  return {
+    apiUrl: envValue(env, API_URL_ENV_KEYS)?.value,
+    cloudApiUrl: envValue(env, CLOUD_API_URL_ENV_KEYS)?.value,
+    databaseUrlPresent: Boolean(envValue(env, DATABASE_URL_ENV_KEYS)),
+    apiAuthTokenPresent: Boolean(envValue(env, API_TOKEN_ENV_KEYS)),
+    cloudAuthTokenPresent: Boolean(envValue(env, CLOUD_TOKEN_ENV_KEYS)),
+    authTokenPresent: Boolean(envValue(env, TOKEN_ENV_KEYS))
+  };
+}
+function sourceOfTruthForMode(mode) {
+  if (mode === "local")
+    return "local_sqlite";
+  if (mode === "self_hosted")
+    return "self_hosted_control_plane";
+  return "cloud_control_plane";
+}
+function displayControlPlaneUrl(value) {
+  if (!value)
+    return;
+  try {
+    const url = new URL(value);
+    const path = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/g, "");
+    return `${url.origin}${path}`;
+  } catch {
+    return "[invalid-url]";
+  }
+}
+function buildDeploymentStatus(opts = {}) {
+  const env = opts.env ?? process.env;
+  const active = resolveLoopDeploymentMode(env);
+  const deploymentMode = opts.perspective ?? active.deploymentMode;
+  const config = loopControlPlaneConfig(env);
+  const rawApiUrl = deploymentMode === "cloud" ? config.cloudApiUrl : config.apiUrl;
+  const apiUrl = displayControlPlaneUrl(rawApiUrl);
+  const controlPlaneKind = deploymentMode === "local" ? "none" : deploymentMode;
+  const deploymentAuthTokenPresent = deploymentMode === "cloud" ? config.cloudAuthTokenPresent : deploymentMode === "self_hosted" ? config.apiAuthTokenPresent : false;
+  const controlPlaneConfigured = deploymentMode === "local" ? false : deploymentMode === "self_hosted" ? Boolean(config.apiUrl || config.databaseUrlPresent) : Boolean(config.cloudApiUrl && deploymentAuthTokenPresent);
+  const warnings = [];
+  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 === "cloud" && config.apiUrl && !config.cloudApiUrl) {
+    warnings.push("LOOPS_API_URL selects self_hosted; cloud mode uses LOOPS_CLOUD_API_URL");
+  }
+  if (deploymentMode === "cloud" && !config.cloudApiUrl) {
+    warnings.push("cloud mode is a public contract until LOOPS_CLOUD_API_URL is configured");
+  }
+  if (deploymentMode === "cloud" && config.cloudApiUrl && !deploymentAuthTokenPresent) {
+    warnings.push("cloud mode needs LOOPS_CLOUD_TOKEN or HASNA_LOOPS_CLOUD_TOKEN before it can become ready");
+  }
+  if (opts.perspective && opts.perspective !== active.deploymentMode) {
+    warnings.push(`active deployment mode is ${active.deploymentMode}; this is the ${opts.perspective} perspective`);
+  }
+  return {
+    packageVersion: packageVersion(),
+    deploymentMode,
+    activeDeploymentMode: active.deploymentMode,
+    active: deploymentMode === active.deploymentMode,
+    deploymentModeSource: active.source,
+    sourceOfTruth: sourceOfTruthForMode(deploymentMode),
+    localStore: {
+      role: deploymentMode === "local" ? "authoritative" : "cache_and_spool"
+    },
+    controlPlane: {
+      kind: controlPlaneKind,
+      configured: controlPlaneConfigured,
+      apiUrl,
+      databaseUrlPresent: config.databaseUrlPresent,
+      authTokenPresent: deploymentAuthTokenPresent
+    },
+    runner: {
+      required: deploymentMode !== "local",
+      role: deploymentMode === "local" ? "daemon" : "control_plane_worker"
+    },
+    warnings
+  };
+}
+function deploymentStatusLine(status) {
+  const configured = status.controlPlane.kind === "none" ? "none" : String(status.controlPlane.configured);
+  const active = status.active ? "active" : `active=${status.activeDeploymentMode}`;
+  return [
+    `deploymentMode=${status.deploymentMode}`,
+    active,
+    `source=${status.deploymentModeSource}`,
+    `truth=${status.sourceOfTruth}`,
+    `local=${status.localStore.role}`,
+    `control_plane=${configured}`
+  ].join(" ");
+}
+export {
+  resolveLoopDeploymentMode,
+  normalizeLoopDeploymentMode,
+  loopControlPlaneConfig,
+  deploymentStatusLine,
+  buildDeploymentStatus,
+  LOOP_DEPLOYMENT_MODES
+};

package/dist/lib/process-identity.d.ts

@@ -0,0 +1,16 @@
+export declare const START_TIME_TOLERANCE_MS = 5000;
+export declare function procStatFields(path: string): string[] | undefined;
+export declare function processStartTimeMs(pid: number): number | undefined;
+/**
+ * Lenient fingerprint comparison: unknown data (no recorded start time, an
+ * unparsable record, or an unresolvable actual start time) counts as a match.
+ * Use for non-destructive liveness checks where "possibly alive" is the safe
+ * answer (pidfile checks, deciding not to take over a lease).
+ */
+export declare function sameProcessStart(recorded: string | number | undefined, actualMs: number | undefined, toleranceMs?: number): boolean;
+/**
+ * Strict fingerprint comparison for destructive paths (signalling processes):
+ * true only when both the recorded and actual start times resolve and match
+ * within tolerance. Unverifiable identity fails closed as a mismatch.
+ */
+export declare function verifiedProcessStart(recorded: string | number | undefined, actualMs: number | undefined, toleranceMs?: number): boolean;

package/dist/lib/{schedule.d.ts → recurrence.d.ts}

@@ -16,6 +16,7 @@ export interface DuePlan {
     slots: string[];
     skippedToNextRunAt?: string;
 }
+export declare const MAX_CATCH_UP_SLOTS = 1000;
 export declare function dueSlots(loop: Loop, now: Date): DuePlan;
 export declare function parseDuration(input: string): number;
 export {};

package/dist/lib/redact.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Write-path secret scrubbing. `scrubSecrets` removes credential material from
+ * text before it is persisted (run stdout/stderr/error, goal evidence, raw
+ * model responses). Display-layer truncation/redaction lives in format.ts;
+ * this module is about never writing recoverable secrets to disk at all.
+ *
+ * The function is idempotent (`scrubSecrets(scrubSecrets(x)) === scrubSecrets(x)`)
+ * and linear over the input, so it stays fast on multi-hundred-KB outputs.
+ */
+/**
+ * Replace credential tokens in `text` with "[SCRUBBED]". Idempotent and safe
+ * to run on JSON-encoded payloads (replacements never introduce quotes).
+ */
+export declare function scrubSecrets(text: string): string;
+/**
+ * Recursively scrub the string leaves of a JSON-serializable value. Run this
+ * BEFORE `JSON.stringify` when persisting structured payloads (goal evidence,
+ * raw model responses): stringify escapes quotes, which would otherwise hide
+ * quoted secrets from the flat text patterns above.
+ */
+export declare function scrubSecretsDeep<T>(value: T): T;

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

@@ -0,0 +1,18 @@
+export interface RouteSelection<T> {
+    selected: T[];
+    cursor: {
+        key: string;
+        total: number;
+        maxActions: number;
+        previousFingerprint?: string;
+        startIndex: number;
+        lastFingerprint?: string;
+    };
+}
+export declare function writeRouteCursor(key: string, lastFingerprint: string | undefined): void;
+export declare function writeRouteEvidence(kind: string, value: unknown, evidenceDir: string | undefined): string | undefined;
+export declare function selectRouteItems<T>(items: T[], maxActions: number, cursorKey: string, fingerprintOf: (item: T) => string): RouteSelection<T>;
+export declare function routeCursorKey(kind: "health" | "hygiene", parts: unknown[], opts: {
+    autoRoute?: boolean;
+    routeProjectPath?: string;
+}): string;

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

@@ -0,0 +1,6 @@
+import type { TodosDrainOptions } from "./types.js";
+export interface DrainResult {
+    value: Record<string, unknown>;
+    human: string;
+}
+export declare function drainTodosTaskRoutes(opts: TodosDrainOptions): DrainResult;