@themoltnet/agent-daemon 0.53.0 → 0.55.0

package/README.md

@@ -81,31 +81,50 @@ All config flows from environment variables. The daemon reads them in
 
 ### MoltNet identity
 
-| Var                   | Required                              | Purpose                                                                    |
-| --------------------- | ------------------------------------- | -------------------------------------------------------------------------- |
-| `GIT_CONFIG_GLOBAL`   | OAuth2/local                          | Optional git identity path; not needed for configless agent-key startup.   |
-| `MOLTNET_AGENT_NAME`  | yes                                   | Agent name (matches `.moltnet/<name>/`).                                   |
-| `MOLTNET_API_URL`     | agent-key only                        | Explicit API endpoint; key mode never reads it from `moltnet.json`.        |
-| `MOLTNET_AGENT_KEY`   | no                                    | Team- or identity-scoped agent key. Set to authenticate instead of OAuth2. |
-| `MOLTNET_PRIVATE_KEY` | agent-key `once`, `poll`, and `drain` | Base64 Ed25519 seed used by daemon-owned executor attestation.             |
-
-For OAuth2/local mode, the agent's `moltnet.json` and gitconfig live next to
+| 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_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.            |
+
+For config-based runs, the agent's `moltnet.json` and gitconfig live next to
 each other in `.moltnet/<agent>/`. Provision them once via
 [`moltnet agents init`](../../docs/start/install-and-initialize.md#initialize-an-autonomous-agent).
 
-**Auth mode.** When `MOLTNET_AGENT_KEY` is set the daemon authenticates with
-that key as an opaque bearer token (no OAuth2 exchange); otherwise it uses the
-OAuth2 client-credentials from `moltnet.json`. The key is read from the
-environment only — never store it in `moltnet.json`. 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
+**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
+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.
+
+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.
+
+Mint or rotate the key with the CLI, which is separate operator tooling and
+keeps using OAuth2 for its own authentication:
+
+```bash
+moltnet agents keys create --agent-id <uuid> --team-id <uuid> \
+  --name <agent>-daemon --store
+moltnet agents keys rotate <key-id> --team-id <uuid> --store
+```
+
+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. How the
-daemon authenticates (an agent key, or OAuth2 resolved from
-`.moltnet/<agent>/moltnet.json` through the host secret provider) decides how the
-host-side SDK `Agent` is built. The guest boundary is fixed: **the guest never
+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)
+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
 Gondolin, and mounted `.moltnet` paths are hidden. Structured MoltNet tools

package/dist/cli.js

@@ -13,9 +13,9 @@ import { parseArgs, promisify } from "node:util";
 import { AgentRuntime, ApiTaskReporter, ApiTaskSource, PollingApiTaskSource, createLocalSeedSigner, resolveAgentIdentity, resolveProfileWarmSessionTtlSec, resolveRuntimeProfile, resolveRuntimeProfiles, validateRuntimeProfilePrerequisites } from "@themoltnet/agent-runtime";
 import { GuestEnvironmentBoundaryError, assertGuestEnvironmentBoundary, createPiRetryTriage, findMainWorktree, isResolvedPathInsideRoot, normalizeRetryTriageResult, redactRetryTriageSecrets, resolveRuntimeProfileModel } from "@themoltnet/pi-runtime";
 import { FILE_SECRET_PROVIDER, FileSecretProvider, connect, createNodeSecretProviderRegistry } from "@themoltnet/sdk/node";
-import { execFile, execFileSync, spawn } from "node:child_process";
 import { constants, createReadStream, createWriteStream, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
-import { AuthenticationError, MoltNetError, agentKeyKey, assertTrustedConfigApiUrl, createExecutorAttestor, deriveMcpUrl, formatSecretReferenceString, identitySeedKey, parseSecretReferenceString, readConfig, register, requireSecureCredentialApiUrl, resolveAgentKey, resolveEnvSecretReference, resolveIdentitySeed, resolveOAuth2ClientSecret } from "@themoltnet/sdk";
+import { AuthenticationError, IDENTITY_ALIAS_PATTERN, MoltNetError, agentKeyKey, assertIdentityAlias, assertTrustedConfigApiUrl, createExecutorAttestor, deriveMcpUrl, formatSecretReferenceString, getConfigDir, getIdentityDir, identitySeedKey, isCanonicalConfig, parseSecretReferenceString, readConfig, register, requireSecureCredentialApiUrl, resolveAgentKey, resolveEnvSecretReference, resolveIdentitySeed, resolveOAuth2ClientSecret } from "@themoltnet/sdk";
+import { execFile, spawn } from "node:child_process";
 import { X509Certificate, createHash, createPrivateKey, createPublicKey, randomBytes, randomUUID, timingSafeEqual, webcrypto } from "node:crypto";
 import { once } from "node:events";
 import { metrics } from "@opentelemetry/api";
@@ -36,13 +36,13 @@ import { lock, lockSync } from "proper-lockfile";
 import { ModelRuntime, readStoredCredential } from "@earendil-works/pi-coding-agent";
 import { Transform, Writable } from "node:stream";
 import { writePiConfig } from "@themoltnet/pi-runtime/pi-config";
-import { homedir, platform } from "node:os";
 import { pathToFileURL } from "node:url";
 import { StringDecoder } from "node:string_decoder";
 import rateLimit from "@fastify/rate-limit";
 import Fastify from "fastify";
 import { isIP } from "node:net";
 import "reflect-metadata";
+import { homedir, platform } from "node:os";
 import { BasicConstraintsExtension, ExtendedKeyUsage, ExtendedKeyUsageExtension, IP, KeyUsageFlags, KeyUsagesExtension, SubjectAlternativeNameExtension, X509CertificateGenerator } from "@peculiar/x509";
 import { createGzip } from "node:zlib";
 //#region ../../libs/tasks/src/rubric.ts
@@ -795,7 +795,14 @@ var AGENT_CREDENTIAL_SCOPES = [
 	CREDENTIAL_SCOPES.TaskExecute
 ];
 Object.freeze(ALL_CREDENTIAL_SCOPES.filter((scope) => scope !== CREDENTIAL_SCOPES.HumanProfile));
-[
+/**
+* REST capabilities exercised by the current MCP tool surface.
+*
+* Intentionally excludes connector invocation, key management, runtime
+* management/read, and task claiming because MCP exposes none of those
+* operations.
+*/
+var MCP_CLIENT_SCOPES = [
 	CREDENTIAL_SCOPES.AgentProfile,
 	CREDENTIAL_SCOPES.CryptoSign,
 	CREDENTIAL_SCOPES.DiaryManage,
@@ -809,7 +816,13 @@ Object.freeze(ALL_CREDENTIAL_SCOPES.filter((scope) => scope !== CREDENTIAL_SCOPE
 	CREDENTIAL_SCOPES.TaskRead,
 	CREDENTIAL_SCOPES.TeamManage,
 	CREDENTIAL_SCOPES.TeamRead
-].filter((scope) => scope !== CREDENTIAL_SCOPES.HumanProfile);
+];
+MCP_CLIENT_SCOPES.filter((scope) => scope !== CREDENTIAL_SCOPES.HumanProfile);
+Object.freeze([...[
+	"openid",
+	"offline",
+	"offline_access"
+], ...MCP_CLIENT_SCOPES]);
 //#endregion
 //#region ../../libs/models/src/preview-sign.ts
 function schemaRef$2(schema, id) {
@@ -1350,7 +1363,8 @@ Type.Object({ "x-moltnet-team-id": Type.Optional(Type.String({
 })) });
 Type.Object({
 	kind: Type.Literal("agent"),
-	identityId: UuidSchema,
+	agentId: UuidSchema,
+	identityId: Type.Union([UuidSchema, Type.Null()]),
 	fingerprint: FingerprintSchema,
 	publicKey: PublicKeySchema
 }, {
@@ -1367,7 +1381,8 @@ Type.Object({
 });
 var principalUnionVariants = [Type.Object({
 	kind: Type.Literal("agent"),
-	identityId: UuidSchema,
+	agentId: UuidSchema,
+	identityId: Type.Union([UuidSchema, Type.Null()]),
 	fingerprint: FingerprintSchema,
 	publicKey: PublicKeySchema
 }, { additionalProperties: false }), Type.Object({
@@ -3395,8 +3410,8 @@ var COMMON_OPTIONAL_FLAGS = `\
   --git-author <"Name <email>">
                               Non-secret git identity projected into the
                               guest for host-brokered commit signing. Default:
-                              host git config (OAuth2) or
-                              <identityId>+<agent>[bot]@users.noreply.github.com.
+                              host git config. Configless agent-key runs must
+                              provide this flag or MOLTNET_GIT_AUTHOR.
                               Env: MOLTNET_GIT_AUTHOR.
   --lease-ttl-sec <n>         Sliding liveness window. Silence longer than
                               this ends the attempt with lease_expired.
@@ -3451,9 +3466,19 @@ Commands:
 Run \`agent-daemon <command> --help\` for command-specific flags.
 
 Prerequisites:
-  - agent-key mode: MOLTNET_AGENT_KEY (or MOLTNET_AGENT_KEY_REF) and
+  - configless: MOLTNET_AGENT_KEY (or MOLTNET_AGENT_KEY_REF) and
     MOLTNET_PRIVATE_KEY (or MOLTNET_PRIVATE_KEY_REF); no agent files
-  - OAuth2 and sync-sessions: <agent-root>/.moltnet/<agent>/moltnet.json
+  - config-based and sync-sessions: <agent-root>/.moltnet/<agent>/moltnet.json
+    carrying agent_key_ref (OAuth2 client credentials are not accepted)
+
+No key yet? Mint one with the CLI (--store writes agent_key_ref into
+moltnet.json and keeps the secret in a provider):
+
+  moltnet teams list             # find the team id
+  moltnet agents keys create --team-id <team-uuid> \\
+    --name <agent>-daemon --store
+
+  https://docs.themolt.net/operate/agent-keys#run-the-daemon-with-an-agent-key
   - --profile — remote runtime profile supplies provider/model/sandbox
     policy and CWD is used as the VM mountPath.
 
@@ -3603,8 +3628,17 @@ remove that exact CA. Linux continues to use the Chromium PNA HTTP path.
 //#region src/lib/identity-pin.ts
 /** Compare every pinned field without choosing a caller-specific error type. */
 function assessIdentityPin(current, expected) {
+	for (const [field, label] of [["publicKey", "public key"], ["fingerprint", "fingerprint"]]) if (!current[field] || current[field] !== expected[field]) return {
+		ok: false,
+		field,
+		label
+	};
+	return { ok: true };
+}
+function assessAgentStartupPin(current, expected) {
 	for (const [field, label] of [
-		["identityId", "identity id"],
+		["subjectId", "subject id"],
+		["subjectType", "subject type"],
 		["publicKey", "public key"],
 		["fingerprint", "fingerprint"]
 	]) if (!current[field] || current[field] !== expected[field]) return {
@@ -3617,18 +3651,30 @@ function assessIdentityPin(current, expected) {
 //#endregion
 //#region src/lib/agent-context.ts
 /**
-* Report which auth mode `connect()` will use, without ever reading the secret
-* value into anything logged. Agent-key mode is selected when
-* `MOLTNET_AGENT_KEY` or `MOLTNET_AGENT_KEY_REF` holds a non-blank value —
-* mirroring the SDK precedence
-* where an environment key opts into key mode ahead of the config-file OAuth2
-* credentials. The daemon never passes explicit in-code credentials to
-* `connect()`, so this env-only check matches what `connect()` actually does.
+* Where an operator goes after the daemon refuses to start. The published site
+* rather than a GitHub blob: it renders, and it tracks the deployed docs
+* instead of whatever `main` happens to say. Sidebar entry lives in
+* `docs/.vitepress/config.ts`.
+*/
+var AGENT_KEYS_DOC_URL = "https://docs.themolt.net/operate/agent-keys#run-the-daemon-with-an-agent-key";
+/** Scopes a daemon key must carry; mirrors `DAEMON_REQUIRED_SCOPES`. */
+var DAEMON_KEY_SCOPES = AGENT_CREDENTIAL_SCOPES;
+/**
+* Report where `connect()` will find the key, without ever reading the secret
+* value into anything logged. A non-blank `MOLTNET_AGENT_KEY` or
+* `MOLTNET_AGENT_KEY_REF` means configless; otherwise the key comes from
+* `moltnet.json`. This mirrors the SDK precedence, where an environment key
+* wins over the config file.
+*
+* It reports the *source*, not what `connect()` would pick on its own: the
+* config path resolves the key and passes it explicitly, because ambient
+* resolution ranks environment OAuth2 credentials above a configured
+* `agent_key_ref` (see `resolveAgentContext`).
 *
 * Pure: `env` is passed in (the config module owns the `process.env` read).
 */
-function detectAuthMode(env) {
-	return env.MOLTNET_AGENT_KEY?.trim() || env.MOLTNET_AGENT_KEY_REF?.trim() ? "agent-key" : "oauth2";
+function detectCredentialSource(env) {
+	return env.MOLTNET_AGENT_KEY?.trim() || env.MOLTNET_AGENT_KEY_REF?.trim() ? "environment" : "config";
 }
 /**
 * Pure check: may the identity described by `whoami` operate the daemon as
@@ -3677,47 +3723,118 @@ async function validateStartupBinding(options) {
 	}
 	const assessment = assessStartupBinding(whoami, options.teamId);
 	if (!assessment.ok) throw new Error(`Daemon startup validation failed: ${assessment.reason}`);
-	const expected = options.expectedIdentity;
-	if (expected && !assessIdentityPin(whoami, expected).ok) throw new Error("Daemon startup validation failed: authenticated identity does not match the Agent Server activation.");
+	const expected = options.expectedAgent;
+	if (expected && !assessAgentStartupPin(whoami, expected).ok) throw new Error("Daemon startup validation failed: authenticated agent does not match the Agent Server activation.");
 	return whoami;
 }
 /**
 * Resolve the agent's MoltNet credentials directory and connect via SDK.
 *
-* Looks under an explicit agent root first, then falls back to the git root
-* when available. Fails fast if the dir is missing — credentials are required,
-* the daemon never falls back to unauthenticated calls.
+* The daemon selects the same central identity directory as the CLI. It never
+* inspects a repository, Git state, or legacy agent bundle for credentials.
 */
 async function resolveAgentContext(agentName, options = {}) {
-	if (!/^[a-zA-Z0-9_-]+$/.test(agentName)) throw new Error(`Invalid agent name "${agentName}": must match /^[a-zA-Z0-9_-]+$/`);
-	const roots = resolveCredentialRoots(options.agentRootDir);
-	if (options.authMode === "agent-key") {
-		const rootDir = roots[0] ?? process.cwd();
-		return {
-			agentDir: join(rootDir, ".moltnet", agentName),
-			agentRootDir: rootDir,
-			agent: await connect({ secretProviders: createNodeSecretProviderRegistry() }),
-			credentialSource: "environment",
-			authMechanism: "agent-key"
-		};
-	}
-	const located = locateAgentConfig(roots, agentName);
-	if (located) {
-		const agent = await connect({
-			configDir: located.agentDir,
-			secretProviders: createNodeSecretProviderRegistry()
-		});
-		const config = await readConfig(located.agentDir);
-		return {
-			agentDir: located.agentDir,
-			agentRootDir: located.rootDir,
-			agent,
-			credentialSource: "config",
-			authMechanism: config?.agent_key_ref ? "agent-key" : "oauth2"
+	assertIdentityAlias(agentName);
+	const { agentDir, agentRootDir } = resolveIdentityLocation(agentName, options.agentRootDir, { requireConfig: options.credentialSource !== "environment" });
+	if (options.credentialSource === "environment") return {
+		agentDir,
+		agentRootDir,
+		agent: await connect({ secretProviders: createNodeSecretProviderRegistry() }),
+		credentialSource: "environment"
+	};
+	const config = await readConfig(agentDir);
+	if (!config?.agent_key_ref) throw new Error(agentKeyRequiredMessage(agentDir, agentName));
+	const secretProviders = createNodeSecretProviderRegistry();
+	const agentKey = await resolveAgentKey(config, secretProviders);
+	if (!agentKey) throw new Error(agentKeyRequiredMessage(agentDir, agentName));
+	return {
+		agentDir,
+		agentRootDir,
+		agent: await connect({
+			configDir: agentDir,
+			secretProviders,
+			agentKey,
+			apiUrl: resolveConfigApiUrl(config, options.envApiUrl)
+		}),
+		credentialSource: "config"
+	};
+}
+/**
+* The daemon runs on an agent key only. A `moltnet.json` carrying OAuth2
+* client credentials but no `agent_key_ref` is the pre-#2160 shape, and
+* `connect()` would happily authenticate it — so this has to be refused here
+* rather than left to surface as an over-scoped token later.
+*/
+function agentKeyRequiredMessage(agentDir, agentName) {
+	return [
+		`${join(agentDir, "moltnet.json")} has no "agent_key_ref". The daemon`,
+		`requires a team-bound agent key; OAuth2 client_credentials is no longer`,
+		`accepted.`,
+		``,
+		`Mint one (--agent-id defaults to the agent you authenticate as):`,
+		``,
+		`  moltnet teams list             # find the team id`,
+		`  moltnet agents keys create \\`,
+		`    --team-id <team-uuid> \\`,
+		`    --name ${agentName}-daemon \\`,
+		`    --scopes ${DAEMON_KEY_SCOPES.join(",")} \\`,
+		`    --store`,
+		``,
+		`--store writes "agent_key_ref" into moltnet.json and keeps the secret in`,
+		`a provider, so the key itself never lands in the file. Omit --scopes to`,
+		`get the same daemon minimum by default.`,
+		``,
+		`To run configless instead, set MOLTNET_AGENT_KEY (or`,
+		`MOLTNET_AGENT_KEY_REF) and skip the config entirely.`,
+		``,
+		`Full guide: ${AGENT_KEYS_DOC_URL}`
+	].join("\n");
+}
+/**
+* The central identity directory, unless an explicit `--agent-root` names a
+* legacy bundle that actually exists.
+*
+* The flag is documented as "Directory that owns .moltnet/<agent>" and is still
+* accepted by `once`, `poll` and `sync-sessions`. Ignoring it silently sent
+* every caller that passes one — sandboxed runs, the e2e harness — to a
+* central store they never populated, and failed with a bare "No credentials
+* found".
+*/
+/**
+* `agentDir` is where credentials live; `agentRootDir` is the directory that
+* OWNS it and is mounted into the sandbox. They differ for a legacy bundle
+* (`<root>/.moltnet/<agent>` inside `<root>`) and coincide for a central
+* identity, which owns nothing above itself. Collapsing them mounted the
+* credentials directory itself into the guest.
+*/
+function resolveIdentityLocation(agentName, explicitRootDir, { requireConfig }) {
+	const root = explicitRootDir?.trim();
+	if (root) {
+		const bundle = join(root, ".moltnet", agentName);
+		if (!requireConfig || existsSync(join(bundle, "moltnet.json"))) return {
+			agentDir: bundle,
+			agentRootDir: root
 		};
 	}
-	const tried = roots.map((root) => join(root, ".moltnet", agentName));
-	throw new Error(`Missing credentials for ${agentName}. Checked ${tried.join(", ")}. Run the agent onboarding flow first.`);
+	const central = getIdentityDir(agentName);
+	return {
+		agentDir: central,
+		agentRootDir: central
+	};
+}
+/**
+* Pick the API URL for an explicitly-keyed connect, preserving the checks
+* ambient config resolution would have applied. An explicit `apiUrl` skips
+* ambient's own normalisation, so a URL taken from `moltnet.json` still has to
+* clear the config-trust and transport checks before it is used.
+*/
+function resolveConfigApiUrl(config, envApiUrl) {
+	if (envApiUrl?.trim()) return void 0;
+	const fromConfig = config.endpoints?.api?.trim();
+	if (!fromConfig) return void 0;
+	assertTrustedConfigApiUrl(fromConfig);
+	requireSecureCredentialApiUrl(fromConfig);
+	return fromConfig;
 }
 function isTransientWhoamiError(error) {
 	if (error instanceof TypeError) return true;
@@ -3725,26 +3842,6 @@ function isTransientWhoamiError(error) {
 	const statusCode = error.statusCode;
 	return typeof statusCode === "number" && (statusCode === 408 || statusCode === 429 || statusCode >= 500);
 }
-function locateAgentConfig(roots, agentName) {
-	for (const rootDir of roots) {
-		const agentDir = join(rootDir, ".moltnet", agentName);
-		if (existsSync(join(agentDir, "moltnet.json"))) return {
-			rootDir,
-			agentDir
-		};
-	}
-}
-function resolveCredentialRoots(agentRootDir) {
-	const roots = agentRootDir ? [agentRootDir] : [];
-	try {
-		const gitRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
-			encoding: "utf8",
-			stdio: "pipe"
-		}).trim();
-		if (!roots.includes(gitRoot)) roots.push(gitRoot);
-	} catch {}
-	return roots;
-}
 //#endregion
 //#region src/config.ts
 /**
@@ -3757,14 +3854,15 @@ function resolveCredentialRoots(agentRootDir) {
 function loadConfig() {
 	assertSingleCredentialForm("MOLTNET_AGENT_KEY", "MOLTNET_AGENT_KEY_REF");
 	assertSingleCredentialForm("MOLTNET_PRIVATE_KEY", "MOLTNET_PRIVATE_KEY_REF");
-	const expectedIdentity = readExpectedIdentity();
+	const expectedAgent = readExpectedAgent();
 	return {
 		otelEndpoint: process.env["MOLTNET_OTEL_ENDPOINT"] ?? "",
 		logLevel: process.env["LOG_LEVEL"] ?? "",
 		profilePrerequisiteEnv: process.env,
 		profilePrerequisitePath: process.env.PATH ?? "",
 		piCodingAgentDir: process.env["PI_CODING_AGENT_DIR"] ?? "",
-		authMode: detectAuthMode(process.env),
+		credentialSource: detectCredentialSource(process.env),
+		apiUrl: process.env["MOLTNET_API_URL"] ?? "",
 		signingPrivateKey: process.env["MOLTNET_PRIVATE_KEY"] ?? "",
 		signingPrivateKeyRef: process.env["MOLTNET_PRIVATE_KEY_REF"] ?? "",
 		gitAuthor: process.env["MOLTNET_GIT_AUTHOR"] ?? "",
@@ -3772,22 +3870,27 @@ function loadConfig() {
 		credentialBindings: process.env["MOLTNET_CREDENTIAL_BINDINGS"] ?? "",
 		credentialEnforcement: process.env["MOLTNET_CREDENTIAL_ENFORCEMENT"] ?? "",
 		traceIdlePolling: readBoolean("MOLTNET_TRACE_IDLE_POLLING", process.env["MOLTNET_TRACE_IDLE_POLLING"]),
-		...expectedIdentity ? { expectedIdentity } : {}
+		...expectedAgent ? { expectedAgent } : {}
 	};
 }
-function readExpectedIdentity() {
-	const identityId = process.env["MOLTNET_EXPECTED_IDENTITY_ID"]?.trim() ?? "";
+function readExpectedAgent() {
+	if (process.env["MOLTNET_EXPECTED_IDENTITY_ID"]?.trim()) throw new Error("MOLTNET_EXPECTED_IDENTITY_ID is no longer supported; set the complete MOLTNET_EXPECTED_SUBJECT_ID, MOLTNET_EXPECTED_SUBJECT_TYPE=agent, MOLTNET_EXPECTED_PUBLIC_KEY, and MOLTNET_EXPECTED_FINGERPRINT pin");
+	const subjectId = process.env["MOLTNET_EXPECTED_SUBJECT_ID"]?.trim() ?? "";
+	const subjectType = process.env["MOLTNET_EXPECTED_SUBJECT_TYPE"]?.trim() ?? "";
 	const publicKey = process.env["MOLTNET_EXPECTED_PUBLIC_KEY"]?.trim() ?? "";
 	const fingerprint = process.env["MOLTNET_EXPECTED_FINGERPRINT"]?.trim() ?? "";
 	const present = [
-		identityId,
+		subjectId,
+		subjectType,
 		publicKey,
 		fingerprint
 	].filter(Boolean).length;
 	if (present === 0) return void 0;
-	if (present !== 3) throw new Error("MOLTNET_EXPECTED_IDENTITY_ID, MOLTNET_EXPECTED_PUBLIC_KEY, and MOLTNET_EXPECTED_FINGERPRINT must be set together");
+	if (present !== 4) throw new Error("MOLTNET_EXPECTED_SUBJECT_ID, MOLTNET_EXPECTED_SUBJECT_TYPE, MOLTNET_EXPECTED_PUBLIC_KEY, and MOLTNET_EXPECTED_FINGERPRINT must be set together");
+	if (subjectType !== "agent") throw new Error("MOLTNET_EXPECTED_SUBJECT_TYPE must be agent");
 	return {
-		identityId,
+		subjectId,
+		subjectType,
 		publicKey,
 		fingerprint
 	};
@@ -3809,7 +3912,6 @@ function loadAgentServerEnvConfig() {
 		port: process.env["MOLTNET_AGENT_SERVER_PORT"] ?? "",
 		allowedOrigins: process.env["MOLTNET_AGENT_SERVER_ALLOWED_ORIGINS"] ?? "",
 		root: process.env["MOLTNET_AGENT_SERVER_ROOT"] ?? "",
-		xdgConfigHome: process.env["XDG_CONFIG_HOME"] ?? "",
 		apiUrl: process.env["MOLTNET_API_URL"] ?? "",
 		logLevel: process.env["LOG_LEVEL"] ?? ""
 	};
@@ -3839,13 +3941,13 @@ async function abortActiveAttemptOnSignal(opts) {
 //#region src/lib/agent-identity.ts
 /**
 * Build the non-secret identity projected into guests. Host git config is a
-* non-secret input and is consulted only on OAuth2 hosts, which already read
-* that configuration for the signing seed; configless agent-key hosts never
-* touch a config directory.
+* non-secret input and is consulted only on config-based hosts, which already
+* read that configuration for the signing seed; configless hosts never touch a
+* config directory.
 */
 async function resolveDaemonAgentIdentity(input) {
 	let hostGit;
-	if (input.gitAuthor === void 0 && input.authMode === "oauth2") {
+	if (input.gitAuthor === void 0 && input.credentialSource === "config") {
 		const config = await readConfig(input.agentDir);
 		hostGit = config?.git ? {
 			name: config.git.name,
@@ -4390,26 +4492,26 @@ function recoverScratchWorkspacePath(producer, stateDirs) {
 //#region src/lib/executor-attestation.ts
 var DAEMON_REQUIRED_SCOPES = AGENT_CREDENTIAL_SCOPES;
 async function resolveExecutorSigningPrivateKey(input) {
-	if (input.authMode === "agent-key") {
+	if (input.credentialSource === "environment") {
 		const privateKey = input.configuredPrivateKey.trim();
 		if (privateKey) return privateKey;
 		const reference = input.configuredPrivateKeyRef?.trim();
-		if (!reference) throw new Error("Agent-key daemon startup requires MOLTNET_PRIVATE_KEY (or MOLTNET_PRIVATE_KEY_REF) containing the base64-encoded Ed25519 private key seed.");
+		if (!reference) throw new Error("Configless daemon startup requires MOLTNET_PRIVATE_KEY (or MOLTNET_PRIVATE_KEY_REF) containing the base64-encoded Ed25519 private key seed.");
 		let resolved;
 		try {
 			resolved = await resolveEnvSecretReference(reference, createNodeSecretProviderRegistry());
 		} catch (cause) {
-			throw new Error(`Agent-key daemon startup could not resolve MOLTNET_PRIVATE_KEY_REF: ${cause.message}`, { cause });
+			throw new Error(`Configless daemon startup could not resolve MOLTNET_PRIVATE_KEY_REF: ${cause.message}`, { cause });
 		}
 		if (Buffer.from(resolved, "base64").length !== 32) throw new Error("MOLTNET_PRIVATE_KEY_REF must resolve to a base64-encoded 32-byte Ed25519 seed.");
 		return resolved;
 	}
 	const config = await readConfig(input.agentDir);
-	if (!config) throw new Error(`OAuth2 daemon startup requires ${input.agentDir}/moltnet.json.`);
+	if (!config) throw new Error(`Config-based daemon startup requires ${input.agentDir}/moltnet.json.`);
 	try {
 		return await resolveIdentitySeed(config, createNodeSecretProviderRegistry());
 	} catch (cause) {
-		throw new Error(`OAuth2 daemon startup could not resolve the signing seed from ${input.agentDir}/moltnet.json (keys.private_key or keys.private_key_ref): ${cause.message}`, { cause });
+		throw new Error(`Config-based daemon startup could not resolve the signing seed from ${input.agentDir}/moltnet.json (keys.private_key or keys.private_key_ref): ${cause.message}`, { cause });
 	}
 }
 function validateDaemonScopes(whoami) {
@@ -5105,7 +5207,7 @@ async function logDaemonStartupFailure(input) {
 		event: "agent-daemon.startup_failed",
 		gate: input.gate,
 		agent: input.agent,
-		authMode: input.authMode
+		credentialSource: input.credentialSource
 	}, "Agent daemon startup validation failed");
 	await shutdown();
 }
@@ -5924,23 +6026,24 @@ async function runPolling(opts) {
 		bindings: cfg.credentialBindings
 	};
 	const runtimeCredentialConfig = resolveCredentialEnforcement(cfg.credentialEnforcement, credentialSources) === "off" ? null : loadRuntimeCredentialConfig(credentialSources);
-	const agentRootDir = resolve(process.cwd(), values["agent-root"] ?? process.cwd());
+	const explicitAgentRootDir = values["agent-root"] ? resolve(process.cwd(), values["agent-root"]) : void 0;
 	const { ctx, signingPrivateKey, startupWhoami, agentIdentity, hostCapabilitySigner } = await (async () => {
 		let gate = "resolve_agent_context";
 		try {
 			const resolvedContext = await resolveAgentContext(baseCommon.agent, {
-				agentRootDir,
-				authMode: cfg.authMode
+				agentRootDir: explicitAgentRootDir,
+				credentialSource: cfg.credentialSource,
+				envApiUrl: cfg.apiUrl
 			});
 			gate = "authenticate_and_bind";
 			const whoami = await validateStartupBinding({
 				agent: resolvedContext.agent,
 				teamId,
-				expectedIdentity: cfg.expectedIdentity
+				expectedAgent: cfg.expectedAgent
 			});
 			gate = "resolve_signing_material";
 			const privateKey = await resolveExecutorSigningPrivateKey({
-				authMode: cfg.authMode,
+				credentialSource: cfg.credentialSource,
 				agentDir: resolvedContext.agentDir,
 				configuredPrivateKey: cfg.signingPrivateKey,
 				configuredPrivateKeyRef: cfg.signingPrivateKeyRef
@@ -5956,7 +6059,7 @@ async function runPolling(opts) {
 			const agentIdentity = await resolveDaemonAgentIdentity({
 				agentName: baseCommon.agent,
 				whoami,
-				authMode: cfg.authMode,
+				credentialSource: cfg.credentialSource,
 				agentDir: resolvedContext.agentDir,
 				gitAuthor: values["git-author"] ?? (cfg.gitAuthor || void 0)
 			});
@@ -5977,7 +6080,7 @@ async function runPolling(opts) {
 				level: cfg.logLevel || (baseCommon.debug ? "debug" : "info"),
 				gate,
 				agent: baseCommon.agent,
-				authMode: cfg.authMode,
+				credentialSource: cfg.credentialSource,
 				error
 			});
 			throw error;
@@ -6081,7 +6184,7 @@ async function runPolling(opts) {
 		resourceAttributes: {
 			"moltnet.team.id": teamId,
 			"moltnet.agent.name": baseCommon.agent,
-			"moltnet.auth.mode": ctx.authMechanism,
+			"moltnet.credential.source": ctx.credentialSource,
 			"moltnet.runtime_profile.count": String(profiles.length),
 			"moltnet.runtime_profile.ids": profiles.map((p) => p.id).join(",")
 		}
@@ -6129,7 +6232,7 @@ async function runPolling(opts) {
 		}
 	});
 	rootLogger.info({
-		authMode: cfg.authMode,
+		credentialSource: cfg.credentialSource,
 		subjectType: startupWhoami.subjectType,
 		bindingScope: startupWhoami.credentialBinding?.bindingScope ?? null,
 		credentialKeyId: startupWhoami.credentialBinding?.keyId ?? null,
@@ -6581,23 +6684,24 @@ async function runOnce(argv, runtimeAdapter = defaultPiDaemonAdapter) {
 	};
 	const runtimeCredentialConfig = resolveCredentialEnforcement(cfg.credentialEnforcement, credentialSources) === "off" ? null : loadRuntimeCredentialConfig(credentialSources);
 	const initialOpts = opts;
-	const agentRootDir = resolve(process.cwd(), values["agent-root"] ?? process.cwd());
+	const explicitAgentRootDir = values["agent-root"] ? resolve(process.cwd(), values["agent-root"]) : void 0;
 	const { ctx, signingPrivateKey, agentIdentity, hostCapabilitySigner } = await (async () => {
 		let gate = "resolve_agent_context";
 		try {
 			const resolvedContext = await resolveAgentContext(initialOpts.agent, {
-				agentRootDir,
-				authMode: cfg.authMode
+				agentRootDir: explicitAgentRootDir,
+				credentialSource: cfg.credentialSource,
+				envApiUrl: cfg.apiUrl
 			});
 			gate = "authenticate_and_bind";
 			const whoami = await validateStartupBinding({
 				agent: resolvedContext.agent,
 				teamId: values.team,
-				expectedIdentity: cfg.expectedIdentity
+				expectedAgent: cfg.expectedAgent
 			});
 			gate = "resolve_signing_material";
 			const privateKey = await resolveExecutorSigningPrivateKey({
-				authMode: cfg.authMode,
+				credentialSource: cfg.credentialSource,
 				agentDir: resolvedContext.agentDir,
 				configuredPrivateKey: cfg.signingPrivateKey,
 				configuredPrivateKeyRef: cfg.signingPrivateKeyRef
@@ -6613,7 +6717,7 @@ async function runOnce(argv, runtimeAdapter = defaultPiDaemonAdapter) {
 			const agentIdentity = await resolveDaemonAgentIdentity({
 				agentName: initialOpts.agent,
 				whoami,
-				authMode: cfg.authMode,
+				credentialSource: cfg.credentialSource,
 				agentDir: resolvedContext.agentDir,
 				gitAuthor: values["git-author"] ?? (cfg.gitAuthor || void 0)
 			});
@@ -6633,7 +6737,7 @@ async function runOnce(argv, runtimeAdapter = defaultPiDaemonAdapter) {
 				level: cfg.logLevel || (initialOpts.debug ? "debug" : "info"),
 				gate,
 				agent: initialOpts.agent,
-				authMode: cfg.authMode,
+				credentialSource: cfg.credentialSource,
 				error
 			});
 			throw error;
@@ -6703,7 +6807,7 @@ async function runOnce(argv, runtimeAdapter = defaultPiDaemonAdapter) {
 		resourceAttributes: {
 			"moltnet.task.id": taskId,
 			"moltnet.agent.name": opts.agent,
-			"moltnet.auth.mode": ctx.authMechanism,
+			"moltnet.credential.source": ctx.credentialSource,
 			"moltnet.llm.provider": profile.provider,
 			"moltnet.llm.model": profile.model,
 			...profile.thinkingLevel ? { "moltnet.llm.thinking_level": profile.thinkingLevel } : {},
@@ -7752,11 +7856,14 @@ function snapshot(login) {
 		...waitingForAuthorization ? { waitingForAuthorization } : {}
 	};
 }
-var NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+var NAME_RE = IDENTITY_ALIAS_PATTERN;
 var PROVIDER_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 function assertStoreName(kind, value) {
-	if (!NAME_RE.test(value)) throw new AgentServerStoreError("invalid_name", `${kind} must match ${NAME_RE.source}`);
-	return value;
+	try {
+		return assertIdentityAlias(value);
+	} catch {
+		throw new AgentServerStoreError("invalid_name", `${kind} must match ${NAME_RE.source}`);
+	}
 }
 function assertProviderId(value) {
 	if (!PROVIDER_ID_RE.test(value)) throw new AgentServerStoreError("invalid_name", `provider id must match ${PROVIDER_ID_RE.source}`);
@@ -7769,12 +7876,20 @@ var AgentServerStoreError = class extends Error {
 		this.code = code;
 	}
 };
-/** `MOLTNET_AGENT_SERVER_ROOT` override, else `$XDG_CONFIG_HOME/moltnet`, else `~/.config/moltnet`. */
+/**
+* `MOLTNET_AGENT_SERVER_ROOT` override, else `~/.config/moltnet`.
+*
+* Deliberately does NOT consult `XDG_CONFIG_HOME`. The Go CLI's GetConfigDir
+* and @moltnet/agent-config's getConfigDir both resolve `~/.config/moltnet`,
+* so honouring XDG here gave one application two config roots: on a machine
+* with the variable set, the daemon wrote identities the CLI and SDK could not
+* read. `MOLTNET_AGENT_SERVER_ROOT` remains the explicit escape hatch for a
+* genuinely custom location.
+*/
 function resolveAgentServerRoot(input) {
 	const override = input.root?.trim();
 	if (override) return override;
-	const xdg = input.xdgConfigHome?.trim();
-	return join(xdg || join(homedir(), ".config"), "moltnet");
+	return getConfigDir();
 }
 function providerEnvName(providerId) {
 	return `MOLTNET_PROVIDER_${assertProviderId(providerId).replaceAll("-", "_").toUpperCase()}_API_KEY`;
@@ -7812,14 +7927,14 @@ function writeJsonAtomic(path, value) {
 }
 var AgentServerStore = class {
 	root;
-	agentsDir;
+	identitiesDir;
 	runsDir;
 	secretsDir;
 	/** Shared Pi credential dir; `auth.json` inside is pi-managed (lockfiled). */
 	piDir;
 	constructor(root) {
 		this.root = root;
-		this.agentsDir = join(root, "agents");
+		this.identitiesDir = join(root, "identities");
 		this.runsDir = join(root, "runs");
 		this.secretsDir = join(root, "secrets");
 		this.piDir = join(root, "pi");
@@ -7831,7 +7946,7 @@ var AgentServerStore = class {
 	ensure() {
 		for (const dir of [
 			this.root,
-			this.agentsDir,
+			this.identitiesDir,
 			this.runsDir,
 			this.secretsDir
 		]) mkdirSync(dir, {
@@ -7846,20 +7961,20 @@ var AgentServerStore = class {
 	readAgentServerState() {
 		const state = readJson(this.statePath);
 		if (!state) return {
-			version: 1,
+			version: 2,
 			pendingRegistrations: {},
 			activations: {}
 		};
-		if (!isRecord$1(state) || state.version !== 1) throw new AgentServerStoreError("invalid_state", `agent-server.json version ${String(isRecord$1(state) ? state.version : void 0)} is not supported`);
-		if ("pairedOrigins" in state) throw new AgentServerStoreError("invalid_state", "agent-server.json uses the obsolete pairing format; clear the unreleased agent server store and reconfigure it");
-		if (!isRecord$1(state.pendingRegistrations) || !isRecord$1(state.activations)) throw new AgentServerStoreError("invalid_state", "agent-server.json is missing the version 1 activation map; clear the unreleased agent server store and reconfigure it");
+		if (!isRecord$1(state) || state.version !== 2) throw new AgentServerStoreError("invalid_state", `agent-server.json version ${String(isRecord$1(state) ? state.version : void 0)} is not supported; move agent-server.json aside, run \`moltnet config migrate\`, then add or attach the agents again`);
+		if ("pairedOrigins" in state) throw new AgentServerStoreError("invalid_state", "agent-server.json uses the obsolete pairing format; move agent-server.json aside and configure the agent server again");
+		if (!isRecord$1(state.pendingRegistrations) || !isRecord$1(state.activations)) throw new AgentServerStoreError("invalid_state", "agent-server.json is missing the version 2 activation map; move agent-server.json aside, run `moltnet config migrate`, then add or attach the agents again");
 		for (const [alias, activation] of Object.entries(state.activations)) validateActivation(alias, activation);
 		for (const [alias, registration] of Object.entries(state.pendingRegistrations)) {
 			assertStoreName("agent name", alias);
 			if (!isRecord$1(registration) || typeof registration.apiUrl !== "string" || registration.apiUrl.length === 0 || typeof registration.createdAt !== "string" || registration.createdAt.length === 0) throw new AgentServerStoreError("invalid_state", `pending registration "${alias}" is not valid`);
 		}
 		return {
-			version: 1,
+			version: 2,
 			pendingRegistrations: state.pendingRegistrations,
 			activations: state.activations
 		};
@@ -7868,16 +7983,58 @@ var AgentServerStore = class {
 		writeJsonAtomic(this.statePath, state);
 	}
 	agentPath(name) {
-		return storeChildPath(this.agentsDir, "agent name", name, ".json");
+		return join(storeChildPath(this.identitiesDir, "identity alias", name), "moltnet.json");
+	}
+	/** Central identity directory, shared with the Go CLI layout. */
+	identityDir(name) {
+		return storeChildPath(this.identitiesDir, "identity alias", name);
+	}
+	get identitySelectorPath() {
+		return join(this.root, "identity-selector.json");
+	}
+	readIdentitySelector() {
+		const selector = readJson(this.identitySelectorPath);
+		if (!selector) return null;
+		if (!isRecord$1(selector) || selector.version !== 1 || selector.default_identity !== void 0 && typeof selector.default_identity !== "string") throw new AgentServerStoreError("invalid_state", "identity-selector.json is not a supported selector document");
+		if (selector.default_identity) assertStoreName("identity alias", selector.default_identity);
+		return selector;
+	}
+	writeIdentitySelector(alias) {
+		writeJsonAtomic(this.identitySelectorPath, {
+			version: 1,
+			default_identity: assertStoreName("identity alias", alias)
+		});
+	}
+	resolveIdentityAlias(explicit, active) {
+		const alias = explicit?.trim() || active?.trim() || this.readIdentitySelector()?.default_identity;
+		if (!alias) throw new AgentServerStoreError("not_found", "no active identity selected");
+		return assertStoreName("identity alias", alias);
 	}
 	readAgentConfig(alias) {
 		return readJson(this.agentPath(alias));
 	}
 	writeAgentConfig(alias, config) {
+		mkdirSync(this.identityDir(alias), {
+			recursive: true,
+			mode: 448
+		});
 		writeJsonAtomic(this.agentPath(alias), config);
+		if (!this.readIdentitySelector()?.default_identity) this.writeIdentitySelector(alias);
 	}
 	removeAgentConfig(alias) {
 		rmSync(this.agentPath(alias), { force: true });
+		this.clearIdentitySelectorIfDefault(alias);
+	}
+	/** Clears the persisted default when it names `alias`. */
+	clearIdentitySelectorIfDefault(alias) {
+		let selector = null;
+		try {
+			selector = this.readIdentitySelector();
+		} catch {
+			return;
+		}
+		if (!selector || selector.default_identity !== alias) return;
+		writeJsonAtomic(this.identitySelectorPath, { version: 1 });
 	}
 	readActivation(alias) {
 		return this.readAgentServerState().activations[assertStoreName("agent name", alias)] ?? null;
@@ -8046,13 +8203,13 @@ function isStrictDescendant(root, candidate) {
 }
 function validateActivation(alias, value) {
 	const invalid = () => {
-		throw new AgentServerStoreError("invalid_state", `activation "${alias}" is not a valid version 1 activation`);
+		throw new AgentServerStoreError("invalid_state", `activation "${alias}" is not a valid version 2 activation`);
 	};
 	if (!isRecord$1(value)) invalid();
 	const activation = value;
 	if (activation.alias !== alias) invalid();
 	if (![
-		"identityId",
+		"subjectId",
 		"publicKey",
 		"fingerprint",
 		"createdAt"
@@ -8097,7 +8254,7 @@ async function createManagedAgent(store, secrets, input, connectAgent = connect)
 	const alias = assertStoreName("agent name", input.name);
 	if (!input.enrollmentToken.trim()) throw new AgentServerIdentityError("enrollment_required", "an enrollment token from the target team is required — a self-registered agent would be stranded in its own personal team");
 	const releaseAlias = reserveAlias(store, alias);
-	let registeredIdentityId;
+	let registered = false;
 	try {
 		let apiUrl;
 		try {
@@ -8114,18 +8271,19 @@ async function createManagedAgent(store, secrets, input, connectAgent = connect)
 		});
 		if (result.credentials.type !== "agent_key") throw new AgentServerIdentityError("unsupported_credential", `registration returned credential type "${result.credentials.type}"; agent server manages agent-key credentials only`);
 		const now = (/* @__PURE__ */ new Date()).toISOString();
-		const { identityId, fingerprint, publicKey, privateKey } = result.identity;
-		registeredIdentityId = identityId;
+		const { subjectId, fingerprint, publicKey, privateKey } = result.identity;
+		registered = true;
 		const agentKeyReference = {
 			provider: FILE_SECRET_PROVIDER,
-			key: agentKeyKey(identityId)
+			key: agentKeyKey(subjectId)
 		};
 		const seedReference = {
 			provider: FILE_SECRET_PROVIDER,
 			key: identitySeedKey(fingerprint)
 		};
 		const config = {
-			identity_id: identityId,
+			subject_id: subjectId,
+			subject_type: "agent",
 			registered_at: now,
 			agent_key_ref: agentKeyReference,
 			keys: {
@@ -8146,15 +8304,15 @@ async function createManagedAgent(store, secrets, input, connectAgent = connect)
 			apiUrl: result.apiUrl
 		}, store.agentPath(alias), input.signal);
 		assertIdentityMatches(whoami, {
-			identityId,
 			publicKey,
 			fingerprint
 		}, "authenticated whoami", `new managed agent "${alias}"`);
+		assertSubjectMatches(whoami, config, "authenticated whoami", `managed config ${store.agentPath(alias)}`);
 		const boundTeamId = boundTeamIdFromWhoami(whoami);
 		const activation = {
 			alias,
 			source: "managed",
-			identityId,
+			subjectId: whoami.subjectId,
 			publicKey,
 			fingerprint,
 			...boundTeamId ? { boundTeamId } : {},
@@ -8168,11 +8326,11 @@ async function createManagedAgent(store, secrets, input, connectAgent = connect)
 			...boundTeamId ? { boundTeamId } : {}
 		};
 	} catch (cause) {
-		if (!registeredIdentityId && cause instanceof MoltNetError && cause.statusCode !== void 0 && cause.statusCode >= 400 && cause.statusCode < 500) {
+		if (!registered && cause instanceof MoltNetError && cause.statusCode !== void 0 && cause.statusCode >= 400 && cause.statusCode < 500) {
 			store.clearPendingRegistration(alias);
 			throw new AgentServerIdentityError("registration_failed", registrationRejectionMessage(alias, cause), { cause });
 		}
-		if (store.hasPendingRegistration(alias)) throw new AgentServerIdentityError("registration_incomplete", registeredIdentityId ? `identity "${registeredIdentityId}" was registered but local activation is incomplete; reconcile or clear its pending Agent Server record before retrying` : `registration for "${alias}" may be incomplete; inspect the remote API before changing its pending Agent Server record`, { cause });
+		if (store.hasPendingRegistration(alias)) throw new AgentServerIdentityError("registration_incomplete", registered ? `the remote agent was registered but local activation is incomplete; reconcile or clear its pending Agent Server record before retrying` : `registration for "${alias}" may be incomplete; inspect the remote API before changing its pending Agent Server record`, { cause });
 		throw cause;
 	} finally {
 		releaseAlias();
@@ -8203,17 +8361,19 @@ async function reconcileManagedRegistration(store, secrets, aliasInput, action,
 	if (!config?.agent_key_ref || config.agent_key_ref.provider !== FILE_SECRET_PROVIDER || config.keys.private_key_ref?.provider !== FILE_SECRET_PROVIDER) throw new AgentServerIdentityError("registration_incomplete", `pending registration for "${alias}" does not have complete managed references`);
 	const [agentKey, privateKeyState] = await Promise.all([secrets.read(config.agent_key_ref.key), secrets.probe(config.keys.private_key_ref.key)]);
 	if (!agentKey || privateKeyState !== "present") throw new AgentServerIdentityError("registration_incomplete", `pending registration for "${alias}" is missing persisted secret material`);
-	const identity = identityFromConfig(config);
 	const apiUrl = requireConfigApiUrl(config, store.agentPath(alias));
 	const whoami = await callWhoami(connectAgent, {
 		agentKey,
 		apiUrl
 	}, store.agentPath(alias), signal);
+	assertSubjectMatches(whoami, config, "authenticated whoami", `pending registration "${alias}" config`);
+	const identity = identityFromConfig(config);
 	assertIdentityMatches(whoami, identity, "authenticated whoami", `pending registration "${alias}" config`);
 	const boundTeamId = boundTeamIdFromWhoami(whoami);
 	const recovered = {
 		alias,
 		source: "managed",
+		subjectId: whoami.subjectId,
 		...identity,
 		...boundTeamId ? { boundTeamId } : {},
 		createdAt: config.registered_at,
@@ -8239,10 +8399,12 @@ async function attachExternalAgent(store, secretProviders, input, connectAgent =
 		const whoami = await authenticateConfig(input.configDir, effectiveApiUrl, secretProviders, connectAgent, input.signal);
 		const identity = identityFromConfig(config);
 		assertIdentityMatches(identity, whoami, `external config ${configPath}`, "authenticated whoami");
+		assertSubjectMatches(whoami, config, "authenticated whoami", `external config ${configPath}`);
 		const boundTeamId = boundTeamIdFromWhoami(whoami);
 		const activation = {
 			alias,
 			source: "external",
+			subjectId: whoami.subjectId,
 			...identity,
 			...boundTeamId ? { boundTeamId } : {},
 			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -8260,15 +8422,26 @@ async function attachExternalAgent(store, secretProviders, input, connectAgent =
 		releaseAlias();
 	}
 }
-/** Load and authenticate the current config, then compare all pinned fields. */
+/** Load and authenticate the current config, then refresh its derived pin. */
 async function verifyAgentActivation(store, alias, managedSecretProviders, externalSecretProviders, connectAgent = connect, signal) {
 	const activation = requireActivation(store, alias);
 	const verified = activation.source === "managed" ? await verifyManagedActivation(store, activation, managedSecretProviders, connectAgent, signal) : await verifyExternalActivation(activation, externalSecretProviders, connectAgent, signal);
-	assertIdentityMatches(verified.whoami, activation, "authenticated whoami", `agent "${activation.alias}" pinned activation`);
+	assertSubjectMatches(verified.whoami, verified.config, "authenticated whoami", `agent "${activation.alias}" config`);
+	if (verified.whoami.subjectId !== activation.subjectId) throw new AgentServerIdentityError("verification_failed", `authenticated whoami subject does not match agent "${activation.alias}" pinned activation`);
+	const identity = identityFromConfig(verified.config);
+	assertIdentityMatches(verified.whoami, identity, "authenticated whoami", `agent "${activation.alias}" config`);
 	const boundTeamId = boundTeamIdFromWhoami(verified.whoami);
 	if (activation.boundTeamId !== boundTeamId) throw new AgentServerIdentityError("verification_failed", `authenticated whoami team binding does not match agent "${activation.alias}" pinned activation`);
+	const refreshed = {
+		...activation,
+		...identity
+	};
+	if (activation.publicKey !== refreshed.publicKey || activation.fingerprint !== refreshed.fingerprint) {
+		store.writeActivation(refreshed);
+		process.stderr.write(`agent-server: refreshed the authenticated signing identity for ${JSON.stringify(activation.alias)}\n`);
+	}
 	return {
-		activation,
+		activation: refreshed,
 		config: verified.config,
 		...boundTeamId ? { boundTeamId } : {}
 	};
@@ -8311,7 +8484,7 @@ function requireTrustedApiOverride(override, configApiUrl, configPath) {
 }
 function assertActivatedConfig(config, activation, configPath, currentApiUrl, pinnedApiUrl) {
 	if (currentApiUrl !== pinnedApiUrl) throw new AgentServerIdentityError("verification_failed", `agent config at ${configPath} API endpoint does not match its pinned activation`);
-	assertIdentityMatches(identityFromConfig(config), activation, configPath, `agent "${activation.alias}" pinned activation`);
+	if (config.subject_id !== activation.subjectId) throw new AgentServerIdentityError("verification_failed", `agent config at ${configPath} subject does not match its pinned activation`);
 }
 function requireConfigApiUrl(config, configPath) {
 	const apiUrl = config?.endpoints?.api?.trim();
@@ -8383,16 +8556,18 @@ function boundedIdentitySignal(signal) {
 	return signal ? AbortSignal.any([signal, timeout]) : timeout;
 }
 function identityFromConfig(config) {
-	const identityId = config?.identity_id?.trim();
 	const publicKey = config?.keys?.public_key?.trim();
 	const fingerprint = config?.keys?.fingerprint?.trim();
-	if (!identityId || !publicKey || !fingerprint) throw new AgentServerIdentityError("verification_failed", "agent config is missing canonical identity_id, keys.public_key, or keys.fingerprint");
+	if (!publicKey || !fingerprint) throw new AgentServerIdentityError("verification_failed", "agent config is missing keys.public_key or keys.fingerprint");
 	return {
-		identityId,
 		publicKey,
 		fingerprint
 	};
 }
+function assertSubjectMatches(current, expected, currentLabel, expectedLabel) {
+	if (!isCanonicalConfig(expected)) throw new AgentServerIdentityError("verification_failed", `${expectedLabel} is missing canonical subject_type=agent and subject_id; run \`moltnet config migrate\` first`);
+	if (current.subjectType !== "agent" || current.subjectId !== expected.subject_id) throw new AgentServerIdentityError("verification_failed", `${currentLabel} subject does not match ${expectedLabel}`);
+}
 function assertIdentityMatches(current, expected, currentLabel, expectedLabel) {
 	const assessment = assessIdentityPin(current, expected);
 	if (!assessment.ok) throw new AgentServerIdentityError("verification_failed", `${currentLabel} ${assessment.label} does not match ${expectedLabel}`);
@@ -8407,7 +8582,7 @@ function publicAgentView(store, activation) {
 		return {
 			kind: "managed",
 			agentName: activation.alias,
-			identityId: activation.identityId,
+			subjectId: activation.subjectId,
 			fingerprint: activation.fingerprint,
 			...activation.boundTeamId ? { teamId: activation.boundTeamId } : {},
 			apiUrl: activation.apiUrl,
@@ -8421,7 +8596,7 @@ function publicAgentView(store, activation) {
 		agentName: activation.alias,
 		configDir: dirname(activation.configPath),
 		...activation.apiUrl ? { apiUrl: activation.apiUrl } : {},
-		identityId: activation.identityId,
+		subjectId: activation.subjectId,
 		fingerprint: activation.fingerprint,
 		...activation.boundTeamId ? { teamId: activation.boundTeamId } : {},
 		createdAt: activation.createdAt
@@ -8567,7 +8742,8 @@ var RunManager = class {
 				throw new AgentServerRunError("invalid_spec", `external credentials for "${activation.alias}" could not be projected`);
 			}
 		}
-		env["MOLTNET_EXPECTED_IDENTITY_ID"] = activation.identityId;
+		env["MOLTNET_EXPECTED_SUBJECT_ID"] = activation.subjectId;
+		env["MOLTNET_EXPECTED_SUBJECT_TYPE"] = "agent";
 		env["MOLTNET_EXPECTED_PUBLIC_KEY"] = activation.publicKey;
 		env["MOLTNET_EXPECTED_FINGERPRINT"] = activation.fingerprint;
 		env["MOLTNET_SUPERVISED_RUN"] = "1";
@@ -9224,7 +9400,7 @@ var AgentServerProblemSchema = Type.Object({
 var AgentServerAgentSchema = Type.Object({
 	kind: Type.Union([Type.Literal("managed"), Type.Literal("external")]),
 	agentName: Type.String(),
-	identityId: Type.Optional(Type.String()),
+	subjectId: Type.String(),
 	fingerprint: Type.Optional(Type.String()),
 	apiUrl: Type.Optional(Type.String()),
 	teamId: Type.Optional(Type.String()),
@@ -10387,10 +10563,7 @@ async function runAgentServer(argv) {
 		return 1;
 	}
 	const allowedOrigins = parseAllowedOrigins(values["allowed-origins"] ?? (envConfig.allowedOrigins || DEFAULT_ALLOWED_ORIGINS));
-	const root = values.root ?? resolveAgentServerRoot({
-		root: envConfig.root,
-		xdgConfigHome: envConfig.xdgConfigHome
-	});
+	const root = values.root ?? resolveAgentServerRoot({ root: envConfig.root });
 	const defaultApiUrl = values["api-url"] ?? (envConfig.apiUrl || DEFAULT_API_URL);
 	const store = new AgentServerStore(root).ensure();
 	if (trustRequested) return runTrustCommand(commandArgs, root);
@@ -10686,7 +10859,13 @@ async function runSyncSessions(argv) {
 	const state = parseState(values.state);
 	const limit = parseLimit(values.limit);
 	const agentRootDir = resolve(process.cwd(), values["agent-root"] ?? process.cwd());
-	const ctx = await resolveAgentContext(opts.agent, { agentRootDir });
+	const explicitAgentRootDir = values["agent-root"] ? resolve(process.cwd(), values["agent-root"]) : void 0;
+	const cfg = loadConfig();
+	const ctx = await resolveAgentContext(opts.agent, {
+		credentialSource: cfg.credentialSource,
+		envApiUrl: cfg.apiUrl,
+		agentRootDir: explicitAgentRootDir
+	});
 	await validateStartupBinding({
 		agent: ctx.agent,
 		teamId: values.team
@@ -10721,18 +10900,51 @@ function parseLimit(raw) {
 }
 //#endregion
 //#region src/lib/update.ts
-var UPDATE_MANIFEST_URL = "https://themolt.net/download/manifest.json";
+/**
+* `npm install -g @themoltnet/agent-daemon@latest` resolves the registry's own
+* dist-tag, so for an npm install the registry is the precise answer — the
+* manifest serves the themolt.net pin, which gates the bundle installer's
+* default and says nothing about what npm already has. It is also the origin an
+* npm install already talks to, so this adds no new dependency in CI, where the
+* daemon runs as `npx @themoltnet/agent-daemon` and would otherwise reach for
+* api.github.com from shared runner IPs.
+*
+* Bundle and direct installs ask the release listing, and their upgrade command
+* passes `MOLTNET_AGENT_VERSION=latest` so the installer resolves the same thing
+* rather than falling back to its own pinned default. Reporting the pin here
+* would hide releases that are already downloadable; reporting the release
+* without the sentinel would advertise a version the command could not deliver.
+* The pin still governs a fresh `curl .../install/agent | sh`.
+*/
+var UPDATE_RELEASES_URL = "https://api.github.com/repos/getlarge/themoltnet/releases?per_page=100";
+var RELEASE_TAG_PREFIX = "agent-daemon-v";
+var UPDATE_NPM_REGISTRY_URL = "https://registry.npmjs.org/@themoltnet/agent-daemon/latest";
 var UPDATE_CACHE_TTL_MS = 1440 * 60 * 1e3;
 var UPDATE_ERROR_CACHE_TTL_MS = 300 * 1e3;
+/**
+* Node does not resolve `process.argv[1]`: invoked through npm's bin shim it
+* reports `/usr/local/bin/moltnet-agent`, not the `node_modules` path this
+* matches on. Every global npm install therefore looked like `direct` and was
+* offered the bundle installer, which would drop a bundle on top of an npm
+* install. Resolve first; a missing path falls back to the input.
+*/
+function resolveDaemonExecutable(executable) {
+	if (!executable) return executable;
+	try {
+		return realpathSync(executable);
+	} catch {
+		return executable;
+	}
+}
 function detectDaemonInstallMethod(executable = process.argv[1] ?? "") {
-	const path = executable.replaceAll("\\", "/");
+	const path = resolveDaemonExecutable(executable).replaceAll("\\", "/");
 	if (path.includes("/node_modules/@themoltnet/agent-daemon/")) return "npm";
 	if (path.includes("/.local/share/moltnet/") || path.includes("/opt/moltnet/")) return "bundle";
 	return "direct";
 }
 function daemonUpdateCommand(method) {
 	if (method === "npm") return "npm install -g @themoltnet/agent-daemon@latest";
-	return "curl -fsSL https://themolt.net/install/agent | sh";
+	return "curl -fsSL https://themolt.net/install/agent | MOLTNET_AGENT_VERSION=latest sh";
 }
 async function checkDaemonUpdate(input) {
 	const installMethod = detectDaemonInstallMethod(input.executable ?? process.argv[1] ?? "moltnet-agent");
@@ -10753,11 +10965,15 @@ async function checkDaemonUpdate(input) {
 			return result;
 		}
 	}
+	const viaNpm = installMethod === "npm";
+	const source = viaNpm ? UPDATE_NPM_REGISTRY_URL : UPDATE_RELEASES_URL;
+	const label = viaNpm ? "npm registry" : "release listing";
 	try {
-		const response = await (input.fetchFn ?? fetch)(UPDATE_MANIFEST_URL, { signal: AbortSignal.timeout(5e3) });
-		if (!response.ok) throw new Error(`manifest returned HTTP ${response.status}`);
-		const latest = manifestVersion(await response.json());
-		if (!latest) throw new Error("manifest has no valid agent version");
+		const response = await (input.fetchFn ?? fetch)(source, { signal: AbortSignal.timeout(5e3) });
+		if (!response.ok) throw new Error(`${label} returned HTTP ${response.status}`);
+		const body = await response.json();
+		const latest = viaNpm ? distTagVersion(body) : newestReleaseVersion(body);
+		if (!latest) throw new Error(`${label} has no valid agent version`);
 		await writeCache({
 			checkedAt: now.toISOString(),
 			latest
@@ -10773,13 +10989,31 @@ async function checkDaemonUpdate(input) {
 		throw new Error(`could not check for MoltNet agent updates: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }
-function manifestVersion(value) {
+function distTagVersion(value) {
 	if (!value || typeof value !== "object") return void 0;
-	const agent = value.agent;
-	if (!agent || typeof agent !== "object") return void 0;
-	const version = agent.version;
+	const version = value.version;
 	return typeof version === "string" && validVersion(version) ? normalizeVersion(version) : void 0;
 }
+/**
+* The listing is ordered by creation date, not version, so compare every
+* candidate rather than trusting position. Drafts are filtered explicitly:
+* unauthenticated callers never see them, but a token would, and this
+* repository carries stuck drafts that would otherwise look newest.
+*/
+function newestReleaseVersion(value) {
+	if (!Array.isArray(value)) return void 0;
+	let newest;
+	for (const entry of value) {
+		if (!entry || typeof entry !== "object") continue;
+		const { tag_name: tag, draft, prerelease } = entry;
+		if (draft === true || prerelease === true) continue;
+		if (typeof tag !== "string" || !tag.startsWith(RELEASE_TAG_PREFIX)) continue;
+		const candidate = tag.slice(14);
+		if (!validVersion(candidate)) continue;
+		if (!newest || compareVersions(candidate, newest) > 0) newest = normalizeVersion(candidate);
+	}
+	return newest;
+}
 function normalizeVersion(value) {
 	return value.trim().replace(/^v/, "");
 }
@@ -10819,7 +11053,7 @@ async function writeCache(cache) {
 }
 //#endregion
 //#region src/version.ts
-var DAEMON_VERSION = "0.53.0";
+var DAEMON_VERSION = "0.55.0";
 //#endregion
 //#region src/cli.ts
 async function runAgentDaemonCli(options) {
@@ -10877,11 +11111,7 @@ async function runUpdate(argv) {
 	}
 }
 async function runRuntime(argv) {
-	const config = loadAgentServerEnvConfig();
-	const registry = new RuntimeRegistry(resolveAgentServerRoot({
-		root: config.root,
-		xdgConfigHome: config.xdgConfigHome
-	}));
+	const registry = new RuntimeRegistry(resolveAgentServerRoot({ root: loadAgentServerEnvConfig().root }));
 	const [command, ...rest] = argv;
 	if (command === "list") {
 		console.log(JSON.stringify(registry.list(), null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/agent-daemon",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "license": "AGPL-3.0-only",
   "type": "module",
   "description": "Universal MoltNet agent daemon host with a built-in Pi/Gondolin runtime and support for trusted operator-owned runtime modules. CLI: moltnet-agent.",
@@ -85,10 +85,10 @@
     "proper-lockfile": "4.1.2",
     "reflect-metadata": "^0.2.2",
     "typebox": "^1.2.8",
-    "@themoltnet/agent-runtime": "0.45.3",
+    "@themoltnet/agent-runtime": "1.0.0",
+    "@themoltnet/pi-runtime": "0.15.0",
     "@themoltnet/os-keyring": "0.3.0",
-    "@themoltnet/pi-runtime": "0.14.2",
-    "@themoltnet/sdk": "0.140.1"
+    "@themoltnet/sdk": "0.141.0"
   },
   "devDependencies": {
     "@fastify/swagger": "^9.6.1",
@@ -98,16 +98,16 @@
     "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^3.0.0",
-    "@moltnet/agent-eval": "0.1.0",
+    "@moltnet/bootstrap": "0.1.0",
     "@moltnet/crypto-service": "0.1.0",
     "@moltnet/execution-integrations": "0.1.0",
-    "@moltnet/bootstrap": "0.1.0",
+    "@moltnet/agent-eval": "0.1.0",
     "@moltnet/execution-plan": "0.1.0",
+    "@moltnet/loopback-companion": "0.1.0",
     "@moltnet/models": "0.1.0",
+    "@moltnet/tasks": "0.1.0",
     "@moltnet/observability": "0.1.0",
-    "@moltnet/loopback-companion": "0.1.0",
-    "@moltnet/runtime-profiles": "0.1.0",
-    "@moltnet/tasks": "0.1.0"
+    "@moltnet/runtime-profiles": "0.1.0"
   },
   "nx": {
     "projectType": "application",
@@ -132,6 +132,14 @@
           "cwd": "{workspaceRoot}",
           "command": "node tools/release/agent-bundle/build.mjs --skip-daemon-build --out dist/agent-bundle"
         }
+      },
+      "test": {
+        "inputs": [
+          "default",
+          "^production",
+          "{workspaceRoot}/docs/operate/*.md",
+          "{workspaceRoot}/docs/.vitepress/config.ts"
+        ]
       }
     }
   },