dev-setup #

local-dev is the loop once you are in it: five terminals and a swarm. This is getting there. The gap is not the scripts, it is everything around them — a certificate, a name, an edit to the user's harness configuration, and a restart before any of it takes effect.

The shape is a command that asks rather than assumes. It touches a person's settings file and possibly their trust store, so it says what it will do, does the parts it may, and stops with a specific instruction for the parts it may not.

What the shape is #

One set of defaults per machine, in scripts/dev-profile.sh: the port, the zone and the state directory, each overridable from the environment. A second stack on one machine is a second set of those variables, or a second checkout. Each daemon knows its own default state directory under $XDG_STATE_HOME (didbot-agentd's default_state_dir, dev-pds.sh's --data), so nothing has to be told where anything lives before it can start.

Installing an agent host — the daemon's unit file, the plugin, the hooks — is the agent host's installer's job, which is shell owned by the didbot-claude plugin: it writes the unit files and reports whether the plugin is present.

Where accounts come from, and the bootstrap #

Hooks are captured at session start, so a session that installs them is never itself hooked — and neither are its subagents, which inherit the session's captured configuration rather than re-reading disk. A directory is therefore set up from outside it, before a session starts there.

Recovery is a different problem from bootstrap, and a more frequent one: a server that was down when the session opened, or one restarted without --data. SessionStart cannot be replayed, so PreToolUse provisions as well, and the first record of a session with no usable account mints one. The identity still comes from the harness payload and never from the model, which is why this is a hook rather than something the record host offers: the Model Context Protocol carries no verified caller identity, so a tool that let a session register itself would let a model claim to be any session.

Setup #

Name the steps a machine cannot take for you and stop cleanly on each: choosing a zone, and restarting the harness so new hooks load. Both of the TLS ones are named in running locally and neither stops cleanly yet: a server whose authority nobody has trusted, and one that cannot bind 443, both fail at the first request rather than at startup with the command to run.

The parts that are not the server #

Working in it #

Keep docs/running-locally.md true, which is local-dev's item and fails first here. Its closing section currently interleaves several revisions of the same paragraph and contradicts itself about whether records are signed into commits.

Done #

The TLS story is a local certificate authority. The server signs one into $XDG_STATE_HOME/didbot/local-ca on its first run, mints a <zone> + *.<zone> leaf under it, and serves that; --tls local is refused for any zone that is not under .localhost, and --tls acme for one that is, from the one table in didbot_tls::source. The authority carries an RFC 5280 name constraint permitting localhost and what sits under it and nothing else, so a machine that trusts it has trusted exactly this and a leaked key cannot impersonate a real site — which is what the objection to mkcert was about. The zone and the did:web values are the production ones, so nothing diverges.
```
A `did:web` carries no port, so accounts answer on 443 and the binary
gets `cap_net_bind_service`. A machine running several servers at once
says where each zone answers in `DIDBOT_RESOLVE_PORTS`, which every
tool here reads and a browser is told through its own resolver rules.
```
An account the configured server already holds is adopted rather than minted again. localhost and 127.0.0.1 are two strings and one machine, and the hook does not guess which spellings of a host mean the same thing — so it asks. Without that, a session whose server is named the other way dead-ends: provisioning refused because the account exists, and every record after it unstamped.
One switch for debugging, and an identifier that survives three processes. The hook stamps the payload's tool_use_id, the record host logs it and forwards it in a quernstone-turn header, and the server puts it on the span every line of that request is emitted under. The harness's own identifier rather than a fresh one, so the same string finds the turn in the session transcript too; never written to a record, because a repository is public and permanent and an operational identifier does not belong in one. RUST_LOG turns the detail up, and every component reads it.
The development scripts share one set of defaults. Each dev-*.sh sources scripts/dev-profile.sh, which exports the port, the zone and the state directory. A variable already set wins, so a second stack is a second environment and nothing in the checkout is edited.
Wiring in two scopes is a conflict. Settings files merge rather than override, so it means two accounts provisioned per session and one never torn down, and it has no other symptom anyone would recognise.
PreToolUse provisions when a session has no usable account, and the server that minted an account is recorded beside its DID, so a DID is never stamped into a call bound somewhere else. The server goes in a second map rather than in each entry, so a hook built before it existed still parses the file instead of forgetting every account in it.
The PreToolUse matcher is a pattern, not a literal tool name, so a machine can run a second record host and the settings block is written once and never edited again.
The hook binary says what it was built from. One binary serves every checkout on a machine, so the last one to build it wins for every session afterwards, and nothing else could say so.