Moves 5 related docs into docs/devops/gitea-runner/ to keep this
multi-doc workstream from colliding with future roadmaps and
delegation prompts in docs/devops/.
Renames:
HOSTINGER_GITEA_RUNNER_ROADMAP.md -> ROADMAP.md
HOSTINGER_GITEA_ACT_RUNNER_SETUP.md -> ACT_RUNNER_SETUP.md
GITEA_PACKAGES_PUBLISH_WORKFLOW.md -> PUBLISH_WORKFLOW.md
HOSTINGER_GITHUB_RUNNER_SETUP.md -> _PLAN_B_GITHUB_RUNNER.md
CODEX_DELEGATION_PROMPT.md -> (same name, moved)
All internal cross-links updated via sed sweep. Verified no stale
references remain.
Adds README.md in the new folder as the index + pattern doc for
future multi-doc workstreams (one-liner handoff, file map,
architecture summary).
Updated one-liner handoff path:
Read docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md ...
Captures the exact bootstrap prompt to paste to Codex on the
Hostinger VM, plus a one-liner that just points Codex at the prompt
file (after Codex has the repo).
Also documents how to monitor Codex's progress from Cascade side
(grep roadmap-update commits) and how to recover if it gets stuck
(the checkbox state in the roadmap IS the resume pointer).
Adds HOSTINGER_GITEA_RUNNER_ROADMAP.md — a single execution tracker
that Codex on the Hostinger VM works through phase-by-phase, ticking
checkboxes and recording commit hashes as it goes.
Structure:
- 6 phases (P0 Pre-flight → P5 First real release) + P6 review handoff
- Each task: [ ] checkbox + Commit hash field + Status note
- Detail steps live in the two companion docs (act_runner setup +
publish workflow); the roadmap is the orchestrator
- Final report section Codex fills in when P0-P5 are complete
- Human review checklist (R1-R9) for verification after handoff
- Operating notes: commit message format, when to ask, never-do list
- Change log table Codex auto-appends to
Critical invariant repeated at P3.6 and P5.4: cross-Gitea SHA1
comparison must match. If it doesn't, Codex stops — it's the
load-bearing architectural guarantee that the dual-Gitea, no-sync-
script model rests on.
Also adds roadmap-pointer banners to the two companion docs
(HOSTINGER_GITEA_ACT_RUNNER_SETUP.md, GITEA_PACKAGES_PUBLISH_WORKFLOW.md)
so anyone landing there knows the master tracker exists.
Adds two new docs and a banner on the existing GitHub-runner doc.
WHY: the user already has Gitea Actions configured across all 20+
repos (.gitea/workflows/ci.yml). Building a parallel GitHub Actions
self-hosted runner pipeline is unnecessary work that also drags in
GitHub Organization migration pressure (with Vercel/Netlify pricing
side-effects on free tiers).
The canonical architecture instead:
- Each Gitea instance (corp Mac local + Hostinger VM) runs its own
act_runner.
- A single publish-packages.yml workflow lives in every package-
publishing repo.
- When the same git tag is pushed to both Giteas, each one builds
inside the same pinned Docker image (node:20-bookworm@sha256:...)
with the same lockfile, producing BYTE-IDENTICAL tarballs.
- No sync script is needed; the shared git tag IS the sync mechanism.
- Lockfile integrity hashes match across both registries, so corp Mac
and personal Mac + Hostinger prod all see the same packages.
New: HOSTINGER_GITEA_ACT_RUNNER_SETUP.md
- Codex-actionable prompt to install act_runner on the Hostinger VM
- Pre-flight checks (arch detection, Docker daemon, Gitea reachable)
- Idempotent user creation, SHA-verified binary download
- Docker mode runner config with labels mapping ubuntu-latest to
pinned Node image
- Smoke test + full E2E with throwaway @bytelyst/_runner-e2e-test
package
- The architectural invariant check: cross-Gitea SHA comparison —
same tag pushed to both must produce identical tarballs
- Monitoring (Gitea UI, API, systemd journal)
- Hardening, rollback, deliverables, guardrails, questions
New: GITEA_PACKAGES_PUBLISH_WORKFLOW.md
- The actual publish-packages.yml triggered by v* tags
- Docker image pinned by digest for build determinism
- pnpm@9.12.0 pinned, --frozen-lockfile, host-network container
- Token mounted as read-only secret file (not env var)
- Concurrency cancel-in-progress: false (never cancel a publish)
- Pack tarballs + SHA512 manifest as Gitea Release assets for audit
trail
- Two propagation strategies: reusable workflow (preferred) vs
sync-publish-workflow.sh script
- Operator runbook for cutting a release
- Failure-mode table + remediation
- Deliverables checklist
Updated: HOSTINGER_GITHUB_RUNNER_SETUP.md
- Added 'PLAN B' banner at the top
- Cross-links to the Gitea Actions docs
- Kept the doc intact as a valid alternative if priorities ever
shift to making GitHub Actions the publish driver
Adds the missing pieces revealed during review:
§1 Multi-repo registration decision — choose repo-level vs org-level
up-front. Default doc remains repo-level, but explicitly calls out
org-level as the scaling path for 20+ repos.
§2 Pre-flight check additions:
- Arch detection (x86_64 / aarch64) before downloading runner tarball
- github.com + objects.githubusercontent.com reachability check
- gh CLI auth status check (must be saravanakumardb1)
§4 Installation hardening:
- Step 1 is now idempotent (getent guards on useradd/usermod)
- Step 3 queries latest runner version via gh api (no more stale pin)
- Step 3 includes SHA256 verification of the downloaded tarball
against the release-notes manifest, with explicit STOP-if-mismatch
- Step 3 has REGISTRATION_URL var with commented Option A/B for
repo-level vs org-level scope
§5 Smoke test — added explicit git checkout/add/commit/push commands
for creating the runner/smoke branch (was implicit before).
§8 (renamed) — comprehensive org migration guide:
- Side-by-side table: personal account today vs under-an-org
- Bash loop to transfer all 18 repos via gh api
- git remote set-url commands for each local clone
- Post-migration org-level registration token fetch
- Workflow propagation strategies (reusable workflow vs sync script)
§9 (new) — Monitoring + observability:
- GitHub Actions tab per-repo + per-org workflow views
- Runner pool health (Settings → Actions → Runners) at repo + org level
- gh CLI commands for scripted monitoring (run watch, list, view, runners)
- Host-side journalctl + _diag/ inspection commands
§14 Questions — updated to ask about scope (repo vs org) first.
Section numbering shifted by +1 from §9 onward to make room for the
new Monitoring section.
Delegation prompt for the Codex agent running on the Hostinger VM to:
- Install a dedicated GitHub Actions self-hosted runner under gha-runner user
- Register it with saravanakumardb1/learning_ai_common_plat
- Run as a systemd service with auto-start
- Install Node 20 / pnpm 9 / gh CLI / Docker prerequisites
- Wire up local Gitea publish token
Includes full end-to-end validation that proves the actual publish
pipeline works:
- Creates a throwaway @bytelyst/_runner-e2e-test package
- Publishes to local Gitea
- Uploads tarball as GitHub Release asset
- Verifies Gitea registry returns the version
- Verifies pnpm install + require works from a clean directory
- Verifies the byte-identical-tarball invariant (sha256 match between
Gitea-served tarball and GitHub Release asset) — this is the key
guarantee that lockfiles will remain portable across corp Mac's
local Gitea after sync
- Documents cleanup of test artifacts
Plus pre-flight checks, hardening (systemd limits, log rotation,
workflow approval), scaling notes, deliverables checklist, guardrails,
rollback, and follow-up prompt list (publish-packages.yml,
bytelyst-sync script, SKILL doc).
- packages/llm: add FallbackLLMProvider (providers/fallback.ts) that
tries each provider in order, skipping unconfigured or erroring ones;
wire 'fallback' as a first-class LLMProviderType in factory + types
- packages/llm: improve auto-detection in factory — PERPLEXITY_API_KEY
and GEMINI_API_KEY trigger auto-selection when no explicit provider set
- scripts/release.sh: new pipeline — rebase from origin/main, build,
apply changesets, publish outdated packages to Gitea registry, push
- scripts/run-registry-tests.sh: fix Gitea URL health-check to use a
real package endpoint with auth header instead of bare registry root
- docs: mark Vercel track-B prompts B1–B3 as complete
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Reframed from 'review and fix' to 'execute, monitor, fix failures, validate'
- 4 clear tasks: run script, handle failures, validate deployment, report results
- Moved bug history and development context to background reference
- Added copy-pastable validation commands for all 31 services
- Simplified constraints: don't modify unless actual runtime failure
