@loopover/miner 0.1.0

package/docs/observability.md

@@ -0,0 +1,60 @@
+# Observing your miner
+
+How to point Grafana at redacted miner reporting exports to see attempt and prediction history without exposing the
+miner's live local ledgers. This covers the **miner-specific** observability wiring only; for general self-host
+operations, see your ops runbook.
+
+## What's observable
+
+The miner writes append-only SQLite ledgers under `GITTENSORY_MINER_CONFIG_DIR` (default
+`~/.config/gittensory-miner` on a laptop, or `/data/miner` in the fleet Docker image — see
+[`DEPLOYMENT.md`](../DEPLOYMENT.md)):
+
+- **`attempt-log.sqlite3`** — the driver-level attempt event trace (event type, action class, mode, reason,
+  timestamps), table `attempt_log_events`.
+- **`prediction-ledger.sqlite3`** — recorded predicted-gate verdicts for later scoring.
+
+Those live files can contain free-form payloads, repo/target identifiers, readiness scores, and blocker/warning
+codes. Keep `GITTENSORY_MINER_CONFIG_DIR` private to the miner. Grafana should read only sanitized reporting
+exports that operators create from those ledgers.
+
+## Point Grafana at reporting exports
+
+The repo ships datasource provisioning at
+[`grafana/provisioning/datasources/ams-ledgers.yml`](../../../grafana/provisioning/datasources/ams-ledgers.yml)
+— two **read-only** `frser-sqlite-datasource` entries: `AMS Attempt Log` (uid `ams-attempt-log`) and
+`AMS Prediction Ledger` (uid `ams-prediction-ledger`). Their default paths live under Grafana's reporting mount,
+not under the miner config directory.
+
+1. **Install the SQLite plugin** in Grafana — the same one the maintainer `LoopoverDB` datasource uses:
+
+   ```sh
+   GF_INSTALL_PLUGINS=frser-sqlite-datasource
+   ```
+
+2. **Run the AMS reporting exporter**, a dedicated compose profile (only useful when a miner also runs on this
+   same host — an engine-only deployment has nothing for it to read):
+
+   ```sh
+   docker compose --profile ams-observability up -d
+   ```
+
+   Set `GITTENSORY_MINER_CONFIG_DIR` in your `.env` (see [`.env.example`](../../../.env.example)) to the same
+   directory your miner uses. The `ams-reporting-exporter` container mounts it **read-only**, runs
+   [`scripts/export-ams-reporting-db.sh`](../../../scripts/export-ams-reporting-db.sh) on an interval
+   (`GITTENSORY_AMS_REPORTING_EXPORT_INTERVAL_SECONDS`, default 30s), and writes the redacted snapshots into the
+   same `reporting` volume Grafana already reads — Grafana itself never mounts the live ledgers. The exported
+   schema drops `attempt_log_events.reason`/`.payload_json` (the free-form fields) entirely; every other column,
+   including the `predictions` table's `blocker_codes_json`/`warning_codes_json` (fixed, engine-defined codes —
+   never free text), passes through unchanged.
+
+3. **Restart Grafana.** The two datasources appear under **Connections → Data sources**, already provisioned
+   (non-editable) so they survive restarts.
+
+## Load a dashboard
+
+Dashboards live in [`grafana/dashboards/`](../../../grafana/dashboards/) and are auto-provisioned from that
+directory. To visualize AMS activity, add a dashboard JSON there — or import one at runtime via the Grafana UI
+(**Dashboards → Import**) — and point its panels at the `AMS Attempt Log` / `AMS Prediction Ledger` datasources
+above. Panels should query only the redacted reporting schema (e.g. `SELECT * FROM attempt_log_events`), never a
+`payload_json`/`reason` column — the exporter drops both, so a panel referencing them returns no such column.

package/docs/operations-runbook.md

@@ -0,0 +1,209 @@
+# gittensory-miner — operational runbook
+
+Operator-facing runbook for **local SQLite state**: what the concurrency guarantees actually mean, how to recover from corruption, what to do when two miner processes collide on the same files, and how schema upgrades migrate your on-disk ledgers after a package update.
+
+> **Scope:** AMS local stores only. For laptop/fleet deployment layout see [`../DEPLOYMENT.md`](../DEPLOYMENT.md). For Grafana setup see [#5190](https://github.com/JSONbored/gittensory/issues/5190). For the optional hosted discovery plane see [`discovery-plane-operator-guide.md`](discovery-plane-operator-guide.md). This runbook does **not** cover the self-hosted **review stack** (Orb/API/LoopoverDB).
+
+## Local state at a glance
+
+Every miner keeps **independent SQLite files** under one state directory (default `~/.config/gittensory-miner/`, override with `GITTENSORY_MINER_CONFIG_DIR`). Each store has its own file, table, and optional per-store env override — see the table in [`../README.md`](../README.md#local-storage) and [`env-reference.md`](env-reference.md).
+
+Common files you will touch in incidents:
+
+| File | Purpose |
+|------|---------|
+| `laptop-state.sqlite3` | Bootstrap metadata (`gittensory-miner init`) |
+| `claim-ledger.sqlite3` | Soft issue claims on this machine |
+| `event-ledger.sqlite3` | Append-only manage-loop audit trail |
+| `portfolio-queue.sqlite3` | Per-repo portfolio queue |
+| `run-state.sqlite3` | Discover/plan/prepare phase markers |
+| `attempt-log.sqlite3` | Per-attempt coding-agent driver events |
+| `prediction-ledger.sqlite3` | Predicted gate verdicts for self-improve |
+| `plan-store.sqlite3` | Persisted MCP plan DAGs |
+| `governor-ledger.sqlite3` | Governor allow/deny/throttle decisions |
+
+Files are created with **`0700` directories / `0600` database files** on first open.
+
+## SQLite concurrency — what `busy_timeout` guarantees
+
+Every store opened through `local-store.js` sets:
+
+```sql
+PRAGMA busy_timeout = 5000;
+```
+
+(default **5000 ms**; overridable via `openLocalStoreDb(path, { busyTimeoutMs })` in tests only — production stores use the default.)
+
+### What this means for operators
+
+| Situation | Expected behavior |
+|-----------|-------------------|
+| Two **short-lived** writers on the **same file** (e.g. CLI command finishing while `loop` is idle, or Grafana reading while the miner appends) | SQLite waits up to **5 seconds** for the lock, then proceeds or surfaces `database is locked` |
+| Append-only ledgers (`event-ledger`, `attempt-log`, …) | Writes use **`BEGIN IMMEDIATE`** (or equivalent single-statement atomicity) so sequence allocation cannot interleave |
+| Claim / queue stores | **`INSERT … ON CONFLICT`** and **`UPDATE … RETURNING`** patterns avoid read-then-write races **within one file** |
+| Two **long-running `gittensory-miner loop` daemons** on the **same `GITTENSORY_MINER_CONFIG_DIR`** | **Unsupported.** `busy_timeout` reduces transient lock errors; it does **not** make multi-process loop workers safe on one volume |
+
+**Invariant:** one active loop (or one intentional writer set) per state directory. Horizontal scale = **isolated state dirs** (separate compose projects, separate `GITTENSORY_MINER_CONFIG_DIR`, or the k8s StatefulSet pattern in [`../DEPLOYMENT.md`](../DEPLOYMENT.md)).
+
+### Quick health check
+
+```sh
+gittensory-miner doctor --json
+gittensory-miner status --json
+```
+
+`doctor` includes `laptop-state-sqlite` (file exists + readable) and `state-dir-writable`. It performs **no network I/O**.
+
+## Scenario: two miners collided
+
+**Symptoms**
+
+- `database is locked` / `SQLITE_BUSY` in logs or stderr
+- Duplicate or out-of-order event sequences after an unclean shutdown
+- Two systemd units, two `docker compose --scale miner=N` replicas, or a manual `loop` plus a supervised `loop` sharing one config dir
+- Claims or queue rows flipping unexpectedly
+
+**Diagnosis**
+
+1. List processes using the state dir:
+
+   ```sh
+   STATE_DIR="$(gittensory-miner status --json | jq -r .stateDir)"
+   ls -la "$STATE_DIR"
+   # Linux: lsof +D "$STATE_DIR" 2>/dev/null || fuser -v "$STATE_DIR"/*.sqlite3 2>/dev/null
+   ```
+
+2. Confirm only **one** long-lived miner should own that directory.
+
+3. Inspect soft claims and queue without mutating:
+
+   ```sh
+   gittensory-miner claim list --json
+   gittensory-miner queue list --json
+   gittensory-miner ledger list --json | tail -20
+   ```
+
+**Remediation**
+
+1. **Stop all but one** miner process targeting that state dir (`systemctl stop`, `docker compose down`, kill stray `loop`).
+2. If you need **N parallel workers**, give each an isolated state path — do **not** share one volume:
+
+   ```sh
+   # Example: two isolated compose projects
+   docker compose -p miner-a -f docker-compose.miner.yml up -d
+   docker compose -p miner-b -f docker-compose.miner.yml up -d
+   ```
+
+   Or set distinct `GITTENSORY_MINER_CONFIG_DIR` per worker.
+
+3. Re-run `gittensory-miner doctor`. If locks persist with a single process, see **Ledger corrupted** below.
+
+4. **Claims are local bookkeeping only.** Two miners on different machines claiming the same GitHub issue is a **fleet coordination** problem (duplicate-cluster adjudication in the engine), not something SQLite resolves — split state dirs and use operational claim hygiene.
+
+## Scenario: ledger corrupted
+
+**Symptoms**
+
+- Command throws `corrupted_*_row` (`corrupted_attempt_log_row`, `corrupted_governor_row`, `corrupted_plan_row`, `corrupted_prediction_row`, …)
+- `gittensory-miner doctor` reports `laptop-state-sqlite` not readable
+- `sqlite3` reports `database disk image is malformed`
+- Partial writes after disk full, forced kill during a migration transaction, or copying a live `.sqlite3` while the miner is writing
+
+**Diagnosis**
+
+1. Identify which file fails (error message or env override path).
+2. Read-only probe:
+
+   ```sh
+   DB="$STATE_DIR/event-ledger.sqlite3"   # example
+   sqlite3 "$DB" "PRAGMA integrity_check;"
+   sqlite3 "$DB" "PRAGMA user_version;"
+   ```
+
+3. Check filesystem: disk space, permissions (`0600` file, `0700` parent), backup tools copying mid-write.
+
+**Remediation**
+
+1. **Stop the miner** before any file surgery.
+2. **Backup the whole state directory** (even damaged files help post-mortems):
+
+   ```sh
+   cp -a "$STATE_DIR" "${STATE_DIR}.bak.$(date +%Y%m%d%H%M%S)"
+   ```
+
+3. Choose a recovery tier:
+
+   | Tier | When | Action |
+   |------|------|--------|
+   | **A — single store reset** | One ledger is corrupt; others healthy; you accept losing that store's history | Remove only the bad `*.sqlite3` (and any `-wal`/`-shm` siblings). Next command recreates an empty store. |
+   | **B — restore from backup** | You have a recent quiesced backup | Stop miner → restore the known-good file → restart. |
+   | **C — full re-init** | Multiple files suspect or state is disposable | Archive dir → `gittensory-miner init` → reconfigure env/goals. Rebuild claims/plans from GitHub metadata as needed. |
+
+4. **Never copy a live SQLite file** from a running miner as backup — stop first, or use SQLite's `.backup` command:
+
+   ```sh
+   sqlite3 "$DB" ".backup '${DB}.safe-copy'"
+   ```
+
+5. After recovery, run `gittensory-miner doctor --json` and spot-check read-only listings (`claim list`, `ledger list`).
+
+Append-only stores **do not repair individual bad rows** in place — corrupted payload JSON is rejected on read by design so bad data cannot silently propagate.
+
+## Scenario: migrate ledgers after a package upgrade
+
+**How upgrades work**
+
+Stores use the lightweight **`schema-version.js`** convention ([#4832](https://github.com/JSONbored/gittensory/issues/4832)):
+
+- Bootstrap `CREATE TABLE IF NOT EXISTS …` is schema **version 1** (`BASELINE_SCHEMA_VERSION`).
+- Each store may register post-baseline migrations; `applySchemaMigrations` runs pending steps on **every open**.
+- Version is stamped in SQLite **`PRAGMA user_version`**.
+- Migrations run **once**, in order, inside a transaction; a failed migration rolls back and retries on next open.
+- **Downgrade is not supported** — older miner versions may not read files written by newer migrations.
+
+**Operator checklist**
+
+1. **Before upgrading** the `@loopover/miner` package (npm, image tag, or git pull):
+
+   ```sh
+   gittensory-miner doctor --json > /tmp/miner-pre-upgrade-doctor.json
+   STATE_DIR="$(gittensory-miner status --json | jq -r .stateDir)"
+   tar -czf "/tmp/gittensory-miner-state-$(date +%Y%m%d).tar.gz" -C "$(dirname "$STATE_DIR")" "$(basename "$STATE_DIR")"
+   ```
+
+2. **Stop** supervised loops (`systemctl stop gittensory-miner.service`, `docker compose stop miner`, etc.).
+
+3. **Install** the new version (`npm install -g @loopover/miner@latest`, rebuild image, …). The CLI prints a one-line npm upgrade nudge when behind registry latest — informational only.
+
+4. **Migrate**, before starting any miner process, so every existing store is brought up to date in one
+   deliberate pass instead of relying on whichever command happens to open a given store first:
+
+   ```sh
+   gittensory-miner migrate --json
+   ```
+
+   (Pending migrations still apply automatically on first open regardless — e.g. `portfolio-queue` adds
+   `leased_at` when upgrading from pre-#4827 files — `migrate` is the proactive, explicit alternative to
+   waiting for that implicit path. A store file that hasn't been created yet is reported as skipped, not
+   created; `migrate` never bootstraps fresh state.)
+
+5. **Start** one miner process, then **verify**:
+
+   ```sh
+   gittensory-miner doctor --json
+   gittensory-miner status --json
+   gittensory-miner migrate --json   # re-run: every store should now report "up-to-date"
+   ```
+
+6. If a migration throws on startup, **do not delete files immediately** — restore the pre-upgrade tarball, pin the previous package version, and file an issue with the failing `user_version` and store filename.
+
+**Rolling fleet upgrades:** upgrade and restart **one worker/state dir at a time** so isolated workers never share a directory mid-migration.
+
+## Related docs
+
+- [`../DEPLOYMENT.md`](../DEPLOYMENT.md) — laptop vs fleet, volumes, systemd, scaling rules
+- [`../README.md`](../README.md#local-storage) — store inventory
+- [`env-reference.md`](env-reference.md) — per-store path overrides
+- [`coding-agent-driver.md`](coding-agent-driver.md) — attempt log semantics
+- [#5190](https://github.com/JSONbored/gittensory/issues/5190) — Grafana + SQLite ledgers (observability doc)
+- [`discovery-plane-operator-guide.md`](discovery-plane-operator-guide.md) — optional hosted plane (distinct from local ledger ops)

package/docs/repo-agnostic-capability-audit.md

@@ -0,0 +1,129 @@
+# Repo-agnostic capability audit — miner discovery / claim / scoring
+
+Audit of the `packages/gittensory-miner` discovery, claim, and scoring code for hardcoded or
+implicitly gittensory-specific assumptions that would need to become per-tenant configuration before
+the loop can run against an arbitrary repo. This is the checklist deliverable for **#4780**; the
+follow-up **#4784** executes it (turning each open item below into config, gittensory's own values
+surviving only as the default). Audit-and-document only — no code changes here.
+
+## Summary
+
+The miner's discovery/claim/scoring code is **already largely repo-agnostic**. Discovery queries are
+caller-supplied, label preferences are generic per-tenant config (`.gittensory-miner.yml` uses plain
+`bug`/`enhancement`, not `gittensor:*`), ranking/feasibility are delegated to
+`@loopover/engine` with config-overridable inputs, and runtime knobs live in
+`.gittensory-ams.yml`. The remaining assumptions fall into three buckets:
+
+1. **GitHub as the only forge** — the fan-out hardcodes GitHub's REST paths, headers, API version, and
+   search-qualifier syntax. This is the single largest gap for a non-GitHub tenant.
+2. **An existing forge-host override that isn't reachable from the CLI** — `opportunity-fanout` already
+   accepts `apiBaseUrl` (GitHub Enterprise), but `discover-cli` never parses or threads it.
+3. **Engine-delegated gittensory *defaults*** — label taxonomy and the miner goal spec default to
+   gittensory's conventions in `@loopover/engine`; they are overridable, but the miner uses
+   the gittensory defaults out of the box unless a per-tenant config is supplied.
+
+Everything else audited is already parameterized (see the last section) and needs no #4784 work.
+
+## Findings by file / module
+
+### `lib/opportunity-fanout.js` — discovery fan-out (biggest gap)
+
+| Line | Assumption | Category | Should become |
+| --- | --- | --- | --- |
+| 4 | `const defaultApiBaseUrl = "https://api.github.com"` | (6) endpoint | Per-tenant forge base URL (default github.com). Override path exists (see below) but the default is GitHub. |
+| 7 | `const githubApiVersion = "2022-11-28"` | (2) forge protocol | Per-forge API version; **no override today**. |
+| 69–71 | `accept: "application/vnd.github+json"`, `"x-github-api-version": githubApiVersion` | (2) forge protocol | Per-forge request headers (a forge adapter). |
+| 83 | `` `/repos/${owner}/${repo}${suffix}` `` | (5) query construction | Per-forge repo path template. |
+| 202 | `` `${trimmed} state:open type:issue` `` (search qualifiers) | (5) query construction | Per-forge search dialect (GitHub search syntax is assumed). |
+| 241 | `"/search/issues"` | (5) query construction | Per-forge search endpoint. |
+| 70 | `"user-agent": "gittensory-miner"` | (7) branding | Cosmetic; low priority — a configurable UA string. |
+
+Note: the label extractor (`labelNames`, ~168) and issue projection are already generic — they read
+whatever label strings the forge returns, with no `gittensor:*` filter. No change needed there.
+
+### `lib/discover-cli.js` — `discover` command wiring
+
+| Line | Assumption | Category | Should become |
+| --- | --- | --- | --- |
+| 289–290 (fanout) vs `runDiscover` | `opportunity-fanout` accepts `options.apiBaseUrl`, but `runDiscover`'s arg parser only handles `--search` / targets / `--json` — it never parses or passes `apiBaseUrl`, so the existing GitHub-Enterprise override is **unreachable from the CLI**. | (6) endpoint | Thread a forge base URL from `.gittensory-miner.yml` / a `--api-base-url` flag into the fan-out call. |
+| 102 | `process.env.GITHUB_TOKEN` | (6) auth | Per-forge credential env var (default `GITHUB_TOKEN`). |
+
+### `lib/opportunity-ranker.js` — candidate ranking (delegated)
+
+| Line | Assumption | Category | Should become |
+| --- | --- | --- | --- |
+| 1–5 | imports `DEFAULT_MINER_GOAL_SPEC`, `parseMinerGoalSpecContent`, `rankMetadataOpportunities` from `@loopover/engine` | (3) scoring rubric | Ranking is engine-delegated and config-driven via `parseMinerGoalSpecContent`, but falls back to `DEFAULT_MINER_GOAL_SPEC` (gittensory's rubric) when no per-tenant goal spec is provided. #4784 should ensure a tenant goal spec is surfaced/required rather than silently defaulting. |
+
+### `lib/feasibility-cli.js` — feasibility verdict (delegated)
+
+| Line | Assumption | Category | Should become |
+| --- | --- | --- | --- |
+| 4 | delegates to engine `buildFeasibilityVerdict` | (3) scoring rubric | The status vocabularies (`CLAIM_STATUSES`, `DUPLICATE_CLUSTER_RISKS`, `ISSUE_STATUSES`) are generic; the *verdict logic* lives in the engine. No miner-side hardcode, but the engine rubric is a shared dependency to confirm is tenant-neutral. |
+
+### `@loopover/engine` (shared dependency the miner scores through)
+
+| Location | Assumption | Category | Should become |
+| --- | --- | --- | --- |
+| `src/settings/pr-type-label.ts:26–28` | `DEFAULT_TYPE_LABELS = { bug: "gittensor:bug", feature: "gittensor:feature", priority: "gittensor:priority" }` | (1) label names | Already overridable per repo (`#label-modularity`), **default gittensory**. The miner inherits these defaults; #4784 should pass the tenant's label names through. |
+
+## Already parameterized — no #4784 change needed
+
+These were checked and are already tenant-agnostic / config-driven; call them out so #4784 doesn't
+redo them:
+
+- **Discovery query** — caller-supplied via `discover --search <query>` or explicit `owner/repo`
+  targets; no hardcoded gittensory label query (`discover-cli.js`).
+- **Label preferences** — `.gittensory-miner.yml` `preferredLabels` / `blockedLabels` are generic
+  (`bug`, `enhancement`, `wontfix`, `duplicate`), not `gittensor:*`.
+- **Path scope, feasibility gate, self-plagiarism threshold, concurrency** — all per-tenant in
+  `.gittensory-miner.yml` (`wantedPaths`, `blockedPaths`, `feasibilityGate`, `selfPlagiarism`,
+  `maxConcurrentClaims`).
+- **Runtime caps** — `.gittensory-ams.yml` (`submissionMode`, `capLimits`, `convergenceThresholds`,
+  `maxIterations`) are generic runtime knobs.
+- **Local stores** — `portfolio-queue`, `claim-ledger`, `event-ledger`, etc. are generic SQLite
+  bookkeeping with env-configurable DB paths; no gittensory-specific schema.
+
+## Prioritized checklist for #4784
+
+- [x] **High — forge abstraction (`opportunity-fanout.js`):** move the GitHub API version (7),
+  headers (69–71), repo path (83), search endpoint (241), and search-qualifier dialect (202) behind a
+  per-tenant forge adapter; keep GitHub as the default.
+- [x] **High — thread `apiBaseUrl` to the CLI (`discover-cli.js`):** surface the already-supported
+  `opportunity-fanout` `apiBaseUrl` override via config / a flag so a non-`api.github.com` host is
+  reachable.
+- [x] **Medium — credential env var (`discover-cli.js:102`):** make the token env var name
+  configurable (default `GITHUB_TOKEN`).
+- [x] **Medium — pass tenant label taxonomy + goal spec through (`opportunity-ranker.js`, engine
+  `DEFAULT_TYPE_LABELS`):** ensure the miner supplies the tenant's labels / goal spec instead of
+  silently falling back to the gittensory defaults.
+- [x] **Low — configurable user-agent (`opportunity-fanout.js:70`).**
+
+## Resolution (#4784)
+
+All five checklist items are resolved (or, where noted, explicitly deferred with a reason); gittensory's
+own github.com conventions survive only as defaults, and the existing gittensory discovery path is
+unchanged (`resolveForgeConfig()` with no overrides is byte-identical to the pre-#4784 hardcoded
+behavior).
+
+- **Forge abstraction — resolved.** [`lib/forge-config.js`](../lib/forge-config.js) is the per-tenant
+  forge adapter: `DEFAULT_FORGE_CONFIG` holds every github.com value (base URL, API version + version
+  header name, `accept` header, user-agent, repo path prefix, search endpoint, search qualifiers,
+  token env var) and `resolveForgeConfig(overrides)` fills any missing field from that default.
+  `opportunity-fanout.js` now reads these from the resolved forge instead of module constants, so the
+  API version, request headers, repo path, search endpoint, and search-qualifier dialect are all
+  per-tenant.
+- **`apiBaseUrl` reachable from the CLI — resolved.** `discover` accepts `--api-base-url <url>` (and
+  `runDiscover({ apiBaseUrl })`), threading the forge host that the fan-out already supported but that
+  the CLI never surfaced. A programmatic caller can also pass the rest of the forge knobs via
+  `runDiscover({ forge })`.
+- **Credential env var — resolved.** `discover --token-env <VAR>` (and `runDiscover({ tokenEnv })`)
+  reads a non-`GITHUB_TOKEN` variable, defaulting to `GITHUB_TOKEN`.
+- **Tenant goal spec through — resolved.** `runDiscover` forwards `goalSpecsByRepo` /
+  `goalSpecContentByRepo` to the ranker and surfaces `usedDefaultGoalSpec` in both the JSON and the
+  human-readable summary, so the fall-back to gittensory's built-in rubric is explicit rather than
+  silent. The **discovery** label taxonomy is the goal spec's generic `preferredLabels` /
+  `blockedLabels` (already per-tenant). The engine's `DEFAULT_TYPE_LABELS` (`gittensor:*`) is a
+  **review-stack** default (overridable per repo via the focus manifest) that the miner discovery
+  ranker never consults, so it is **deferred**: changing it belongs to the review path, not #4784's
+  discovery/claim scope.
+- **Configurable user-agent — resolved.** `forge.userAgent` (default `loopover-miner`).

package/docs/unattended-scheduling.md

@@ -0,0 +1,107 @@
+# gittensory-miner — unattended scheduling & failure alerting
+
+Operational guidance for running the miner's scheduled commands — `manage poll` and `discover` —
+unattended on a timer (cron or systemd), and for alerting when a run fails. These are the two commands
+most likely to run on a schedule; everything they need is local and they make no interactive prompts.
+
+> **Scope:** scheduling + failure alerting for `manage poll` / `discover`. For local-state recovery see
+> [`operations-runbook.md`](operations-runbook.md); for deployment layout see
+> [`../DEPLOYMENT.md`](../DEPLOYMENT.md).
+
+## The exit-code contract (what to alert on)
+
+Both commands follow the same convention, so any scheduler can detect a failed run from the exit code:
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Success — the command completed. |
+| `2` | Failure — invalid arguments, or the run hit an error (network / API / local state). **Alert on this.** |
+
+For scheduled runs, two flags matter:
+
+- `--no-update-check` (or `GITTENSORY_MINER_NO_UPDATE_CHECK=1`) — skip the npm-registry version nudge so
+  an unattended run never depends on / prints it.
+- `--json` — machine-parseable stdout, so an alert handler can attach the structured output.
+
+## cron
+
+```cron
+# crontab env applies to every job below.
+MAILTO=you@example.com
+GITTENSORY_MINER_NO_UPDATE_CHECK=1
+
+# Poll a tracked PR every 10 minutes. The `||` branch fires on any non-zero exit: it logs the failing
+# code to syslog AND re-raises it with `exit "$status"`, so the failure stays visible to exit-status
+# monitoring instead of being masked by logger's own success.
+*/10 * * * * /usr/local/bin/gittensory-miner manage poll acme/widgets 42 --json || { status=$?; logger -t gittensory-miner "manage poll failed (exit $status)"; exit "$status"; }
+
+# Discover + enqueue candidate work hourly.
+0 * * * * /usr/local/bin/gittensory-miner discover --search "label:good-first-issue" --json || { status=$?; logger -t gittensory-miner "discover failed (exit $status)"; exit "$status"; }
+```
+
+Two cron facts to get right here:
+
+- **`MAILTO` mails *output*, not exit status.** cron emails whatever a job writes to stdout/stderr to
+  `MAILTO` — it does not send a message "because" the exit code was non-zero. A job that fails *silently*
+  (non-zero exit, no output) produces no mail, so don't rely on `MAILTO` alone as the failure signal.
+- **A bare `|| logger …` hides the failure.** `logger` succeeds (exit 0), so `cmd || logger …` makes the
+  whole cron job exit 0 — any exit-status-based monitoring then sees success. Capture the code first
+  (`status=$?`) and re-raise it (`exit "$status"`) as shown, so the real failing code survives.
+
+## systemd (service + timer)
+
+A `oneshot` service plus a timer is the more observable option: `systemctl status` / `journalctl`
+capture each run, and `OnFailure=` is a first-class alerting hook.
+
+`gittensory-miner-discover.service`:
+```ini
+[Unit]
+Description=gittensory-miner discover
+OnFailure=gittensory-miner-alert@%n.service
+
+[Service]
+Type=oneshot
+Environment=GITTENSORY_MINER_NO_UPDATE_CHECK=1
+# A non-zero exit (2) marks the unit failed and triggers OnFailure=.
+ExecStart=/usr/local/bin/gittensory-miner discover --search "label:good-first-issue" --json
+```
+
+`gittensory-miner-discover.timer`:
+```ini
+[Unit]
+Description=Run gittensory-miner discover hourly
+
+[Timer]
+OnCalendar=hourly
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+Enable with `systemctl enable --now gittensory-miner-discover.timer`.
+
+## Alerting on failure
+
+Every option keys on the same exit-code contract (`2` = failure):
+
+- **cron:** append `|| { status=$?; <alert-command>; exit "$status"; }` (as in the cron example above) —
+  capture `$?` before the alert command runs and re-raise it, so the failure isn't masked. Substitute
+  `logger` with a webhook `curl`, a PagerDuty/Slack CLI, etc. (`MAILTO` still mails any output, but is not
+  a reliable signal for a silent failure — see the cron note above.)
+- **systemd:** `OnFailure=gittensory-miner-alert@%n.service` runs a templated alert unit on any non-zero
+  exit. A minimal alert unit:
+  ```ini
+  # gittensory-miner-alert@.service
+  [Service]
+  Type=oneshot
+  ExecStart=/usr/local/bin/notify-failure "gittensory-miner unit %i failed"
+  ```
+- **wrapper script:** for any scheduler, wrap the command and preserve its exit code:
+  ```sh
+  #!/bin/sh
+  gittensory-miner "$@" || { status=$?; notify-failure "gittensory-miner $* exited $status"; exit "$status"; }
+  ```
+
+Keep `--json` on scheduled runs so the alert handler can forward the structured output; the
+human-readable form is for interactive use.

package/expected-engine.version

@@ -0,0 +1 @@
+1.0.0

package/lib/ams-policy.d.ts

@@ -0,0 +1,20 @@
+import type { AmsPolicySpec } from "@loopover/engine";
+export function resolveAmsPolicyConfigPath(env?: Record<string, string | undefined>): string;
+
+export type AmsPolicySource = "local" | "default";
+
+export type ResolvedAmsPolicy = {
+  spec: AmsPolicySpec;
+  source: AmsPolicySource;
+  warnings: string[];
+};
+
+export function resolveAmsPolicy(
+  repoFullName: string,
+  options?: {
+    fetchImpl?: unknown;
+    readFileSync?: (path: string, encoding: "utf8") => string;
+    existsSync?: (path: string) => boolean;
+    env?: Record<string, string | undefined>;
+  },
+): Promise<ResolvedAmsPolicy>;

package/lib/ams-policy.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from "node:fs";
+import { DEFAULT_AMS_POLICY_SPEC, parseAmsPolicySpecContent } from "@loopover/engine";
+import { resolveLocalStoreDbPath } from "./local-store.js";
+
+// Resolver for the operator-local `.gittensory-ams.yml` (#5132, Wave 3.5 follow-up). AmsPolicySpec
+// (ams-policy-spec.ts, engine package) is the type/parser surface; this module is the actual local
+// read+resolve caller.
+//
+// This is deliberately NOT the same resolution shape as self-review-context.js/rejection-signal.js, which
+// read from the target repo: AmsPolicySpec's fields are the OPERATOR's own execution-risk policy, so an
+// untrusted target repo must never get final say over them.
+
+const AMS_POLICY_FILENAME = ".gittensory-ams.yml";
+
+/** Resolve the operator's local AMS policy file path: explicit env var > `GITTENSORY_MINER_CONFIG_DIR` >
+ *  `XDG_CONFIG_HOME`/`~/.config`, mirroring every other local-store path in this package. */
+export function resolveAmsPolicyConfigPath(env = process.env) {
+  return resolveLocalStoreDbPath(AMS_POLICY_FILENAME, "GITTENSORY_MINER_AMS_POLICY_PATH", env);
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    readFileSync: options.readFileSync ?? readFileSync,
+    existsSync: options.existsSync ?? existsSync,
+    env: options.env ?? process.env,
+  };
+}
+
+/** Read the operator's own local `.gittensory-ams.yml`, if one exists. Never throws: an unreadable file is
+ *  treated the same as an absent one, falling through to the next resolution layer. */
+function readLocalAmsPolicyContent(resolved) {
+  const path = resolveAmsPolicyConfigPath(resolved.env);
+  if (!resolved.existsSync(path)) return null;
+  try {
+    return resolved.readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the real, effective AMS execution policy for one attempt: the operator's own local
+ * `.gittensory-ams.yml` when present (source: "local"), else the engine's safe defaults (source: "default").
+ * Never throws -- an unreadable/malformed local file degrades through the tolerant parser to the safe
+ * defaults, same discipline as every other tolerant parser in this pipeline.
+ *
+ * `repoFullName` is accepted for API compatibility with callers that resolve policy per target repo, but the
+ * resolver intentionally does not fetch or trust target-repository AMS policy content.
+ *
+ * @param {string} repoFullName
+ * @param {{
+ *   readFileSync?: (path: string, encoding: "utf8") => string, existsSync?: (path: string) => boolean,
+ *   env?: Record<string, string | undefined>,
+ * }} [options]
+ * @returns {Promise<{ spec: import("@loopover/engine").AmsPolicySpec, source: "local"|"default", warnings: string[] }>}
+ */
+export async function resolveAmsPolicy(repoFullName, options = {}) {
+  void repoFullName;
+  const resolved = normalizeOptions(options);
+
+  const localContent = readLocalAmsPolicyContent(resolved);
+  if (localContent !== null) {
+    const parsed = parseAmsPolicySpecContent(localContent);
+    return { spec: parsed.spec, source: "local", warnings: parsed.warnings };
+  }
+
+  return { spec: DEFAULT_AMS_POLICY_SPEC, source: "default", warnings: [] };
+}