ThiaQ Local Runner

Customer-hosted runner for ThiaQ discovery, repo summaries, recipe runs, and deterministic suite execution.

ThiaQ Cloud is hosted at https://app.thiaq.com.

Discovery behavior is governed by ../../docs/guides/discovery-operating-playbook.md. The runner or connected Chrome-extension harness should own deterministic branch-frontier execution: inventory safe visible and adapter-exposed actions, execute one branch at a time, capture before/after evidence, fingerprint/de-duplicate states, restore parents when possible, and emit compact review packets. Frontier models review those packets; they are not the long-running click engine.

npm install --save-dev @thiaq/local-runner
npx thiaq login
npx thiaq setup
npx thiaq runner doctor
npx thiaq runner start

thiaq login opens the browser and authorizes the CLI against https://app.thiaq.com by default. Use --host <url> for a self-hosted or local control plane.

thiaq setup is the guided path. It confirms the current repo, asks whether to use hosted ThiaQ Cloud or a custom control-plane URL, lets you select the ThiaQ project by name or creates the first project for the repo, asks for the local or staging app URL, adapter id, and repo tooling folder, then creates the adapter files and registers the local runner.

runner setup writes only repo-local QA/tooling files. It chooses an existing QA/test folder when possible (qa/thiaq, tests/thiaq, e2e/thiaq, and similar), or use --tooling-dir tests/thiaq to choose explicitly. It also adds .thiaq/ and thiaq.runner.json to .gitignore.

The runner executes in the customer environment. Product secrets stay local. Do not change application code for ThiaQ setup unless the team explicitly asks for an app-code change.

Discovery jobs need a product adapter or command when the runner is installed from npm. Implement adapter.runDiscovery, or set discoveryCommand in thiaq.runner.json; the command must write .thiaq/latest-report.json. The built-in source-checkout discovery path is only for ThiaQ monorepo development.

For authenticated discovery, pass product session material through the local environment. Creately-style token files are read locally and converted into a browser cookie for discovery and recipe validation:

CREATELY_E2E_TOKEN_FILE=tests/.env.tokens npx thiaq runner start

Contract verification schedules dispatch jobType: "verification". The repo adapter must implement runSuite; the runner routes both verification and deterministic_run jobs through that method. Missing verification support is a job failure, never a diagnostic pass.

While a claimed job is running, the runner emits a per-job heartbeat every minute. This is separate from the environment heartbeat: it renews only the active job lease, so a long suite is not mistaken for an abandoned claim and an idle process cannot keep another process's dead job alive.