feat(miner): add a hosted-container entry point for AMS cron-wake cycles

[JSONbored]

Summary

Part of #7182 (miner-side half — control-plane's cron-triggered wake/poll-exit-code logic is a separate follow-up PR, since it calls into this entry point via a Cloudflare Container entrypoint override).

• Adds packages/loopover-miner/bin/loopover-miner-hosted.ts (+ lib/hosted-entry.ts, the real logic) as an additional entry point alongside the existing loopover-miner CLI — self-host is completely unaffected.
• Starts Add a minimal HTTP health endpoint to hosted AMS containers #7177's already-built-but-previously-unwired AMS health server (ams-health-server.ts) with a state-dir readiness probe, for the brief window a cron-woken container is up.
• Dispatches to exactly one existing one-shot unattended command — discover, manage-poll, or attempt (docs/unattended-scheduling.md's own documented pattern) — reused in-process via the same exported functions bin/loopover-miner.ts already calls, unmodified.
• Stops the health server and returns that command's own 0=success/2=failure exit code unchanged — no new exit-code vocabulary introduced.
• Deliberately excludes loop (the continuous self-scheduling mode, semantically incompatible with "wake, run one cycle, sleep") and any strictly-local command (status/doctor/etc).

Scope

• The PR title follows type(scope): short summary Conventional Commit format.
• Additive only — does not modify bin/loopover-miner.ts, the CLI dispatch table, or any existing command's behavior; self-host mode is unaffected.
• Owner-authored infra PR (hosted-container entry point, part of the maintainer-only Cloudflare Cron Trigger wake scheduling for hosted AMS containers #7182).
• Does not implement the control-plane side (cron trigger, per-tenant schedule storage, wake orchestration, exit-code ingestion into health aggregation) — that's the follow-up PR.

Validation

• git diff --check
• npm run typecheck (root)
• npm run build:miner
• Full packages/loopover-miner test suite: 176/176 files, 2757/2757 tests passing (including the new test/unit/miner-hosted-entry.test.ts, 100% line/branch/function coverage).
• npm run test:miner-pack — new bin/lib files correctly allowlisted, no forbidden content.
• npm run test:miner-deployment-docs-audit — passes unchanged.
• New behavior has unit tests for every branch: no cycle name given, an unknown cycle name, each of the three valid cycle dispatches with argument forwarding, propagating the underlying command's real exit code, health-server port/probe wiring (including the default port and a custom one), the state-dir probe passing/failing, the health server closing (and the error still propagating) when the cycle command throws, and a health-server startup failure itself propagating cleanly.

Safety

• No secrets, tokens, or credentials anywhere.
• No visible UI changes.

Notes

Landed first (of the two-PR set) since control-plane's cron/wake logic depends on this entry point existing in the AMS image.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-22 18:52:56 UTC}

6 files · 1 AI reviewer · 2 blockers · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
This adds a new hosted-container entry point (bin/loopover-miner-hosted.ts + lib/hosted-entry.ts) that reuses existing runDiscover/runManagePoll/runAttempt functions unmodified, wrapped with an AMS health server lifecycle, plus package.json/bin wiring and a package-contents allowlist update. The logic is correct: it starts the health server, dispatches to exactly one known cycle command, always closes the server in a finally block (verified in tests covering both success and throw paths), and propagates exit codes unchanged. This is additive-only, does not touch bin/loopover-miner.ts or self-host behavior, and is backed by a thorough new test suite covering the unknown-cycle-name path, dispatch/forwarding for all three commands, probe pass/fail, and server-close-on-error.

Nits — 5 non-blocking

• packages/loopover-miner/lib/hosted-entry.ts:69 — the health server default port 8080 is a bare literal; consider a named constant for clarity since it's part of the container's operational contract.
• packages/loopover-miner/lib/hosted-entry.ts:63 — console.error is used directly for the unknown-cycle-name failure path rather than any structured logger used elsewhere in the codebase; confirm this matches existing miner logging conventions.
• The PR description doesn't link an eligible open issue for this repo's contributor requirements (it references Cloudflare Cron Trigger wake scheduling for hosted AMS containers #7182 as a maintainer-authorized parent issue, which should be sufficient if that's confirmed as the tracking issue, but worth double-checking it's explicitly linked/labeled).
• packages/loopover-miner/lib/hosted-entry.ts: consider extracting the default port (8080) into a named constant (e.g. `DEFAULT_HOSTED_HEALTH_PORT`) for readability.
• test/unit/miner-hosted-entry.test.ts is thorough; no changes needed there.

Concerns raised — review before merging

• No linked issue detected: No closing reference or linked issue number was found in the PR metadata/body. — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue: This repo's maintainer focus manifest requires every PR to reference a tracked issue. — Link the relevant issue (for example Closes #123) before opening the PR.

📋 Copy for AI agents — paste into your coding agent

Fix the following blocker(s) from this PR review:

1. No linked issue detected: No closing reference or linked issue number was found in the PR metadata/body. — If this PR is intended to solve an issue, link it explicitly in the PR body.

2. Maintainer requires a linked issue: This repo's maintainer focus manifest requires every PR to reference a tracked issue. — Link the relevant issue (for example `Closes #123`) before opening the PR.

Decision drivers

• ❌ Code review — 2 blockers (1 reviewer)
• ❌ Gate result — Blocking (Repo-configured hard blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 16 registered-repo PR(s), 14 merged, 290 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 16 PR(s), 290 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, Ruby, Go, JavaScript, MDX, Shell, Solidity
• Official Gittensor activity: 16 PR(s), 290 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Then work through the remaining 2 steps in the Signals table above.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[codecov]

Codecov Report

❌ Patch coverage is 94.44444% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.06%. Comparing base (dbf54e3) to head (f2d6bee).
⚠️ Report is 8 commits behind head on main.

Files with missing lines	Patch %	Lines
...ckages/loopover-miner/bin/loopover-miner-hosted.ts	0.00%	1 Missing ⚠️

❌ Your patch status has failed because the patch coverage (94.44%) is below the target coverage (99.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8070      +/-   ##
==========================================
+ Coverage   91.82%   93.06%   +1.23%     
==========================================
  Files         734      653      -81     
  Lines       75036    54391   -20645     
  Branches    23050    19406    -3644     
==========================================
- Hits        68902    50617   -18285     
+ Misses       5034     2852    -2182     
+ Partials     1100      922     -178     

Flag	Coverage Δ
rees	?
shard-1	59.40% <0.00%> (-0.58%)	⬇️
shard-2	54.15% <0.00%> (+3.64%)	⬆️
shard-3	46.31% <94.44%> (-4.33%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/loopover-miner/lib/hosted-entry.ts	100.00% <100.00%> (ø)
...ckages/loopover-miner/bin/loopover-miner-hosted.ts	0.00% <0.00%> (ø)

... and 84 files with indirect coverage changes