@hasna/loops 0.4.14 → 0.4.22

package/dist/runner/index.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.14",
+  version: "0.4.22",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -113,7 +113,6 @@ var package_default = {
     bun: ">=1.0.0"
   },
   dependencies: {
-    "@hasna/contracts": "^0.4.1",
     "@hasna/events": "^0.1.9",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@openrouter/ai-sdk-provider": "2.9.1",
@@ -123,7 +122,8 @@ var package_default = {
     zod: "4.4.3"
   },
   optionalDependencies: {
-    "@hasna/machines": "0.0.49"
+    "@hasna/machines": "0.0.49",
+    "@hasna/contracts": "^0.4.2"
   },
   devDependencies: {
     "@types/bun": "latest",
@@ -1098,6 +1098,7 @@ var TRANSPORT_ENV_KEYS = new Set([
   "LOGNAME",
   "PATH",
   "SHELL",
+  "SHLVL",
   "SSH_AGENT_PID",
   "SSH_AUTH_SOCK",
   "TERM",
@@ -1319,6 +1320,7 @@ function composeExecutionEnv(spec, metadata, opts, accountEnv) {
   Object.assign(env, spec.env ?? {});
   Object.assign(env, allowlistEnv(spec.allowlist));
   env.PATH = normalizeExecutionPath(env);
+  env.SHLVL ||= "1";
   Object.assign(env, metadataEnv(metadata));
   return env;
 }
@@ -1390,7 +1392,7 @@ function remoteWorktreePrepareLines(worktree) {
   return [
     "__openloops_prepare_worktree() {",
     `  local repo=${shellQuote(repoRoot)} path=${shellQuote(path)} branch=${shellQuote(branch)}`,
-    "  local top expected_common actual_common current",
+    "  local top expected_common actual_common current status recovered",
     '  if [ -L "$path" ]; then echo "refusing symlinked worktree path $path" >&2; return 1; fi',
     '  if [ -e "$path" ]; then',
     '    top="$(git -C "$path" rev-parse --show-toplevel 2>/dev/null)" || { echo "refusing to reuse non-worktree path: $path" >&2; return 1; }',
@@ -1399,7 +1401,19 @@ function remoteWorktreePrepareLines(worktree) {
     '    actual_common="$(cd "$path" 2>/dev/null && cd "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null && pwd -P)"',
     '    if [ -z "$expected_common" ] || [ "$expected_common" != "$actual_common" ]; then echo "existing worktree $path belongs to a different git common dir" >&2; return 1; fi',
     '    current="$(git -C "$path" branch --show-current 2>/dev/null)"',
-    '    if [ "$current" != "$branch" ]; then echo "existing worktree $path is on branch ${current:-unknown}, expected $branch" >&2; return 1; fi',
+    '    if [ "$current" != "$branch" ]; then',
+    '      status="$(git -C "$path" status --porcelain=v1 --untracked-files=all 2>/dev/null)" || { echo "existing worktree $path is on branch ${current:-unknown}, expected $branch, and cleanliness could not be checked; inspect or remove the stale worktree" >&2; return 1; }',
+    '      if [ -n "$status" ]; then echo "existing worktree $path is on branch ${current:-unknown}, expected $branch, and has local changes; commit/stash them or remove the stale worktree before retrying" >&2; return 1; fi',
+    '      if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then',
+    '        git -C "$path" checkout "$branch" 1>&2 || { echo "existing worktree $path is clean but could not switch from branch ${current:-unknown} to expected $branch; remove/prune the stale worktree or free the branch before retrying" >&2; return 1; }',
+    '      elif [ -z "$current" ]; then',
+    '        git -C "$path" checkout -b "$branch" 1>&2 || { echo "existing worktree $path is clean but could not recreate expected branch $branch at the current detached HEAD; remove/prune the stale worktree before retrying" >&2; return 1; }',
+    "      else",
+    '        echo "existing worktree $path is on branch $current, expected $branch, but expected branch does not exist; remove/prune the stale worktree or recreate the expected branch before retrying" >&2; return 1',
+    "      fi",
+    '      recovered="$(git -C "$path" branch --show-current 2>/dev/null)"',
+    '      if [ "$recovered" != "$branch" ]; then echo "existing worktree $path branch recovery ended on ${recovered:-unknown}, expected $branch; remove/prune the stale worktree before retrying" >&2; return 1; fi',
+    "    fi",
     "    return 0",
     "  fi",
     '  git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "worktree repoRoot is not a git repository: $repo" >&2; return 1; }',
@@ -1480,8 +1494,21 @@ function transportEnv(opts) {
       env[key] = value;
   }
   env.PATH = normalizeExecutionPath(env);
+  env.SHLVL ||= "1";
   return env;
 }
+function remotePreflightFailureMessage(machineId, detail) {
+  const normalized = detail.trim();
+  if (/Host key verification failed|REMOTE HOST IDENTIFICATION HAS CHANGED|Offending .*key in .*known_hosts/i.test(normalized)) {
+    return [
+      `remote preflight failed on ${machineId}: SSH host key verification failed.`,
+      `Verify ${machineId}'s host identity and repair SSH known_hosts/trust material outside OpenLoops;`,
+      "OpenLoops will not disable host-key checking or modify known_hosts automatically.",
+      normalized ? `Transport detail: ${normalized}` : ""
+    ].filter(Boolean).join(" ");
+  }
+  return `remote preflight failed on ${machineId}${normalized ? `: ${normalized}` : ""}`;
+}
 function assertCodewithProfileListed(profile, result) {
   const profiles = codewithProfileSetFromResult(result);
   if (!profiles.has(profile)) {
@@ -1533,6 +1560,9 @@ async function preflightNativeAuthProfile(spec, env) {
   const tableResult = await spawnCapture(spec.command, ["profile", "list"], { env, timeoutMs: 15000 });
   assertCodewithProfileListed(spec.nativeAuthProfile.profile, tableResult);
 }
+function spawnDetail(result) {
+  return (result.stderr || result.stdout || result.error || "").toString().trim();
+}
 function resolvedDirEquals(left, right) {
   try {
     return realpathSync(left) === realpathSync(right);
@@ -1582,8 +1612,45 @@ async function ensureLocalWorktree(worktree, env) {
     }
     const current = await git(["-C", path, "branch", "--show-current"]);
     const actualBranch = current.stdout.trim();
-    if (current.error || (current.status ?? 1) !== 0 || actualBranch !== branch) {
-      return { error: `existing worktree ${path} is on branch ${actualBranch || "unknown"}, expected ${branch}` };
+    if (current.error || (current.status ?? 1) !== 0) {
+      return { error: `existing worktree ${path} branch could not be inspected${spawnDetail(current) ? `: ${spawnDetail(current)}` : ""}` };
+    }
+    if (actualBranch !== branch) {
+      const actualLabel = actualBranch || "unknown";
+      const status = await git(["-C", path, "status", "--porcelain=v1", "--untracked-files=all"]);
+      if (status.error || (status.status ?? 1) !== 0) {
+        const detail = spawnDetail(status);
+        return {
+          error: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, and cleanliness could not be checked; inspect or remove the stale worktree${detail ? `: ${detail}` : ""}`
+        };
+      }
+      if (status.stdout.trim()) {
+        return {
+          error: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, and has local changes; commit/stash them or remove the stale worktree before retrying`
+        };
+      }
+      const hasBranch2 = await git(["-C", repoRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+      const checkout = hasBranch2.status === 0 ? await git(["-C", path, "checkout", branch]) : actualBranch ? {
+        status: 1,
+        stdout: "",
+        stderr: `existing worktree ${path} is on branch ${actualLabel}, expected ${branch}, but expected branch does not exist; remove/prune the stale worktree or recreate the expected branch before retrying`,
+        signal: null,
+        timedOut: false
+      } : await git(["-C", path, "checkout", "-b", branch]);
+      if (checkout.error || (checkout.status ?? 1) !== 0) {
+        const detail = spawnDetail(checkout);
+        return {
+          error: `existing worktree ${path} is clean but could not recover branch ${branch} from ${actualLabel}; remove/prune the stale worktree before retrying${detail ? `: ${detail}` : ""}`
+        };
+      }
+      const recovered = await git(["-C", path, "branch", "--show-current"]);
+      if (recovered.error || (recovered.status ?? 1) !== 0 || recovered.stdout.trim() !== branch) {
+        const recoveredBranch = recovered.stdout.trim() || "unknown";
+        const detail = spawnDetail(recovered);
+        return {
+          error: `existing worktree ${path} branch recovery ended on ${recoveredBranch}, expected ${branch}; remove/prune the stale worktree before retrying${detail ? `: ${detail}` : ""}`
+        };
+      }
     }
     return { cwd: worktree.cwd };
   }
@@ -1599,7 +1666,7 @@ async function ensureLocalWorktree(worktree, env) {
   const hasBranch = await git(["-C", repoRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
   const add = hasBranch.status === 0 ? await git(["-C", repoRoot, "worktree", "add", path, branch]) : await git(["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
   if (add.error || (add.status ?? 1) !== 0) {
-    const detail = (add.stderr || add.stdout || add.error || "").toString().trim();
+    const detail = spawnDetail(add);
     return { error: `git worktree add failed for ${path}${detail ? `: ${detail}` : ""}` };
   }
   return { cwd: worktree.cwd };
@@ -1645,7 +1712,7 @@ function preflightRemoteSpec(spec, machine, metadata, opts) {
     throw new Error(`remote preflight failed on ${machine.id}: ${result.error.message}`);
   if ((result.status ?? 1) !== 0) {
     const detail = (result.stderr || result.stdout || `exit ${result.status ?? "unknown"}`).trim();
-    throw new Error(`remote preflight failed on ${machine.id}${detail ? `: ${detail}` : ""}`);
+    throw new Error(remotePreflightFailureMessage(machine.id, detail));
   }
 }
 async function executeRemoteSpec(spec, machine, metadata, opts, fallbackSpec) {

package/dist/sdk/http.d.ts

@@ -57,6 +57,60 @@ export interface DeleteResponse {
     "ok": boolean;
     "deleted": boolean;
 }
+export type RunReceiptMachine = string | Record<string, unknown>;
+export interface RunReceiptSummary {
+    "text"?: string;
+    "stdout_bytes": number;
+    "stderr_bytes": number;
+    "stdout_excerpt"?: string;
+    "stderr_excerpt"?: string;
+    "error"?: string;
+    "duration_ms"?: number;
+}
+export interface RunReceipt {
+    "loop_id": string;
+    "run_id": string;
+    "machine": RunReceiptMachine;
+    "repo": string;
+    "task_ids": Array<string>;
+    "knowledge_ids": Array<string>;
+    "digest_id": string;
+    "started_at": string | null;
+    "finished_at": string | null;
+    "status": string;
+    "exit_code": number | null;
+    "summary": RunReceiptSummary;
+    "evidence_paths": Array<string>;
+    "created_at": string;
+    "updated_at": string;
+}
+export interface WriteRunReceiptInput {
+    "loop_id"?: string;
+    "run_id": string;
+    "machine"?: RunReceiptMachine;
+    "repo"?: string;
+    "task_ids"?: Array<string>;
+    "knowledge_ids"?: Array<string>;
+    "digest_id"?: string;
+    "started_at"?: string | null;
+    "finished_at"?: string | null;
+    "status"?: string;
+    "exit_code"?: number | null;
+    "summary"?: string | RunReceiptSummary | null;
+    "evidence_paths"?: Array<string>;
+    "stdout"?: string;
+    "stderr"?: string;
+    "error"?: string;
+    "duration_ms"?: number;
+}
+export interface RunReceiptResponse {
+    "ok": boolean;
+    "receipt": RunReceipt;
+}
+export interface RunReceiptListResponse {
+    "ok": boolean;
+    "receipts": Array<RunReceipt>;
+}
 export interface LoopsClientOptions {
     /** Base URL, e.g. process.env.APP_API_URL. */
     baseUrl: string;
@@ -102,6 +156,19 @@ export declare class LoopsClient {
     archiveLoop(id: string, init?: RequestInit): Promise<LoopResponse>;
     /** Unarchive a loop */
     unarchiveLoop(id: string, init?: RequestInit): Promise<LoopResponse>;
+    /** List run receipts */
+    listRunReceipts(query?: {
+        "loopId"?: string;
+        "repo"?: string;
+        "taskId"?: string;
+        "knowledgeId"?: string;
+        "status"?: string;
+        "limit"?: number;
+    }, init?: RequestInit): Promise<RunReceiptListResponse>;
+    /** Write a run receipt */
+    writeRunReceipt(body: WriteRunReceiptInput, init?: RequestInit): Promise<RunReceiptResponse>;
+    /** Get a run receipt by run id */
+    getRunReceipt(runId: string, init?: RequestInit): Promise<RunReceiptResponse>;
     /** List runs */
     listRuns(query?: {
         "loopId"?: string;

package/dist/sdk/http.js

@@ -117,6 +117,27 @@ class LoopsClient {
       init
     });
   }
+  async listRunReceipts(query, init) {
+    return this.request("GET", `/v1/receipts`, {
+      body: undefined,
+      query,
+      init
+    });
+  }
+  async writeRunReceipt(body, init) {
+    return this.request("POST", `/v1/receipts`, {
+      body,
+      query: undefined,
+      init
+    });
+  }
+  async getRunReceipt(runId, init) {
+    return this.request("GET", `/v1/receipts/${encodeURIComponent(String(runId))}`, {
+      body: undefined,
+      query: undefined,
+      init
+    });
+  }
   async listRuns(query, init) {
     return this.request("GET", `/v1/runs`, {
       body: undefined,

package/dist/sdk/index.d.ts

@@ -1,13 +1,22 @@
-import type { CreateLoopInput, Goal, GoalRun, Loop, LoopRun, LoopStatus, OpenAutomationsRuntimeBinding, RunStatus } from "../types.js";
+import type { CreateLoopInput, Goal, GoalRun, Loop, LoopRun, LoopStatus, OpenAutomationsRuntimeBinding, RunReceipt, RunStatus, WriteRunReceiptInput } from "../types.js";
 import { type DoctorReport } from "../lib/doctor.js";
 import { type BuildHealthScanOptions, type LoopsHealthReport, type LoopsHealthScan } from "../lib/health.js";
 import { type ApplyLoopsMigrationResult, type ExportLoopsMigrationOptions, type ImportLoopsMigrationOptions, type LoopsMigrationBundle, type LoopsMigrationPlan, type SelfHostedPlanOptions } from "../lib/migration.js";
 import { tick } from "../lib/scheduler.js";
 import { Store } from "../lib/store.js";
+import { type LoopStore } from "../lib/store/index.js";
 export { runGoal } from "../lib/goal/runner.js";
 export { LOOPS_MIGRATION_SCHEMA, applyImportMigrationBundle, buildImportMigrationPlan, buildSelfHostedMigrationPlan, exportLoopsMigrationBundle, migrationHash, registerSelfHostedRunner, validateLoopsMigrationBundle, } from "../lib/migration.js";
 export type { ApplyLoopsMigrationResult, ExportLoopsMigrationOptions, ImportLoopsMigrationOptions, LoopsMigrationAction, LoopsMigrationBundle, LoopsMigrationPlan, LoopsMigrationPlanRow, LoopsMigrationPlanSummary, LoopsMigrationResource, RunnerRegistrationOptions, RunnerRegistrationResult, SelfHostedPlanOptions, } from "../lib/migration.js";
 export interface LoopsClientOptions {
+    /**
+     * Inject an on-box sqlite {@link Store} (mainly for tests and in-process local
+     * runtimes). When provided, both data and local-runtime operations run against
+     * it. When omitted, the data store is resolved from the client-flip env via
+     * {@link getStore} — the local sqlite store OR the hosted `/v1` API when
+     * HASNA_LOOPS_API_URL/HASNA_LOOPS_API_KEY (or HASNA_LOOPS_STORAGE_MODE) select
+     * it — so every data method routes through the one Store abstraction.
+     */
     store?: Store;
     /**
      * Claim owner id for inline runs. Keep the `<surface>:<pid>` shape (see
@@ -29,21 +38,49 @@ export interface ListRunsFilters {
     status?: RunStatus;
     limit?: number;
 }
+export interface ListRunReceiptsFilters {
+    loopId?: string;
+    repo?: string;
+    taskId?: string;
+    knowledgeId?: string;
+    status?: string;
+    limit?: number;
+}
 export declare class LoopsClient {
-    readonly store: Store;
+    /**
+     * The resolved data store: an on-box {@link LocalStore} (sqlite) or the hosted
+     * {@link ApiStore} (`/v1` + bearer key). EVERY data method routes through here,
+     * so nothing silently touches the on-box island while flipped to the cloud API.
+     */
+    readonly store: LoopStore;
     private readonly ownStore;
     private readonly runnerId;
     constructor(opts?: LoopsClientOptions);
-    create(input: CreateLoopInput): Loop;
-    list(filters?: ListLoopsFilters): Loop[];
-    get(idOrName: string): Loop;
-    pause(idOrName: string): Loop;
-    resume(idOrName: string): Loop;
-    stop(idOrName: string): Loop;
-    archive(idOrName: string): Loop;
-    unarchive(idOrName: string): Loop;
-    delete(idOrName: string): boolean;
-    runs(idOrName?: string, filters?: ListRunsFilters): LoopRun[];
+    /**
+     * The raw on-box sqlite {@link Store} for local-runtime operations that cannot
+     * route over HTTP — the scheduler (tick / inline run-now), migration
+     * export/import, and local diagnostics (doctor/health). These act on THIS
+     * machine's runtime and database, so they fail loudly instead of silently
+     * hitting the on-box island when the client is flipped to the hosted API.
+     */
+    private localRuntime;
+    create(input: CreateLoopInput): Promise<Loop>;
+    list(filters?: ListLoopsFilters): Promise<Loop[]>;
+    get(idOrName: string): Promise<Loop>;
+    pause(idOrName: string): Promise<Loop>;
+    resume(idOrName: string): Promise<Loop>;
+    stop(idOrName: string): Promise<Loop>;
+    archive(idOrName: string): Promise<Loop>;
+    unarchive(idOrName: string): Promise<Loop>;
+    delete(idOrName: string): Promise<boolean>;
+    runs(idOrName?: string, filters?: ListRunsFilters): Promise<LoopRun[]>;
+    writeReceipt(input: WriteRunReceiptInput): Promise<RunReceipt>;
+    receipt(runId: string): Promise<RunReceipt | undefined>;
+    receipts(filters?: ListRunReceiptsFilters): Promise<RunReceipt[]>;
+    goal(idOrName: string): Promise<{
+        goal?: Goal;
+        runs: GoalRun[];
+    }>;
     doctor(): DoctorReport;
     health(opts?: {
         includeArchived?: boolean;
@@ -54,10 +91,6 @@ export declare class LoopsClient {
         doctor?: boolean;
         daemon?: boolean;
     }): LoopsHealthScan;
-    goal(idOrName: string): {
-        goal?: Goal;
-        runs: GoalRun[];
-    };
     tick(): Promise<Awaited<ReturnType<typeof tick>>>;
     runNow(idOrName: string): Promise<LoopRun>;
     exportBundle(opts?: ExportLoopsMigrationOptions): LoopsMigrationBundle;
@@ -66,7 +99,7 @@ export declare class LoopsClient {
     planSelfHostedMigration(opts?: Omit<SelfHostedPlanOptions, "operation"> & {
         operation?: SelfHostedPlanOptions["operation"];
     }): Promise<LoopsMigrationPlan>;
-    close(): void;
+    close(): Promise<void>;
 }
 export declare function loops(opts?: LoopsClientOptions): LoopsClient;
 export declare function openAutomationsRuntimeBinding(overrides?: Partial<OpenAutomationsRuntimeBinding>): OpenAutomationsRuntimeBinding;