Skip to content

feat(cli): managers busy, /api/busy with trigger runs, and a SIGTERM that finishes or records (F2) - #21

Merged
edspencer merged 4 commits into
mainfrom
cli-contract-busy
Nov 5, 2026
Merged

edspencer merged 4 commits into
mainfrom
cli-contract-busy

Conversation

@edspencer

Copy link
Copy Markdown
Owner

Wave F2 of the CLI-contract rollout (SPEC 0.2 §4, §8). Paddock's C1 (paddock#984) ported by the same three-way merge as #20, plus two things that are Managers' own.

From Paddock (C1)

  • GET /api/busy → { busy, version, counts }. No auth (added to HEALTH_PATHS), counts only, in-memory, synchronous. job comes from scheduler.getTotalRunningJobCount(), not fleetStatus() (which re-reads the fleet state file).
  • managers busy [--json] → 0 / 75 / 3, and 1 for a foreign answer. Copied from reference/busy-client.ts, with the keeper-chat hint.
  • service stop / restart refuse with 75 unless --force (Overriding: …). --force anywhere else is exit 2.
  • <data-dir>/runtime.json, 0600, { pid, port, url, version, startedAt }, removed on a clean exit.
  • cli-contract.json: busy and busy-json turned on (9 of 9). service-real.mjs gains the busy/refusal steps, with C1's rig fixes (the stand-in /api/busy is a child process; spawnSync so a successful command's stderr is seen; runtime.json is the one file uninstall may remove).

Managers' own

  • counts.run: trigger runs in flight (ManagersState.liveRuns, in memory). A run is in flight from the moment its running record is written until its completion hook has finished and committed it. That window is wider than the chat turn at both ends (the briefing is built before the turn; the record, a consolidation's #reflection and the commit after it), and a restart inside it leaves a run "interrupted by restart". ROADMAP's "as Paddock, plus a trigger run with status: running".
  • A SIGTERM that finishes or records, instead of closing at once (shutdown-drain.ts). If turns or runs are in flight, the stop waits up to 8 s for them to end by themselves. Whatever is left is recorded: each run still in flight is finished failed, error: interrupted by shutdown, through its own completion hook (so expect is evaluated, a consolidation still writes its #reflection, and the record is committed). That hook is now once-only, so the dying turn's own completion can't overwrite it. An idle instance stops at once. The whole stop stays bounded at 15 s, inside launchd's 20 s. The changeset and README say Docker wants stop_grace_period ≥ 20 s, since docker stop defaults to 10 s.

Minor changeset, naming exit 75 on stop/restart and --force → 2.

Testing

  • Server tests 3101 passed, 0 failed; typecheck and check:nul clean. New: shutdown-drain.test.ts (idle doesn't sleep; waits until work ends; bounded by a poll count; a throwing source; bounded recording; the log lines), the run count in cli-contract.test.ts, and an integration test in busy-endpoint.test.ts: a [[HANG]] trigger run shows run: 1, the shutdown interrupt finishes its record as interrupted by shutdown, and cancelling the turn afterwards does not rewrite it.
  • Real-use QA: the packed tarball installed into a throwaway prefix and HOME, run as managers serve under pm, MANAGERS_DRIVE_MODE=batch, the repo's fake claude first on PATH, no Claude/API tokens and no PADDOCK_*/HOST/PORT/NODE_ENV (checked in /proc/<pid>/environ), and MANAGERS_AUTH_MODE=trusted-header:
    • serve's first line Managers 0.3.1: http://127.0.0.1:5207; runtime.json correct; / → 401 while /api/busy → 200 (the auth exemption, proven).
    • idle: busy → 0. A [[HANG]] trigger via Run now: /api/busy {"chat":1,"run":1}, busy → 75 with the terminal hint; --json puts the document on stdout and only prose on stderr.
    • SIGTERM with the run hung: exited in 8.06 s, runtime.json gone, the log line SIGTERM: shutting down with 1 chat turn and 1 trigger run still in flight — cut short. 1 of 1 run record marked failed (interrupted by shutdown)., and the run record status: failed, error: interrupted by shutdown, with its sessionId.
    • SIGTERM with a [[SLOWTOOL]] run that finishes inside the window: exited in 3.0 s, waited for 1 chat turn and 1 trigger run to finish, and they did., run succeeded.
    • Idle SIGTERM: 0.1 s, nothing in flight.
    • service stop's 75 against an installed unit can't run on this box (no systemd); service-real.mjs covers it on the real runners.

No UI change.

🤖 Generated with Claude Code

HomeLab Agent and others added 4 commits November 5, 2026 03:19
Ported from Paddock, whose CLI this is, by three-way merging Paddock's own
changes onto Managers: B1 (paddock#981, #983), the launchd bootout/bootstrap
race fix (paddock#984) and the systemd restart-an-active-unit fix (paddock#986).

- /api/health answers { ok, version } (version.ts, shared with the OpenAPI
  document and the management MCP handshake).
- `serve`, with `start` a permanent alias; the server logs to stderr so the
  first stdout line is `Managers <version>: <url>`.
- Exit codes: usage errors 2 with the usage after; `service status` 0/3/4;
  logs/start/stop/restart 4 with no unit; an install that never answers 1.
- `service status --json`, `service logs [-f] [-n]`; Linux logs go to
  <data>/logs/service.log, rotated by copy-and-truncate.
- Units: realpath'd Node, a rebuilt PATH, quoted ExecStart, a linger check.
- launchd: poll until a bootout has finished, retry bootstrap on 5/37.
- systemd: install restarts a unit that was already active.
- Real-service CI (scripts/service-real.mjs) and the conformance runner
  (@edspencer/cli-conformance ^0.2.0): 7 passed, 2 skipped (busy, F2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…a SIGTERM that finishes or records (F2)

Ported from Paddock's C1 (paddock#984) by three-way merge, plus Managers' own:

- /api/busy gains `run`: trigger runs in flight (ManagersState.liveRuns), from
  the running record being written until it is finished and committed.
- SIGTERM waits up to 8s for in-flight turns and runs to end by themselves,
  then finishes each run still in flight as failed, "interrupted by shutdown",
  through its own (now once-only) completion hook. Bounded at 15s overall.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	.github/workflows/ci.yml
#	README.md
#	cli-contract.json
#	packages/server/src/cli/args.ts
#	packages/server/src/cli/managers.ts
#	packages/server/src/cli/service/index.ts
#	packages/server/src/routes/meta.ts
#	packages/server/src/start.ts
#	packages/server/test/unit/cli-contract.test.ts
#	scripts/service-real.mjs
@edspencer
edspencer merged commit 6be9d28 into main Nov 5, 2026
7 checks passed
@edspencer
edspencer deleted the cli-contract-busy branch November 5, 2026 08:34
@github-actions github-actions Bot mentioned this pull request Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant