# AGENTS.md - working rules for this repository Read this file first. It is the one guide for agents in this repository. `CLAUDE.md` imports it. This repository (socialweb-computer-kcp) is the monorepo of the socialweb-computer project. It is the single source of truth for its Go code. The only TypeScript left is `scripts/*.ts` and the policy actions under `internal/policyengine/bundled-actions/tangy/`. `docs/ARCHITECTURE.md` holds the decisions, the measurements and the invariants. This file points at it and states the working rules. Open a section of `docs/ARCHITECTURE.md` by its heading when a change needs the argument behind it. Do not read it end to end. ## Orientation: which file answers which question | Question | File | | --- | --- | | What is this, in one paragraph? | `README.md` | | The objective, stated once | `docs/ARCHITECTURE.md` section 1 | | Where a concept lives; the package layout | `docs/ARCHITECTURE.md` section 12, and Layout below | | Rules a change must not break | `docs/ARCHITECTURE.md` section 13 | | Why a decision was made, and what it closed | `docs/ARCHITECTURE.md` section 15 | | The plans and the status of each item | `docs/plans/*.yaml` | | The live backlog (what is open now) | `NEXT.yaml` | | The TypeScript that is left | `scripts/*.ts`, and the policy actions in `internal/policyengine/bundled-actions/tangy/` | | Env the clusterprovider reads | `internal/providermain/config.go`; the gateway's defaults for it in `internal/stack/gatewaykcp/env.go` | | Env the gateway reads | `internal/gatewaymain/config.go`, `deploy/socialweb-gateway.env.example` | | How prod is installed and upgraded | `scripts/deploy.sh` (gateway: `install gateway`, then `upgrade`), `socialweb-computer install bidder`, `socialweb-computer install requester` | | What a host must provide | `socialweb-computer check-host -role gateway`, `-role bidder` or `-role requester`, `docs/host-contract.md` | | The market network | `deploy/market-network/README.md` | | The operator handoff | `handoff.yaml` | | What CI runs on a push, and its runners | `.knotless/workflows/` (knotless only; GitHub CI is gone): the workflows `release`, `test` and `promote`, in series (each after the one before), and `pins` (kcp-small 4/8) runs only when asked. `release` (kcp-build 12/16; on pushes to main only, a branch when asked; no v* tag is built: plan 0040 step 15) is the gate's checks (`deploy/check.sh --fast`: gofmt, apigen, codegen drift, go vet on the host and every cross-OS target, architecture rules, the docs checker, the pins records, the policy engine tests; nothing is built), then the ONE build (the release binaries for every platform, the static test host, the wasm test modules and the static meshd of this commit's trees; a tree already published is skipped), the amd64 binary pushed to ttl.sh by digest for `test`, the node downloads and the guest image, and on main its last steps stage `staging//`, copy it inside the bucket to `main//` and `main/latest/` and check what was published from the public URLs (its key a sealed secret of main pushes; `superseded: finish` on main, a newer branch push cancels the older run). `test` (kcp-test 4/8, `after: [release]`) is the staging gate: it stands up ONE staging network (two bidders) from its CI VM (its guest requester) and `tests/compositions/staging/suite.sh` runs every entry of `tests/entries.txt` (46) on it (as the network's alice1 to alice4, four at once; `scripts/ci-test.sh` `input_default`), printing `gate: staging: N of 46 PASS` (about 2 h 40 min; `scripts/ci-staging-total.sh ` reads it back); it takes release's binary (main: `main//`) and release's test host and meshd. `promote` (the `release` executor binding, which asks for no guest requester: no `association`, `scripts/promote.sh prepare` exits 1 on a VM that has one and makes the gate's unix user r2, docs/ci-debug.md "The release binding"; `after: [release, test]`: it starts only once this commit's `test` passed, and is filed failure without running when it failed; on a push to main with test's paths, and when asked: plan 0040 step 15) is the release: a plain first step (`scripts/promote.sh test`) ends the run unless this commit's `test` ran green (`scripts/ci-check-wait.sh`; path-skipped is not green), before release-workload writes the rc's records and moves channel `rc`; then `scripts/promote.sh` writes the prod target (`scripts/ci-prod-target.sh`), deploys the droplets, waits for every rc operator's heartbeat, runs the prod gate (`tests/gate.sh --account bob,alice` with `GATE_VMS=6`: the `both` entries; about 90 min), then copies `main//` to `releases//` in the bucket (`scripts/copy-spaces.ts` with the bucket key, checked from the public URLs; vT is release-workload's `RELEASE_STABLE_VERSION`); exit 0 moves channel stable to vT, anything else moves rc back to what it rolled forward from at once. Nothing but `release` compiles anything, and nothing rebuilds anything to compare (no reproducible-build verification in CI). The release pipeline: `docs/plans/0040-release-pipeline.md` Flow. Since 2026-11-19 the cycle is in series (owner: less compute, though slower): release, then test, then promote, so staging and the prod gate do not rent at once for one commit; a rerun of a red `test` does not start promote again (docs/ci-debug.md "After a red test"). | | What the system does, end to end, and its tests | `docs/acceptance/` (the runbooks), `tests/system` (one test file per runbook), `tests/testkit/README.md` | ## Layout Go: | Directory | What it holds | | --- | --- | | `cmd/` | one directory per binary (`socialweb-computer`, `socialweb-node`, `socialweb-vmexec`, `socialweb-guest-agent`, `socialweb-apigen`, the two OpenBao auth plugins) | | `internal/` | the Go packages, in the plan 0026 layers (`docs/ARCHITECTURE.md` section 12) | | `pkg/` | the packages another module imports: `pkg/embedded`, the requester an app runs in its own in-process kcp (plan 0038); its `Config.OnSnapshot` bytes hold every vault secret in clear JSON: store them encrypted (Keychain, Data Protection Complete, no backup), never log them; `Config.StateDir` holds the renter PLC rotation key `components/Requester-requester/plc-rotation.key` (k256, 0600, made on first use; first rotation key of every guest DID it rents, so it tombstones them when the guest is gone): same protection, never in a backup | | `api/` | the kcp API types; `go generate ./api/...` writes the schemas, the APIExports and the generated Go | | `deploy/` | manifests, sets, the generated schemas and exports, `check.sh` | | `docs/` | `ARCHITECTURE.md`, `plans/`, inventories, research notes | | `rust/` | socialweb-meshd | | `did-key-associator/` | the QR session-transfer service (qr.fedfork.com): static page and deno backend, vendored 2026-11-18 with its history from github.com/publicdomainrelay/did-key-associator (0a48e76; that repo is private since 2026-11-20, this tree is the source); deployed by `infra/did-key-associator` | | `typescript-helpers/` | the deno libraries did-key-associator imports by relative path (`../typescript-helpers/lib/{oauth-scope,cli-args-env,logger,serve}`), vendored 2026-11-18 with its history from github.com/publicdomainrelay/typescript-helpers (3fae6da; private since 2026-11-20, this tree is the source) | | `site/` | https://socialweb.computer/: the landing page (`site/index.md`, the owner's text; README sections spliced in at build) and the user docs rendered to static pages (`site/build.sh`; mermaid drawn at build), deployed by hand with `site/deploy.sh` (`site/README.md`); in no CI workflow's `paths:` | | `tests/` | the Rust system integration tests: `testkit` (harness), `system` (runbook ports), `targets/`; `vmm` (the VMM wrapper on a KVM host, `-p swc-vmm-tests`) | TypeScript: | Directory | What it holds | | --- | --- | | `scripts/*.ts` | one-off operator scripts (`oauth-signin.ts`, `associate-bidder.ts`, `publish-spaces.ts`), run with `deno run` | | `internal/policyengine/bundled-actions/tangy//` | one policy action: `index.ts` and its built `dist/index.js`, embedded by the policy engine | There is no deno workspace and no vendored TypeScript repository here any more; the one lockfile is `site/deno.lock` (the site build: the markdown renderer, shiki, mermaid and puppeteer-core). ## The TypeScript that is left - `scripts/*.ts` are one-off operator scripts, run with `deno run -A`. No Go code runs them; the knotless `release` workflow and `tests/publish-test-host.sh` run `scripts/publish-spaces.ts`. - The policy actions under `internal/policyengine/bundled-actions/tangy//` are gha-lite assets that the policy engine embeds: `action.yml`, `index.ts` and its built `dist/index.js`. Edit them as such assets, with the workflows beside them in `internal/policyengine/bundled-actions/workflows/`. - No comments in code. ASCII only. ## The kcp paradigm, port 0, and the RFP flow - kcp is part of each application, not infrastructure. An application instance is a kcp of its own (or, in a market network, a workspace of the network's one kcp), a manifest set and a profile. State is kcp objects. Components (Pds, Plc, Relay, Bidder, Requester and the other component kinds) run in process in the core, in the component runtime of `internal/component`, and host processes are HostProcess units; both are reconciled from those objects. Only the virtual Kubernetes clusters project uses kcp in the traditional way. - Which kcp, by profile: a prod profile (the gateway, `run bidder`, `run request` and `run requester` without `--network`) runs a strict kcp per application. The market network profile (dev, CI, soak) runs every application in one kcp, each in its own workspace `root:` (components in `root::app`), from the same manifest set: the applier rebases the set's workspaces under the application's workspace. Either way applications talk only over the atproto market protocol; the shared kcp is composition and isolation, never a data channel. Write service names in manifests as `.default.{{.ServiceSuffix}}`. - Port 0 behind the edge: every listener binds port 0 and reports its bound address into the status of its kcp object. Peers find it by service name through kcp. Only the stable public entry points (caddy on 443, an application's front) keep a known address. - The RFP flow is the only way a guest comes up: the requester posts a `compute.vm` record and a signed `market.rfp`, bidders bid, the requester accepts, and the winner boots the guest from cloud-init `user_data` (`BuildUserData` and the module registry in `internal/atproto/cloudinit`). The requester reaches the guest only through the guest transports below. Never start a container or VM by hand in code or in a test, and never install a guest agent outside cloud-init. A live run that needs a guest brings up its own market network, and `socialweb-computer run request` or a tenant cluster of the network's gateway rents the guest. `run request` composes a MarketRequester root (`internal/app/marketrequester`), and its Requester component (`internal/services/requester` over `internal/market/requester`) runs the RFP, the accept and the release; `run request list`, `run request release` and `run request resume` manage the invocations it recorded. - `run requester --name ` (plan 0039 A-RUN-REQUESTER, `cmd/socialweb-computer/requester.go`) is the long-lived form: the same MarketRequester root and the same bring-up (standalone: bringUp profile quick, role requester; `--network `: a child application), state under `/requesters/` (never `requests/`) with the owner flock of `internal/stack/request/owner.go`, no contract of its own. Its application options (`deploy/apps/option-map.yaml`) are the MarketRequesterSpec part of `run request`'s, parsed by one shared function (`parseRequesterSpec`); a contract option is refused. Once the root is Ready it writes a workspace kubeconfig (`/kubeconfig`, 0600) and the ready file (`/ready.json`, plus `--ready-file` when given; tmp then rename, 0600; `internal/stack/request/ready.go`) {schema 1, name, pid, startedAt, kcpUrl, kubeconfig, workspace, did, handle, identityMode, pdsUrl, ingress {pds, requester}, sshPublicKey}: paths and public values only. It prints that as a JSON summary, rewrites the file when a field changes (a watch on the MarketRequester), stays in the foreground (`--fg` is a no-op for the unit form), and on Ctrl-C or SIGTERM removes the ready file and stops its kcp keeping its state (a network child is stopped, not removed). `/requester.json` records the first start's network, `--identity` and spec; a restart with no application options, or the same ones, reuses it (other options are refused), adopts the units and keeps the DID, the vault and every contract (Held ones stay Held). `kubectl apply` Infra, EphemeralInfra or ComputeContract against the ready file's kubeconfig. Helpers on a running one read its ready file: `run requester env ` (KUBECONFIG, the kcp URL, the workspace, the DID, the ssh public key; `--json`) and `run requester ssh --contract [--transport webrtc] [--exec -- [args...]]` (the `run request ssh` code with the requester's own key `/ssh/id_ed25519`; put its `.pub` in the contract's `sshAuthorizedKeys`); `run requester proxy` is its webrtc ProxyCommand. Every ssh the CLI runs gets `SHELL=/bin/sh`, because ssh runs its ProxyCommand with `$SHELL -c` and an installed account's shell is nologin (sudo and the user manager set SHELL from passwd). With `--host-backend systemd-user` (plan 0039 B-INSTALL-REQUESTER, the installed form; refused with `--network`) the process is the core itself (`request.RunCore`, the `bidder.RunCore` pattern over `devcore.Run` with the bootstrap app `table.Requester`, key `req-/requesters//dev/)[:10]>` (plan 0046 step 6: by state dir and name), layout `install.RequesterLayout` under `/dev/`): it places kine, front and slot as user units, applies the root, signs in and sends READY=1 only after the ready file; a stop leaves those units and the HostProcesses running for the next start to adopt. `install requester --name ` (default account `swc-requester`) writes the unit template `socialweb-computer-requester@.service` (Type=notify, TimeoutStartSec the ready budget plus `install.RequesterStartGrace`, 1 h for a sign-in) and, once per name, `/requester.json` from its application options (default `--atproto-oauth-qr`). The account is a system account, so journald puts its user units' lines in the system journal (only root reads them: `journalctl _UID= _SYSTEMD_USER_UNIT=`); `run requester signin ` prints the MarketIdentity's `pendingAction.url` from the requester's own kcp, and `install` prints both. A password never goes into requester.json: `run requester password ` reads one from stdin into `identity/requester/keys` of the requester's vault. With `--atproto-identity-mode pdsAccount`, `run request` and `run requester` (standalone or `--network`, where the network child takes only that mode, `--atproto-handle` and `--atproto-pds-url`, default the network's bob PDS) put `ATPROTO_PASSWORD` from their own environment into that path before the sign-in; a missing or unreadable keysRef keeps the MarketIdentity Pending (`WaitingForCredential`, `VaultUnavailable`), never Failed; so does a transient sign-in failure (`SignInRetrying`: a timeout, a connection error, a 5xx or a 429 of createSession, or of an oauthBrowser begin, by `netretry.Transient`), retried by the controller's backoff; Failed (`SignInFailed`) is the PDS's own refusal (401 AuthenticationRequired, AccountTakedown, AuthFactorTokenRequired, a 400), a DNS not-found and a certificate verification error. A PDS call of the controller is bounded by the core's `identityResolverTimeout` (10 s) on the core's network client. The CLI waits for Ready up to its deadline (`run request` and `run bidder` 5 min). A pdsAccount requester signs its market callbacks with its PDS service auth (`signing: owner-identity`) and publishes its badge.blue signer key. `upgrade` takes the role from the install record. The same-account form is a kubectl-applied HostProcess (`examples/infra/requester-hostprocess.yaml`); no root prunes a HostProcess outside its set. - `run requester --with-gateway` (plan 0039 C-GATEWAY-COMPOSE, `cmd/socialweb-computer/requestergateway.go`, `internal/stack/gatewaykcp/requester.go`, `internal/app/gateway/requester.go`) applies a Gateway root `gateway` of profile `requester` with `spec.requesterRef` (the MarketRequester `app` of the same workspace) and runs its clusterprovider in the `run requester` process. With requesterRef the Gateway composes no PlanAccount, Pds, Requester, PolicyEngine, root vault or web app: only the rbac phase of the gateway set (the NodeClaim agent) and a nodes-only GatewayAPI (`spec.nodesOnly`, the NodeClaim binding and the downloads route) whose node bundles go to the requester's vault (`nodeMarket.vaultMount` requester); the nodes' Infra is in the requester workspace and the MarketRequester's Requester rents them as the user's DID. A Gateway without requesterRef composes what it did before. Its clusterprovider serves only the clusters of the requester's DID (`SOCIALWEB_CLUSTERPROVIDER_ACCOUNT`: the registry and the Cluster controller skip every other account), and `--with-gateway` is refused in a market network that has a gateway child (that provider serves every Cluster of the network's kcp). The cluster's k3s, kine and OpenBao are HostProcesses of the requester's core; in a market network the child core runs the gateway's outbound trust and egress (`gatewaykcp.NetworkOutbound`) when `/gateway` exists, which `run requester --with-gateway` makes before the network places it. `requester.json` records `withGateway`; the ready file is first written only once the Gateway is Ready too, with `gateway {workspace, name, clusters}`; `run requester cluster --cluster ` makes the home workspace `root::` and its Cluster, and `run requester kubeconfig --cluster ` prints its admin kubeconfig path once the Cluster is Ready (exit 1 before). A node fetches socialweb-meshd and socialweb-node from `/downloads//` and checks the pinned sha256: the base is the nodes-only GatewayAPI's `spec.publicOrigin`, set from `--node-download-base` (default the public bucket, where the CI `publish` job puts the pinned socialweb-computer-k8s-downloads tree content-addressed under `downloads/`); with `--network`, a dev build and the default it is the local Exposure (the requester's host only; a release build uses the bucket). - Comms modes (`spec.comms.mode` of the MarketRequester and its Requester; `run request --comms-mode XRPC|Firehose|Both`). XRPC takes bids and events on the requester ingress only. Firehose has no inbound endpoint. Both (the requester default) is the ingress plus the same streams as Firehose. In Firehose and Both the requester composer (`internal/app/compose/streams.go`, the same code in the browser build) composes EventStreams from the network relay, `spec.comms.eventSourceRefs` and the default public firehoses; it composes no per-bidder stream (no subscribeRepos of a bidder PDS: a did:key bidder requestCrawls our relay and a bsky-hosted one is on the Jetstreams, and a shared host replays every repo it holds), and it prunes the old `bidder-pds-*` sources by their label `socialweb.computer/bidder-source`. The defaults (`api/v1alpha1` `DefaultFirehoseRelayURLs`, `DefaultFirehoseJetstreamURLs`): our relay `https://relay.mini-cloud-0002.chadig.com` (subscribeRepos; on a network with a relay host the network relay replaces it) and the two Jetstream v2 instances Bluesky documents, `wss://jetstream.us-east.bsky.network` and `wss://jetstream.us-west.bsky.network` at `/xrpc/network.bsky.jetstream.subscribeEvents` (`collections`, `dids`, `kinds=commit`). bsky.network is not a default. A Jetstream URL whose path ends in `/subscribe` is spoken as v1 (`wantedCollections`, `wantedDids`); a bare host is v2. Every relay subscribe sends the stream's filter as repeated `wantedCollections` and `wantedDids` (at most 100 and 10000, else that param is left out); our Go relay (`internal/atproto/relay`, the network relay and prod) filters on them, other relays ignore them, and the client filter (`events.Filter.Narrow`) always runs too. Each subscribe logs `relay_subscribe_dial` or `jetstream_subscribe_dial` (endpoint without query, the filter params, the cursor), and the EventStream's `status.serverFilter {collections, dids, supported: true|false|unknown}` is written on connect only. Each is a RelayEventSource or JetstreamEventSource with its EventSource (`firehose-relay-`, `firehose-jetstream-`, label `socialweb.computer/market-source=public-requester`) and an EventStream with `spec.resume: Live` (no stored cursor; a reconnect resumes from the cursor in memory). `spec.comms.relayUrls` and `spec.comms.jetstreamUrls` replace a default list; an empty list turns it off. A requester stream carries only `market.bid`, `market.receipt` and `market.event`; a bidder stream only `market.rfp`, `market.accept` and `market.event` (`compose.MarketStreamCollections`); payload records (`bids.free`, `compute.events.*`, ...) are read through the strongRef, never taken as stream input. Every market EventStream of a role delivers to one handler sink (`internal/eventstream/market.go`), which drops a `uri|cid` it took in the last 15 s (at most 10000 keys) and logs `market_event_duplicate_dropped` once per key with the running count. The requester tracks only the records of its own ComputeContracts (`internal/atproto/market/addressee.go`; the sink's index `internal/eventstream/addressees.go` is fed by a ComputeContract watch, no kcp read per record, and no DID allowlist): a bid whose `rfp` is the RFP of one of its contracts that has no accept yet, a receipt whose `accept` is one of its accepts, an event whose `receipt` is one of its receipts or, before that receipt is in the contract status, whose `receipt` resolves to a receipt of one of its accepts. Before the fetch it drops a bid while no contract takes bids, and a receipt or event whose repo is not the repo of an accepted bid of a contract that is not settled. Every StateSync and inbound ContractEvent it creates has an ownerReference to that ComputeContract, so deleting the contract (or the Infra or EphemeralInfra that owns it) deletes them. The bidder takes every RFP, an accept whose `bid` is in its repo and an event whose `receipt` is in its repo (its MarketIdentity DIDs). The rest is dropped before any object and counted in `market_foreign_dropped` (every 1000). The roles prune their market inbox StateSyncs (Outbound, Retain: the role adapter is the target, and a delete has no remote side): one that matches no own contract at once; the requester's of a Released or Failed contract once Acked and 10 min old (`MarketInboxRetention`); the bidder's every Acked one at 10 min (`requester_inbox_pruned`, `bidder_inbox_pruned`, every 100). No inbox StateSync is a dedup fact. A bidder bids only inside an RFP's bid window (`market.RFPBidWindow`, 10 min from its `createdAt`, else from its TID rkey; the lexicon has no expiry), which the bidder's inbox retention equals: its sink drops a closed RFP before the record fetch and again after it (`market_rfp_closed_dropped`, with the source, every 100), submitRfp answers 409 `RFPClosed`, and a Deciding Bid of a closed RFP fails `BidWindowOver` (`bidder_rfp_closed`). It never bids twice on one RFP: the handled fact is the Bid object (name `market.BidRKey`) and, after its TTL, the bidder's own `market.bid` record at that rkey (`bidder_rfp_already_bid`). A relay stream reconnects 1000 events back, a Jetstream 30 s back, but never before the cursor its last connection started at, after a 1 s backoff that doubles to 30 s and resets only after a connection that stayed up 30 s; each close logs `event_stream_closed` (the cursor, `openSeconds`, `retryIn`, `restored`, the error) and a failed dial `event_stream_subscribe_failed`. A close the browser page fires after a memory snapshot restore (code 1006, reason `wsconn.RestoredCloseReason` "restored from a memory snapshot", the page's `RESTORE_CLOSE_REASON`; `wsconn.Restored`) redials at once from the cursor in memory and resets the backoff to 1 s; the pdsclient subscribeRepos stream does the same. Any other close keeps the backoff. Our relay answers a subscribeRepos without a cursor with live events only (the atproto sync spec); a cursor replays its backlog. The js/wasm WebSocket (`internal/kit/wsconn/conn_js.go`) has no receive backpressure, so it queues frames up to 16 MiB (`MaxBufferedBytes`), never by a frame count. - The bidder's requester streams (any comms mode, `internal/app/compose/requesterstreams.go`): requester events reach the bidder through submitEvent first; as a record-only fallback, while the bidder has live ComputeVMs (not deleted, not Lost or Failed), it composes EventStreams with the bidder's market NSIDs and `dids` = the requester DIDs of those ComputeVMs (at most 100, read at runtime, never configured): sources `requesters-relay-` (the network relay, else `spec.comms.relayUrls` or our relay; the relay filters on the server) and `requesters-jetstream-` (`spec.comms.jetstreamUrls`, else `wss://jetstream.us-east.bsky.network` when the network has no relay). They deliver to the bidder's market sink (the same intake as submitEvent, deduplicated by `uri|cid`). A ComputeVM watch reconciles the MarketBidder only when that DID set changes; a new set is a spec change, so the stream reconnects with the new filter. Their `spec.resume` is `Recent`: after a restart or a spec change the stream resumes from its stored cursor only when it was saved in the last `delivery.RecentResumeWindow` (10 min), else it starts live. No live ComputeVM, no stream. ## Guest user data: never reload systemd while a start job is in flight - The guest image's systemd (255.4-1ubuntu8.17) PID 1 aborts in `service_sigchld_event()` (`src/core/service.c:4054`, `assert_not_reached()` in the control-process-exited switch) when a `daemon-reload` lands while a service start job is in flight (observed: `ssh.service` starting, a `systemctl` of cloud-final reloading 2 ms later). `CrashAction=freeze` then freezes PID 1: every later `systemctl` gets `Connection reset by peer` or a 25 s timeout, iroh never starts, and the guest never reports on the network ("did not come on network within 2m0s"; the apport core pipe can deadlock the same crash). Closest upstream issue: systemd/systemd#44705 (same assert, line 4064, a shutdown race, closed). We do not patch systemd. - Rule for the runcmd entries OUR modules contribute (RuncmdPrepend and Runcmd of the modules and the overrides of `cloudinit.BuildUserData`, which also covers guestseed's seed modules): one `systemctl daemon-reload`, standing where our first systemctl command stood; every `enable` is `systemctl --no-reload enable`; no `enable ssh` (it runs systemd-sysv-install and update-rc.d, which reload; the image has `ssh.socket` enabled, runcmd only starts `ssh.service`); all our `start`s come last, after the base's entries and our appended ones. `assembleRuncmd` lays this out: our prepended entries, the base's runcmd, our appended entries, our starts; it drops module-local reloads, rewrites enables and splits `enable --now` into a no-reload enable plus a start. A module writes one `systemctl` command per runcmd entry (a compound line with a reloading verb fails the build: our bug). - The base's runcmd entries (a requester's user_data, or what an earlier BuildUserData wrote) pass through byte for byte and never fail a rental: their VM, their user data. Each BuildUserData layer puts its reload before its own starts, so layers stack safely. An older requester CLI builds its modules' reloads and starts into the base it sends: the bidder cannot fix those; they need a requester release. - A restart from the recorded state (`dev up`, a `run request release` of a killed owner) never adopts the units of a devsup that is shutting down: its Hello says `stopping`, it refuses Start, `startOrAdoptDevsup` waits for it to exit (120 s) and starts a new one, and `Observe` waits for a unit that is deactivating (60 s). Before that, a release started right after its owner was SIGKILLed mid-stop adopted kine and front that devsup then stopped under the new kcp (not ready for 60 s). Testcase: composition 0017 entry `devsup` (the host runs a real devsup with no VM: `dev up --profile quick`, then `dev down` SIGKILLed mid-stop and `dev up` at once, 12 times; every kcp must be ready). - Debugging a silent guest on a dev net: `SWC_DEV_GUEST_BOOT_ARGS_EXTRA` or the file `$XDG_RUNTIME_DIR/swc-dev-guest-boot-args-extra` (read by the VM runtime, dev only) appends kernel arguments; `sysrq_always_enabled=1 ignore_loglevel systemd.log_target=kmsg systemd.journald.forward_to_console=1` puts PID 1's crash line on the serial console, and QMP `send-key` alt+sysrq+w/t/s over the VM's `api.sock` shows what PID 1 waits for. With `systemd.mask=apport.service sysctl.kernel.core_pattern=/var/tmp/core.%e.%p.%s` the core lands on the guest disk (copy `rootfs.ext4` with `cp --reflink` and read it with gdb and debuginfod). `systemd.log_level=debug` writes 7 MB to the serial console per boot and slows a boot past the 2 minute window by itself. ## Guest transports, guest events and the host-loopback fence - Three guest transports, and no other. Never add one. - iroh is the default and required transport: every guest gets the iroh module, the requester's ssh and `status.contract.vmAddress` are iroh, and a contract is Held on the iroh address and the host keys alone. - opentunnel https, opt-in per entry of the ComputeContract's `spec.tunnels` with transport `opentunnel` (the default): one https URL per tag for the guest's `127.0.0.1:`, back as a `vm.onNetwork` kind `https` in `status.contract.networks` (plans 0032, 0034). - webrtc, opt-in per entry with transport `webrtc`: socialweb-guest-agent (`cmd/socialweb-guest-agent`, `internal/guestagent`, pion and age) bridges each datachannel labelled with the tag to `127.0.0.1:`; its DTLS fingerprint comes back as a `vm.onNetwork` kind `webrtc`. The CLI side is `run request proxy --tag ` (`internal/webrtcproxy`), and `run request ssh --transport webrtc` uses it as the ssh ProxyCommand; `run request --tunnel :[:]` asks for tunnels. STUN is `stun:stun.cloudflare.com:3478` only; no TURN (plan 0034). A tunnels.json entry maps its tag to `"port": ` (127.0.0.1) or `"unix": ""`; each datachannel is one connection to it. The guest agent's shell service (an MCP server: `internal/guestagent/mcp.go`, `jobs.go`; tools exec, start, read, write, kill, list, as root) is `/etc/socialweb-guest-agent/services.json` `{"shell": {"unix": "/run/socialweb-guest-agent/shell.sock"}}` (the socket directly in the state dir): HTTP (POST /mcp, JSON, stateless) on that unix socket only, root:root 0600 in a 0700 dir, never TCP; a services.json makes the bidder install the agent too. Reach it over webrtc with `{"tag": "shell", "unix": "/run/socialweb-guest-agent/shell.sock"}`, over iroh with `ssh root@guest socialweb-guest-agent relay /run/socialweb-guest-agent/shell.sock` (stdin and stdout to any unix socket, raw bytes) or ssh streamlocal forwarding. Jobs outlive a connection. - The browser shell: ssh over webrtc comes first; wootty is the fallback. An opentunnel entry with `shell {envFile}` (default `/etc/wootty/wootty.env`) runs `wootty-.service` on `127.0.0.1:` behind that tag's https URL; a shell on transport webrtc is invalid. The shell needs `spec.secretsRef`: its `WOOTTY_AUTH_TOKEN` (32 characters or more, else it does not start) comes only in the secrets bundle, and the unit waits for `setup-guest-binaries.service` and the secrets ready file. `run request --tunnel ::opentunnel:shell[=]` (or the older `::`) asks for one. - The atirc agent (plan 0035; peer to peer, no token): `spec.agent {envFile}` (default `/etc/atirc/atirc.env`) needs `spec.secretsRef`; with no `spec.association` the requester treats it as `{fromGuest: true}` plus `guestTools: [socialweb-computer]` (`requester.DefaultAssociation`, every path: CLI, infra, kubectl, page, iOS). After the receipt is verified the requester (`internal/market/requester/agentpeer.go`) generates the agent's iroh key (a 32-byte ed25519 seed) into the bundle at `/etc/atirc/iroh_key.hex` (hex, 0600), writes envFile `ATP_USERNAME=`, `ATIRC_DID=` (0600) and `/etc/socialweb-computer/r2-agent.env` `R2_COLOCATED=