agent-device runs as an optional module on workers #597

Part of #591.

Scope

Moves agent-device's worker side onto the module host from #595. After
this PR, agent-device is the registry's first module:

• It is turned on with capabilities.agent-device.enabled. The top-level
  agentDevice key goes.
• A worker with it turned off never loads its code.
• src/daemon/main.ts no longer wires it on a worker.

Its behaviour is otherwise unchanged, with three exceptions:

• With agent-device off, simlock no longer stops an agent-device daemon
  left by a crash (ADR 0030 §2).
• On daemon stop, agent-device's two stop steps are now bounded by the
  Hook deadline;
  today they have no limit. Its slowest stop is about 22 s: a running
  --version check or reap (ps 5 s, SIGTERM 10 s, SIGKILL 2 s,
  F18). Past 30 s the drivers are disposed with agent-device still
  stopping, and the warning names it.
• A gateway's warning for command uses the generic text (below).

The gateway side stays hand-wired in main.ts until #598. In this PR it
loads agent-device with a dynamic import(), only when it is turned on.
That way no daemon loads agent-device's code through a static import.

Test fixtures that build a whole Config lose their agentDevice line.
That edit is mechanical and is not counted in this task's size. Setup
lines that turn agent-device on (edge.test.ts, gateway-front.test.ts,
main.test.ts, worker-capabilities.e2e.test.ts,
lease-requires.e2e.test.ts) move to capabilities["agent-device"]
instead. The slow-lane files are rewritten (F14).

In short

An operator turns agent-device on under capabilities:

{ "capabilities": { "agent-device": { "enabled": true, "command": "agent-device", "leaseTtlCapMs": 60000 } } }

A config that still says { "agentDevice": { "enabled": true } } gets
Unknown config key: "agentDevice", and agent-device stays off. The
integration is unreleased, so nothing migrates the old key.

flowchart LR
  R["module-registry: agent-device *"] --> H[module host]
  H -->|on| L["loadWorker() → createWorker *"]
  H -->|off| O["agent-device: off<br/>no code loaded, no reap *"]

If this goes wrong: agent-device does not start on a worker that turns it
on, or simlock daemon stop leaves its process behind.

Technical spec

Facts

Modules touched

flowchart LR
  main["daemon/main.ts *"] --> host["modules host"]
  main --> reg["module-registry *"]
  reg --> def["agent-device/definition *new*"]
  def -. loadWorker .-> w["agent-device/worker *new*"]
  main -. "dynamic import (gateway, until #598)" .-> idx["agent-device/index *"]
  w --> sup["agent-device supervisor *"]
  cfg["core/config.ts, core/index.ts *"]
  contract["contract/schemas.ts, protocol.ts *"]

Surface and extension points

src/agent-device/definition.ts exports agentDeviceModule, an
OptionalModuleDefinition:

• name: "agent-device".
• config:
  • F8's validator without enabled, which the core owns (Optional modules load through one host and are turned on under capabilities #595), built
    from validators that src/core/index.ts now exports
    (objectValidator, nonEmptyString, integerInRange,
    invalidValue);
  • F8's defaults without enabled;
  • gatewayKeys: ["leaseTtlCapMs"];
  • a check that leaseTtlCapMs is at most lease.maxTtlMs, failing
    with invalidValue's text,
    Invalid config value for "capabilities.agent-device.leaseTtlCapMs": expected at most lease.maxTtlMs.
• Every agent-device piece F8 lists leaves src/core/config.ts.
• loadWorker: () => import("./worker.js"). No loadGateway until agent-device's gateway side runs as an optional module #598.

src/agent-device/worker.ts exports createWorker(ctx). It builds the
supervisor and the edge parts from ctx (F2), and returns:

• capability, from today's capability source;
• relayTarget, from today's relay target;
• mount, the HTTP front's handler (the front keeps using src/http's
  helpers, F19; ADR 0030 §6), with ctx.config.leaseTtlCapMs and
  maxRunMs = ctx.daemonConfig.lease.maxTtlMs;
• findings, today's agentDeviceFindings returning
  { message, remedy }; the host now stamps module (Doctor reports every optional module with one module-unavailable finding #596's line moves
  here);
• hooks.afterSocketClaimed: void supervisor.start() (F5);
• hooks.beforeDeviceReclaim: the lease-end participant;
• hooks.beforeDrain: dispose the edge, then cancel waiting allocates
  through ctx.cancelPending (F4);
• hooks.beforeDriversDispose: supervisor.stop() (F3).

src/agent-device/testing.ts exports
agentDeviceModuleWith({ upstream?, health? }), a definition whose
createWorker uses the given fakes. With upstream, the supervisor is
never started, as F5 does today.

Other changes:

• src/agent-device/index.ts keeps only what the gateway path uses
  (F16). main.ts's gateway path loads it with await import(...) only
  when capabilities.agent-device.enabled is true. It reads the section
  through the type definition.ts exports, and a missing section counts
  as off. Every other name F1 lists leaves main.ts.
• StartDaemonOptions drops agentDeviceUpstream and agentDeviceHealth.
• The supervisor drops its enabled branch (F6). It is built only for a
  turned-on module.
• The supervisor's remedies say capabilities.agent-device.command (F13).
• A gateway warns Ignoring "capabilities.agent-device.command": it configures a worker, and this daemon runs in gateway mode.,
  Optional modules load through one host and are turned on under capabilities #595's generic text, in place of F20's.
• New dependency-cruiser rule main-loads-modules-lazily: main.ts
  imports src/agent-device only as dynamic-import, type-only or
  type-import (F17). agent-device's gateway side runs as an optional module #598 tightens it to no import at all.

Contract and event changes

configSchema drops agentDevice (F10); agent-device's section travels in
capabilities. This PR bumps the protocol by one. No event changes.

Other code on the same state

• The gateway path in main.ts (F16) reads agent-device's config. It
  switches to config.capabilities["agent-device"], with the same
  behaviour.
• Optional modules load through one host and are turned on under capabilities #595's host tests pin agent-device's hand-wired entry first in the
  capability list, and its stop steps before the hooks. With the hand
  wiring gone, those tests assert the registry order only, with
  agent-device as a registered module.
• The core doctor gets only host.findings() at main.ts:329.
• A leftover agent-device daemon while off: nothing acts on it any
  more. The next start with agent-device on reaps it, as today (F6).

Rules in play

• architecture.md rules 18 and 21: main.ts names no module on the
  worker path.
• safety.md: the reap's ownership proof is unchanged.
• testing.md: delete only F7's two tests, whose path is gone. F9's tests
  move, they are not deleted.
• documentation.md: F15, plus CLI.md, HTTP-API.md and CLIENT.md
  wherever they write agentDevice.

Tests

Seam:
startDaemon({ optionalModules: [agentDeviceModuleWith({ upstream: fake })], configOverrides: { capabilities: { "agent-device": … } } })
in place of agentDeviceUpstream in the suites F11 names, modelled on
src/agent-device/edge.test.ts. Those suites still pass, with their setup
changed and F12's three assertions renamed to the new key.

• a worker with no capabilities["agent-device"] section answers status.get with { name: agent-device, state: off }, and so does one with enabled: false
• a worker with agent-device off never calls agent-device's loadWorker (a spying definition that wraps agentDeviceModule)
• a gateway with agent-device off, or with no section for it, mounts no /v1/agent-device (as today)
• a worker whose config has only the old agentDevice key warns Unknown config key: "agentDevice" and reports agent-device off
• a worker with agent-device off starts no supervisor: no ps runs and no signal is sent, even with a recorded daemon on disk
• F9's tests move to src/agent-device/definition.test.ts, under capabilities.agent-device (as today):
  • the defaults, and an explicit section kept as written;
  • command refused when empty, and when a number;
  • leaseTtlCapMs accepted at 5000 and at lease.maxTtlMs, refused as a fraction, refused below 5000, and refused above lease.maxTtlMs with invalidValue's text naming capabilities.agent-device.leaseTtlCapMs;
  • a loaded config parsed through configSchema keeps the section;
  • on a gateway, enabled and leaseTtlCapMs read without a warning, and command warned about with the generic text
• startDaemon with agent-device on stops the agent-device child before the drivers are disposed (as today, main.test.ts:2449)
• with agent-device on, a release still waits for agent-device's lease end before the device is reclaimed (as today)
• daemon stop cancels an agent-device allocate waiting in the queue before leasing settles (as today)
• doctor.run reports { kind: "module-unavailable", module: "agent-device" }, with the module stamped by the host
• the supervisor's not-found and not-agent-device remedies name capabilities.agent-device.command (F12's two supervisor assertions)
• config.get shows agent-device's section under capabilities["agent-device"] and no agentDevice key
• the conformance suite runs over agent-device as a registered module
• dependency-cruiser fails a value import of src/agent-device from main.ts (a lint-harness case); pnpm lint passing on this PR's main.ts, with its dynamic and type imports, shows the allowed kinds pass
• the protocol version is one above the base branch's

Done when

• Every Tests line passes, and every other test in the suites F11 names
  passes with only its setup changed and F12's assertions renamed.
• F7's two supervisor tests are deleted. No other agent-device test is
  deleted.
• docs/CONFIGURATION.md documents capabilities.agent-device.*. Its
  leftover-daemon line says it applies with
  capabilities.agent-device.enabled true.
• F14's config writes and deletes use capabilities["agent-device"]. On a
  Mac with an iOS runtime: scripts/slow-e2e.sh e2e/slow-agent-device.test.ts
  and scripts/slow-e2e.sh e2e/slow-agent-device-gateway.test.ts pass.

Out of scope

• The gateway side moving onto the host (agent-device's gateway side runs as an optional module #598).
• The doctor finding's shape (Doctor reports every optional module with one module-unavailable finding #596).

Depends on

• Optional modules load through one host and are turned on under capabilities #595

Written by an agent.