@the-open-engine/zeroshot 6.2.0 → 6.4.0

package/src/isolation-manager.js

@@ -20,6 +20,7 @@ const { normalizeProviderName } = require('../lib/provider-names');
 const { resolveMounts, resolveEnvs, expandEnvPatterns } = require('../lib/docker-config');
 const { getProvider } = require('./providers');
 const { readRepoSettings } = require('../lib/repo-settings');
+const { provisionClaudeCredentials } = require('./claude-credentials');
 
 const DEFAULT_WORKTREE_SETUP_TIMEOUT_MS = 15 * 60 * 1000;
 
@@ -1036,14 +1037,12 @@ class IsolationManager {
     const projectsDir = path.join(configDir, 'projects');
     fs.mkdirSync(projectsDir, { recursive: true });
 
-    // Copy only credentials file (essential for auth)
-    const credentialsFile = path.join(sourceDir, '.credentials.json');
-    if (fs.existsSync(credentialsFile)) {
-      fs.copyFileSync(credentialsFile, path.join(configDir, '.credentials.json'));
-    }
+    // Copy credentials file, or materialize from macOS Keychain if none exists
+    // (essential for auth; see src/claude-credentials.js)
+    provisionClaudeCredentials({ sourceDir, destDir: configDir });
 
     // Copy hook script to block AskUserQuestion (CRITICAL for autonomous execution)
-    const hookScriptSrc = path.join(__dirname, '..', 'hooks', 'block-ask-user-question.py');
+    const hookScriptSrc = path.join(__dirname, '..', 'cluster-hooks', 'block-ask-user-question.py');
     const hookScriptDst = path.join(hooksDir, 'block-ask-user-question.py');
     if (fs.existsSync(hookScriptSrc)) {
       fs.copyFileSync(hookScriptSrc, hookScriptDst);
@@ -1651,10 +1650,14 @@ class IsolationManager {
     // Tear down any Docker Compose services that may have been started in this worktree.
     // Without this, containers keep running with host port mappings after the worktree is deleted,
     // blocking port allocation for the main project or other worktrees.
-    const composePath = path.join(worktreeInfo.path, 'docker-compose.yml');
-    if (fs.existsSync(composePath)) {
+    // NEVER pass --volumes (irreversible data loss) and NEVER tear down a pinned/shared
+    // Compose project — only a project scoped to the worktree directory basename, which is
+    // the only kind zeroshot could itself have created, is touched.
+    const { resolveWorktreeComposeTeardown } = require('../lib/compose-utils');
+    const teardown = resolveWorktreeComposeTeardown(worktreeInfo.path);
+    if (teardown.shouldTeardown) {
       try {
-        runSync('docker', ['compose', 'down', '--remove-orphans', '--volumes', '--timeout', '10'], {
+        runSync('docker', teardown.args, {
           cwd: worktreeInfo.path,
           encoding: 'utf8',
           stdio: 'pipe',

package/src/issue-providers/README.md

@@ -1,15 +1,16 @@
 # Issue Providers
 
-Multi-platform issue support for Zeroshot. Fetch issues from GitHub, GitLab, Jira, and Azure DevOps.
+Multi-platform issue support for Zeroshot. Fetch issues from GitHub, GitLab, Jira, Azure DevOps, and Linear.
 
 ## Supported Providers
 
-| Provider         | CLI Tool | URL Pattern                                  | Issue Key Format      |
-| ---------------- | -------- | -------------------------------------------- | --------------------- |
-| **GitHub**       | `gh`     | `github.com/org/repo/issues/123`             | `123`, `org/repo#123` |
-| **GitLab**       | `glab`   | `gitlab.com/org/repo/-/issues/123`           | `123`, `org/repo#123` |
-| **Jira**         | `jira`   | `*.atlassian.net/browse/KEY-123`             | `KEY-123`             |
-| **Azure DevOps** | `az`     | `dev.azure.com/org/proj/_workitems/edit/123` | `123`                 |
+| Provider         | CLI Tool               | URL Pattern                                  | Issue Key Format      |
+| ---------------- | ---------------------- | -------------------------------------------- | --------------------- |
+| **GitHub**       | `gh`                   | `github.com/org/repo/issues/123`             | `123`, `org/repo#123` |
+| **GitLab**       | `glab`                 | `gitlab.com/org/repo/-/issues/123`           | `123`, `org/repo#123` |
+| **Jira**         | `jira`                 | `*.atlassian.net/browse/KEY-123`             | `KEY-123`             |
+| **Azure DevOps** | `az`                   | `dev.azure.com/org/proj/_workitems/edit/123` | `123`                 |
+| **Linear**       | _(none — GraphQL API)_ | `linear.app/ws/issue/ENG-42`                 | `ENG-42`              |
 
 ## Quick Start
 
@@ -30,6 +31,11 @@ zeroshot run https://company.atlassian.net/browse/PROJ-123
 # Azure DevOps
 zeroshot run https://dev.azure.com/org/project/_workitems/edit/123
 zeroshot run 123 --devops
+
+# Linear
+zeroshot run ENG-42
+zeroshot run https://linear.app/workspace/issue/ENG-42/some-title
+zeroshot run 42 --linear
 ```
 
 ## Automatic Git Remote Detection
@@ -59,6 +65,7 @@ Override auto-detection with explicit provider flags:
 -L, --gitlab    # Force GitLab as issue source
 -J, --jira      # Force Jira as issue source
 -D, --devops    # Force Azure DevOps as issue source
+-N, --linear    # Force Linear as issue source
 ```
 
 **Example:**
@@ -100,18 +107,24 @@ zeroshot settings set jiraProject MYPROJECT  # Default project for bare numbers
 # Azure DevOps configuration
 zeroshot settings set azureOrg mycompany
 zeroshot settings set azureProject myproject  # Default project for bare numbers
+
+# Linear configuration
+zeroshot settings set linearApiKey lin_api_...  # API key (falls back to LINEAR_API_KEY env var)
+zeroshot settings set linearTeam ENG  # Default team key for bare numbers (auto-derived on first use if unset)
 ```
 
 ### Settings Reference
 
-| Setting              | Type   | Default | Description                                |
-| -------------------- | ------ | ------- | ------------------------------------------ |
-| `defaultIssueSource` | string | github  | Provider for bare numbers (123)            |
-| `gitlabInstance`     | string | null    | Self-hosted GitLab URL                     |
-| `jiraInstance`       | string | null    | Self-hosted Jira URL                       |
-| `jiraProject`        | string | null    | Default Jira project key for bare numbers  |
-| `azureOrg`           | string | null    | Azure DevOps organization name             |
-| `azureProject`       | string | null    | Azure DevOps project name for bare numbers |
+| Setting              | Type   | Default | Description                                                                                         |
+| -------------------- | ------ | ------- | --------------------------------------------------------------------------------------------------- |
+| `defaultIssueSource` | string | github  | Provider for bare numbers (123)                                                                     |
+| `gitlabInstance`     | string | null    | Self-hosted GitLab URL                                                                              |
+| `jiraInstance`       | string | null    | Self-hosted Jira URL                                                                                |
+| `jiraProject`        | string | null    | Default Jira project key for bare numbers                                                           |
+| `azureOrg`           | string | null    | Azure DevOps organization name                                                                      |
+| `azureProject`       | string | null    | Azure DevOps project name for bare numbers                                                          |
+| `linearApiKey`       | string | null    | Linear personal API key (falls back to `LINEAR_API_KEY` env var)                                    |
+| `linearTeam`         | string | null    | Default Linear team key for bare numbers (auto-derived from the workspace if unset and unambiguous) |
 
 ## CLI Tool Setup
 
@@ -166,6 +179,23 @@ az login
 az devops configure --defaults organization=https://dev.azure.com/yourorg
 ```
 
+### Linear
+
+No CLI install needed — Linear is accessed directly via its GraphQL API.
+
+```bash
+# Create a personal API key at https://linear.app/settings/api
+zeroshot settings set linearApiKey lin_api_...
+
+# Or, as a fallback, export it as an env var (checked if linearApiKey is unset):
+export LINEAR_API_KEY=lin_api_...
+```
+
+Note: `KEY-NUMBER` input (e.g. `ENG-42`) is ambiguous between Jira and Linear.
+It's routed to Linear automatically when Linear is configured
+(`linearApiKey`/`linearTeam`) and Jira isn't; otherwise Jira wins. Use
+`--linear`/`--jira` to force a specific provider.
+
 ## Self-Hosted Instances
 
 ### GitLab Self-Hosted

package/src/issue-providers/index.js

@@ -7,6 +7,7 @@
 const GitHubProvider = require('./github-provider');
 const GitLabProvider = require('./gitlab-provider');
 const JiraProvider = require('./jira-provider');
+const LinearProvider = require('./linear-provider');
 const AzureDevOpsProvider = require('./azure-devops-provider');
 const { detectGitContext } = require('../../lib/git-remote-utils');
 
@@ -180,6 +181,7 @@ function validateIssueProviderSetting(key, value) {
 registerProvider(GitHubProvider);
 registerProvider(GitLabProvider);
 registerProvider(JiraProvider);
+registerProvider(LinearProvider);
 registerProvider(AzureDevOpsProvider);
 
 module.exports = {

package/src/issue-providers/jira-provider.js

@@ -44,8 +44,15 @@ class JiraProvider extends IssueProvider {
       return true;
     }
 
-    // Jira issue key pattern (KEY-123)
+    // Jira issue key pattern (KEY-123) - shared with Linear (ENG-42 vs PROJ-123).
+    // Defer to Linear when it's configured and Jira isn't, so the sole
+    // configured tracker wins instead of registration order.
     if (/^[A-Z][A-Z0-9]+-\d+$/.test(input)) {
+      const jiraConfigured = !!(settings.jiraInstance || settings.jiraProject);
+      const linearConfigured = !!(settings.linearApiKey || settings.linearTeam);
+      if (!jiraConfigured && linearConfigured) {
+        return false;
+      }
       return true;
     }
 

package/src/issue-providers/linear-provider.js

@@ -0,0 +1,405 @@
+/**
+ * Linear Provider - Fetch issues from Linear via GraphQL API
+ * Linear is not a git host; no CLI binary required (talks to api.linear.app directly)
+ */
+
+const IssueProvider = require('./base-provider');
+
+const AUTH_CHECK_TIMEOUT_MS = 2000;
+const FETCH_TIMEOUT_MS = 10000;
+const LINEAR_API_URL = 'https://api.linear.app/graphql';
+const LINEAR_URL_PATTERN = /linear\.app\/[^/]+\/issue\/([A-Z][A-Z0-9]*-\d+)/;
+const LINEAR_KEY_PATTERN = /^[A-Z][A-Z0-9]*-\d+$/;
+
+class LinearProvider extends IssueProvider {
+  static id = 'linear';
+  static displayName = 'Linear';
+
+  /**
+   * Detect Linear issue keys and URLs
+   * Matches:
+   * - Linear issue URLs (linear.app/<workspace>/issue/<TEAM>-<n>/...)
+   * - Linear issue keys (TEAM-123 format)
+   * - Bare numbers when defaultIssueSource=linear (requires linearTeam setting)
+   *
+   * Note: Linear doesn't use git context since it's not a git hosting platform.
+   * Git context will never match 'linear', so this provider only activates via
+   * explicit Linear URLs, Linear issue keys, or settings.
+   *
+   * Note: Linear and Jira share the same KEY-NUMBER key format (e.g. ENG-42 vs
+   * PROJ-123), so a bare key is ambiguous between the two providers. This is
+   * resolved by configuration, not registration order: JiraProvider.detectIdentifier
+   * defers to Linear for KEY-NUMBER input when Linear is configured
+   * (linearApiKey/linearTeam) and Jira is not. If neither or both are configured,
+   * Jira wins by registration order. Use --linear or defaultIssueSource=linear
+   * for unambiguous Linear selection regardless of configuration.
+   *
+   * @param {string} input - Issue identifier (URL, key, or number)
+   * @param {Object} settings - User settings
+   * @param {Object|null} gitContext - Git context (unused for Linear, but kept for API consistency)
+   * @returns {boolean} True if this provider should handle the input
+   */
+  static detectIdentifier(input, settings, gitContext = null) {
+    // Linear issue URLs
+    if (LINEAR_URL_PATTERN.test(input)) {
+      return true;
+    }
+
+    // Linear issue key pattern (TEAM-123)
+    if (LINEAR_KEY_PATTERN.test(input)) {
+      return true;
+    }
+
+    // Bare numbers - use shared priority cascade logic
+    // Linear requires linearTeam setting to convert bare numbers to issue keys
+    // Note: gitContext check will never match 'linear' since Linear isn't a git host
+    return IssueProvider.detectBareNumber(input, settings, gitContext, 'linear', {
+      requiredSettings: ['linearTeam'],
+    });
+  }
+
+  static getRequiredTool() {
+    // No CLI binary required - talks to Linear's GraphQL API directly via fetch
+    return {
+      name: null,
+      checkCmd: null,
+      installHint: null,
+    };
+  }
+
+  /**
+   * Validate response status and parse GraphQL JSON body.
+   * Shared by checkAuth and fetchIssue so both surface 401/429/non-OK/invalid-body
+   * failures the same way instead of falling through to a generic JSON-parse error.
+   * @private
+   */
+  static async _handleGraphQLResponse(response) {
+    if (response.status === 401) {
+      throw new Error('Linear API key invalid');
+    }
+
+    if (response.status === 429) {
+      throw new Error('Linear API rate limit exceeded, try again later');
+    }
+
+    if (!response.ok) {
+      throw new Error(`Linear API request failed with status ${response.status}`);
+    }
+
+    try {
+      return await response.json();
+    } catch {
+      throw new Error(`Linear API returned an invalid response (status ${response.status})`);
+    }
+  }
+
+  /**
+   * Resolve the Linear API key: settings-owned, with env var fallback.
+   * @param {Object} [settings] - User settings (may be undefined/null)
+   * @returns {string|null}
+   */
+  static _resolveApiKey(settings) {
+    return settings?.linearApiKey || process.env.LINEAR_API_KEY || null;
+  }
+
+  /**
+   * Recovery hints pointing at the settings-based fix for a missing/invalid key.
+   * @returns {string[]}
+   */
+  static _recoveryHints() {
+    return [
+      'Set it: zeroshot settings set linearApiKey <key>',
+      'Get a key at https://linear.app/settings/api',
+      'Or export LINEAR_API_KEY=lin_api_...',
+    ];
+  }
+
+  /**
+   * Check Linear API key authentication via a minimal GraphQL query
+   */
+  static async checkAuth() {
+    // Lazy require avoids circular dependency (settings.js lazy-loads issue-providers).
+    const { loadSettings } = require('../../lib/settings');
+    const apiKey = LinearProvider._resolveApiKey(loadSettings());
+
+    if (!apiKey) {
+      return {
+        authenticated: false,
+        error: 'Linear API key not configured',
+        recovery: LinearProvider._recoveryHints(),
+      };
+    }
+
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), AUTH_CHECK_TIMEOUT_MS);
+
+      let response;
+      try {
+        response = await fetch(LINEAR_API_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: apiKey,
+          },
+          body: JSON.stringify({ query: '{ viewer { id } }' }),
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timeout);
+      }
+
+      const json = await LinearProvider._handleGraphQLResponse(response);
+      if (json.errors) {
+        return {
+          authenticated: false,
+          error: 'Linear API key invalid',
+          recovery: ['Verify LINEAR_API_KEY at https://linear.app/settings/api'],
+        };
+      }
+
+      return { authenticated: true, error: null, recovery: [] };
+    } catch (err) {
+      if (err.message === 'Linear API key invalid') {
+        return {
+          authenticated: false,
+          error: err.message,
+          recovery: ['Verify LINEAR_API_KEY at https://linear.app/settings/api'],
+        };
+      }
+
+      return {
+        authenticated: false,
+        error: err.message,
+        recovery: ['Check network connectivity', 'Verify https://api.linear.app is reachable'],
+      };
+    }
+  }
+
+  /**
+   * Linear-specific settings schema
+   */
+  static getSettingsSchema() {
+    return {
+      linearTeam: {
+        type: 'string',
+        nullable: true,
+        default: null,
+        description: "Default Linear team key for bare numbers (e.g., 'ENG')",
+        pattern: /^[A-Z][A-Z0-9]*$/,
+        patternMsg: 'linearTeam must be a valid Linear team key (e.g., ENG, PROJ)',
+      },
+      linearApiKey: {
+        type: 'string',
+        nullable: true,
+        default: null,
+        description: 'Linear personal API key (get one at https://linear.app/settings/api)',
+      },
+    };
+  }
+
+  /**
+   * Fetch the workspace's Linear teams and, if there's exactly one, persist its
+   * key as `linearTeam` so future bare-number runs skip this round-trip.
+   * @private
+   */
+  static async _resolveTeamKey(apiKey) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+    let response;
+    try {
+      response = await fetch(LINEAR_API_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: apiKey,
+        },
+        body: JSON.stringify({ query: '{ teams { nodes { key } } }' }),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+
+    const json = await LinearProvider._handleGraphQLResponse(response);
+    if (json.errors) {
+      throw new Error(json.errors.map((e) => e.message).join('; '));
+    }
+
+    const teams = json.data?.teams?.nodes || [];
+    if (teams.length === 0) {
+      throw new Error('No Linear teams found for this API key.');
+    }
+    if (teams.length > 1) {
+      const keys = teams.map((t) => t.key).join(', ');
+      throw new Error(
+        `Multiple Linear teams found (${keys}). Set one: zeroshot settings set linearTeam <KEY>`
+      );
+    }
+
+    const key = teams[0].key;
+    const { loadSettings, saveSettings } = require('../../lib/settings');
+    const current = loadSettings();
+    current.linearTeam = key;
+    saveSettings(current);
+    return key;
+  }
+
+  /**
+   * Resolve the issue key, auto-deriving `linearTeam` for bare numbers when it
+   * isn't configured yet.
+   * @private
+   */
+  async _resolveIssueKey(identifier, settings, apiKey) {
+    if (/^\d+$/.test(identifier) && !settings.linearTeam) {
+      const team = await LinearProvider._resolveTeamKey(apiKey);
+      return `${team}-${identifier}`;
+    }
+    return this._extractIssueKey(identifier, settings);
+  }
+
+  async fetchIssue(identifier, settings) {
+    const apiKey = LinearProvider._resolveApiKey(settings);
+    if (!apiKey) {
+      throw new Error(
+        `Failed to fetch Linear issue: Linear API key not configured. ${LinearProvider._recoveryHints().join(' ')}`
+      );
+    }
+
+    try {
+      const issueKey = await this._resolveIssueKey(identifier, settings, apiKey);
+
+      const query = `
+      query($id: String!) {
+        issue(id: $id) {
+          identifier
+          number
+          title
+          description
+          url
+          # Linear defaults to a 50-node first page with no pagination here; long
+          # label sets or comment threads beyond that are silently truncated.
+          labels {
+            nodes {
+              name
+            }
+          }
+          comments {
+            nodes {
+              user {
+                name
+              }
+              createdAt
+              body
+            }
+          }
+        }
+      }
+    `;
+
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+
+      let response;
+      try {
+        response = await fetch(LINEAR_API_URL, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: apiKey,
+          },
+          body: JSON.stringify({ query, variables: { id: issueKey } }),
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timeout);
+      }
+
+      const json = await LinearProvider._handleGraphQLResponse(response);
+
+      if (json.errors) {
+        throw new Error(json.errors.map((e) => e.message).join('; '));
+      }
+
+      if (!json.data?.issue) {
+        throw new Error(`Linear issue not found: ${issueKey}`);
+      }
+
+      return this._parseIssue(json.data.issue);
+    } catch (error) {
+      throw new Error(`Failed to fetch Linear issue: ${error.message}`);
+    }
+  }
+
+  /**
+   * Extract Linear issue key from URL or return as-is
+   * @private
+   */
+  _extractIssueKey(identifier, settings) {
+    // URL format: https://linear.app/<workspace>/issue/TEAM-123/...
+    const urlMatch = identifier.match(LINEAR_URL_PATTERN);
+    if (urlMatch) {
+      return urlMatch[1];
+    }
+
+    // Bare number: construct from linearTeam setting
+    if (/^\d+$/.test(identifier) && settings.linearTeam) {
+      return `${settings.linearTeam}-${identifier}`;
+    }
+
+    // Assume it's already a key
+    return identifier;
+  }
+
+  /**
+   * Parse Linear issue into standardized InputData format
+   * @private
+   */
+  _parseIssue(issue) {
+    const labels = issue.labels?.nodes || [];
+    const comments = issue.comments?.nodes || [];
+    const description = issue.description || '';
+
+    let context = `# Linear Issue ${issue.identifier}\n\n`;
+    context += `## Title\n${issue.title}\n\n`;
+
+    if (description) {
+      context += `## Description\n${description}\n\n`;
+    }
+
+    if (labels.length > 0) {
+      context += `## Labels\n`;
+      context += labels.map((l) => `- ${l.name}`).join('\n');
+      context += '\n\n';
+    }
+
+    if (comments.length > 0) {
+      context += `## Comments\n\n`;
+      for (const comment of comments) {
+        const author = comment.user?.name || 'unknown';
+        context += `### ${author} (${comment.createdAt})\n`;
+        context += `${comment.body}\n\n`;
+      }
+    }
+
+    const mappedLabels = labels.map((l) => ({ name: l.name }));
+    const mappedComments = comments.map((c) => ({
+      author: { login: c.user?.name || 'unknown' },
+      createdAt: c.createdAt,
+      body: c.body,
+    }));
+
+    return {
+      number: issue.number,
+      title: issue.title,
+      body: description,
+      labels: mappedLabels,
+      comments: mappedComments,
+      url: issue.url || null,
+      context,
+    };
+  }
+}
+
+module.exports = LinearProvider;

package/src/ledger.js

@@ -18,9 +18,10 @@ const {
 } = require('./guidance-topics');
 
 class Ledger extends EventEmitter {
-  constructor(dbPath = ':memory:') {
+  constructor(dbPath = ':memory:', options = {}) {
     super();
     this.dbPath = dbPath;
+    this.readonly = options.readonly === true;
     const busyTimeoutMs = (() => {
       const raw = process.env.ZEROSHOT_SQLITE_BUSY_TIMEOUT_MS;
       if (!raw) return 5000;
@@ -28,12 +29,23 @@ class Ledger extends EventEmitter {
       return Number.isFinite(value) && value >= 0 ? value : 5000;
     })();
 
-    this.db = new Database(dbPath, { timeout: busyTimeoutMs });
+    // Read-only connections (CLI list/status/logs) never take a write lock on
+    // another process's live database and skip schema DDL entirely - the schema
+    // is guaranteed to already exist for any cluster with a live daemon.
+    this.db = this.readonly
+      ? new Database(dbPath, { readonly: true, fileMustExist: true, timeout: busyTimeoutMs })
+      : new Database(dbPath, { timeout: busyTimeoutMs });
     this.cache = new Map(); // LRU cache for queries
     this.cacheLimit = 1000;
     this._closed = false; // Track closed state to prevent write-after-close
     this._lastTimestamp = 0;
-    this._initSchema();
+
+    if (this.readonly) {
+      this._prepareStatements();
+      this._loadLastTimestamp();
+    } else {
+      this._initSchema();
+    }
   }
 
   _initSchema() {
@@ -475,7 +487,13 @@ class Ledger extends EventEmitter {
     if (!cluster_id) {
       throw new Error('cluster_id is required for getTokensByRole');
     }
+    return this._computeTokensByRole(cluster_id);
+  }
 
+  /**
+   * @private
+   */
+  _computeTokensByRole(cluster_id) {
     // Query all TOKEN_USAGE messages for this cluster
     const sql = `SELECT * FROM messages WHERE cluster_id = ? AND topic = 'TOKEN_USAGE' ORDER BY timestamp ASC`;
     const stmt = this.db.prepare(sql);
@@ -531,6 +549,27 @@ class Ledger extends EventEmitter {
     return byRole;
   }
 
+  /**
+   * Read messageCount and tokensByRole as one consistent point-in-time view.
+   * Runs both queries inside a single BEGIN DEFERRED transaction so a concurrent
+   * writer's commit can never be observed by one query but not the other
+   * (the exact straddle that produced the msgs=0/$0 phantom in `zeroshot list`).
+   * @param {String} cluster_id - Cluster ID
+   * @returns {{ messageCount: number, tokensByRole: Object }}
+   */
+  readSnapshot(cluster_id) {
+    if (!cluster_id) {
+      throw new Error('cluster_id is required for readSnapshot');
+    }
+    if (!this._snapshotTxn) {
+      this._snapshotTxn = this.db.transaction((id) => ({
+        messageCount: this.stmts.count.get(id).count,
+        tokensByRole: this._computeTokensByRole(id),
+      })).deferred;
+    }
+    return this._snapshotTxn(cluster_id);
+  }
+
   /**
    * Subscribe to new messages
    * @param {Function} callback - Called with each new message
@@ -676,6 +715,9 @@ class Ledger extends EventEmitter {
    * Close the database connection
    */
   close() {
+    if (this._closed) {
+      return;
+    }
     this._closed = true; // Set flag BEFORE closing to prevent race conditions
     this.db.close();
   }