Context
AMS tracks per-repo run-state (idle/discovering/planning/preparing, keyed by owner/repo) in packages/gittensory-miner/lib/run-state.js. ORB already exposes an analogous surface as gittensory_get_automation_state. AMS has no MCP-exposed read path into this state today, so a caller cannot tell what an autonomously running miner is currently doing on a given repo without inspecting local state directly.
Dependencies
Requires the AMS MCP server scaffold to exist first (same scaffold C06/C07 depend on). Otherwise independent — not mentioned in Wave 5 or Wave 3.5, and unrelated to #4840 (cron/systemd/alerting guidance docs).
Requirements
- Add a new MCP tool,
gittensory_miner_get_run_state, registered on the AMS MCP server.
- The tool must read via
packages/gittensory-miner/lib/run-state.js's existing state accessor(s) — reuse the existing read function rather than re-implementing state lookup.
- Accept an
owner/repo key as an input parameter; if run-state.js already supports listing all repos' states, also support an unfiltered "list all" mode.
- Return the state string (
idle/discovering/planning/preparing) plus any other already-existing per-repo metadata run-state.js exposes for that key — do not invent new state fields.
- This PR must be strictly read-only: it must NOT add a
state set or any other mutation tool. A remote mutation capability is explicitly out of scope for this issue and needs its own separate safety discussion/issue.
- Handle the "unknown repo" / "no state yet" case explicitly (e.g. return an explicit idle/unknown result rather than throwing), with a test covering that path.
- The tool's MCP-facing description must state that this is the read-only analog of ORB's
gittensory_get_automation_state.
Deliverables / Acceptance Criteria
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new/changed logic's success and failure paths (known state, unknown repo, list-all mode if applicable, malformed input), (2) an invariant test asserting the read-only run-state tool never triggers a state transition as a side effect of being queried, and (3) no regression test is required since this is new functionality, not a bug fix.
Codecov visibility note: packages/gittensory-miner/**, apps/gittensory-miner-ui/**, and apps/gittensory-miner-extension/** currently sit entirely outside vitest's coverage.include glob, so codecov/patch cannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change under packages/gittensory-engine/src/** or the repo's own src/** remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.
Expected Outcome
An operator or MCP-connected agent can check what an AMS miner is currently doing on a given repo (idle, discovering, planning, preparing) over MCP, matching the visibility ORB already provides for its own automation state.
Links & Resources
Context
AMS tracks per-repo run-state (
idle/discovering/planning/preparing, keyed byowner/repo) inpackages/gittensory-miner/lib/run-state.js. ORB already exposes an analogous surface asgittensory_get_automation_state. AMS has no MCP-exposed read path into this state today, so a caller cannot tell what an autonomously running miner is currently doing on a given repo without inspecting local state directly.Dependencies
Requires the AMS MCP server scaffold to exist first (same scaffold C06/C07 depend on). Otherwise independent — not mentioned in Wave 5 or Wave 3.5, and unrelated to #4840 (cron/systemd/alerting guidance docs).
Requirements
gittensory_miner_get_run_state, registered on the AMS MCP server.packages/gittensory-miner/lib/run-state.js's existing state accessor(s) — reuse the existing read function rather than re-implementing state lookup.owner/repokey as an input parameter; ifrun-state.jsalready supports listing all repos' states, also support an unfiltered "list all" mode.idle/discovering/planning/preparing) plus any other already-existing per-repo metadatarun-state.jsexposes for that key — do not invent new state fields.state setor any other mutation tool. A remote mutation capability is explicitly out of scope for this issue and needs its own separate safety discussion/issue.gittensory_get_automation_state.Deliverables / Acceptance Criteria
gittensory_miner_get_run_statetool implemented and registered on the AMS MCP serverrun-state.js's existing accessor (no duplicated state logic)run-state.jssupports itgittensory_get_automation_stateTest Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Add: (1) unit tests covering the new/changed logic's success and failure paths (known state, unknown repo, list-all mode if applicable, malformed input), (2) an invariant test asserting the read-only run-state tool never triggers a state transition as a side effect of being queried, and (3) no regression test is required since this is new functionality, not a bug fix.
Codecov visibility note:
packages/gittensory-miner/**,apps/gittensory-miner-ui/**, andapps/gittensory-miner-extension/**currently sit entirely outside vitest'scoverage.includeglob, socodecov/patchcannot measure changes there yet — closing that gap is exactly what #4864 and #4865 (in this same milestone) do. Any part of this change underpackages/gittensory-engine/src/**or the repo's ownsrc/**remains fully Codecov-instrumented as usual. Either way, this does not lower the bar: treat the 100%-including-invariants-and-regression target above as the enforced house standard regardless of what Codecov can currently see, and it becomes gate-enforced for real once #4864/#4865 ship.Expected Outcome
An operator or MCP-connected agent can check what an AMS miner is currently doing on a given repo (idle, discovering, planning, preparing) over MCP, matching the visibility ORB already provides for its own automation state.
Links & Resources
packages/gittensory-miner/lib/run-state.jsgittensory_get_automation_statetool (shape reference)