Skip to content

📖 docs(crux): document --runs-config and /v1/runs; refresh work-services design status - #17035

Merged
hivecommons-hive[bot] merged 3 commits into
v5from
scanner/fix-17027
Nov 7, 2026
Merged

hivecommons-hive[bot] merged 3 commits into
v5from
scanner/fix-17027

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

The S2+S7 commit (#17014) shipped the contained-run service without updating the operator, env-var and design docs. Operators could not discover --runs-config / CRUX_RUNS_CONFIG or the /v1/runs routes, and the deferral pointer in src/crux/api/runs.go led to a design doc with no text on it.

  • crux-serve.md: add the --runs-config flag row and the /v1/runs route family.
  • env-vars.md: add CRUX_RUNS_CONFIG; shift the one cited line range in move-hub-registered-cutover.md.
  • crux-work-services.md: update status for S2/S7, note InUse wiring remains an open follow-up, add a "Deferred runs routes" section.
  • Changelog fragment added.

Closes #17027
Closes #17028

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

…ces design status

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 7, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign kellyaa for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Nov 7, 2026
@github-actions

github-actions Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

@hivecommons-hive

hivecommons-hive Bot commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor Author

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

hive/awaiting-ci: CI pending — sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

Hive filed review findings that do not block this PR as backlog items:

Cap: 10 backlog item(s) per PR per day.

Review findings from reviewer-2 (folded here because this head already carries its hive review):

Checked the new docs against src/crux at cb8bbe5; every claim I could trace holds. Looks correct to me.

  • --runs-config / CRUX_RUNS_CONFIG: crux/cli/serve.go:46,164.
  • Routes POST /v1/runs, GET /v1/runs/{id}, POST /v1/runs/{id}/cancel: crux/serve/runs.go:26-28; they are always mounted, and POST without a backend answers 501 not_supported (runs.go:35,109).
  • "runs left in flight by an earlier process are marked unfinished at startup": crux/cli/serve.go:170-196, crux/runs/service.go:122.
  • "InUse … remains an open follow-up": the hook is declared at crux/checkout/checkout.go:108 and nothing under crux/runs references it.
  • The env-vars.md:305-320 → 306-321 citation shift in move-hub-registered-cutover.md matches the one row inserted at env-vars.md:133.

Review findings from reviewer (folded here because this head already carries its hive review):

Read the diff against the crux tree at c687ceb. The operator-facing claims all match the code, so this looks correct to me; one low-severity citation nit on a line the PR touched.

Verified

  • --runs-config / CRUX_RUNS_CONFIG, flag over env: src/crux/cli/serve.go:46,164,172-174.
  • Saved records always served, POST /v1/runs → 501 not_supported without a backend: src/crux/serve/runs.go:35,108-109, src/crux/runs/service.go:37-38.
  • In-flight records marked unfinished at startup via Reconcile(): src/crux/cli/serve.go:187-194.
  • Routes and "cancel after completion returns the result": src/crux/serve/runs.go:25-27, src/crux/runs/service.go:190-198 (already_finished: true).
  • Deferral pointer in src/crux/api/runs.go:12-13 now resolves to a real section (#deferred-runs-routes).
  • InUse still unwired: checkout.Config.InUse is never set — both constructors at src/crux/cli/checkout.go:93,110 omit it — so the design-doc note is accurate.

Low — src/docs/move-hub-registered-cutover.md:41
The citation was shifted 305-320 → 306-321 to account for the new CRUX_RUNS_CONFIG row, but at the head commit env-vars.md:306-321 is the GOOSE_MODEL … HIVE_CLAUDE_DANGEROUSLY_ALLOW_HOST_STATE block, not the HMAC derived-key text. The section it means is "Spoke-side derived keys" at roughly env-vars.md:461-475. The drift predates this PR (the old range was equally wrong), so this is not a regression — but since the line is being edited anyway, pointing it at the heading anchor (env-vars.md#spoke-side-derived-keys) would stop it rotting on every table edit. Suggestion, not a blocker.

Evidence bundle `#17035cb8bbe5` sha256:eb43d5206577c1b81de54bd0773e577a1719517d5e3ce671553da8fc9fa04b32 — download from the dashboard or `hivectl review evidence #17035`.

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 7, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

correctness — read at head c687ceb. The new doc text matches the code: POST /v1/runs without a backend → 501 CodeNotSupported (src/crux/serve/runs.go:34-35, :108-109), saved records still served and in-flight runs marked unfinished at startup (src/crux/cli/serve.go:166-196), cancel after completion returns the record with AlreadyFinished (src/crux/runs/service.go:190-198), restart/listing deferred (src/crux/api/runs.go:12-13). No in-scope issues.

Adjacent (out of scope, pre-existing): src/docs/move-hub-registered-cutover.md:41 shifts the citation to src/docs/env-vars.md:306-321, but that range (both before and after this PR) covers the OPENAI_*/HIVE_*_BACKOFF rows, not the HMAC-derived-key section. The derived-key rows (HIVE_HEARTBEAT_KEY…HIVE_TERMINAL_KEY) are at src/docs/env-vars.md:464-475 at this head. The +1 shift is mechanically right; the anchor was already wrong.

— hive: agent=adjudicator backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checked every behavioural claim in this docs change against v5 after #17014 merged; all hold:

  • --runs-config PATH with CRUX_RUNS_CONFIG fallback: src/crux/cli/serve.go:46, :164.
  • POST /v1/runs, GET /v1/runs/{id}, POST /v1/runs/{id}/cancel always mounted: src/crux/serve/runs.go:24-26.
  • 501 on POST without a backend while saved records are still served: src/crux/serve/runs.go:31-37 (runsReady, "only Create checks Configured separately").
  • In-flight runs reconciled to unfinished at serve start: src/crux/runs/service.go:122, src/crux/runstate/runstate.go:8.

The design-doc edit correctly notes InUse wiring is still open (#17014's file list has no runtime.go change). Looks correct to me.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Conclusion: the documented behaviour matches the code; looks correct to me. One stale pointer worth fixing while this file is being touched.

Verified against origin/v5 @ c649246:

  • --runs-config / CRUX_RUNS_CONFIG: src/crux/cli/serve.go:46,164. Flag takes precedence over the env var as env-vars.md says.
  • Routes POST /v1/runs, GET /v1/runs/{id}, POST /v1/runs/{id}/cancel: src/crux/api/runs.go:7-9; 501/CodeUnsupported without a backend: runs.go:22.
  • "runs left in flight by an earlier process are marked unfinished at startup": src/crux/runs/service.go:28-30,122 (ReconcileReason, called once at serve start).
  • "cancel after completion returns the result": service.go:189.

Low — the move-hub-registered-cutover.md:41 citation is stale before and after this PR. It is bumped from env-vars.md:305-320 to 306-321 to account for the one row inserted at line 133, but at v5 lines 305-320 are the OPENROUTER_API_KEY … HIVE_CONN_<NAME>_URL rows, not the derived-key material. The HMAC/derived-key content this sentence refers to is ### Spoke-side derived keys at env-vars.md:460-474 (461-475 after this PR). Since the line is already being edited, pointing it at the section anchor (env-vars.md#spoke-side-derived-keys) would stop it drifting again. Not a blocker for the crux docs this PR is about.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive
hivecommons-hive Bot merged commit 484f649 into v5 Nov 7, 2026
80 of 81 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the scanner/fix-17027 branch November 7, 2026 20:35
@github-actions

github-actions Bot commented Nov 7, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/S Denotes a PR that changes 10-29 lines, ignoring generated files. stage/050-review-pending Review swarm requested; awaiting a verdict for the current head

Projects

None yet

0 participants