alembic-test-real-routes

name	alembic-test-real-routes
description	Use when AlembicTest needs to run or monitor real-project Alembic tests, especially BiliDili/AlembicWorkspace cold-start, after-run, Dashboard, PCVM, runtime linkage, or test-mode verification; or when AlembicTest-IDE is explicitly assigned Codex Plugin / host MCP / environment probe evidence. Follow verified routes and collect evidence instead of inventing new paths.

AlembicTest Real Routes

Use this skill after reading AlembicTest/AGENTS.md and the current state-root test card / control test document. It contains command routes and evidence checklists; AGENTS.md remains the authority for boundaries and stop cards.

Internet research may help discover candidate practices or tool details, but do not treat it as proof that an AlembicTest route works. Promote a route only after local commands, API responses, logs, Dashboard evidence, reports, or probe output validate it.

First confirm the current职责窗口:

• AlembicTest-IDE may use only the Codex Plugin / host MCP / environment probe route.
• AlembicTest may use only the real BiliDili / AlembicWorkspace cold-start / rescan / AI / Dashboard routes.

If the requested route does not match the current window, stop and ask total control to reassign.

Route Selection

• AlembicTest-IDE: Codex Plugin, host MCP, local environment, installed / packaged runtime smoke, or IDE / direct-thread readback evidence. Do not run BiliDili / AlembicWorkspace AI cold-start / rescan from this window.
• BiliDili: open-source real test project. If the current user request, state-root test card, or automation dispatch assigns AlembicTest to run BiliDili cold-start / rescan / after-run, use the automatic test-mode route.
• AlembicWorkspace or protected targets: start Alembic, open Dashboard, start passive monitoring, then wait for the developer to click cold-start / rescan unless the test document explicitly authorizes automatic context sending.
• Dashboard/front-end checks: use Codex in-app browser first. If the Browser tool is unavailable and UI evidence is required, pause with the exact URL instead of pretending the page was observed.

Environment Readiness Route

Use this route when the task is only to make the Alembic test environment available and stable, or before any cold-start / after-run probe.

1. Start or restart with restart-alembic.mjs only if no suitable daemon is already running or the target/test mode is wrong.
2. Run the deterministic environment check:

node AlembicTest/scripts/verify-test-environment.mjs --project BiliDili --json
node AlembicTest/scripts/verify-test-environment.mjs --url <dashboardUrl> --json

3. Treat ok=true / verdict=ready as the environment baseline: daemon health is good, test mode is enabled when expected, URL/dataRoot are resolved, and compact jobs API responds.
4. If the verdict is codex-localhost-sandbox-blocked, do not call the daemon broken. Rerun the same script with escalated Codex permissions, or use direct curl snapshots:

curl -sS --max-time 10 <dashboardUrl>/api/v1/health
curl -sS --max-time 10 <dashboardUrl>/api/v1/modules/test-mode
curl -sS --max-time 10 '<dashboardUrl>/api/v1/jobs?kind=bootstrap&limit=1&compact=true'

5. If the environment is ready and the user did not ask AlembicTest to run the cold-start chain, stop there and report the ready URL/pid/test-mode state.

AlembicTest-IDE Codex MCP Reload Boundary

AlembicTest-IDE can verify Codex MCP behavior when assigned, but it does not own Plugin reload or current host MCP repair. AlembicTest must not use this route for real-project cold-start / rescan work.

• npm run dev:codex-plugin:reload belongs to AlembicPlugin. Its safe default refreshes the installed plugin projection and runs a fresh MCP probe; it does not live-reload the current Codex host MCP process already attached to the running Codex session.
• Use MCP probes only for evidence collection requested by the current test order:

node AlembicTest/scripts/probe-codex-prime.mjs --project <target>
node AlembicTest/scripts/probe-resident-vector-search.mjs --project <target>
node AlembicTest/scripts/probe-unified-resident-service.mjs --phase baseline
node AlembicTest/scripts/probe-unified-resident-service.mjs --phase resident

• If the current Codex host tool returns Transport closed, do not repair it by running Plugin reload with --stop-mcp from AlembicTest. First distinguish fresh MCP startup evidence from the current host session; current-session refresh requires AlembicPlugin projection work plus a Codex restart/refresh.
• --stop-mcp and watch --restart-mcp are forbidden in AlembicTest unless the active state-root test card explicitly asks to validate that destructive path and accepts that the current Codex session will lose Alembic MCP until Codex restarts.

BiliDili Test-Mode Cold-Start / After-Run Route

Verified non-destructive checks on 2026-05-30:

• restart-alembic.mjs --help exposes the needed restart flags.
• probe-cold-start-process-timeline.mjs --help exposes --max-files, --content-max-lines, --skip-guard, --url, --data-root, and --output.
• A test-mode BiliDili daemon responded healthy at /api/v1/health.
• /api/v1/modules/test-mode returned enabled=true with bootstrapDims=["architecture"] and rescanDims=["architecture"].

Default command shape:

ALEMBIC_TEST_MODE=1 \
ALEMBIC_TEST_BOOTSTRAP_DIMS=architecture \
ALEMBIC_TEST_RESCAN_DIMS=architecture \
node AlembicTest/scripts/restart-alembic.mjs \
  --project BiliDili \
  --json \
  --wait 20000 \
  --no-dev-link

If preclean already killed the old daemon but the restart script reports preclean failure, first confirm the old pid stopped, then rerun the same environment with --no-preclean. Do not change dimensions or disable test mode during the rerun.

After restart, verify before triggering a job:

node AlembicTest/scripts/verify-test-environment.mjs --url <dashboardUrl> --json
curl -sS --max-time 10 <dashboardUrl>/api/v1/health
curl -sS --max-time 10 <dashboardUrl>/api/v1/modules/test-mode
curl -sS --max-time 10 '<dashboardUrl>/api/v1/jobs?kind=bootstrap&limit=1&compact=true'

Open the new Dashboard URL in the Codex in-app browser. For visible testing, prefer the most specific page: jobs?job=<jobId> > jobs > candidates > recipes.

Trigger and collect evidence with the probe, not a bare bootstrap POST:

node AlembicTest/scripts/probe-cold-start-process-timeline.mjs \
  --project BiliDili \
  --url <dashboardUrl> \
  --data-root <dataRoot> \
  --max-files 4 \
  --content-max-lines 40 \
  --skip-guard \
  --timeout-ms 180000 \
  --poll-ms 2500 \
  --output AlembicTest/tmp/<task-id>-cold-start.json

Use a larger sample only when the current test document explicitly asks for it. If a full run starts by mistake, cancel it, record the cancellation evidence, and rerun the bounded route.

Protected Project Manual Route

1. Start Alembic in test mode when the plan allows it.
2. Verify health and test-mode state.
3. Open Dashboard in the Codex in-app browser.
4. Start direct curl snapshots for health, compact job list, job events, report/artifact APIs, and logs.
5. Tell the developer exactly which button to click.
6. After the click, record the job id, session id, Dashboard URL, API snapshots, report path, and log signals.

Never use BiliDili's open-source rule to justify sending protected project context automatically.

Fresh Runtime / Agent Dist Route

When the test involves Alembic runtime consuming @alembic/agent:

1. Record git -C ../Alembic rev-parse HEAD.
2. Record git -C ../AlembicAgent rev-parse HEAD.
3. Run npm --prefix ../AlembicAgent run build unless the active state-root test card names an equivalent dev-link/build command.
4. Resolve the runtime package path from the Alembic process context when possible.
5. Search relevant dist/ files for the exact field, node id, metadata, carry, or projection being tested.

If source evidence exists but fresh dist proof or runtime linkage is missing, report stale dist / runtime linkage risk instead of product failure.

Monitoring Route

• Use direct curl snapshots as the primary monitoring path.
• Quote URLs with ? to avoid shell globbing.
• Avoid sleep 30; curl ...; node read-file chains; one failed command can manufacture misleading follow-up errors.
• Avoid Node fetch or Node child-process curl as the primary localhost monitor inside Codex unless the command is running with appropriate permissions; ordinary sandbox runs may fail with EPERM even when direct curl or an escalated script succeeds.
• On a single API disconnect, immediately check health, pid/state, logs, and persisted job files. Continue only if daemon health or pid/log evidence shows the service is still alive.
• If a monitor wrapper fails, stop only that monitor after verifying its pid/command; do not kill the Alembic daemon or a developer-triggered job.

Restart Troubleshooting

• If restart-alembic.mjs preclean already killed the old daemon but reports failure because cleanup escalated to SIGKILL, first verify the old pid/state is gone. Then rerun the same target/test-mode/AI config with --no-preclean. Do not call this product failure unless the old process remains alive, runtime state is unwritable, or log cleanup damaged the test boundary.
• If test mode looks disabled, inspect the raw /api/v1/modules/test-mode response before concluding environment drift. Some endpoints wrap values under data.
• If verify-test-environment.mjs reports daemon-connection-refused, check daemon.json, pid, ps, and .asd/logs/ before restarting.
• If a full run or wrong-parameter job starts accidentally, cancel only that job with evidence, then rerun the bounded route. Do not let an out-of-bound job become the test conclusion.

Evidence Checklist

Every real-project report or backfill should include:

• target project and why it is allowed for this route;
• command route and key parameters;
• Dashboard URL and whether it was opened in Codex in-app browser;
• job id / session id when a job runs;
• health, test-mode, jobs/events/report/log evidence;
• provider/model and AI config source, with secret presence only;
• source commit, fresh dist proof, and runtime linkage when relevant;
• real project git status before/after when relevant;
• clear boundary: what passed, what failed, what cannot be concluded.