Gateway Module — `agent-tune/`

1. Purpose

The agent-tune module backs the Agent Self-Improvement (ASI) pipeline's Phase 5a monitoring stage. When an approved agent-definition change lands, a monitoring window is opened recording the pre-change baseline (quality, stall rate, affinity rate) and the commit SHA; the window is later closed as completed or rolled_back after post-change telemetry is compared. Its defining invariant is global serialisation: only ONE active monitoring window may exist across ALL agents at any time, so tune effects are never confounded by overlapping changes. Smallest of the seven shard modules (~267 lines).

2. File Inventory

No index.ts factory — the repository + router are wired directly in the main server/index.ts (createAgentTuneRepository + createAgentTuneRouter, mounted at index.ts:754).

3. Public API Surface

REST Endpoints (mount: index.ts:754 → /api/agent-tune)

MCP Tools

None. This surface is driven by the agent-tune skill (ASI orchestration), not by an MCP tool.

4. Internal API

createAgentTuneRepository(db) → AgentTuneRepository { getActiveMonitoringWindows, createMonitoringWindow, closeMonitoringWindow }. createAgentTuneRouter(repo) → Express Router.

5. Background Services

None. The window expires_at field is set by the caller; there is no gateway-side expiry sweep — expiry enforcement is the ASI skill's responsibility (see §9).

6. Data Contracts

• CreateMonitoringWindowSchema: agent_name, rule_id, change_date, pre_quality (number), pre_stall_rate (number), pre_affinity_rate (number), commit_sha, expires_at — all required.
• CloseMonitoringWindowSchema: status (completed|rolled_back).
• MonitoringStatus = active|completed|rolled_back. Serialisation constraint enforced in createMonitoringWindow via SELECT COUNT(*) WHERE status='active' > 0 → throw SERIALISATION_VIOLATION (route maps to 409).

7. Dependencies

• Gateway modules: shared/zod-error.js.
• External: better-sqlite3, express, zod.
• Environment variables: none. Table agent_tune_monitoring (created via boot DDL).

8. Test Coverage

9. Known Limitations

• expires_at is advisory only. No gateway timer auto-closes an expired window; a monitoring window left open indefinitely will block every subsequent createMonitoringWindow with a 409 until manually closed. Expiry enforcement lives entirely in the ASI/agent-tune skill layer.
• The serialisation check + insert are not wrapped in a single transaction — a race between two concurrent POSTs could theoretically admit two windows. In practice the ASI pipeline is single-threaded (one tune at a time by design), so the window for the race is negligible, but it is not structurally closed.
• GET returns a bare array rather than the {data: ...} envelope used by most other gateway routes — a minor contract inconsistency for dashboard consumers.

10. Change History