Per-statement timeout for the SQL executor (resource_limit)

[sandeep-agami]

Adds a per-statement timeout to the SQL executor so a runaway query (a recursive CTE, a cartesian product, an unbounded scan) is bounded rather than hanging. The result-row cap shipped earlier (#109); this is the timeout half of the same work.

What changes

• AGAMI_SQL_TIMEOUT_S (default 30s) bounds every query at the single executor chokepoint, so both the stdio and HTTP surfaces inherit it. A query that exceeds it is cancelled and returns a resource_limit refusal — the query is killed, no partial data.
• Genuine server-side cancellation where the engine supports it: Postgres/Redshift statement_timeout (delivered via SET LOCAL so transaction-mode poolers don't reject it), MySQL max_execution_time / MariaDB max_statement_time, Snowflake STATEMENT_TIMEOUT_IN_SECONDS, BigQuery job_timeout_ms + job.cancel(), SQL Server / Oracle / Trino / Databricks each their native param or cursor cancel — layered under a universal wall-clock watchdog (per-driver conn.cancel / conn.interrupt / cur.cancel / socket timeout) so no engine hangs past the deadline.
• Documented in both agami.env.example copies alongside the row-cap knob.

Verification

• The genuine cancel is proven in-process against SQLite and DuckDB — a real recursive-CTE bomb is interrupted mid-flight (~1s under a 1s deadline) and returns a resource_limit refusal, not a hang or a generic error.
• The cloud engines' native params are asserted by config (a unit test per driver, checking the param and its units — the ms-vs-s mix is the easy way to silently make a timeout 1000x wrong). CI has no live warehouses, so this mirrors the same call as the prior fail-closed spec.
• Full test gate green; driven end-to-end through the executor CLI (bomb → resource_limit + exit 1; fast query unaffected).

Review

Ran the Agami review panel — correctness, silent-failure, test-quality, and a mandatory High-lane security review. Security sign-off satisfied (Postgres genuinely cancels DB-side; a timed-out query is a refused response with no data; no injection/leak/egress; the timeout can't be disabled by query or env). Fixes applied from the panel:

• MySQL/MariaDB could hang — closing a connection from the watchdog thread doesn't unblock a recv() on Linux, and MariaDB's native variable differs; added socket read_timeout/write_timeout (a reliable client bound) and try both dialects' native timeout.
• Postgres pooler regression — the libpq options startup parameter is rejected at connect by transaction-mode poolers; deliver statement_timeout per-transaction via SET LOCAL instead.
• Postgres exit code — a cancelled query aborts the txn, so the server-side cursor close raised and masked the refusal; swallow the close so the resource_limit exit code survives.
• Classifier race — classify a timeout on elapsed wall-clock time as well as the watchdog flag, so a native server timeout that wins the race is never mislabeled.

Stacked on #112; retarget to main once #111 and #112 merge.

Spec: ACE-038

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements ACE-038’s per-statement SQL timeout at the shared executor chokepoint, ensuring runaway queries are cancelled and surfaced as a typed resource_limit refusal (no partial data) across both stdio and HTTP surfaces.

Changes:

• Adds AGAMI_SQL_TIMEOUT_S (default 30s) plus a universal wall-clock watchdog layered with engine-native timeout/cancel mechanisms.
• Ensures refusal semantics are consistent (exit code 1 + refusal JSON; discard any partial stdout on refusal).
• Adds focused tests covering in-process cancellation (SQLite/DuckDB) and config/unit assertions for native timeout parameters, plus env example documentation.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/agami-core/src/execute_sql.py	Adds watchdog-based per-statement deadline, engine-specific native timeout wiring, and maps deadline hits to resource_limit refusals.
plugins/agami/lib/execute_sql.py	Mirrors the same executor timeout/refusal behavior for the plugin-distributed copy.
tests/test_resource_limits.py	New test suite proving real cancellation for SQLite/DuckDB and asserting native timeout parameters/units per driver.
tests/test_execute_sql_envelope.py	Pins that resource_limit refusals discard partial stdout so refused envelopes never include partial data.
tests/test_ace044_bounded_fetch.py	Updates test cursor stub with cancel() to support the new watchdog cancel primitive.
deploy/agami.env.example	Documents AGAMI_SQL_TIMEOUT_S alongside row cap as executor-enforced resource limits.
plugins/agami/skills/agami-deploy/bundle/agami.env.example	Same env documentation for the deploy bundle copy.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[sandeep-agami]

Superseded by #174, which is the Wave 1 port of this work onto main.

This branch has no mergeable base — it sits on #112 → #111, so merging it would drag its whole ancestry — which is why the governance remediation plan ports rather than merges it. #174 is that port, cut fresh from main after ACE-035 landed.

What carried over: the wall-clock watchdog, the per-driver cancels, and the Postgres SET LOCAL statement_timeout. What did not, and why:

• The refusal here is the pre-ACE-035 Refusal{kind, reason, remediation} and is raised as GuardRefused. That type no longer exists; a refusal is returned.
• Deadline classification here ORs "watchdog fired" with "elapsed ≥ timeout", which turns any post-deadline OOM, disk error or admin kill into a resource_limit refusal telling the caller to narrow a query that was fine. ACE-038: the per-statement timeout — one budget, four ordered bounds, one boolean #174 classifies on the watchdog flag alone.
• The native-timeout setting is swallowed on failure, the remediation names AGAMI_SQL_TIMEOUT_S (a variable the caller cannot set), and the supervisor is left at a fixed 240s.
• The per-driver cancel map here is wrong on three drivers: pymysql.Connection has no cancel(), the Snowflake connector has none anywhere, and pymssql's is on the wrapped connection.

Kept as a reference diff, not deleted.