box/docs/BOX-DEV-HTTPS.md

Box Dev + Comms over HTTPS (No SSH)

Box is the main surface. All operator work goes through Box (box.muse-dev.online). The web UI, box CLI, and agents share the same API endpoints. No UI-only powers.

Date: 2026-10-06 Status: implemented on bl (exec-constrained.py + box-ctl.py + box-relay.sh) Scope: git visibility, test runs, notify, work-order acks. Read-only lookups live in docs/BOX-API-READ-HTTPS.md.

1. Why

Agents developing the box must inspect the tree, run the suite, nudge peers, and acknowledge work orders without SSH. All of this now rides the existing agent HTTPS path (https://exec.muse-dev.online/exec, signature or bearer auth, named-op allowlist, audit log) — no new trust model.

2. New ops

Op	Args	Backend	Write?	Who
git.status	{}	box-ctl.py git-status	no	any valid signer
git.diff	{path?, stat?}	box-ctl.py git-diff [--stat] [--path p]	no	any valid signer
git.log	{limit?, path?} (1..50, default 10)	box-ctl.py git-log	no	any valid signer
tests.run	{test?, filter?} (tests.<module> or full suite; filter is unittest -k)	box-ctl.py tests-run [module] [--filter p]	yes (executes)	known identities only
notify.send	{agent, message≤1000, sidechat?, sender?}	box-ctl.py notify ...	yes (sends DM)	known identities only
dm.ack	{id, to, sender!, sidechat?, allow_main_chat?}	box-ctl.py ack ...	yes (sends DM)	known identities only

New box-ctl.py verbs: git-status, git-diff, git-log, tests-run, ack (all in USAGE, quality-validate, and — for the git reads — IDEMPOTENT_ACTIONS).

New box-relay.sh client commands:

box git status
box git diff [--stat] [--path <path>]     # path also accepted positionally
box git log [<limit=10>] [--path <path>]
box tests run [tests.<module>] [--filter <pattern>]  # full suite (~2-3 min) when omitted; filter is -k
box notify <agent> [--sidechat <n>] [--sender <a>] <message...>
box dm ack <id> --to <agent> --sender <agent> [--sidechat <name>]

Raw op call (signature auth, no token):

exec-sign.sh git.log '{"limit": 5, "path": "bin/dm.py"}'
exec-sign.sh tests.run '{"test": "tests.test_box_dev_https"}'
exec-sign.sh dm.ack '{"id": "bdf7beb6", "to": "pip", "sender": "opm"}'

3. Safety notes (same posture as existing ops)

• Fixed argv, validated values. Clients influence only whitelisted argument values. Git paths must be repo-relative without .. (plus symlink-escape check in box-ctl); test modules must match ^tests\.[a-z0-9_]+$ and exist; ack ids must be 6–64 hex; notify messages ≤1000 chars.
• Caps. git diff output capped at 64KB, status at 200 entries, test output at 32KB tail; every capped response carries truncated: true.
• Sidechat-first. notify.send and dm.ack default to the recipient's sidechat and never touch Main Chat unless allow_main_chat is set — mirroring box-ctl.py notify and the WO dispatcher.
• Attribution. sender is caller-asserted (validated ∈ fleet agents), same as the existing dm.send op; the HTTPS identity is recorded separately in the exec audit log. dm.ack requires an explicit sender — no silent default.
• tests.run executes repo code (whatever is in tests/), so it is side_effecting, excluded from the read-only default permission subset, and capped at a 600s timeout. Test failures report as {"ok": false, "returncode", "output"} — the op itself succeeded.
• New box-ctl.py fail codes GIT_ERROR / TESTS_ERROR are registered in KNOWN_ERROR_CODES, so quality-check stays at its baseline.

4. Rollout notes

• Restart exec-constrained.py after deploy for the new ops to appear in GET /ops.
• box-relay.sh is served from bl (GET /box); agents re-fetch to get git / tests / notify / dm ack.
• Non-goals: git commit/push, service restarts for box itself, live streaming tails — future expansions, same pattern.