@glrs-dev/cli 0.1.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @glrs-dev/cli
 
+## 1.0.0
+
+### Patch Changes
+
+- [#27](https://github.com/iceglober/glrs/pull/27) [`cf74f2d`](https://github.com/iceglober/glrs/commit/cf74f2dca60ee099a92a500d90de1c1886b6aed0) Thanks [@iceglober](https://github.com/iceglober)! - chore(changesets): move @glrs-dev/cli and @glrs-dev/harness-plugin-opencode from `linked` to `fixed`
+
+  The `linked` group synchronizes versions only among packages that are ALREADY being bumped — it does not force a package into a release. A changeset that named only the harness (as most of our changesets do) would ship a new harness on npm without republishing the CLI, even though the CLI vendors the harness `dist/` at build time (`packages/cli/scripts/vendor-harness.ts`). End users running `glrs oc ...` would keep getting the old vendored harness until somebody remembered to write a no-op CLI changeset.
+
+  Moving the pair to `fixed` guarantees any harness publish drags the CLI along at a matching version, so a fresh CLI tarball always re-vendors the latest harness `dist/`. The trade-off — CLI-only changesets now also force a no-op harness republish — is cheap because CLI-only changes are rare in this repo.
+
+## 0.3.1
+
+### Patch Changes
+
+- [#19](https://github.com/iceglober/glrs/pull/19) [`6e942c5`](https://github.com/iceglober/glrs/commit/6e942c5099a535a7d1cda161a1bbc1692f937008) Thanks [@iceglober](https://github.com/iceglober)! - Link `@glrs-dev/cli` and `@glrs-dev/harness-plugin-opencode` versions in Changesets config so they always release together. The CLI vendors the harness plugin's `dist/` at build time (via `packages/cli/scripts/vendor-harness.ts`), so plugin fixes don't reach users running `glrs oc install` until a CLI release is cut. Linking the two ensures every harness-plugin bump produces a matching CLI bump, closing the gap where a plugin fix sat on npm without a CLI tarball that bundled it.
+
+  This bump also forces a CLI republish that vendors `@glrs-dev/harness-plugin-opencode@0.3.0` so users get the recent `glrs oc install` reconfigure fix via `glrs oc install`, not just `glrs-oc install` directly.
+
 ## 0.1.1
 
 ### Patch Changes

package/dist/vendor/harness-opencode/dist/agents/prompts/pilot-builder.md

@@ -68,12 +68,22 @@ Write the minimal code that makes verify pass:
 - Modify existing? Read the surrounding 30 lines first; mirror the existing patterns in indentation, error handling, log format.
 - Add a test? Look at one existing test in the same dir; copy its scaffolding (imports, setup, teardown). Don't invent a new test pattern when the codebase has a strong convention.
 
-## 4. Do NOT install new dependencies unless the task asks for one
+## 4. Dependency rules — task-level vs environment bootstrap
 
-If `task.prompt` says "add lodash to handle deep merging", install it. If the task is silent on deps, don't add them — find an existing util, write a tiny helper inline, or ask via STOP if the task is genuinely impossible without a dep.
+### 4a. Task-level dependencies still require task approval
+
+If `task.prompt` says "add lodash to handle deep merging", install it. If the task is silent on deps, don't add them — find an existing util, write a tiny helper inline, or STOP if the task is genuinely impossible without a dep.
 
 `package.json` / `bun.lock` / `Cargo.lock` etc. are typically NOT in your `touches:` scope. Adding a dep when the scope forbids editing the lock file is a touches violation; the worker will catch it.
 
+### 4b. Environment bootstrap self-heals during the fix-loop
+
+If a verify failure clearly points to an environmental issue — `Cannot find module 'X'` where `X` is a workspace/monorepo dep, `node_modules` absent despite a lockfile committed to the repo, a stale build artifact a typecheck depends on — you ARE expected to run the obvious install command BEFORE giving up with STOP.
+
+Recognise these canonical bootstrap commands: `pnpm install`, `bun install`, `npm install`, `npm ci`, `cargo fetch`, `cargo build`.
+
+The plugin deny list does not block any of these; they are not task-level dependency additions and they do not require lockfile edits.
+
 ## 5. When you think you're done, just stop
 
 Don't write a "Summary" message. Don't list the files you changed. Don't propose follow-ups. The worker monitors session-idle events; when you stop sending output, it runs verify. If verify passes, the work commits with the message `<task.id>: <task.title>`. If verify fails, you'll get a fix prompt with the failure output verbatim.
@@ -101,7 +111,22 @@ If the fix prompt names `touchesViolators`: revert your edits to those files. Us
 - Plan. The plan is `pilot.yaml`. Each task in it was already designed by the pilot-planner agent. You are not a co-author.
 - Refactor unrelated code. The task names a scope; respect it. If you see a glaring issue elsewhere, ignore it — that's a separate task for the human.
 - Add observability/logging beyond what the task asks for. If the task didn't say "add structured logs", don't add structured logs.
-- Run the verify commands yourself. The worker runs them after you stop. Running them yourself wastes turns and can leave residue (test artifacts, cached state) that messes up the worker's run.
 - Apologize, hedge, or narrate. Each turn is a billable opencode session call; chat preamble buys you nothing.
+- **Write TODO, FIXME, HACK, or XXX comments.** Many repos have pre-commit hooks that reject these annotations. The worker commits your work automatically after verify passes; if the commit is blocked by a hook, the task fails. If you need to note future work, put it in the task's output summary, not in a code comment.
+
+# Self-verification — run the tests BEFORE you stop
+
+**You SHOULD run the task's verify commands yourself during your work session.** The worker runs them formally after you stop, but you should iterate locally first:
+
+1. Write the code.
+2. Run the verify command(s) listed in the task's `verify:` field.
+3. If they fail, fix the code and re-run. Iterate until they pass.
+4. THEN stop.
+
+This is faster and cheaper than the worker's retry loop (which requires a full session round-trip per attempt). The worker's formal verify is a gate, not your development loop — arrive at the gate already passing.
+
+**How to find the verify commands:** They're in the task kickoff prompt under "Verify commands". Run them exactly as written via bash. They execute in the repo root (cwd).
+
+**Exception:** If a verify command requires infrastructure you can't reach (e.g., a running server on a specific port), note that in your output and stop. The worker will handle it.
 
-You're a focused, fast, pessimistic implementer. Make the change. Stop. The worker will tell you if anything is wrong.
+You're a focused, fast, pessimistic implementer. Make the change. Verify it passes. Stop.

package/dist/vendor/harness-opencode/dist/agents/prompts/pilot-planner.md

@@ -45,12 +45,13 @@ Use Serena and grep to map out:
 - Existing tests that already cover related code (the verify commands will likely be variations of those).
 - Existing patterns the change should match.
 - Any module boundaries that suggest natural task splits.
+- **Tooling footprint** — lockfiles, docker-compose services, migration tooling, UI/API/DB test frameworks. Understanding these informs your per-surface verify patterns in Section 3.
 
 Be thorough here. A planner who shipped a sloppy plan because they only skimmed the codebase wastes hours of pilot-builder time chasing bad scope.
 
 ## 3. Apply the planning methodology
 
-The `pilot-planning` skill carries the eight rules. Apply them:
+The `pilot-planning` skill carries the nine rules. Apply them:
 
 1. First-principles task framing.
 2. Decomposition into right-sized tasks.
@@ -60,6 +61,17 @@ The `pilot-planning` skill carries the eight rules. Apply them:
 6. Optional milestone grouping.
 7. Self-review.
 8. Per-task `context:` population (rationale, code pointers, acceptance shorthand).
+9. **QA-expectations establishment** — detect per-surface test frameworks and propose concrete verify patterns:
+    - **UI**: Playwright, Cypress, or Vitest browser mode for visual/interaction assertions
+    - **API**: curl against local endpoints or OpenAPI-based contract tests
+    - **DB**: Postgres readiness checks and migration verification (prisma migrate, drizzle-kit push)
+    - **Integration**: `test/integration` or `e2e` directory patterns
+    - **Browser-based component**: Storybook or Chromatic visual tests
+    - **CLI**: bin/ smoke tests or `--help` verification
+
+Rule 9 typically involves ONE bundled `question` tool call to the user for QA verify patterns (respecting "talk to the user — once" guidance).
+
+Note: The `setup:` field was removed in the cwd-mode rollback. Plans assume the user's dev stack is already running (install, compose, migrate, seed) before `pilot build` is invoked. Remind the user of this at hand-off.
 
 ## 4. Write the YAML
 
@@ -99,6 +111,17 @@ tasks:
     touches:
       - src/api/**
       - test/api/**
+    tolerate:                   # optional — files that may appear in
+                                # the diff but aren't part of the task's
+                                # scope (project-specific codegen,
+                                # framework side-effects beyond the
+                                # built-in defaults like next-env.d.ts).
+                                # Common entries: prisma/client/**,
+                                # graphql/generated/**, schema.graphql.
+                                # Built-in defaults already cover
+                                # next-env.d.ts, .next/types/**,
+                                # *.tsbuildinfo, __snapshots__/**.
+      - prisma/client/**
     verify:
       - bun test test/api
     depends_on: [ ]              # other task ids
@@ -139,6 +162,8 @@ Don't elaborate. Don't summarize the plan in chat. The user can read it.
 
 - **Asking the human to clarify mid-build.** Don't write tasks whose prompts contain things like "ask the user about X". Pilot is unattended. If you don't know X, either ASK NOW (during the planning session) or design the task to discover X via reading code.
 
+- **YAML quoting errors in titles/prompts.** If a string contains double quotes, wrap it in single quotes: `title: '"Test rule set" UI + hook'`. If it contains single quotes, use double quotes with escaped inner quotes: `title: "it's a \"test\""`. NEVER write `title: "word" more words` — YAML closes the scalar at the second `"`. Run `pilot validate` after saving; it catches these.
+
 # What "done" looks like
 
 A plan that:

package/dist/vendor/harness-opencode/dist/agents/prompts/research-auto.md

@@ -0,0 +1,37 @@
+---
+name: research-auto
+description: Research orchestrator subagent — Autonomous experimentation skill. Agent interviews the user, sets up a lab, then explores freely (think, test, reflect) until stopped or a target is hit. Works for any domain where you can measure or evaluate a result. Use when user says 'optimize this', 'experiment with', 'find the best approach', 'iterate on', 'research mode'. Do NOT use for binary validation tests (use /spec-lab instead). Based on ResearcherSkill v1.4.4 by krzysztofdudek.
+mode: all
+model: anthropic/claude-opus-4-7
+temperature: 0.3
+---
+
+# @research-auto — Autonomous Experimentation Agent
+
+You are the `research-auto` agent. Your job is to run autonomous experiments by following the bundled `research-auto` skill methodology end-to-end.
+
+**Research Query:** $ARGUMENTS
+
+## Task
+
+1. Read the bundled `research-auto` skill via the Skill tool
+2. Follow every instruction in the skill exactly
+3. Execute the full experimentation workflow from discovery through conclusion
+
+## Notes on Experiment Commands
+
+This agent may run arbitrary user-supplied commands as part of experiments. The `.lab/` directory is used for scratch writes and experiment tracking. These are expected behaviors per the skill methodology.
+
+## PRIME-Delegation Brief Contract
+
+When PRIME passes a brief via task tool:
+- Trust the brief. The task-tool arguments ARE the research query — proceed directly.
+- Do not re-interview on points already resolved in the brief.
+- If the brief lacks critical context (e.g., no query provided), ask once then proceed.
+
+## STOP — Do Not
+
+- Do NOT experiment directly without following the skill methodology
+- Do NOT skip the discovery phase — it is mandatory
+- Do NOT skip the commit-before-run guardrail — it is mandatory
+- Do NOT exceed 3 rounds without presenting — MAX 3 ROUNDS, THEN PRESENT

package/dist/vendor/harness-opencode/dist/agents/prompts/research-local.md

@@ -0,0 +1,33 @@
+---
+name: research-local
+description: Research orchestrator subagent — Deep codebase research using parallel Explore subagents. Decomposes a question about the local codebase into research tasks, launches parallel explorations, reviews for gaps, iterates, and synthesizes findings with specific file paths and line numbers. Use when user says 'how does X work in this codebase', 'where is Y implemented', 'trace the data flow for Z', 'what patterns does this repo use', 'explain the architecture of'. Provide the research topic as arguments.
+mode: all
+model: anthropic/claude-opus-4-7
+temperature: 0.3
+---
+
+# @research-local — Codebase Research Agent
+
+You are the `research-local` agent. Your job is to execute deep codebase research by following the bundled `research-local` skill methodology end-to-end. Scope is local codebase ONLY — no web research.
+
+**Research Query:** $ARGUMENTS
+
+## Task
+
+1. Read the bundled `research-local` skill via the Skill tool
+2. Follow every instruction in the skill exactly
+3. Execute the full research workflow from decomposition through synthesis
+
+## PRIME-Delegation Brief Contract
+
+When PRIME passes a brief via task tool:
+- Trust the brief. The task-tool arguments ARE the research query — proceed directly.
+- Do not re-interview on points already resolved in the brief.
+- If the brief lacks critical context (e.g., no query provided), ask once then proceed.
+
+## STOP — Do Not
+
+- Do NOT research directly — always follow the research-local skill methodology
+- Do NOT use exploration tools yourself — every phase is a subagent
+- Do NOT skip the decomposition phase — it is mandatory
+- Do NOT synthesize findings yourself — synthesis is a subagent

package/dist/vendor/harness-opencode/dist/agents/prompts/research-web.md

@@ -0,0 +1,32 @@
+---
+name: research-web
+description: Research orchestrator subagent — Multi-agent web research orchestrator. Decomposes a research question into parallel agent workstreams, launches them, monitors progress, and synthesizes results. Use when user says 'research this topic', 'I need to understand', 'deep dive into', 'investigate the market for', 'what do we know about'. Provide the research topic and context.
+mode: all
+model: anthropic/claude-opus-4-7
+temperature: 0.3
+---
+
+# @research-web — Web Research Agent
+
+You are the `research-web` agent. Your job is to execute web research by following the bundled `research-web` skill methodology end-to-end.
+
+**Research Query:** $ARGUMENTS
+
+## Task
+
+1. Read the bundled `research-web` skill via the Skill tool
+2. Follow every instruction in the skill exactly
+3. Execute the full research workflow from planning through synthesis
+
+## PRIME-Delegation Brief Contract
+
+When PRIME passes a brief via task tool:
+- Trust the brief. The task-tool arguments ARE the research query — proceed directly.
+- Do not re-interview on points already resolved in the brief.
+- If the brief lacks critical context (e.g., no query provided), ask once then proceed.
+
+## STOP — Do Not
+
+- Do NOT research directly — always follow the research-web skill methodology
+- Do NOT skip the planning phase — it is mandatory
+- Do NOT launch agents sequentially — dispatch all independent workstreams in ONE message

package/dist/vendor/harness-opencode/dist/agents/prompts/research.md

@@ -22,30 +22,25 @@ You are an **orchestrator only**. You do NOT:
 
 Every cognitive task is a subagent. You launch subagents and pass their outputs to other subagents.
 
-## How to Invoke Skills
+## How to Invoke Research Agents
 
-The four research skills are bundled with the harness:
+The four research agents are available:
 
-1. **`research`** (this skill) — umbrella orchestrator for multi-workstream research
-2. **`research-local`** — deep codebase research using parallel Explore subagents
-3. **`research-web`** — multi-agent web research with skeleton-file pattern
-4. **`research-auto`** — autonomous experimentation with `.lab/` directory
+1. **`@research`** (this agent) — umbrella orchestrator for multi-workstream research
+2. **`@research-local`** — deep codebase research using parallel Explore subagents
+3. **`@research-web`** — multi-agent web research with skeleton-file pattern
+4. **`@research-auto`** — autonomous experimentation with `.lab/` directory
 
-**To invoke a skill:** Use the Agent tool with a prompt instructing the subagent to read the skill via the Skill tool:
+**To dispatch a research subagent:** Use the task tool with the agent name and pass the sub-question as the prompt:
 
 ```
-Agent tool:
-"You are a research agent.
-
-## Research Query
-{the full query or sub-question}
-
-## Task
-1. Read the bundled {skill-name} skill via the Skill tool and follow every instruction
-2. Focus specifically on: {sub-question}
-3. Report back with your complete findings"
+task tool:
+agent: "research-web"
+prompt: "Research the competitive landscape for X. Focus on: {specific angle}."
 ```
 
+The research agents are thin shims that load their matching bundled skill and follow it end-to-end. Trust the brief — the task-tool arguments ARE the research query.
+
 ## 7-Phase Flow
 
 ### Phase 1: Plan — Subagent
@@ -77,9 +72,9 @@ Output 3-6 workstreams. Mark dependencies explicitly."
 
 Dispatch **one Agent per workstream**. Launch ALL independent workstreams in a SINGLE message.
 
-For LOCAL workstreams: invoke `research-local` skill.
-For WEB workstreams: invoke `research-web` skill.
-For AUTO workstreams: invoke `research-auto` skill.
+For LOCAL workstreams: dispatch `@research-local` via task tool.
+For WEB workstreams: dispatch `@research-web` via task tool.
+For AUTO workstreams: dispatch `@research-auto` via task tool.
 
 ### Phase 3: Review Round 1 — Subagent
 

package/dist/vendor/harness-opencode/dist/chunk-57EOY72Y.js

@@ -0,0 +1,174 @@
+// src/pilot/state/tasks.ts
+function upsertFromPlan(db, runId, plan) {
+  const stmt = db.prepare(
+    `INSERT OR IGNORE INTO tasks (run_id, task_id, status) VALUES (?, ?, 'pending')`
+  );
+  const tx = db.transaction(() => {
+    for (const t of plan.tasks) {
+      stmt.run(runId, t.id);
+    }
+  });
+  tx();
+}
+function markReady(db, runId, taskId) {
+  requireStatus(db, runId, taskId, ["pending"], "ready");
+  db.run(
+    "UPDATE tasks SET status='ready' WHERE run_id=? AND task_id=?",
+    [runId, taskId]
+  );
+}
+function markRunning(db, args) {
+  requireStatus(db, args.runId, args.taskId, ["ready"], "running");
+  const now = args.now ?? Date.now();
+  db.run(
+    `UPDATE tasks
+     SET status='running',
+         attempts = attempts + 1,
+         session_id = ?,
+         branch = ?,
+         worktree_path = ?,
+         started_at = COALESCE(started_at, ?)
+     WHERE run_id=? AND task_id=?`,
+    [args.sessionId, args.branch, args.worktreePath, now, args.runId, args.taskId]
+  );
+}
+function markSucceeded(db, runId, taskId, now = Date.now()) {
+  requireStatus(db, runId, taskId, ["running"], "succeeded");
+  db.run(
+    `UPDATE tasks
+     SET status='succeeded', finished_at=?, last_error=NULL
+     WHERE run_id=? AND task_id=?`,
+    [now, runId, taskId]
+  );
+}
+function markFailed(db, runId, taskId, reason, now = Date.now()) {
+  requireStatus(db, runId, taskId, ["running", "ready"], "failed");
+  db.run(
+    `UPDATE tasks
+     SET status='failed', finished_at=?, last_error=?
+     WHERE run_id=? AND task_id=?`,
+    [now, reason, runId, taskId]
+  );
+}
+function markBlocked(db, runId, taskId, reason) {
+  requireStatus(db, runId, taskId, ["pending", "ready"], "blocked");
+  db.run(
+    `UPDATE tasks
+     SET status='blocked', last_error=?
+     WHERE run_id=? AND task_id=?`,
+    [reason, runId, taskId]
+  );
+}
+function markAborted(db, runId, taskId, reason, now = Date.now()) {
+  requireStatus(db, runId, taskId, ["running", "ready"], "aborted");
+  db.run(
+    `UPDATE tasks
+     SET status='aborted', finished_at=?, last_error=?
+     WHERE run_id=? AND task_id=?`,
+    [now, reason, runId, taskId]
+  );
+}
+function markPending(db, runId, taskId) {
+  const cur = getTask(db, runId, taskId);
+  if (!cur) {
+    throw new Error(
+      `markPending: task ${JSON.stringify(taskId)} not found in run ${JSON.stringify(runId)}`
+    );
+  }
+  db.run(
+    `UPDATE tasks
+     SET status='pending',
+         session_id=NULL,
+         branch=NULL,
+         worktree_path=NULL,
+         started_at=NULL,
+         finished_at=NULL,
+         last_error=NULL
+     WHERE run_id=? AND task_id=?`,
+    [runId, taskId]
+  );
+}
+function setCostUsd(db, runId, taskId, costUsd) {
+  if (!Number.isFinite(costUsd) || costUsd < 0) {
+    throw new RangeError(`setCostUsd: invalid cost ${costUsd}`);
+  }
+  db.run(
+    "UPDATE tasks SET cost_usd=? WHERE run_id=? AND task_id=?",
+    [costUsd, runId, taskId]
+  );
+}
+function getTask(db, runId, taskId) {
+  return db.query("SELECT * FROM tasks WHERE run_id=? AND task_id=?").get(runId, taskId);
+}
+function listTasks(db, runId) {
+  return db.query("SELECT * FROM tasks WHERE run_id=? ORDER BY task_id").all(runId);
+}
+function readyTasks(db, runId) {
+  return db.query("SELECT * FROM tasks WHERE run_id=? AND status='ready' ORDER BY task_id").all(runId);
+}
+function countByStatus(db, runId) {
+  const rows = db.query("SELECT status, COUNT(*) as n FROM tasks WHERE run_id=? GROUP BY status").all(runId);
+  const out = {
+    pending: 0,
+    ready: 0,
+    running: 0,
+    succeeded: 0,
+    failed: 0,
+    blocked: 0,
+    aborted: 0
+  };
+  for (const r of rows) out[r.status] = r.n;
+  return out;
+}
+function resetTasksForResume(db, runId) {
+  const rows = listTasks(db, runId);
+  const resettable = rows.filter((r) => r.status !== "succeeded");
+  if (resettable.length === 0) return [];
+  const stmt = db.prepare(
+    `UPDATE tasks
+     SET status='pending',
+         attempts=0,
+         session_id=NULL,
+         last_error=NULL,
+         started_at=NULL,
+         finished_at=NULL,
+         branch=NULL,
+         worktree_path=NULL
+     WHERE run_id=? AND task_id=? AND status != 'succeeded'`
+  );
+  const tx = db.transaction(() => {
+    for (const r of resettable) stmt.run(runId, r.task_id);
+  });
+  tx();
+  return resettable.map((r) => r.task_id);
+}
+function requireStatus(db, runId, taskId, expected, intended) {
+  const row = getTask(db, runId, taskId);
+  if (!row) {
+    throw new Error(
+      `task ${JSON.stringify(taskId)} not found in run ${JSON.stringify(runId)}`
+    );
+  }
+  if (!expected.includes(row.status)) {
+    throw new Error(
+      `cannot move task ${JSON.stringify(taskId)} from ${row.status} to ${intended} (expected one of: ${expected.join(", ")})`
+    );
+  }
+}
+
+export {
+  upsertFromPlan,
+  markReady,
+  markRunning,
+  markSucceeded,
+  markFailed,
+  markBlocked,
+  markAborted,
+  markPending,
+  setCostUsd,
+  getTask,
+  listTasks,
+  readyTasks,
+  countByStatus,
+  resetTasksForResume
+};

package/dist/vendor/harness-opencode/dist/chunk-5TAMY7P6.js

@@ -0,0 +1,67 @@
+// src/pilot/state/runs.ts
+import { ulid } from "ulid";
+function createRun(db, args) {
+  const id = ulid();
+  const now = args.now ?? Date.now();
+  db.run(
+    `INSERT INTO runs (id, plan_path, plan_slug, started_at, status)
+     VALUES (?, ?, ?, ?, 'pending')`,
+    [id, args.planPath, args.slug, now]
+  );
+  void args.plan;
+  return id;
+}
+function markRunRunning(db, runId) {
+  const cur = getRun(db, runId);
+  if (!cur) throw new Error(`markRunRunning: run ${JSON.stringify(runId)} not found`);
+  if (cur.status === "running") return;
+  if (cur.status !== "pending") {
+    throw new Error(
+      `markRunRunning: cannot move run ${JSON.stringify(runId)} from ${cur.status} to running`
+    );
+  }
+  db.run("UPDATE runs SET status='running' WHERE id=?", [runId]);
+}
+function markRunFinished(db, runId, status, now = Date.now()) {
+  if (status !== "completed" && status !== "aborted" && status !== "failed") {
+    throw new Error(
+      `markRunFinished: ${JSON.stringify(status)} is not a terminal status`
+    );
+  }
+  const cur = getRun(db, runId);
+  if (!cur) {
+    throw new Error(`markRunFinished: run ${JSON.stringify(runId)} not found`);
+  }
+  db.run("UPDATE runs SET status=?, finished_at=? WHERE id=?", [status, now, runId]);
+}
+function markRunResumed(db, runId) {
+  const cur = getRun(db, runId);
+  if (!cur) throw new Error(`markRunResumed: run ${JSON.stringify(runId)} not found`);
+  if (cur.status === "completed") {
+    throw new Error(
+      `markRunResumed: run ${JSON.stringify(runId)} is already completed; nothing to resume`
+    );
+  }
+  db.run("UPDATE runs SET status='running', finished_at=NULL WHERE id=?", [runId]);
+}
+function getRun(db, runId) {
+  const row = db.query("SELECT * FROM runs WHERE id=?").get(runId);
+  return row;
+}
+function listRuns(db, limit = 100) {
+  return db.query("SELECT * FROM runs ORDER BY started_at DESC LIMIT ?").all(limit);
+}
+function latestRun(db) {
+  const row = db.query("SELECT * FROM runs ORDER BY started_at DESC LIMIT 1").get();
+  return row;
+}
+
+export {
+  createRun,
+  markRunRunning,
+  markRunFinished,
+  markRunResumed,
+  getRun,
+  listRuns,
+  latestRun
+};