Named lab actions, and pairing scopes so a lab page cannot run arbitrary code

[thinkinginmath]

Lets a course page run a lab's declared commands, and nothing else, on the learner's machine.

Why

Today a paired site can run any Python through /cell/run. A lab page only needs to start a few prepared commands, such as docker compose up and python demo.py …. With this PR, a site paired with the new actions scope can only do that. If the page were compromised, its token could run only commands the learner already approved.

Pairing scopes

• POST /pairing/request takes {"scope": "code" | "actions"}. The default is code, which is today's behaviour, so existing clients are unaffected.
• The terminal prompt now shows the access being granted, e.g. Access: actions - this site could run only the named actions of labs you approve one by one.
• actions tokens get 403 from /kernel/* and /cell/*.
• Pairings saved before this change, loopback origins and --no-pairing all count as code.

Named lab actions

• lab.toml in the lab repo (schema 1) declares [actions.<name>] entries. Each has a label, a description, a timeout, and steps given as argv lists, run without a shell. Unknown keys are errors.
• POST /labs/prepare {repo, commit}:
  • accepts https URLs only (GIT_ALLOW_PROTOCOL, so no ssh, file or ext::), without credentials, and a full 40-character SHA;
  • fetches exactly that commit (--depth 1, no submodules, never prompts for credentials) and reads lab.toml;
  • once per site, repo, commit and manifest, prompts in the terminal, listing every command;
  • creates the lab's venv, which comes first on PATH for its actions.
• Runs:
  • POST /labs/runs starts one, one at a time per lab.
  • GET /labs/runs/{id}?offset= returns status plus new output.
  • POST /labs/runs/{id}/stop sends SIGINT to the process group, then SIGKILL.
  • GET /labs/runs lists runs, so a reloaded page can find one still going.
  • A run is visible only to the site that started it. Timeouts are enforced, and shutdown stops and waits for running actions.

The docs cover all of this (protocol.md, integration.md, security.md, README). The security doc states the limit plainly: approving a lab pins which commands and which code run, down to the commit; it does not sandbox them.

Verified end to end (Linux)

This branch's runtime ran with pairing required, against SciMigo/restate-durable-agent-demo @ e7bdf44 (its lab-toml branch):

• paired as https://scimigo.com with scope actions; /cell/run returned 403;
• /labs/prepare showed the approval prompt with all nine actions' commands, and was approved once, in 14.5 s; the second prepare didn't prompt;
• setup ran docker compose up and pip install; 1.1 → model calls: 3 weather calls: 1, the same as the recorded run; teardown removed the container.

Tests

tests/test_labs.py has 35 tests:

• manifest rules; source rules; fetching a commit from a file:// repo (a protocol allowed only in tests) and reusing it;
• approval once, and a declined lab being unable to run;
• runs: success, a failing step ending the action, Stop, one at a time, timeout, and other sites not seeing a run;
• scope enforcement, and the scope carried through the pairing request.

167 passed; ruff, format and strict mypy are clean.

After this merges, the demo repo's lab-toml branch merges too, and then scimigo.com's Restate lab page gets its run panel.

🤖 Generated with Claude Code