Skip to content

Add the management-plane skeleton under plane/ - #3134

Merged
Birfy merged 1 commit into
mainfrom
dev/3113-plane-skeleton
Nov 17, 2026
Merged

Birfy merged 1 commit into
mainfrom
dev/3113-plane-skeleton

Conversation

@Birfy

@Birfy Birfy commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes #3113

Owner: Chief
Reviewer: Reviewer
Written-by: Chief
Base: 8f01c23

What changed

The first cut of the management plane, as the Triage slice on #3113 (2026-11-17T01:16Z, 19 files: 14 new / 5 modified) asked for: one new top-level package plane/ (@flybot/plane, private, type: module, zero runtime dependencies, not shipped in the image). 14 new files, 5 modified, nothing deleted.

  • plane/src/store.mjs — one plane.json under the data directory ({ version: 1, accounts, workspaces, instances }), written through a temp file and a rename, file 0600 and directory 0700; (workspaceId, name) is unique and a repeat raises DuplicateInstanceError.
  • plane/src/credentials.mjs — the one place the two credentials exist: op_<32hex> operator session tokens and ctl_<32hex> instance control tokens, only the sha256 stored, compared with timingSafeEqual, and neither verifier accepts the other kind.
  • plane/src/lifecycle.mjs — the LifecycleBackend contract (create/start/stop/upgrade/recycle), a MemoryBackend for tests and a first ComposeBackend.materialize() that writes instances/<id>/compose.yaml (project flybot-<id>, host network, loopback port) plus a 0600 control.env and never spawns docker; upgrade/recycle throw NotImplementedError instead of pretending.
  • plane/src/server.mjs — handle({method,path,headers,body}) as a pure router (POST/GET /api/instances, GET /api/instances/:id, start, stop), each instance route verifying the operator token and then instance.ownerId === accountId (403 otherwise), with serve() as the only node:http seam.
  • plane/bin/plane.mjs — token --data-dir (prints once) and serve --data-dir --port.
  • plane/README.md — the three working defaults (one instance per owner, one JSON file with a version, compose as the first backend) marked as replaceable, not owner decisions.
  • plane/test/*.test.js — the 20 cases of the slice's red-first list: ownership 403/401, duplicate 409, persistence across a reopen, the start/stop/start loop, 404, NotImplementedError, credential separation in both directions, no plaintext token in plane.json, per-instance control tokens, and compose output (project name, host network, no control token inside compose.yaml, idempotent, zero runner calls).
  • Root package.json verify gains && npm --prefix plane test; .github/actions/flybot-tests/action.yml gains one Plane tests step (added, nothing removed); docs/testing-layers.json gains the plane L1 suite row and docs/testing-layers.md is regenerated by node .github/scripts/testing-layers.mjs --write; docs/subsystems/plane.md is the new subsystem page with owned_paths: [plane/] and docs/subsystems/README.md gains its row.

No changelog fragment: the package is not in the image (Dockerfile and compose.yaml untouched, check-pack.mjs unchanged) and no user-visible surface moves. No gate file is touched, so no Policy-sign is owed. Dockerfile, compose.yaml, docker/**, core/ and patches/ are untouched.

Verification at the tip

Tip SHA: 59f60b970a00de732367c09161ae0135398f267e

Ran at the tip:

  • npm --prefix plane test → # tests 20 / # pass 20 / # fail 0 (the slice's acceptance command; its floor was >= 16).
  • node .github/scripts/testing-layers.mjs --check → every test file and every workflow is classified (898 test files, 16 workflows).
  • node --test ".github/scripts/*.test.mjs" → # tests 675 / # pass 673 / # fail 0 / # skipped 2.
  • node .github/scripts/changelog.mjs check → 0 fragment(s) ... well formed.

Not run, and why:

  • node core/scripts/check-arch-docs.mjs → arch-docs: FAIL — cannot diff against origin/main: this box has no git and no network route to github.com, so the check needs the CI checkout. The slice's arch-doc reasoning is why docs/subsystems/plane.md is in this diff.
  • npm run verify end to end (core suite, plugin lint, build-client --check, ds-bot-patches) — same missing-git limit; CI's test job runs it.
  • The secondary Docker check (serve + a 401 probe) is the slice's second-cut check and is not this cut's acceptance.

No red log is attached: this cut's implementation run wrote tests and source in one pass, so the only red-first artefact is the pre-slice state the Triage comment recorded (npm --prefix plane test → ENOENT, exit 254, because plane/package.json did not exist). Every test imports ../index.js, so the un-implemented state is a module-not-found red rather than a silent pass.

Provenance

The code was produced by the issue fast lane (wf-1cdf6ec5, run run-ff21dba4, task i3113-impl) and finished on disk; that run died at its Triage step on the provider 400 tracked in #3132 (max_completion_tokens above 12288), so it never pushed. This pull request publishes that commit as-is, plus the checks above run here.

Claim note: #3113 carries a Claim from FlyBot Lead at 2026-11-17T01:17Z on branch dev/3113-3110-flybot, which has no pushed commit and no pull request as of this write (branch list read at 2026-11-17T02:05Z). If that branch lands a second implementation, this one supersedes or is superseded by it — one of the two should be closed, not both merged.

{
  "pr": 3134,
  "claim": "Chief",
  "issue": 3113,
  "summary": "A new top-level package @flybot/plane holds the management-plane skeleton: account/workspace/instance metadata in one 0600 JSON file written by temp-file rename, operator tokens and instance control tokens stored as sha256 only and never interchangeable, create/start/stop/status over an abstract LifecycleBackend with an in-memory backend and a compose materializer that writes the project without spawning docker; upgrade and recycle stay NotImplemented. Root verify and the flybot-tests action gain the plane suite. No image, Dockerfile, compose.yaml, core/ or gate file changes.",
  "files": ["plane/package.json","plane/index.js","plane/src/store.mjs","plane/src/credentials.mjs","plane/src/lifecycle.mjs","plane/src/server.mjs","plane/bin/plane.mjs","plane/README.md","package.json",".github/actions/flybot-tests/action.yml","docs/testing-layers.json","docs/subsystems/plane.md"],
  "checks": { "ran": "npm --prefix plane test (20/20), node .github/scripts/testing-layers.mjs --check, node --test \".github/scripts/*.test.mjs\" (673 pass), node .github/scripts/changelog.mjs check", "result": "green", "at": "59f60b970a00de732367c09161ae0135398f267e" },
  "next": "none — ready for review"
}

A new top-level package @flybot/plane with no runtime dependencies and not
shipped in the image: accounts/workspaces/instance metadata in one JSON file
(0600 / temp-file rename), two credentials that never interchange (operator
op_ tokens vs instance ctl_ control tokens, sha256 only), create/start/stop
and status through an abstract LifecycleBackend with a MemoryBackend and a
ComposeBackend that materializes a project without spawning docker.
upgrade/recycle stay explicitly NotImplemented.

Fixes #3113
@Birfy Birfy added the agent-pr Pull request opened by an agent label Nov 17, 2026
@Birfy

Birfy commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator Author

Verdict: PASS at 59f60b9
Written-by: Reviewer
Attestation: 59f60b9 role=Reviewer

Ran at this tip:

$ npm --prefix plane test
# tests 20  # pass 20  # fail 0
$ mv plane/src /tmp/plane-src.bak && npm --prefix plane test
# tests 5  # pass 0  # fail 5
$ mv /tmp/plane-src.bak plane/src && npm --prefix plane test
# tests 20  # pass 20  # fail 0

Red-first: on a scratch copy of this tip tree, moving the new plane/src/ aside turns all five suites red (5/5 fail, ERR_MODULE_NOT_FOUND) — no base blob exists for these files, so "the un-implemented tree" is the red state; restoring it is green again.

What I checked, at 59f60b9 (tarball of the tip, base 8f01c23):

  • Scope: compare base..tip = 1 commit, 19 files, +1213 −1 (14 added / 5 modified, 0 deleted). It is the [#3110] 管理面控制平面与 FlyBot 容器生命周期最小闭环 #3113 first slice: plane/ package, root verify line, one Plane tests step in .github/actions/flybot-tests/action.yml, the testing-layers rows and the subsystem page. Nothing beyond it.
  • No gate file in the diff: policy/, .github/scripts/**, .github/workflows/** are untouched; Dockerfile, compose.yaml, docker/**, core/, patches/ are untouched (so no image change and no policy signature owed).
  • Tests not loosened: all five plane/test/*.test.js files are new; no existing assertion changed. The two edited config files only add the plane suite — verify gains && npm --prefix plane test, the action gains one step, nothing removed.
  • Checks at the tip: 17 check-runs, every one success except enqueue-guard (failure, at 02:05Z, before the body fixes); tests-ok, merge-gate, policy-sign, package, the four plugins, Node 24, judge, risk tier, reviewed tip all green.
  • Behaviour matches the slice: 0600/0700 store written by temp-file rename, sha256-only tokens compared with timingSafeEqual and not interchangeable, ownership 403/401, duplicate 409, persistence across reopen, start/stop/start, 404, NotImplementedError for upgrade/recycle, compose materialization with the control token kept out of compose.yaml and no docker spawn.

This is the first and only conclusion on this tip — not a replacement. #3113's plane/ slice is a real, tested first cut and I see no defect to send back.

@github-actions github-actions Bot added the pass label Nov 17, 2026
@Birfy
Birfy added this pull request to the merge queue Nov 17, 2026
Merged via the queue into main with commit 6f32e8e Nov 17, 2026
17 of 18 checks passed
@Birfy
Birfy deleted the dev/3113-plane-skeleton branch November 17, 2026 02:20
@github-actions github-actions Bot removed the agent-pr Pull request opened by an agent label Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[#3110] 管理面控制平面与 FlyBot 容器生命周期最小闭环

1 participant