references/scout-data-model.md
Scout data model — what you're reading
Three records describe a scout's life on a project, plus one snapshot it orients from.
This reference is the vocabulary for everything exploring-scouts returns.
SignalScoutConfig — the scout's settings
One row per (team, skill_name).
Returned by scout-config-list.
This is the scout's control surface, separate from its instruction body (the LLMSkill).
| Field | Meaning |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | Config id: the handle scout-config-update takes to tune it. |
| skill_name | The skill this config controls. Fixed; one config per skill per team. Usually signals-scout-*, but any skill name can hold a config. |
| display_name | The name the UI shows. Blank means the default derived from skill_name. |
| description | What the scout watches, read live from the skill's frontmatter. Empty when the skill is gone from the team (an orphan config) or has no description. |
| scout_origin / owners | canonical (PostHog seeded it) or custom (team-authored); owners lists the skill's owners. The value comes from the skill row's seed metadata, which survives an in-place edit, so a canonical scout the team has edited (diverged, no longer synced) still reads canonical here. |
| enabled | false = paused. The coordinator skips disabled scouts entirely. Derived from status. |
| status | Who owns the pause: active, pending_pause (still runs; an ignored warning pauses after a week, a no_output warning only ever warns; any config edit clears it), paused_by_system (automatic, resumable with enabled: true), paused_by_user (a person switched it off; the system never overrides it). |
| pause_reason | Why the system paused or warned: no_output, ignored, or repeated_failures. Null outside pending_pause / paused_by_system. |
| status_changed_at | When status last changed: for pending_pause, when the warning was issued (an ignored warning pauses about a week later; a no_output one never does). |
| consecutive_failure_count | Current streak of failed scheduled runs (manual and workflow-triggered failures don't count; a clean run from any trigger clears it). The failure breaker (repeated_failures) trips one failure past the runs the schedule fits in twelve hours, clamped to 5–25 (daily: 5, rolling hourly interval: 13, hourly cron: 15 because cron slots are counted over a DST-padded window); any config edit resets it. |
| auto_pause_exempt | true = the inactivity sweep never judges this scout (for a watchdog whose silence is the job, or output consumed where the inbox can't see it). |
| emit | false = dry-run: the scout runs and reasons every tick but writes nothing to the inbox. |
| run_interval_minutes | Rolling cadence, 30–43200. Default 1440 (daily). The coordinator dispatches when due. |
| run_cron_schedule | Optional five-field cron in the project timezone. When set it takes precedence over the interval; a new or edited schedule waits for its next slot rather than catching up. |
| output_destinations | Where reports go besides the inbox: slack (integration plus a channel or up to five DM targets, optional thread_reports) is the only destination Signals delivers to itself; a webhook entry is a pointer to a CDP destination the owning product manages, and says nothing about whether anything is delivered there. |
| network_access | What the run's sandbox can reach: trusted (default: the platform's trusted-domain allowlist: PostHog, GitHub, package registries) or full (any site, for skills that read external docs/papers). |
| mcp_gateway_server_ids | MCP store servers the scout's runs may mount, from connections shared with the whole team. Empty = no shared servers (where gateway enforcement is not yet active, the acting user's personal connections may still mount). Security-relevant like network_access, and activity-logged. |
| write_scopes | Project-wide write scopes this scout holds (notebook:write, dashboard:write, insight:write, annotation:write, alert:write, customer_task:write, llm_skill:write, warehouse_view:write, warehouse_table:write, replay_scanner:write, canvas:write, experiment:write). New scouts start with notebook:write. Empty = read-only beyond findings and memory. A dry run never holds them. |
| model | Pinned model for this scout's runs, or null to follow the fleet default. Setting one needs the scouts-model-config early-access flag on the project. |
| structured_output_schema | Optional JSON Schema (object-rooted) describing one structured record the scout produces via scout-record-output. Null = the structured-output channel is off (it also needs emit on). When set, each run is shown the schema and its records are validated against it and recorded as $scout_structured_output events. |
| tags | Free-form kebab-case labels (up to 10) grouping the fleet; scout-config-list filters on them. |
| source_product / source_id | Set when another product stood the scout up for one of its own objects (Replay Vision creates one per scanner) so it can find and clean up its scouts; null for a scout a person created directly. |
| last_run_at | When the coordinator last dispatched it. null = never dispatched by the coordinator, not never run: manual (scout-run-now) and workflow-triggered runs leave it untouched, so check scout-runs-list before calling a scout never-run. Drives the due-check (with run_cron_schedule and creation time on a cron scout). |
The replay_scanner:write grant permits scanner maintenance across the project.
Scouts must set a credit limit on scanners they create, copy, or enable.
Changes to targeting, sampling, or the model of an enabled scanner also require a limit.
Scouts cannot remove a limit, delete a scanner, or start manual scans, retries, or backfills.
They can disable a scanner and keep its observations.
Shared ratings must record explicit user verdicts. Autonomous assessments belong in scout memory or reports.
| updated_at | When the config last changed, including settings edits and system status changes. Scheduled dispatch updates last_run_at, not this field. |
A scout that is enabled: true, emit: false is alive and working — it just can't post reports.
It is the extra-careful rollout posture for a chatty or high-stakes scout (the default is emit: true), and the most common cause of "my scout does nothing" reports.
SignalScoutRun — one execution
Returned by scout-runs-list (summary) and scout-runs-retrieve (detail; same shape).
Each run is one sandboxed agent execution of one scout.
The run is a thin bridge to a tasks.TaskRun — status, timing, and the full transcript live on the Task side.
scout-runs-retrieve takes the run id as id, not run_id — even though the list and the detail payload both name the field run_id.
Pass the list's run_id value through as id.
| Field | Meaning |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| run_id | UUID of the run. Pass it to scout-runs-retrieve as id. Strictly team-scoped (404 across teams). |
| skill_name | Which scout ran. |
| skill_version | The body version that ran. If a scout was edited, older runs ran an older version — useful when comparing behavior before/after a change. |
| status | Run outcome, from the linked TaskRun (see below). |
| started_at | ISO-8601 — when the TaskRun was created. |
| completed_at | ISO-8601 — when it finished. null while in flight. Duration = completed_at - started_at. |
| emitted_report_ids | The reports the run authored via emit_report, in order. This (with edited_report_ids) is the run's output — resolve each id via inbox-reports-retrieve. Empty = the run authored nothing, except on a measurement scout, whose output is its $scout_structured_output records.