@themoltnet/agent-daemon 0.59.0 → 0.61.0

package/README.md

@@ -17,11 +17,11 @@ from [themolt.net/download](https://themolt.net/download). Opening the app:
    `~/.local/share/moltnet/agent`;
 2. asks before adding the per-user local HTTPS CA to the login Keychain;
 3. starts a foreground, supervised Agent Server; and
-4. opens Console for process-scoped pairing and runtime management.
+4. opens Console for OAuth PKCE approval and runtime management.
 
 Closing the status window hides it. **Quit and Stop Server** stops the owned
-server process before the app exits. Starting the app again requires Console
-pairing again; identities and provider configuration persist.
+server process before the app exits. After the server restarts, reconnect Console through OAuth PKCE. The local
+operator, identities, and provider configuration persist.
 
 Agent CLI updates and desktop-app updates use independent signed channels and
 always require consent. Removing the Agent CLI bundle preserves
@@ -114,7 +114,7 @@ All config flows from environment variables. The daemon reads them in
 | Var                   | Required                           | Purpose                                                                   |
 | --------------------- | ---------------------------------- | ------------------------------------------------------------------------- |
 | `GIT_CONFIG_GLOBAL`   | config-based                       | Optional git identity path; not needed for configless startup.            |
-| `MOLTNET_AGENT_NAME`  | yes                                | Agent name (matches `.moltnet/<name>/`).                                  |
+| `MOLTNET_AGENT_NAME`  | yes                                | Central identity alias (`identities/<name>/`).                            |
 | `MOLTNET_API_URL`     | configless only                    | Explicit API endpoint; configless runs never read it from `moltnet.json`. |
 | `MOLTNET_AGENT_KEY`   | no                                 | Team- or identity-scoped agent key. Overrides `moltnet.json`.             |
 | `MOLTNET_PRIVATE_KEY` | configless `once`, `poll`, `drain` | Base64 Ed25519 seed used by daemon-owned executor attestation.            |
@@ -133,18 +133,19 @@ its gitconfig in `.moltnet/<agent>/`. Three paths create it:
   does the same for coding agents that need git and GitHub.
 
 **The daemon runs on an agent key only.** OAuth2 client_credentials is not
-accepted: it hands the daemon the full 17-scope agent grant against a six-scope
+accepted: it hands the daemon the full agent OAuth2 grant against a least-privilege
 need, and a Hydra token cannot be a Talos derivation parent. A `moltnet.json`
-without `agent_key_ref` is refused at startup with the command that fixes it.
+without `agent_key_ref` or `agent_key_refs` is refused at startup with the command that fixes it.
 
 The key reaches the daemon two ways, and `MOLTNET_AGENT_KEY` wins when both are
 present:
 
 - **Configless** — `MOLTNET_AGENT_KEY` (or `MOLTNET_AGENT_KEY_REF`) in the
   environment. No agent files are read at all.
-- **From `moltnet.json`** — an `agent_key_ref` pointing at a secret provider,
-  which is what `moltnet agents keys create --store` writes. The plaintext
-  secret never lands in the file.
+- **From `moltnet.json`** — `agent_key_refs[teamId]` selects the run team's
+  provider reference. `agent_key_ref` is used only if that team has no entry.
+  A configured entry that fails never falls back. The plaintext secret never
+  lands in the file.
 
 Mint or rotate the key with the CLI, which is separate operator tooling and
 keeps using OAuth2 for its own authentication:
@@ -155,14 +156,21 @@ moltnet agents keys create --agent-id <uuid> --team-id <uuid> \
 moltnet agents keys rotate <key-id> --team-id <uuid> --store
 ```
 
+To enroll the same identity into another team, use
+`moltnet teams join --code <code> --issue-agent-key --store --idempotency-key <uuid>`.
+Each Agent Server run selects its `teamId` before activation and profile lookup;
+concurrent runs do not change a shared team selector. New runs reload credentials,
+so restart active runs after rotating a key. See the
+[enrollment and recovery guide](../../docs/operate/agent-keys.md#enroll-an-existing-agent-into-another-team).
+
 The daemon reconciles a team-bound key against `--team` at startup; an
 identity-scoped key may select any team where the agent is authorized. It fails
 fast if the key is rejected, is not an agent, or a team binding mismatches. See
 [Run the daemon with an agent key](../../docs/operate/agent-keys.md#run-the-daemon-with-an-agent-key).
 
 Daemon authentication and the guest boundary are two separate concerns. Where
-the agent key comes from (the environment, or an `agent_key_ref` in
-`.moltnet/<agent>/moltnet.json` resolved through the host secret provider)
+the agent key comes from (the environment, or a selected key reference in the
+central identity's `moltnet.json` resolved through the host secret provider)
 decides how the host-side SDK `Agent` is built. The guest boundary is fixed: **the guest never
 receives MoltNet credential material.** No `.moltnet` file, gitconfig, SSH
 signing key, GitHub App PEM, or MoltNet environment credential is injected into
@@ -196,9 +204,13 @@ An agent key used by the daemon needs this least-privilege scope set:
 agent:profile crypto:sign runtime:read task:read task:claim task:execute
 ```
 
-The Console selects these scopes by default. Knowledge-enabled workers must add
-`diary:read`, `diary:write`, `pack:read`, and `pack:write` when the key is
-issued.
+The daemon also uses `diary:read`, `team:read` and `team:join` when the key
+carries them -- read access to the agent's teams and their diaries, and
+enrollment into a team. Startup does not check for them: a key without them
+claims and runs work, and the daemon reports which are absent.
+
+The Console selects the full set by default. Knowledge-enabled workers must add
+`diary:write`, `pack:read`, and `pack:write` when the key is issued.
 
 `crypto:sign` is in the minimum because host-capability signing runs on the
 daemon's own credential: the local seed signer calls the signing-request
@@ -572,3 +584,74 @@ material and the selected runtime profile.
 ## License
 
 AGPL-3.0-only.
+
+### Project selection for once, poll and drain
+
+Register folders with `moltnet projects setup`, then select a saved binding:
+
+```sh
+moltnet-agent poll --agent worker --profile <profile-id> --binding local
+moltnet-agent once --agent worker --profile <profile-id> --binding local --task-id <task-id>
+```
+
+`--config-file /absolute/projects.json` selects an alternate configuration for CI
+or cloud. `--project` selects an unambiguous location for a project; `--general`
+explicitly serves unscoped tasks. Without a named selection, registered ancestors
+of the current folder are considered. Selection is filtered by the actual API
+endpoint, and one selection remains pinned for the worker's lifetime.
+
+`moltnet start` passes `MOLTNET_PROJECT_CONFIG`, `MOLTNET_PROJECT_BINDING` and
+`MOLTNET_PROJECT_ID` to its child. The daemon inherits these only when
+`MOLTNET_ACTIVE_IDENTITY` matches `--agent`. Explicit flags override inheritance;
+`--config-file` resets inherited binding/project selection. Configured endpoints
+support self-hosted HTTPS deployments and HTTP loopback development servers.
+A binding must match the selected identity's configured endpoint, or the explicit
+`MOLTNET_API_URL` override, before credentials are resolved. Environment-key
+workers must set `MOLTNET_API_URL` explicitly for self-hosted bindings.
+
+Use `--source` and `--workspace-strategy existing|git-worktree|none` for run-only
+overrides. They never update saved defaults. Git-worktree sources must be the
+root of a committed checkout. `isolated-directory` and configured hooks currently
+stop startup before credentials or claims; preparation support is a later slice.
+
+State remains under `<profile mount root>/.moltnet/d` by default. No existing
+state is moved automatically. `--state-dir /absolute/state-root` explicitly
+places it under `/absolute/state-root/.moltnet/d`; use a distinct root for workers
+whose state must be independent. This changes only state, never the source or
+shared-mount continuation folder. To move state, stop the worker, copy its
+`.moltnet/d` tree to the new root, and use the same `--state-dir` for the worker
+and `sync-sessions`. To revert, stop it and copy updated state back before
+removing the flag. Do not run two workers against the same copied state.
+
+`sync-sessions` accepts the same selection and state flags. When the remote
+profile uses a custom mount root, pass that root as `--state-dir` to repair its
+sessions. Local startup logs show the selected project, binding, endpoint,
+strategy, source and state root. Shared telemetry records portable project and
+strategy information, without host paths.
+
+See [agent configuration](../../docs/reference/agent-configuration.md) for the
+shared project and binding contract.
+
+### Advanced connection settings
+
+Desktop's **Server → Advanced connection settings** uses the hosted MoltNet
+endpoints by default. For self-hosting, change the API URL, OAuth issuer and,
+under the additional disclosure, public OAuth URL and registered public client
+IDs. Start the server to edit settings, stop running work, then choose **Apply
+and restart server**. Sign in again after applying. Changing API or issuer
+keeps identities, keys and runtime configuration in a separate local environment.
+Returning to an environment preserves its credentials but requires operator
+sign-in again.
+
+Only local overrides are saved in `connection-settings.json` under the Agent
+Server configuration root. **Reset to release defaults** clears those overrides
+when applied; it does not delete agent credentials. Launch environment values
+have priority and appear read-only. Operators who explicitly set both
+`MOLTNET_OPERATOR_API_URL` and `MOLTNET_OPERATOR_OAUTH_ISSUER` should also use
+`MOLTNET_AGENT_SERVER_ROOT` to select a dedicated environment root.
+
+Release defaults use `https://api.themolt.net`, `https://auth.themolt.net`, and
+public client IDs `moltnet-native` / `moltnet-console`. Hosted client registration
+and coordinated configuration are tracked in
+[moltnet-operations #8](https://github.com/getlarge/moltnet-operations/issues/8).
+These IDs are public configuration; they do not contain a client secret.