@haystackeditor/cli 0.17.1 → 0.19.0

package/dist/index.js

@@ -89,6 +89,9 @@ const headlessLoginCommand = lazy(() => import('./commands/tokens.js'), 'headles
 const headlessLogoutCommand = lazy(() => import('./commands/tokens.js'), 'headlessLogoutCommand');
 const listTokensCommand = lazy(() => import('./commands/tokens.js'), 'listTokensCommand');
 const revokeTokenCommand = lazy(() => import('./commands/tokens.js'), 'revokeTokenCommand');
+const databaseProfileCommand = lazy(() => import('./commands/db-profile.js'), 'databaseProfileCommand');
+const databaseProfileShowCommand = lazy(() => import('./commands/db-profile-show.js'), 'databaseProfileShowCommand');
+const databaseProfileUploadCommand = lazy(() => import('./commands/db-profile-upload.js'), 'databaseProfileUploadCommand');
 // `mcp` is imported lazily inside its command action (below), NOT at the top level.
 // It is the only module that pulls in `@modelcontextprotocol/sdk`; keeping it out of
 // the startup import graph means a missing/broken SDK can never crash core commands
@@ -201,28 +204,50 @@ program
     .action(statusCommand);
 const verify = program
     .command('verify')
-    .description('Verify the current change with the hosted Haystack fleet')
+    .description('Crawl the running app with your current change: where it shows up and what broke')
     .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
-    .option('--base <ref>', 'Base revision (default: merge base of HEAD and origin/default branch)')
-    .option('--head <ref>', 'Head revision (default: current HEAD commit)')
-    .option('--intent-file <path>', 'Optional intent JSON with problem, goal, and intended_outcomes')
-    .option('--idempotency-key <key>', 'Stable retry key (default: derived from repository, refs, and intent)')
     .option('--account <login>', 'Use a specific saved Haystack account')
-    .option('--no-wait', 'Return after the hosted run is queued')
-    .option('--interval <seconds>', 'Hosted polling interval (default 5)')
-    .option('--timeout <minutes>', 'Maximum hosted wait (default 35)')
-    .option('--json', 'Machine-readable run status and results')
+    .option('--no-wait', 'Print the crawl\'s current state and return without waiting')
+    .option('--minutes <n>', 'How long the crawl may take, 1-30 (default: .haystack.json crawl.minutes, else 3)')
+    .option('--json', 'The crawl as one JSON document on stdout (see `haystack schema verify`)')
     .addHelpText('after', `
-Run inside a git checkout after pushing your current commit. The repository
-comes from origin, head from HEAD, and base from git merge-base HEAD with
-origin's default branch (origin/HEAD, falling back to origin/main).
-Explicit --repo, --base, and --head values override these defaults.
-Intent is optional. Hosted status resumes an existing run.
+Run inside a git checkout; nothing needs to be committed or pushed. It captures
+the checkout (committed and uncommitted changes) exactly as the stop hook does,
+with the base at the merge base of HEAD and origin's default branch, and finds
+your crawl of that exact capture: the same code and the same change title (the
+title tells the crawl's judge what the change is). When there is none, or the
+one it finds was cancelled, stopped before finishing or is being cancelled, it
+submits the capture (the service starts the crawl, or runs the stopped one
+again), says so, and follows that crawl.
+
+A crawl builds the app with and without your change, starts from the changed
+code, explores outward with both side by side, and double-checks and judges
+every difference it can within its time: 3 minutes unless the repository's
+.haystack.json sets crawl.minutes or --minutes says otherwise (1 to 30).
+Differences it had no time to check are listed as not finished in time. The
+command waits for the crawl, printing each step and each bug the moment the
+crawl finds it; it finishes when the crawl answers, as soon as its time is up,
+without waiting for the crawl's machines to shut down. Ctrl-C stops waiting,
+never the crawl. It then prints where your change shows up in the app (each
+changed spot, how far the crawl got with it, and the steps that reached it),
+what the crawl found (bugs first, with the steps to see each), and the changed
+code it never ran.
+
+Exit codes:
+  0  the crawl answered or finished (the bugs it found are in the output), or
+     it is still running and --no-wait was given
+  1  the command failed, or no crawl could be started for this change
+  2  the crawl ended without finishing: it stopped early or was cancelled
+     (a newer stop in the repository replaces an older crawl), or the
+     machines it used could not be proven shut down
+
+The hosted fleet run of pushed commits is \`haystack verify hosted start\`.
 
 Examples:
   haystack verify
+  haystack verify --no-wait
+  haystack verify --minutes 10
   haystack verify --json
-  haystack verify --repo owner/repo --base main --head feature --no-wait
   haystack verify history owner/repo --limit 20
   haystack verify hosted status cv_<48 lowercase hex characters> --wait
 `)
@@ -287,10 +312,8 @@ hostedVerify
     .command('start')
     .description('Start an authenticated production verification and wait for its terminal result')
     .argument('<repository>', 'Exact GitHub owner/repository name')
-    // `verify` already owns --base/--head for repository verification.
-    // Re-declaring these as Commander requiredOption values makes the parent
-    // consume them and the child then reject a valid invocation. Runtime
-    // validation below accepts the inherited values and still fails closed.
+    // Not Commander requiredOption values: runtime validation below accepts
+    // values inherited through verifyCommandOptions and still fails closed.
     .option('--base <sha>', 'Required: exact 40-character lowercase base commit SHA')
     .option('--head <sha>', 'Required: exact 40-character lowercase head commit SHA')
     .option('--intent-file <path>', 'Optional JSON with exactly problem, goal, and intended_outcomes')
@@ -810,6 +833,55 @@ Example:
     includeSymbolsFile: options.includeSymbols,
     includeSymbols: undefined,
 }), options.json));
+// ─── db ──────────────────────────────────────────────────────────────────────
+const dbProgram = program
+    .command('db')
+    .description('Profile your own database so Haystack can build a full-size stand-in without personal data');
+const dbProfile = dbProgram
+    .command('profile')
+    .description('Write a read-only, PII-free profile of a Postgres database; run it inside your own environment')
+    .option('--url-env <name>', 'Name of the environment variable holding the postgres:// connection string (never the string itself)')
+    .option('--owner-table <schema.table>', 'Table whose rows are the owners (users or organizations); values must be shared by enough of them')
+    .option('--schema <name>', 'Schema to profile; repeat for several (default: every non-system schema)', (value, previous = []) => [...previous, value])
+    .option('--category-max-distinct <n>', 'Most distinct values a column may have and still count as a category (default 50)')
+    .option('--category-min-owners <n>', 'Fewest owners that must share a value, shape or JSON key before it is kept (default 50, minimum 5)')
+    .option('--concurrency <n>', 'Database connections used at once (default 2, maximum 8)')
+    .option('--statement-timeout <seconds>', 'Longest any one query may run before the profile fails (default 120)')
+    .option('--scan-max-mb <mb>', 'Tables larger than this are read through a TABLESAMPLE of about this size (default 256)')
+    .option('--out <file>', 'Where to write the profile JSON')
+    .addHelpText('after', `
+The profiler only reads. Every query runs in a READ ONLY transaction with a
+statement timeout, and the database computes all counts and patterns: no row
+ever reaches the profiler. A column's values are written only when it has at
+most --category-max-distinct values, is not personal, and each value is shared
+by at least --category-min-owners owners. Review the file before sending it.
+
+Examples:
+  export DATABASE_URL='postgres://readonly@db.internal:5432/app'
+  haystack db profile --url-env DATABASE_URL --owner-table public.users --out profile.json
+  haystack db profile show profile.json
+  haystack db profile upload profile.json --repo acme/app
+`)
+    .action((options) => runPublicCommand(() => databaseProfileCommand(options)));
+dbProfile
+    .command('show <file>')
+    .description('Print, in plain English, exactly what a profile file would send')
+    .action((file) => runPublicCommand(() => databaseProfileShowCommand(file)));
+dbProfile
+    .command('upload <file>')
+    .description('Send a reviewed profile to Haystack for one repository (and, optionally, one run-map database dependency)')
+    .option('--repo <owner/repo>', 'GitHub repository the database belongs to')
+    .option('--dependency <id>', 'Run-map database dependency id the profile describes. Omit it when the run map has one Postgres database: the profile is then used for it, whatever its id')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .addHelpText('after', `
+Without --dependency the profile belongs to the repository, and onboarding
+builds the stand-in database from it when the run map declares exactly one
+Postgres dependency. When it declares none or several, haystack verify hosted
+start prints why no stand-in was used and names the declared ids; upload again with
+--dependency <id> to pick one. A profile uploaded with --dependency is used for
+that dependency; when both apply, the newer upload is used.
+`)
+    .action((file, options) => runPublicCommand(() => databaseProfileUploadCommand(file, options)));
 program
     .command('dismiss <pr>')
     .description('Dismiss analysis findings for a PR')
@@ -1205,7 +1277,8 @@ hooks
     .addHelpText('after', `
 Configures your coding CLI to run \`haystack triage --hook\` on session start.
 This shows pending PR analysis results when you open a new terminal session.
-Claude Code also runs \`haystack verify precompute --hook\` when a session stops.
+Claude Code also runs \`haystack verify precompute --hook\` when a session stops,
+which starts a crawl of the change in the background (see \`haystack verify\`).
 
   Claude Code:  Native SessionStart and Stop hooks (.claude/settings.local.json;
                 --shared writes the committed .claude/settings.json)
@@ -1382,6 +1455,91 @@ webhooks
         process.exit(1);
     }
 });
+// ─── admin ───────────────────────────────────────────────────────────────────
+// Operator commands. The only credential is the operator's Cloudflare Access
+// token (`cloudflared access token`); exit 3 means an epoch conflict (409).
+async function runAdminCommand(action) {
+    try {
+        process.exitCode = await action();
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+    }
+}
+const admin = program.command('admin').description('Haystack operator commands (Cloudflare Access)');
+const fleetPolicy = admin
+    .command('fleet-policy')
+    .description('Fleet policy authority in D1: approved policies per tenant and repository')
+    .addHelpText('after', `
+<repository> is owner/name or github.com:<id>. The worker URL comes from
+--worker-url, else $HAYSTACK_ADMIN_WORKER_URL, else the production agent worker.
+set and revoke need --expected-epoch (read it with show); a stale epoch exits 3.
+`);
+const workerUrlOption = '--worker-url <url>';
+const workerUrlHelp = 'Agent worker origin (default: $HAYSTACK_ADMIN_WORKER_URL or production)';
+fleetPolicy
+    .command('show <repository>')
+    .description('Show the active policy, epoch and binding of each matching scope')
+    .option('--tenant <id>', 'Tenant id, when several tenants have the repository')
+    .option('--json', 'Print the raw response')
+    .option(workerUrlOption, workerUrlHelp)
+    .action(async (repository, options) => {
+    const { fleetPolicyShowCommand } = await import('./commands/fleet-policy.js');
+    await runAdminCommand(() => fleetPolicyShowCommand(repository, options));
+});
+fleetPolicy
+    .command('diff <repository>')
+    .description('Dry-run a set and print what would change, field by field')
+    .requiredOption('--file <policy.json>', 'One VerifyPolicyV1 object')
+    .option('--tenant <id>', 'Tenant id (required for a repository without an installation)')
+    .option(workerUrlOption, workerUrlHelp)
+    .action(async (repository, options) => {
+    const { fleetPolicyDiffCommand } = await import('./commands/fleet-policy.js');
+    await runAdminCommand(() => fleetPolicyDiffCommand(repository, options));
+});
+fleetPolicy
+    .command('set <repository>')
+    .description('Write a new policy version at the expected epoch (live GitHub check first)')
+    .requiredOption('--file <policy.json>', 'One VerifyPolicyV1 object')
+    .requiredOption('--expected-epoch <n>', 'The epoch show printed; never filled in for you')
+    .requiredOption('--reason <text>', 'Why, 1 to 500 characters; recorded in the change log')
+    .option('--tenant <id>', 'Tenant id (required for a repository without an installation)')
+    .option(workerUrlOption, workerUrlHelp)
+    .action(async (repository, options) => {
+    const { fleetPolicySetCommand } = await import('./commands/fleet-policy.js');
+    await runAdminCommand(() => fleetPolicySetCommand(repository, options));
+});
+fleetPolicy
+    .command('revoke <repository>')
+    .description('Revoke the scope at the expected epoch and stop its running attempts (never contacts GitHub)')
+    .requiredOption('--expected-epoch <n>', 'The epoch show printed; never filled in for you')
+    .requiredOption('--reason <text>', 'Why, 1 to 500 characters; recorded in the change log')
+    .option('--tenant <id>', 'Tenant id, when several tenants have the repository')
+    .option(workerUrlOption, workerUrlHelp)
+    .action(async (repository, options) => {
+    const { fleetPolicyRevokeCommand } = await import('./commands/fleet-policy.js');
+    await runAdminCommand(() => fleetPolicyRevokeCommand(repository, options));
+});
+fleetPolicy
+    .command('history <repository>')
+    .description('Print the change log and the versions, newest first')
+    .option('--tenant <id>', 'Tenant id, when several tenants have the repository')
+    .option('--limit <n>', 'At most this many events and versions, 1 to 500 (default 100)')
+    .option(workerUrlOption, workerUrlHelp)
+    .action(async (repository, options) => {
+    const { fleetPolicyHistoryCommand } = await import('./commands/fleet-policy.js');
+    await runAdminCommand(() => fleetPolicyHistoryCommand(repository, options));
+});
+fleetPolicy
+    .command('import-kv')
+    .description('One time: import the KV policies and tenant overrides into D1')
+    .option('--dry-run', 'Report what would be imported without writing')
+    .option(workerUrlOption, workerUrlHelp)
+    .action(async (options) => {
+    const { fleetPolicyImportKvCommand } = await import('./commands/fleet-policy.js');
+    await runAdminCommand(() => fleetPolicyImportKvCommand(options));
+});
 // ─── rules ───────────────────────────────────────────────────────────────────
 const rules = program.command('rules').description('Manage .haystack/pr-rules.yml');
 rules

package/dist/schema.js

@@ -20,6 +20,7 @@ export const SCHEMA_VERSIONS = {
     action: '1.0.0',
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
+    verify: '1.0.0',
     error: '1.0.0',
 };
 /** Wrap a payload with the `schema_version` envelope. */

package/dist/types.js

@@ -294,6 +294,9 @@ const PreferencesSchema = z.object({
 export const HaystackConfigSchema = z.object({
     /** Config version (must be "1") */
     version: z.literal('1'),
+    /** Hosted crawls of this repository (`haystack verify`, the stop hook): how long one may take, whole minutes from 1 to 30.
+     * Absent: the service's default (3 minutes). `haystack verify --minutes` overrides it for one run. */
+    crawl: z.object({ minutes: z.number().int().min(1).max(30).optional() }).strict().optional(),
     /** Project name (for display) */
     name: z.string().optional(),
     /** Repository-level Haystack behavior */

package/dist/utils/verify-base.js

@@ -0,0 +1,31 @@
+import { resolveDiffBaseRef } from './git.js';
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
+export function resolveOriginDefaultBranch(git) {
+    // Prints origin/<branch> when the clone records origin/HEAD, nothing when it
+    // does not; for-each-ref exits 0 either way.
+    const remoteHead = git.run(['for-each-ref', '--format=%(symref:short)', 'refs/remotes/origin/HEAD']);
+    if (remoteHead.startsWith('origin/') && remoteHead.length > 'origin/'.length) {
+        const branch = remoteHead.slice('origin/'.length);
+        git.run(['check-ref-format', `refs/heads/${branch}`]);
+        return branch;
+    }
+    const remoteRefs = git.run(['ls-remote', '--symref', 'origin', 'HEAD'], { remote: true });
+    const prefix = 'ref: refs/heads/';
+    const heads = remoteRefs.split('\n').map(line => line.split('\t'))
+        .filter(fields => fields.length === 2 && fields[1] === 'HEAD' && fields[0].startsWith(prefix))
+        .map(fields => fields[0].slice(prefix.length));
+    if (heads.length !== 1 || heads[0].length === 0) {
+        throw new Error('Could not resolve the origin default branch.');
+    }
+    git.run(['check-ref-format', `refs/heads/${heads[0]}`]);
+    return heads[0];
+}
+/** The base commit of `head` under the rule above. */
+export function resolveVerifyBaseSha(head, git) {
+    const defaultBranch = resolveOriginDefaultBranch(git);
+    const baseRef = resolveDiffBaseRef(defaultBranch, git.fetchOptions());
+    const baseSha = git.run(['merge-base', head, baseRef]);
+    if (!COMMIT_SHA.test(baseSha))
+        throw new Error('Could not derive the base commit.');
+    return baseSha;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {
@@ -47,6 +47,8 @@
     "chalk": "6.0.0",
     "commander": "15.0.0",
     "fast-glob": "3.3.3",
+    "pg": "8.23.0",
+    "pg-connection-string": "2.14.0",
     "ws": "8.21.3",
     "yaml": "2.9.1",
     "zod": "4.6.5"
@@ -54,6 +56,7 @@
   "devDependencies": {
     "@eslint/js": "8.57.1",
     "@types/node": "22.19.8",
+    "@types/pg": "8.23.1",
     "@types/ws": "8.18.1",
     "@typescript-eslint/eslint-plugin": "7.18.0",
     "@typescript-eslint/parser": "7.18.0",

package/schemas/verify.v1.json

@@ -0,0 +1,237 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/verify.v1.json",
+  "title": "Haystack verify: the crawl of the current change (CRAWL-V1)",
+  "description": "Machine-readable output of `haystack verify --json`: the caller's crawl of the exact captured checkout (its code and its change title), as GET /api/agent/cloud-verifier/crawls?repository=&workCommit= or, for a crawl the command just submitted, GET /api/agent/cloud-verifier/crawls/:runId?repository= returns it, or null when no crawl of the capture could be started. The crawl shapes mirror infra/lambda/haystack-design-verifier-shared/crawl_contracts.ts (with amendments 1, 8 and 9); that file wins where they differ.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "crawl"],
+  "properties": {
+    "schema_version": { "const": "1.0.0" },
+    "crawl": {
+      "oneOf": [
+        { "type": "null" },
+        { "$ref": "#/$defs/crawlView" }
+      ]
+    }
+  },
+  "$defs": {
+    "runId": { "type": "string", "pattern": "^cv_[0-9a-f]{48}$" },
+    "commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "count": { "type": "integer", "minimum": 0 },
+    "timestamp": { "type": ["string", "null"], "format": "date-time" },
+    "status": { "enum": ["queued", "preparing", "crawling", "draining", "completed", "incomplete", "cancelled"] },
+    "stage": { "enum": ["reconcile", "source", "worlds", "blast", "knobs", "prepare", "crawl", "publish", "cleanup"] },
+    "spotStage": { "enum": ["resolved", "loaded", "exposed", "activated", "pressed", "observed", "confirmed", "judged"] },
+    "reuseValue": { "enum": ["hit", "miss", null] },
+    "reuse": {
+      "type": "object",
+      "required": ["baseWorld", "headWorld", "prepare", "routes"],
+      "properties": {
+        "baseWorld": { "$ref": "#/$defs/reuseValue" },
+        "headWorld": { "$ref": "#/$defs/reuseValue" },
+        "prepare": { "$ref": "#/$defs/reuseValue" },
+        "routes": { "$ref": "#/$defs/reuseValue" }
+      }
+    },
+    "error": {
+      "type": "object",
+      "required": ["code", "stage", "message"],
+      "properties": {
+        "code": {
+          "enum": ["source-mismatch", "blast-unavailable", "world-build-failed", "prepare-failed", "crawl-failed",
+            "no-capacity", "stalled", "lease-lost", "cancelled"]
+        },
+        "stage": { "$ref": "#/$defs/stage" },
+        "message": { "type": "string" }
+      }
+    },
+    "strings": { "type": "array", "items": { "type": "string" } },
+    "finding": {
+      "type": "object",
+      "required": ["id", "verdict", "why", "start", "steps", "observed", "codeThatRan", "confirmedAtSeconds", "images"],
+      "properties": {
+        "id": { "type": "string" },
+        "verdict": { "enum": ["bug", "not-a-bug", "cant-tell", "being-judged"] },
+        "why": { "type": ["string", "null"] },
+        "start": { "type": "string", "description": "Where the replay starts." },
+        "steps": { "type": "array", "maxItems": 64, "items": { "type": "string" } },
+        "observed": { "type": "object" },
+        "codeThatRan": { "type": "object" },
+        "confirmedAtSeconds": { "type": "number", "minimum": 0 },
+        "images": {
+          "type": "object",
+          "required": ["old", "new"],
+          "properties": {
+            "old": { "type": ["string", "null"] },
+            "new": { "type": ["string", "null"] }
+          }
+        }
+      }
+    },
+    "spot": {
+      "description": "One changed spot (one hunk of a changed file) and how far the crawl got with it: the change's product blast radius.",
+      "type": "object",
+      "required": ["id", "file", "line", "furthest", "reachedBy", "shows", "findingIds"],
+      "properties": {
+        "id": { "type": "string", "description": "<file>#<n>: the file's n-th hunk, 1-based." },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "furthest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/spotStage" }] },
+        "reachedBy": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["stage", "start", "steps", "page"],
+              "properties": {
+                "stage": { "$ref": "#/$defs/spotStage" },
+                "start": { "type": "string" },
+                "steps": { "$ref": "#/$defs/strings" },
+                "page": { "type": ["string", "null"] }
+              }
+            }
+          ]
+        },
+        "shows": { "type": "array", "maxItems": 5, "items": { "type": "string" } },
+        "findingIds": { "$ref": "#/$defs/strings" }
+      }
+    },
+    "results": {
+      "description": "The published results' shape, shared by the sealed manifest and an answer; each sets its own status.",
+      "type": "object",
+      "required": ["schemaVersion", "runId", "attemptId", "repository", "baseCommit", "workCommit", "treeSha",
+        "changeTitle", "status", "worlds", "reuse", "timings", "bugs", "findings", "reach", "notFinishedInTime", "error"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "runId": { "$ref": "#/$defs/runId" },
+        "attemptId": { "type": "string" },
+        "repository": { "type": "string" },
+        "baseCommit": { "$ref": "#/$defs/commit" },
+        "workCommit": { "$ref": "#/$defs/commit" },
+        "treeSha": { "$ref": "#/$defs/commit" },
+        "changeTitle": { "type": "string", "maxLength": 200 },
+        "worlds": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["base", "head"],
+              "properties": { "base": { "type": "string" }, "head": { "type": "string" } }
+            }
+          ]
+        },
+        "reuse": { "$ref": "#/$defs/reuse" },
+        "timings": {
+          "description": "Milliseconds per stage, as measured.",
+          "type": "object",
+          "additionalProperties": { "type": "number", "minimum": 0 }
+        },
+        "bugs": { "$ref": "#/$defs/count" },
+        "findings": { "type": "array", "maxItems": 50, "items": { "$ref": "#/$defs/finding" } },
+        "reach": {
+          "type": "object",
+          "required": ["spots", "unreachedChangedFiles", "blast"],
+          "properties": {
+            "spots": { "type": "array", "items": { "$ref": "#/$defs/spot" } },
+            "unreachedChangedFiles": { "$ref": "#/$defs/strings" },
+            "blast": {
+              "oneOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "required": ["functions", "ran", "unreached", "nearestUnreached"],
+                  "properties": {
+                    "functions": { "$ref": "#/$defs/count" },
+                    "ran": { "$ref": "#/$defs/count" },
+                    "unreached": { "$ref": "#/$defs/count" },
+                    "nearestUnreached": { "$ref": "#/$defs/strings" }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "notFinishedInTime": { "$ref": "#/$defs/count" },
+        "error": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/error" }] }
+      }
+    },
+    "manifest": {
+      "description": "Present once the crawl is terminal and published.",
+      "allOf": [{ "$ref": "#/$defs/results" }],
+      "properties": {
+        "status": { "enum": ["completed", "incomplete", "cancelled"] }
+      }
+    },
+    "answer": {
+      "description": "CRAWL-V1 amendment 9: the current attempt's latest answer while no sealed manifest exists: what the crawl found so far (exploring), or its answer once its time is up (answered), with the same findings and reach the sealed manifest will carry. Its findings carry no images.",
+      "allOf": [{ "$ref": "#/$defs/results" }],
+      "required": ["n", "atSeconds"],
+      "properties": {
+        "status": { "enum": ["exploring", "answered"] },
+        "n": { "type": "integer", "minimum": 1, "description": "The attempt's answers are numbered from 1." },
+        "atSeconds": { "type": "integer", "minimum": 0, "description": "How far into the crawl stage it was written." }
+      }
+    },
+    "crawlView": {
+      "type": "object",
+      "required": ["runId", "repository", "baseCommit", "workCommit", "treeSha", "changeTitle", "budgetMs", "observedAt",
+        "createdAt", "updatedAt", "supersededBy", "cancelRequested", "manifest", "answer", "status", "stage", "clocks",
+        "reuse", "worlds", "totals"],
+      "properties": {
+        "runId": { "$ref": "#/$defs/runId" },
+        "repository": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$" },
+        "baseCommit": { "$ref": "#/$defs/commit" },
+        "workCommit": { "$ref": "#/$defs/commit" },
+        "treeSha": { "$ref": "#/$defs/commit" },
+        "changeTitle": { "type": "string", "maxLength": 200 },
+        "budgetMs": { "description": "The time the crawl was asked for (ms), or null for the service's default.",
+          "oneOf": [{ "type": "null" }, { "type": "integer", "minimum": 60000, "maximum": 1800000 }] },
+        "observedAt": { "$ref": "#/$defs/count" },
+        "createdAt": { "type": "string", "format": "date-time" },
+        "updatedAt": { "type": "string", "format": "date-time" },
+        "supersededBy": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/runId" }] },
+        "cancelRequested": { "type": "boolean" },
+        "status": { "$ref": "#/$defs/status" },
+        "stage": { "$ref": "#/$defs/stage" },
+        "clocks": {
+          "type": "object",
+          "required": ["startedAt", "stageStartedAt", "crawlStartedAt", "finishedAt", "crawlBudgetMs"],
+          "properties": {
+            "startedAt": { "$ref": "#/$defs/timestamp" },
+            "stageStartedAt": { "$ref": "#/$defs/timestamp" },
+            "crawlStartedAt": { "$ref": "#/$defs/timestamp" },
+            "finishedAt": { "$ref": "#/$defs/timestamp" },
+            "crawlBudgetMs": { "$ref": "#/$defs/count" }
+          }
+        },
+        "reuse": { "$ref": "#/$defs/reuse" },
+        "worlds": {
+          "type": "object",
+          "required": ["base", "head"],
+          "properties": {
+            "base": { "type": ["string", "null"] },
+            "head": { "type": ["string", "null"] }
+          }
+        },
+        "totals": {
+          "type": "object",
+          "required": ["clicks", "differing", "confirmed", "bugs", "vmsLaunched", "cleanupProven", "cleanupUnproven"],
+          "properties": {
+            "clicks": { "$ref": "#/$defs/count" },
+            "differing": { "$ref": "#/$defs/count" },
+            "confirmed": { "$ref": "#/$defs/count" },
+            "bugs": { "$ref": "#/$defs/count" },
+            "vmsLaunched": { "$ref": "#/$defs/count" },
+            "cleanupProven": { "$ref": "#/$defs/count" },
+            "cleanupUnproven": { "$ref": "#/$defs/count" }
+          }
+        },
+        "error": { "$ref": "#/$defs/error" },
+        "manifest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/manifest" }] },
+        "answer": { "description": "Null once the sealed manifest exists, and before the crawl's first answer.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/answer" }] }
+      }
+    }
+  }
+}

package/dist/commands/combination-search-hook-contract.js

@@ -1 +0,0 @@
-export {};