@ory/argus 0.14.0 → 1.0.1

package/dist/agent-auth.js

@@ -4,48 +4,161 @@
  *
  * The "agent" is the AI process making calls on behalf of the human
  * user. Unlike the user, the agent never authenticates interactively.
- * The default path is **OAuth2 Dynamic Client Registration (RFC 7591)**:
- * on first run the agent registers itself with the project's
- * `/oauth2/register` endpoint, authenticated by the user's bearer token
- * (or an out-of-band initial access token), and persists the issued
- * credentials so subsequent runs reuse them.
+ * The normal path resolves a noninteractive runtime credential: an injected
+ * request authenticator, `ORY_AGENT_API_KEY`, or a Talos key enrolled with the
+ * already-authenticated user. Enrolled keys remain process-local.
  *
- * Resolution order:
- *
- *   1. ORY_AGENT_API_KEY                  — explicit static bearer
- *   2. ORY_AGENT_CLIENT_ID +
- *      ORY_AGENT_CLIENT_SECRET           — explicit static client_credentials
- *   3. Persisted dynamic credentials      — reuse a prior DCR registration
- *   4. Fresh dynamic registration         — POST /oauth2/register using the
- *                                            user's bearer or
- *                                            ORY_AGENT_REGISTRATION_TOKEN
- *   5. ORY_API_KEY (deprecated)          — alias for ORY_AGENT_API_KEY
- *   6. <none>                            — fail-open; plugin runs without
- *                                            agent identity in audit logs
- *
- * Token-exchange (RFC 8693) — deriving an agent token whose `sub` is
- * the user with an `act` claim showing the agent — is intentionally
- * deferred.
+ * Legacy DCR and client-credentials helpers remain exported temporarily so the
+ * monorepo and existing consumers compile, but the normal gates do not select
+ * them.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = void 0;
+exports.DEFAULT_SESSION_RETENTION = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = void 0;
+exports.resolveRuntimeAgentCredentials = resolveRuntimeAgentCredentials;
 exports._resetAgentCredentialsCache = _resetAgentCredentialsCache;
+exports.invalidateAgentAccessToken = invalidateAgentAccessToken;
 exports.loadSubAgentDynamicCredentials = loadSubAgentDynamicCredentials;
+exports.loadAllSubAgentDynamicCredentials = loadAllSubAgentDynamicCredentials;
+exports.loadSubAgentDynamicCredentialsByHarness = loadSubAgentDynamicCredentialsByHarness;
 exports.saveSubAgentDynamicCredentials = saveSubAgentDynamicCredentials;
 exports.clearSubAgentDynamicCredentials = clearSubAgentDynamicCredentials;
+exports.clearSubAgentDynamicCredentialsForHarness = clearSubAgentDynamicCredentialsForHarness;
 exports.loadAgentDynamicCredentials = loadAgentDynamicCredentials;
+exports.loadAgentDynamicCredentialsByHarness = loadAgentDynamicCredentialsByHarness;
 exports.saveAgentDynamicCredentials = saveAgentDynamicCredentials;
 exports.clearAgentDynamicCredentials = clearAgentDynamicCredentials;
+exports.latestAgentRegistration = latestAgentRegistration;
+exports.latestSubAgentSession = latestSubAgentSession;
+exports.countAgentSessions = countAgentSessions;
+exports.loadDelegationNodeId = loadDelegationNodeId;
+exports.saveDelegationNodeId = saveDelegationNodeId;
+exports.loadRetiredCredentials = loadRetiredCredentials;
+exports.clearRetiredCredentials = clearRetiredCredentials;
+exports.sessionRetention = sessionRetention;
+exports.retireAgentSessions = retireAgentSessions;
+exports.claimAgentDynamicCredentials = claimAgentDynamicCredentials;
+exports.claimSubAgentDynamicCredentials = claimSubAgentDynamicCredentials;
 exports.revokeAgentDynamicClient = revokeAgentDynamicClient;
 exports.registerAgentClient = registerAgentClient;
 exports.resolveAgentCredentials = resolveAgentCredentials;
 exports.fetchClientCredentialsToken = fetchClientCredentialsToken;
 exports.ensureAgentIdentity = ensureAgentIdentity;
 exports.ensureSubAgentIdentity = ensureSubAgentIdentity;
+const promises_1 = require("node:fs/promises");
 const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const promises_2 = require("node:timers/promises");
 const client_1 = require("@ory/client");
 const config_js_1 = require("./config.js");
 const branding_js_1 = require("./branding.js");
+const subject_js_1 = require("./subject.js");
+const runtime_credential_js_1 = require("./runtime-credential.js");
+const ENROLLMENT_LOCK_STALE_MS = 120_000;
+const ENROLLMENT_LOCK_WAIT_MS = 35_000;
+async function withEnrollmentLock(identity, work) {
+    const lockRoot = (0, node_path_1.join)((0, config_js_1.getDataDir)(), "runtime-credential-locks");
+    const lockPath = (0, node_path_1.join)(lockRoot, `${(0, runtime_credential_js_1.credentialAccount)(identity)}.lock`);
+    await (0, promises_1.mkdir)(lockRoot, { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + ENROLLMENT_LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            await (0, promises_1.mkdir)(lockPath, { mode: 0o700 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            try {
+                const info = await (0, promises_1.stat)(lockPath);
+                if (Date.now() - info.mtimeMs > ENROLLMENT_LOCK_STALE_MS) {
+                    await (0, promises_1.rm)(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch (statError) {
+                if (statError.code === "ENOENT")
+                    continue;
+                throw statError;
+            }
+            if (Date.now() >= deadline)
+                throw new Error("Timed out waiting for runtime enrollment");
+            await (0, promises_2.setTimeout)(50);
+        }
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await (0, promises_1.rm)(lockPath, { recursive: true, force: true });
+    }
+}
+/**
+ * Resolve the runtime credential used by the normal Agent Security path.
+ * This intentionally does not inspect OAuth client credentials or persisted DCR.
+ */
+async function resolveRuntimeAgentCredentials(options = {}) {
+    const env = options.env ?? process.env;
+    const subject = options.subject ?? (0, subject_js_1.readAgentSubjectOverride)(env, []);
+    const injected = options.runtimeCredential?.kind === "injected"
+        ? options.runtimeCredential
+        : (0, runtime_credential_js_1.resolveRuntimeCredential)({
+            env: {},
+            requestAuthenticator: options.requestAuthenticator,
+            subject,
+            fetch: options.fetchImpl,
+        });
+    const configured = (0, runtime_credential_js_1.resolveRuntimeCredential)({ env, subject, fetch: options.fetchImpl });
+    const existing = injected ?? configured
+        ?? (options.runtimeCredential?.kind === "talos" ? options.runtimeCredential : undefined);
+    if (existing) {
+        return {
+            kind: existing.kind,
+            runtimeCredential: existing,
+            subject: existing.subject,
+            reason: existing.kind === "talos"
+                ? "Using Talos runtime credential"
+                : "Using injected runtime request authenticator",
+            warnings: [],
+        };
+    }
+    if (options.projectUrl) {
+        try {
+            const store = options.credentialStore ?? (0, runtime_credential_js_1.createOsTalosCredentialStore)();
+            const stored = await store.load({
+                projectUrl: options.projectUrl,
+                harness: options.harness?.trim() || config_js_1.UNKNOWN_HARNESS_KEY,
+                sessionId: options.sessionId?.trim() || config_js_1.SESSIONLESS_KEY,
+                kind: "agent",
+            });
+            if (stored) {
+                return {
+                    kind: "talos",
+                    runtimeCredential: (0, runtime_credential_js_1.talosRuntimeCredential)(stored.credential, {
+                        subject: stored.actorId,
+                        fetch: options.fetchImpl,
+                    }),
+                    subject: stored.actorId,
+                    reason: "Using Talos runtime credential from the OS credential store",
+                    warnings: [],
+                };
+            }
+        }
+        catch {
+            return {
+                kind: "none",
+                reason: "No noninteractive runtime credential is configured",
+                warnings: [
+                    "Could not read the Talos runtime credential from the OS credential store",
+                ],
+            };
+        }
+    }
+    return {
+        kind: "none",
+        reason: "No noninteractive runtime credential is configured",
+        warnings: [],
+    };
+}
 /**
  * Skew window before nominal expiry at which a cached client_credentials
  * token is considered stale. Matches the user-token skew in auth-store.
@@ -56,67 +169,409 @@ const ccCache = new Map();
 function _resetAgentCredentialsCache() {
     ccCache.clear();
 }
-// ─── Sub-agent persistence ───────────────────────────────────────────
-/** Load persisted sub-agent DCR credentials keyed by sub-agent type. */
-function loadSubAgentDynamicCredentials(subAgentType) {
-    return (0, config_js_1.loadConfig)().agent?.subAgents?.[subAgentType];
+/** Evict a bearer rejected by Agent Security without disturbing other sessions. */
+function invalidateAgentAccessToken(rejectedToken) {
+    for (const [key, cached] of ccCache) {
+        if (cached.token === rejectedToken)
+            ccCache.delete(key);
+    }
+}
+// ─── Credential persistence ──────────────────────────────────────────
+//
+// `dynamic` is keyed by harness then session. `subAgents` adds the sub-agent
+// type below the session. Processes handling different hooks in one session
+// converge on the same credential through the config lock; another session
+// receives a different DCR client.
+/** Load persisted sub-agent DCR credentials for one harness + type. */
+function loadSubAgentDynamicCredentials(harness, sessionOrType, subAgentType) {
+    const sessionKey = subAgentType === undefined ? config_js_1.SESSIONLESS_KEY : sessionOrType;
+    const type = subAgentType ?? sessionOrType;
+    return (0, config_js_1.loadConfig)().agent?.subAgents?.[harness]?.[sessionKey]?.[type];
 }
-/** Persist sub-agent DCR credentials under the given type key. */
-function saveSubAgentDynamicCredentials(subAgentType, creds) {
+/**
+ * Load one harness's persisted sub-agent registrations, keyed by sub-agent type.
+ * Returns an empty object when none have been registered. Used by the status
+ * report to enumerate the sub-agent kinds this harness has resolved.
+ */
+function loadAllSubAgentDynamicCredentials(harness, sessionKey = config_js_1.SESSIONLESS_KEY) {
+    return { ...((0, config_js_1.loadConfig)().agent?.subAgents?.[harness]?.[sessionKey] ?? {}) };
+}
+/**
+ * Every persisted sub-agent registration, keyed by harness, session, then type. Used by
+ * teardown and reporting paths that must reach beyond the harness they run under.
+ */
+function loadSubAgentDynamicCredentialsByHarness() {
+    const stored = (0, config_js_1.loadConfig)().agent?.subAgents ?? {};
+    return Object.fromEntries(Object.entries(stored).map(([harness, bySession]) => [
+        harness,
+        Object.fromEntries(Object.entries(bySession).map(([session, byType]) => [session, { ...byType }])),
+    ]));
+}
+function saveSubAgentDynamicCredentials(harness, sessionOrType, typeOrCreds, maybeCreds) {
+    const sessionKey = maybeCreds ? sessionOrType : config_js_1.SESSIONLESS_KEY;
+    const subAgentType = maybeCreds ? typeOrCreds : sessionOrType;
+    const creds = maybeCreds ?? typeOrCreds;
     (0, config_js_1.mutateConfig)((current) => {
         const agent = { ...(current.agent ?? {}) };
         const subAgents = { ...(agent.subAgents ?? {}) };
-        subAgents[subAgentType] = creds;
+        const bySession = { ...(subAgents[harness] ?? {}) };
+        bySession[sessionKey] = { ...(bySession[sessionKey] ?? {}), [subAgentType]: creds };
+        subAgents[harness] = bySession;
         agent.subAgents = subAgents;
         return { ...current, agent };
     });
 }
-/** Remove persisted sub-agent DCR credentials for the given type. */
-function clearSubAgentDynamicCredentials(subAgentType) {
-    (0, config_js_1.mutateConfig)((current) => {
-        const next = { ...current };
-        if (!next.agent?.subAgents)
-            return next;
-        const agent = { ...next.agent };
-        const subAgents = { ...agent.subAgents };
-        delete subAgents[subAgentType];
-        if (Object.keys(subAgents).length === 0)
-            delete agent.subAgents;
+/** Remove persisted sub-agent DCR credentials for one harness + type. */
+function clearSubAgentDynamicCredentials(harness, sessionOrType, subAgentType) {
+    const sessionKey = subAgentType === undefined ? config_js_1.SESSIONLESS_KEY : sessionOrType;
+    const type = subAgentType ?? sessionOrType;
+    (0, config_js_1.mutateConfig)((current) => pruneAgentBlock(current, (agent) => {
+        const subAgents = { ...(agent.subAgents ?? {}) };
+        const bySession = { ...(subAgents[harness] ?? {}) };
+        const byType = { ...(bySession[sessionKey] ?? {}) };
+        delete byType[type];
+        if (Object.keys(byType).length === 0)
+            delete bySession[sessionKey];
         else
-            agent.subAgents = subAgents;
-        if (!agent.dynamic && !agent.subAgents)
-            delete next.agent;
+            bySession[sessionKey] = byType;
+        if (Object.keys(bySession).length === 0)
+            delete subAgents[harness];
         else
-            next.agent = agent;
+            subAgents[harness] = bySession;
+        agent.subAgents = subAgents;
+    }));
+}
+/** Remove every persisted sub-agent registration for one harness. */
+function clearSubAgentDynamicCredentialsForHarness(harness) {
+    (0, config_js_1.mutateConfig)((current) => pruneAgentBlock(current, (agent) => {
+        const subAgents = { ...(agent.subAgents ?? {}) };
+        delete subAgents[harness];
+        agent.subAgents = subAgents;
+    }));
+}
+// ─── Dynamic registration persistence ────────────────────────────────
+/** Load persisted DCR credentials for one harness session. */
+function loadAgentDynamicCredentials(harness, sessionKey = config_js_1.SESSIONLESS_KEY) {
+    return (0, config_js_1.loadConfig)().agent?.dynamic?.[harness]?.[sessionKey];
+}
+/**
+ * Every persisted agent registration, keyed by harness then session.
+ * reporting paths that must reach beyond the harness they run under.
+ */
+function loadAgentDynamicCredentialsByHarness() {
+    const stored = (0, config_js_1.loadConfig)().agent?.dynamic ?? {};
+    return Object.fromEntries(Object.entries(stored).map(([harness, bySession]) => [harness, { ...bySession }]));
+}
+function saveAgentDynamicCredentials(harness, sessionOrCreds, maybeCreds) {
+    const sessionKey = typeof sessionOrCreds === "string" ? sessionOrCreds : config_js_1.SESSIONLESS_KEY;
+    const creds = maybeCreds ?? sessionOrCreds;
+    (0, config_js_1.mutateConfig)((current) => {
+        const agent = { ...(current.agent ?? {}) };
+        const bySession = { ...(agent.dynamic?.[harness] ?? {}) };
+        bySession[sessionKey] = creds;
+        agent.dynamic = { ...(agent.dynamic ?? {}), [harness]: bySession };
+        return { ...current, agent };
+    });
+}
+/** Remove one session, or every session when no session key is supplied. */
+function clearAgentDynamicCredentials(harness, sessionKey) {
+    (0, config_js_1.mutateConfig)((current) => pruneAgentBlock(current, (agent) => {
+        const dynamic = { ...(agent.dynamic ?? {}) };
+        if (sessionKey === undefined)
+            delete dynamic[harness];
+        else {
+            const bySession = { ...(dynamic[harness] ?? {}) };
+            delete bySession[sessionKey];
+            if (Object.keys(bySession).length === 0)
+                delete dynamic[harness];
+            else
+                dynamic[harness] = bySession;
+        }
+        agent.dynamic = dynamic;
+    }));
+}
+/** Most recently registered agent session for status/reporting. */
+function latestAgentRegistration(harness) {
+    const entries = Object.entries((0, config_js_1.loadConfig)().agent?.dynamic?.[harness] ?? {}).sort(([aKey, a], [bKey, b]) => b.registeredAt - a.registeredAt || bKey.localeCompare(aKey));
+    const [sessionKey, credentials] = entries[0] ?? [];
+    return sessionKey && credentials ? { sessionKey, credentials } : undefined;
+}
+/** Newest session containing at least one sub-agent registration. */
+function latestSubAgentSession(harness) {
+    return Object.entries((0, config_js_1.loadConfig)().agent?.subAgents?.[harness] ?? {})
+        .map(([sessionKey, byType]) => ({
+        sessionKey,
+        registeredAt: Math.max(...Object.values(byType).map((c) => c.registeredAt), 0),
+    }))
+        .sort((a, b) => b.registeredAt - a.registeredAt || b.sessionKey.localeCompare(a.sessionKey))[0]
+        ?.sessionKey;
+}
+function countAgentSessions(harness) {
+    return Object.keys((0, config_js_1.loadConfig)().agent?.dynamic?.[harness] ?? {}).length;
+}
+/**
+ * Apply `mutate` to a copy of the agent block, then drop any map (and the block
+ * itself) left empty. Every clear path needs the same collapse, and doing it
+ * once keeps an emptied `agent: {}` from lingering in the file.
+ */
+function pruneAgentBlock(current, mutate) {
+    const next = { ...current };
+    if (!next.agent)
         return next;
+    const agent = { ...next.agent };
+    mutate(agent);
+    if (agent.dynamic && Object.keys(agent.dynamic).length === 0)
+        delete agent.dynamic;
+    if (agent.subAgents && Object.keys(agent.subAgents).length === 0)
+        delete agent.subAgents;
+    if (agent.retired && agent.retired.length === 0)
+        delete agent.retired;
+    if (!agent.dynamic && !agent.subAgents && !agent.retired)
+        delete next.agent;
+    else
+        next.agent = agent;
+    return next;
+}
+// ─── Delegation node ids (non-secret, independent of credentials) ───
+/**
+ * The delegation node the broker assigned to this harness's `user → agent` edge
+ * for one session, or `undefined` if that session hasn't recorded one yet.
+ *
+ * Read by the sub-agent edge to pass as `delegated_by` — which is why it is
+ * looked up by session and not just by harness: the credential is shared across
+ * sessions but the node is not, so a sub-agent must hang off *its own* run's
+ * agent node.
+ */
+function loadDelegationNodeId(harness, sessionKey) {
+    const config = (0, config_js_1.loadConfig)();
+    return config.delegationAnchors?.[harness]?.[sessionKey]
+        // Read the old location during the cutover; every subsequent save writes
+        // only the independent non-secret anchor map.
+        ?? config.agent?.dynamic?.[harness]?.[sessionKey]?.delegationNodeIds?.[sessionKey];
+}
+/**
+ * Record the broker-assigned delegation node for `(harness, session)`, trimming
+ * the map to the most recent {@link DELEGATION_NODE_HISTORY} entries.
+ *
+ * The anchor is not a credential and is safe to persist independently. A
+ * repeated idempotent edge does not rewrite the config file.
+ */
+function saveDelegationNodeId(harness, sessionKey, nodeId) {
+    (0, config_js_1.mutateConfig)((current) => {
+        const existing = current.delegationAnchors?.[harness] ?? {};
+        if (existing[sessionKey] === nodeId)
+            return current;
+        // Re-insert rather than spread over the existing entry: a spread keeps an
+        // already-present key in its *original* position, so a session that
+        // re-recorded a changed node id would still be pruned as if it were the
+        // oldest. Deleting first moves it to the end, where the bound never reaches.
+        const merged = { ...existing };
+        delete merged[sessionKey];
+        merged[sessionKey] = nodeId;
+        // Insertion order is oldest-first, so dropping from the front keeps the
+        // newest entries. The session just written is last and always survives.
+        const keys = Object.keys(merged);
+        const kept = keys.slice(Math.max(0, keys.length - config_js_1.DELEGATION_NODE_HISTORY));
+        return {
+            ...current,
+            delegationAnchors: {
+                ...(current.delegationAnchors ?? {}),
+                [harness]: Object.fromEntries(kept.map((key) => [key, merged[key]])),
+            },
+        };
     });
 }
-// ─── Dynamic registration persistence ────────────────────────────────
-/** Load persisted DCR credentials from the shared config file. */
-function loadAgentDynamicCredentials() {
-    return (0, config_js_1.loadConfig)().agent?.dynamic;
-}
-/** Persist DCR credentials. Existing credentials are replaced atomically. */
-function saveAgentDynamicCredentials(creds) {
-    (0, config_js_1.mutateConfig)((current) => ({
-        ...current,
-        agent: { ...(current.agent ?? {}), dynamic: creds },
+// ─── Revocation drain queue ──────────────────────────────────────────
+//
+// Session retention atomically removes an aged parent and its typed children
+// from the active maps and moves them to `agent.retired`. They still exist on
+// the project, so they must be revoked rather than forgotten.
+/** Registrations queued for best-effort revocation. */
+function loadRetiredCredentials() {
+    return [...((0, config_js_1.loadConfig)().agent?.retired ?? [])];
+}
+/**
+ * Remove `clientIds` from the drain queue. Called with the ones that were
+ * actually revoked; anything left stays queued for the next run, so a transient
+ * failure retries instead of orphaning the client.
+ */
+function clearRetiredCredentials(clientIds) {
+    if (clientIds.length === 0)
+        return;
+    const done = new Set(clientIds);
+    (0, config_js_1.mutateConfig)((current) => pruneAgentBlock(current, (agent) => {
+        agent.retired = (agent.retired ?? []).filter((c) => !done.has(c.clientId));
     }));
 }
-/** Remove persisted DCR credentials (e.g. after revocation or unregister). */
-function clearAgentDynamicCredentials() {
+/** Automatic retirement is opt-in because age alone cannot prove a session ended. */
+exports.DEFAULT_SESSION_RETENTION = 0;
+/** `0` disables automatic retirement. */
+function sessionRetention(env = process.env) {
+    const raw = env.ORY_AGENT_SESSION_RETENTION?.trim();
+    if (!raw)
+        return exports.DEFAULT_SESSION_RETENTION;
+    if (!/^\d+$/.test(raw))
+        return exports.DEFAULT_SESSION_RETENTION;
+    const parsed = Number(raw);
+    return Number.isSafeInteger(parsed) ? parsed : exports.DEFAULT_SESSION_RETENTION;
+}
+/**
+ * Move aged-out agent sessions and all of their child credentials to the
+ * retirement queue atomically. They remain addressable until RFC 7592 cleanup
+ * succeeds, avoiding the orphaning behavior of the original pruning path.
+ */
+function retireAgentSessions(harness, opts) {
+    if (opts.keep <= 0)
+        return 0;
+    let retiredCount = 0;
+    (0, config_js_1.mutateConfig)((current) => {
+        const bySession = current.agent?.dynamic?.[harness];
+        if (!bySession)
+            return current;
+        const ordered = Object.entries(bySession).sort(([aKey, a], [bKey, b]) => b.registeredAt - a.registeredAt || bKey.localeCompare(aKey));
+        const hasProtected = !!opts.protect && Object.hasOwn(bySession, opts.protect);
+        const keepOthers = Math.max(0, opts.keep - (hasProtected ? 1 : 0));
+        const doomed = ordered.filter(([key]) => key !== opts.protect).slice(keepOthers);
+        if (doomed.length === 0)
+            return current;
+        const agent = { ...current.agent };
+        const dynamic = { ...(agent.dynamic ?? {}) };
+        const kept = { ...bySession };
+        const subAgents = { ...(agent.subAgents ?? {}) };
+        const subBySession = { ...(subAgents[harness] ?? {}) };
+        const queue = [...(agent.retired ?? [])];
+        const queued = new Set(queue.map((c) => c.clientId));
+        for (const [sessionKey, creds] of doomed) {
+            if (!queued.has(creds.clientId))
+                queue.push({ ...creds, harness });
+            delete kept[sessionKey];
+            for (const child of Object.values(subBySession[sessionKey] ?? {})) {
+                if (!queued.has(child.clientId))
+                    queue.push({ ...child, harness });
+            }
+            delete subBySession[sessionKey];
+            retiredCount++;
+        }
+        if (Object.keys(kept).length === 0)
+            delete dynamic[harness];
+        else
+            dynamic[harness] = kept;
+        if (Object.keys(subBySession).length === 0)
+            delete subAgents[harness];
+        else
+            subAgents[harness] = subBySession;
+        agent.dynamic = dynamic;
+        agent.subAgents = subAgents;
+        agent.retired = queue;
+        return { ...current, agent };
+    });
+    return retiredCount;
+}
+/** Retire one exact session and all children when its identity binding is stale. */
+function retireAgentSession(harness, sessionKey) {
+    let retired = false;
     (0, config_js_1.mutateConfig)((current) => {
-        const next = { ...current };
-        if (!next.agent)
-            return next;
-        const agent = { ...next.agent };
-        delete agent.dynamic;
-        if (Object.keys(agent).length === 0)
-            delete next.agent;
+        const credentials = current.agent?.dynamic?.[harness]?.[sessionKey];
+        if (!credentials)
+            return current;
+        const agent = { ...current.agent };
+        const dynamic = { ...(agent.dynamic ?? {}) };
+        const bySession = { ...(dynamic[harness] ?? {}) };
+        const subAgents = { ...(agent.subAgents ?? {}) };
+        const subBySession = { ...(subAgents[harness] ?? {}) };
+        const queue = [...(agent.retired ?? [])];
+        const queued = new Set(queue.map((item) => item.clientId));
+        if (!queued.has(credentials.clientId))
+            queue.push({ ...credentials, harness });
+        for (const child of Object.values(subBySession[sessionKey] ?? {})) {
+            if (!queued.has(child.clientId))
+                queue.push({ ...child, harness });
+        }
+        delete bySession[sessionKey];
+        delete subBySession[sessionKey];
+        if (Object.keys(bySession).length === 0)
+            delete dynamic[harness];
         else
-            next.agent = agent;
-        return next;
+            dynamic[harness] = bySession;
+        if (Object.keys(subBySession).length === 0)
+            delete subAgents[harness];
+        else
+            subAgents[harness] = subBySession;
+        agent.dynamic = dynamic;
+        agent.subAgents = subAgents;
+        agent.retired = queue;
+        retired = true;
+        return { ...current, agent };
     });
+    return retired;
+}
+/**
+ * True when `existing` is a usable peer registration that should win over a
+ * client we just minted for the same key: it is a *different* client, issued
+ * against the same project, and usable for a client_credentials grant.
+ */
+function isUsablePeer(existing, registered) {
+    return Boolean(existing &&
+        existing.clientId !== registered.clientId &&
+        existing.projectUrl === registered.projectUrl &&
+        existing.clientSecret &&
+        (!registered.delegation ||
+            (existing.delegation?.delegationType === registered.delegation.delegationType &&
+                existing.delegation.delegatedBy === registered.delegation.delegatedBy)));
+}
+/**
+ * Persist a freshly registered agent client, unless a concurrent peer already
+ * claimed the `(projectUrl, harness)` slot.
+ *
+ * Keying credentials by harness removes the cold-start collision *between*
+ * harnesses, but two instances of the *same* harness starting at once still
+ * target one key. Both POST `/oauth2/register`, and a plain last-writer-wins
+ * save would leave one client orphaned server-side (and its delegation edge
+ * dangling). The read and the write happen inside a single `mutateConfig`, so
+ * the loser sees the winner's registration and reports it back to be revoked.
+ */
+function claimAgentDynamicCredentials(harness, sessionKey, registered) {
+    let claim = { credentials: registered, peer: false };
+    (0, config_js_1.mutateConfig)((current) => {
+        const existing = current.agent?.dynamic?.[harness]?.[sessionKey];
+        if (isUsablePeer(existing, registered)) {
+            claim = { credentials: existing, peer: true };
+            return current;
+        }
+        const agent = { ...(current.agent ?? {}) };
+        if (existing &&
+            existing.clientId !== registered.clientId &&
+            existing.projectUrl === registered.projectUrl) {
+            agent.retired = [
+                ...(agent.retired ?? []).filter((c) => c.clientId !== existing.clientId),
+                { ...existing, harness },
+            ];
+        }
+        const bySession = { ...(agent.dynamic?.[harness] ?? {}) };
+        bySession[sessionKey] = registered;
+        agent.dynamic = { ...(agent.dynamic ?? {}), [harness]: bySession };
+        return { ...current, agent };
+    });
+    return claim;
+}
+/** {@link claimAgentDynamicCredentials} for a `(harness, subAgentType)` slot. */
+function claimSubAgentDynamicCredentials(harness, sessionKey, subAgentType, registered) {
+    let claim = { credentials: registered, peer: false };
+    (0, config_js_1.mutateConfig)((current) => {
+        const existing = current.agent?.subAgents?.[harness]?.[sessionKey]?.[subAgentType];
+        if (isUsablePeer(existing, registered)) {
+            claim = { credentials: existing, peer: true };
+            return current;
+        }
+        const agent = { ...(current.agent ?? {}) };
+        const subAgents = { ...(agent.subAgents ?? {}) };
+        const bySession = { ...(subAgents[harness] ?? {}) };
+        bySession[sessionKey] = { ...(bySession[sessionKey] ?? {}), [subAgentType]: registered };
+        subAgents[harness] = bySession;
+        agent.subAgents = subAgents;
+        return { ...current, agent };
+    });
+    return claim;
 }
 /**
  * Best-effort RFC 7592 `DELETE` of a dynamically-registered OAuth2 client.
@@ -157,7 +612,7 @@ async function revokeAgentDynamicClient(creds) {
  * either by the user's interactive token (the natural bootstrap) or by
  * a pre-issued initial access token (`ORY_AGENT_REGISTRATION_TOKEN`).
  * Throws on any non-2xx response so callers can decide whether to
- * retry, fall back, or surface the error in the audit span. The
+ * retry, fall back, or surface the error in audit activity. The
  * `HTTP <status>` error message shape is preserved so callers and tests
  * can pattern-match on it regardless of the underlying transport.
  */
@@ -167,6 +622,7 @@ async function registerAgentClient(args) {
         harness: args.harness,
         host,
         subAgentType: args.subAgentType,
+        sessionId: args.sessionId,
     });
     // Build the delegation anchor (if a delegator is known) and mirror it into the
     // persisted credentials. This is the integrity anchor the Keto tuple is derived
@@ -211,7 +667,10 @@ async function registerAgentClient(args) {
         // Configuration's `accessToken`. Ory projects that gate DCR behind an
         // initial access token then reject the unauthenticated request and the
         // agent never gets credentials. Send the bearer explicitly.
-        args.auth ? { headers: { Authorization: `Bearer ${args.auth}` } } : undefined);
+        {
+            ...(args.auth ? { headers: { Authorization: `Bearer ${args.auth}` } } : {}),
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
     }
     catch (err) {
         const status = err?.response?.status;
@@ -232,35 +691,38 @@ async function registerAgentClient(args) {
         registeredAt: Math.floor(Date.now() / 1000),
         projectUrl: args.projectUrl,
         harness: args.harness,
+        clientName: client.client_name ?? clientName,
         ...(delegation ? { delegation } : {}),
     };
 }
 /**
- * Resolve the agent's credentials from environment configuration and
- * persisted state. Never throws — failures collapse to `kind: "none"`
- * so the caller can fail open.
+ * Legacy OAuth/DCR resolver retained for source compatibility. Normal runtime
+ * gates use {@link resolveRuntimeAgentCredentials} instead.
  */
 async function resolveAgentCredentials(options = {}) {
     const env = options.env ?? process.env;
     const warnings = [];
+    // Read and validate once, not at each of the three grant paths below — the
+    // rule has to be the same whichever credential slot wins (#241).
+    const subjectOverride = (0, subject_js_1.readAgentSubjectOverride)(env, warnings);
     const fetchCcFn = options.fetchClientCredentialsTokenFn ?? fetchClientCredentialsToken;
     const registerFn = options.registerAgentClientFn ?? registerAgentClient;
     const loadDynamicFn = options.loadDynamicFn ?? loadAgentDynamicCredentials;
     const saveDynamicFn = options.saveDynamicFn ?? saveAgentDynamicCredentials;
     const clearDynamicFn = options.clearDynamicFn ?? clearAgentDynamicCredentials;
+    const revokeFn = options.revokeFn ?? revokeAgentDynamicClient;
     const skipCache = options.skipCache ?? false;
-    // 1. Explicit static API key — operator override.
-    const apiKey = env.ORY_AGENT_API_KEY;
-    if (apiKey && apiKey.length > 0) {
-        return {
-            kind: "api_key",
-            token: apiKey,
-            subject: env.ORY_AGENT_SUBJECT_ID,
-            reason: "Resolved agent identity from ORY_AGENT_API_KEY",
-            warnings,
-        };
-    }
-    // 2. Explicit static client_credentials — operator override.
+    // Credentials are keyed by harness *and session*: each installed harness owns
+    // its own agent identity, and each session of that harness gets a distinct
+    // one. A caller with no harness (an SDK embedding, a one-off script) gets the
+    // shared `unknown` slot rather than silently hijacking a harness's identity;
+    // one with no session gets the single `sessionless` identity rather than a
+    // fresh client per call.
+    const harnessKey = options.harness?.trim() || config_js_1.UNKNOWN_HARNESS_KEY;
+    const sessionKey = options.sessionId?.trim() || config_js_1.SESSIONLESS_KEY;
+    // 1. Explicit static client_credentials — operator override. This is the
+    // only non-DCR path: it still yields a real OAuth2 access token, which is
+    // what the Keto `/user` read path authenticates with.
     const clientId = env.ORY_AGENT_CLIENT_ID;
     const clientSecret = env.ORY_AGENT_CLIENT_SECRET;
     if (clientId && clientSecret) {
@@ -272,21 +734,37 @@ async function resolveAgentCredentials(options = {}) {
             };
         }
         return await resolveClientCredentials({
-            projectUrl: options.projectUrl,
+            projectUrl: options.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl,
             clientId,
             clientSecret,
             audience: env.ORY_AGENT_AUDIENCE,
             scope: env.ORY_AGENT_SCOPE,
-            subjectOverride: env.ORY_AGENT_SUBJECT_ID,
+            subjectOverride,
             kind: "client_credentials",
             fetchFn: fetchCcFn,
             skipCache,
             warnings,
+            signal: options.signal,
         });
     }
-    // 3. Persisted dynamic registration — re-use a prior DCR run.
+    // 2. Re-use the DCR client for this exact harness session. Subprocess hook
+    //    processes converge here; a new session has a different slot.
     if (options.projectUrl) {
-        const persisted = loadDynamicFn();
+        let persisted = loadDynamicFn(harnessKey, sessionKey);
+        const expectedDelegator = options.userSubject ? `user:${options.userSubject}` : undefined;
+        if (persisted &&
+            expectedDelegator &&
+            (persisted.delegation?.delegationType !== "user-to-agent" ||
+                persisted.delegation.delegatedBy !== expectedDelegator)) {
+            warnings.push(`Persisted dynamic agent credentials belong to ${persisted.delegation?.delegatedBy ?? "an unknown user"}; registering a credential for ${expectedDelegator}.`);
+            if (options.loadDynamicFn || options.saveDynamicFn) {
+                clearDynamicFn(harnessKey, sessionKey);
+            }
+            else {
+                retireAgentSession(harnessKey, sessionKey);
+            }
+            persisted = undefined;
+        }
         if (persisted && persisted.projectUrl === options.projectUrl && persisted.clientSecret) {
             const result = await resolveClientCredentials({
                 projectUrl: options.projectUrl,
@@ -294,11 +772,12 @@ async function resolveAgentCredentials(options = {}) {
                 clientSecret: persisted.clientSecret,
                 audience: env.ORY_AGENT_AUDIENCE,
                 scope: env.ORY_AGENT_SCOPE,
-                subjectOverride: env.ORY_AGENT_SUBJECT_ID,
+                subjectOverride,
                 kind: "dynamic",
                 fetchFn: fetchCcFn,
                 skipCache,
                 warnings,
+                signal: options.signal,
             });
             if (result.kind !== "none")
                 return result;
@@ -310,7 +789,7 @@ async function resolveAgentCredentials(options = {}) {
             // blip. Keep the persisted creds and report the transient failure instead.
             if (result.authRejected) {
                 warnings.push(`Persisted dynamic agent credentials rejected (${result.reason}); re-registering.`);
-                clearDynamicFn();
+                clearDynamicFn(harnessKey, sessionKey);
             }
             else {
                 warnings.push(`Persisted dynamic agent credentials temporarily unavailable (${result.reason}); keeping them for the next session.`);
@@ -318,15 +797,17 @@ async function resolveAgentCredentials(options = {}) {
             }
         }
     }
-    // 4. Fresh dynamic registration — bootstrap using the user's bearer
+    // 3. Fresh dynamic registration — bootstrap using the user's bearer
     //    or an out-of-band initial access token.
     const iat = options.userToken ?? env.ORY_AGENT_REGISTRATION_TOKEN;
-    if (options.projectUrl && iat) {
+    if (options.allowRegistration !== false && options.projectUrl && iat) {
         try {
             const registered = await registerFn({
                 projectUrl: options.projectUrl,
                 auth: iat,
                 harness: options.harness,
+                sessionId: sessionKey === config_js_1.SESSIONLESS_KEY ? undefined : sessionKey,
+                signal: options.signal,
                 ...(options.userSubject
                     ? {
                         delegation: {
@@ -340,18 +821,34 @@ async function resolveAgentCredentials(options = {}) {
                 warnings.push("Dynamic registration returned no client_secret; cannot run client_credentials grant.");
             }
             else {
-                saveDynamicFn(registered);
+                // Double-checked registration: a concurrent instance of this same
+                // harness may have claimed the slot while our POST was in flight. The
+                // claim re-reads under the config lock; if we lost, adopt the peer's
+                // client and revoke the one we just minted so it isn't orphaned.
+                const claim = claimRegistration(harnessKey, sessionKey, registered, {
+                    loadDynamicFn,
+                    saveDynamicFn,
+                    useSharedStore: !options.loadDynamicFn && !options.saveDynamicFn,
+                });
+                if (claim.peer) {
+                    warnings.push(`A concurrent process registered agent client ${claim.credentials.clientId} for ${harnessKey}/${sessionKey} first; adopting it and revoking ${registered.clientId}.`);
+                    await revokeFn(registered).catch(() => {
+                        /* best-effort cleanup; a failed revoke leaves an orphan, never an error */
+                    });
+                }
+                const adopted = claim.credentials;
                 const result = await resolveClientCredentials({
                     projectUrl: options.projectUrl,
-                    clientId: registered.clientId,
-                    clientSecret: registered.clientSecret,
+                    clientId: adopted.clientId,
+                    clientSecret: adopted.clientSecret ?? registered.clientSecret,
                     audience: env.ORY_AGENT_AUDIENCE,
                     scope: env.ORY_AGENT_SCOPE,
-                    subjectOverride: env.ORY_AGENT_SUBJECT_ID,
+                    subjectOverride,
                     kind: "dynamic",
                     fetchFn: fetchCcFn,
                     skipCache: true, // freshly registered, no stale cache
                     warnings,
+                    signal: options.signal,
                 });
                 if (result.kind !== "none")
                     return result;
@@ -362,24 +859,32 @@ async function resolveAgentCredentials(options = {}) {
             warnings.push(`Dynamic client registration failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    // 5. Deprecated ORY_API_KEY alias.
-    const legacyApiKey = env.ORY_API_KEY;
-    if (legacyApiKey && legacyApiKey.length > 0) {
-        warnings.push("ORY_API_KEY is deprecated for agent authentication — set ORY_AGENT_API_KEY instead");
-        return {
-            kind: "api_key",
-            token: legacyApiKey,
-            subject: env.ORY_AGENT_SUBJECT_ID,
-            reason: "Resolved agent identity from ORY_API_KEY (deprecated alias)",
-            warnings,
-        };
-    }
     return {
         kind: "none",
-        reason: "No agent credentials configured. Run with a user session (the interactive user login runs every session) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
+        reason: "No agent credentials configured. Run with a user session (the interactive user login runs every session) or set ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
         warnings,
     };
 }
+/**
+ * Claim the `(projectUrl, harness, session)` slot for a freshly registered client.
+ *
+ * Against the real config file this is {@link claimAgentDynamicCredentials},
+ * whose read and write share one `mutateConfig` lock — the only way the loser
+ * of a same-harness race reliably sees the winner. When the caller injected its
+ * own credential store (tests), that lock isn't ours to take, so the same
+ * check runs against the injected load/save pair instead.
+ */
+function claimRegistration(harness, sessionKey, registered, store) {
+    if (store.useSharedStore) {
+        return claimAgentDynamicCredentials(harness, sessionKey, registered);
+    }
+    const existing = store.loadDynamicFn(harness, sessionKey);
+    if (isUsablePeer(existing, registered)) {
+        return { credentials: existing, peer: true };
+    }
+    store.saveDynamicFn(harness, sessionKey, registered);
+    return { credentials: registered, peer: false };
+}
 async function resolveClientCredentials(args) {
     const cacheKey = `${args.kind}:${args.clientId}@${args.projectUrl}`;
     const nowSec = Math.floor(Date.now() / 1000);
@@ -404,6 +909,7 @@ async function resolveClientCredentials(args) {
             clientSecret: args.clientSecret,
             audience: args.audience,
             scope: args.scope,
+            signal: args.signal,
         });
         ccCache.set(cacheKey, {
             token: result.accessToken,
@@ -463,6 +969,7 @@ async function fetchClientCredentialsToken(args) {
         method: "POST",
         headers: { "content-type": "application/x-www-form-urlencoded" },
         body: body.toString(),
+        signal: args.signal,
     });
     if (!res.ok) {
         const err = new Error(`HTTP ${res.status}`);
@@ -484,36 +991,48 @@ async function fetchClientCredentialsToken(args) {
  * Resolve the agent's credentials and attach them to the client.
  *
  * Always returns the resolved credentials; never throws and never blocks.
- * Emits exactly one `agent.auth` span so the audit trail records whether
+ * Emits exactly one `agent.auth` activity event so the audit trail records whether
  * the agent identity was available for the session.
  */
 async function ensureAgentIdentity(client, options = {}) {
-    // Audit-only kill switch: Ory is disabled entirely — skip credential
-    // resolution (no DCR, no token grant) and record the no-op, shaped like
-    // the user gate's audit_only result.
-    if ((0, config_js_1.resolveConfig)().auditOnly) {
+    const sessionId = options.sessionId ?? client.sessionId;
+    // Agent Security isn't connected — skip credential resolution entirely
+    // (no DCR, no token grant) and record the no-op, shaped like the user
+    // gate's not_connected result.
+    const resolvedConfig = (0, config_js_1.resolveConfig)();
+    const security = resolvedConfig.security;
+    if (!security.connected) {
         const creds = {
             kind: "none",
-            reason: "Configured for audit-only mode; agent identity resolution is a no-op",
+            reason: `Ory Agent Security is not connected (${(0, config_js_1.describeSecurityGap)(security)}); agent identity resolution is a no-op`,
             warnings: [],
         };
-        client.tracer.record("agent.auth", "skipped", {
-            attributes: { kind: creds.kind, reason: creds.reason, auditOnly: true },
+        client.logger.activity("agent.auth", "skipped", {
+            attributes: { kind: creds.kind, reason: creds.reason, securityConnected: false },
         });
         return creds;
     }
-    const resolveFn = options.resolveFn ?? resolveAgentCredentials;
+    const resolveFn = options.resolveFn ?? resolveRuntimeAgentCredentials;
+    const projectUrl = options.projectUrl ?? (0, config_js_1.resolveConfig)().projectUrl;
+    let credentialStore = options.credentialStore;
+    if (!credentialStore) {
+        try {
+            credentialStore = (0, runtime_credential_js_1.createOsTalosCredentialStore)();
+        }
+        catch {
+            // The resolver and enrollment path report a safe warning below.
+        }
+    }
     let creds;
     try {
         creds = await resolveFn({
-            projectUrl: options.projectUrl,
+            projectUrl,
             env: options.env,
-            // The user gate populates userPrincipal on successful login; we hand the
-            // token to the resolver so DCR can use it as the IAT, and the subject so
-            // the fresh client is stamped with its delegator (metadata.delegatedBy).
-            userToken: client.userPrincipal.token,
-            userSubject: client.userPrincipal.subject,
-            harness: options.harness,
+            signal: options.signal,
+            runtimeCredential: client.runtimeCredential,
+            credentialStore,
+            harness: options.harness ?? client.harness,
+            sessionId,
         });
     }
     catch (err) {
@@ -523,114 +1042,320 @@ async function ensureAgentIdentity(client, options = {}) {
             warnings: [],
         };
     }
+    // Only the session-start gate may issue a credential. Tool/read subprocesses
+    // can load from the OS store but must never turn a read into a write.
+    const userToken = client.userPrincipalForSession(sessionId).token?.trim();
+    if (creds.kind === "none" && options.trigger === undefined && userToken && projectUrl) {
+        try {
+            (0, runtime_credential_js_1.canonicalProjectUrl)(projectUrl);
+            if (!credentialStore) {
+                creds.warnings.push(`Automatic Talos enrollment is unavailable because ${process.platform} has no supported OS credential store`);
+            }
+            else {
+                const enroll = options.enrollFn ?? runtime_credential_js_1.enrollTalosRuntimeCredential;
+                const identity = {
+                    projectUrl,
+                    harness: options.harness?.trim() || client.harness || config_js_1.UNKNOWN_HARNESS_KEY,
+                    sessionId: sessionId?.trim() || config_js_1.SESSIONLESS_KEY,
+                    kind: "agent",
+                };
+                const enrollmentOptions = {
+                    projectUrl,
+                    agentSecurityUrl: resolvedConfig.agentSecurityUrl,
+                    userToken,
+                    name: (0, branding_js_1.agentClientName)({
+                        harness: options.harness ?? client.harness,
+                        host: (0, node_os_1.hostname)(),
+                        sessionId,
+                    }),
+                    idempotencyKey: `talos-runtime-${(0, runtime_credential_js_1.credentialAccount)(identity)}`,
+                    signal: options.signal,
+                    credentialStore,
+                    identity,
+                };
+                let issued = false;
+                const enrolled = await withEnrollmentLock(identity, async () => {
+                    const peer = await credentialStore.load(identity);
+                    if (peer) {
+                        return {
+                            actorId: peer.actorId,
+                            credential: (0, runtime_credential_js_1.talosRuntimeCredential)(peer.credential, { subject: peer.actorId }),
+                            warnings: [],
+                        };
+                    }
+                    issued = true;
+                    return enroll(enrollmentOptions);
+                });
+                creds = {
+                    kind: "talos",
+                    runtimeCredential: enrolled.credential,
+                    subject: enrolled.actorId,
+                    reason: issued
+                        ? "Enrolled a Talos runtime credential using the authenticated user"
+                        : "Using the Talos runtime credential enrolled by a concurrent session process",
+                    warnings: [...creds.warnings, ...enrolled.warnings],
+                };
+            }
+        }
+        catch (error) {
+            const status = typeof error === "object" && error !== null
+                && typeof error.status === "number"
+                ? ` (HTTP ${error.status})`
+                : "";
+            creds.warnings.push(`Could not enroll a Talos runtime credential${status}`);
+        }
+    }
+    if (creds.runtimeCredential && (creds.kind === "talos" || creds.kind === "injected")) {
+        client.setRuntimeCredential(creds.runtimeCredential);
+        if (creds.subject)
+            client.setAgentPrincipal({ subject: creds.subject }, sessionId);
+    }
+    else if (creds.kind !== "none") {
+        creds = {
+            kind: "none",
+            reason: `Legacy ${creds.kind} credentials are not accepted for runtime authentication`,
+            warnings: creds.warnings,
+        };
+    }
     for (const warning of creds.warnings) {
         client.logger.warn("agent.auth.warning", { message: warning });
     }
     if (creds.kind === "none") {
         client.logger.warn("agent.auth.none", { reason: creds.reason });
     }
-    if (creds.token) {
-        client.setAgentPrincipal({ token: creds.token, subject: creds.subject });
-    }
-    // When no credentials were resolved, leave the existing principal in
-    // place. The constructor may have seeded one from `config.apiKey` for
-    // backward compat, and "no resolver match" should not clear it.
-    client.tracer.record("agent.auth", creds.kind === "none" ? "skipped" : "ok", {
+    // When no credentials were resolved, leave the existing principal in place —
+    // a caller may have set one explicitly via `setAgentPrincipal`, and "no
+    // resolver match" should not clear it. With nothing set, the read path falls
+    // back to the rehydrated user token (see `buildApis`).
+    const sessionKey = sessionId?.trim() || config_js_1.SESSIONLESS_KEY;
+    client.logger.activity("agent.auth", creds.kind === "none" ? "skipped" : "ok", {
         attributes: {
             kind: creds.kind,
             reason: creds.reason,
+            sessionKey,
+            ...(options.trigger ? { trigger: options.trigger } : {}),
             ...(creds.subject ? { subject: creds.subject } : {}),
             ...(creds.expiresAt ? { expiresAt: creds.expiresAt } : {}),
+            // Warnings were collected all along and never recorded, so a resolver
+            // that half-worked looked identical to one that worked — which is what
+            // made the rejected-DCR-metadata failure invisible in #182, and what
+            // would hide a rejected subject override here (#241).
+            ...(creds.warnings?.length ? { warnings: creds.warnings } : {}),
         },
     });
     return creds;
 }
 /**
- * Resolve a sub-agent identity via OAuth2 Dynamic Client Registration.
+ * Revoke retired registrations and drop the successful ones from the queue.
  *
- * Reuses persisted credentials when the `(projectUrl, subAgentType)`
- * pair matches; otherwise registers a fresh client named
- * `Ory Agent Security · sub-agent · <harness>/<type> @ <host>` and persists the result.
- * Never throws and never blocks — on any failure the identity collapses
- * to `kind: "none"` and the plugin continues without it. Emits exactly
- * one `agent.auth` span so the audit trail records each sub-agent
- * resolution.
+ * Best-effort throughout: a failed revoke leaves the entry queued for the next
+ * run (and an orphaned client that uninstall or an operator can still prune),
+ * never an error on the session-start path.
+ */
+async function drainRetiredCredentials(client, opts) {
+    let queued = [];
+    try {
+        queued = loadRetiredCredentials();
+    }
+    catch (err) {
+        client.logger.warn("agent.retired.read_failed", {
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return;
+    }
+    if (queued.length === 0)
+        return;
+    const revoke = opts.revokeFn ?? revokeAgentDynamicClient;
+    const revoked = [];
+    for (const creds of queued) {
+        const outcome = await revoke(creds).catch(() => ({ status: "failed" }));
+        // `deleted` (including a 404 — already gone) is done, and so is `skipped`:
+        // that means the record carries no RFC 7592 management credentials, so no
+        // future run could revoke it either and keeping it queued would leak a
+        // growing list into the config file forever. Only a real failure retries.
+        if (outcome.status !== "failed")
+            revoked.push(creds.clientId);
+        client.logger.debug("agent.retired.revoked", {
+            clientId: creds.clientId,
+            revoke: outcome.status,
+        });
+    }
+    try {
+        clearRetiredCredentials(revoked);
+    }
+    catch (err) {
+        client.logger.warn("agent.retired.clear_failed", {
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    client.logger.activity("agent.retired.drain", "ok", {
+        attributes: { queued: queued.length, revoked: revoked.length },
+    });
+}
+/**
+ * Resolve a sub-agent against the process runtime credential. The broker's
+ * `type_name` supplies sub-agent attribution; no separate OAuth identity is
+ * registered, loaded, minted, or persisted.
  */
 async function ensureSubAgentIdentity(client, options) {
-    // Audit-only kill switch: same no-op as ensureAgentIdentity — no
-    // sub-agent DCR while Ory is disabled entirely.
-    if ((0, config_js_1.resolveConfig)().auditOnly) {
+    // Same no-op as ensureAgentIdentity — no sub-agent DCR while Agent
+    // Security is not connected.
+    const resolvedConfig = (0, config_js_1.resolveConfig)();
+    const subAgentSecurity = resolvedConfig.security;
+    if (!subAgentSecurity.connected) {
         const identity = {
             kind: "none",
             subAgentType: options.subAgentType,
-            reason: "Configured for audit-only mode; sub-agent identity resolution is a no-op",
+            reason: `Ory Agent Security is not connected (${(0, config_js_1.describeSecurityGap)(subAgentSecurity)}); sub-agent identity resolution is a no-op`,
             warnings: [],
         };
-        client.tracer.record("agent.auth", "skipped", {
-            attributes: {
-                kind: "subagent_none",
-                subAgentType: identity.subAgentType,
-                reason: identity.reason,
-                auditOnly: true,
-            },
-        });
+        if (options.emitActivity !== false) {
+            client.logger.activity("agent.auth", "skipped", {
+                attributes: {
+                    kind: "subagent_none",
+                    subAgentType: identity.subAgentType,
+                    reason: identity.reason,
+                    securityConnected: false,
+                },
+            });
+        }
         return identity;
     }
-    const env = options.env ?? process.env;
-    const registerFn = options.registerAgentClientFn ?? registerAgentClient;
-    const loadFn = options.loadFn ?? loadSubAgentDynamicCredentials;
-    const saveFn = options.saveFn ?? saveSubAgentDynamicCredentials;
-    const warnings = [];
-    let identity;
-    try {
-        identity = await resolveSubAgentIdentity({
+    const projectUrl = options.projectUrl ?? resolvedConfig.projectUrl;
+    const sessionId = options.sessionId ?? client.sessionId;
+    const perSpawnId = options.perSpawnId?.trim();
+    if (!projectUrl || !perSpawnId) {
+        return {
+            kind: "none",
             subAgentType: options.subAgentType,
-            projectUrl: options.projectUrl,
-            harness: options.harness,
-            // The delegator for a sub-agent is the parent agent. When its subject is
-            // populated, stamp `metadata.delegatedBy` = `agent:<agent>` on the
-            // sub-agent client so the agent→subagent edge is anchored to the identity.
-            delegatorSubject: client.agentPrincipal.subject,
-            iat: options.iat
-                ?? client.agentPrincipal.token
-                ?? client.userPrincipal.token
-                ?? env.ORY_AGENT_REGISTRATION_TOKEN,
-            registerFn,
-            loadFn,
-            saveFn,
-            warnings,
+            reason: "A project and stable spawn identifier are required for a child identity",
+            warnings: [],
+        };
+    }
+    const credentialIdentity = {
+        projectUrl,
+        harness: options.harness?.trim() || client.harness || config_js_1.UNKNOWN_HARNESS_KEY,
+        sessionId: sessionId?.trim() || config_js_1.SESSIONLESS_KEY,
+        kind: "subagent",
+        subAgentType: options.subAgentType,
+        perSpawnId,
+    };
+    let store = options.credentialStore;
+    try {
+        store ??= (0, runtime_credential_js_1.createOsTalosCredentialStore)();
+        const stored = await store.load(credentialIdentity);
+        if (stored) {
+            const runtimeCredential = (0, runtime_credential_js_1.talosRuntimeCredential)(stored.credential, { subject: stored.actorId });
+            return {
+                kind: "runtime",
+                subAgentType: options.subAgentType,
+                subject: stored.actorId,
+                runtimeCredential,
+                reason: "Using the child Talos credential from the OS credential store",
+                warnings: [],
+            };
+        }
+    }
+    catch {
+        // Enrollment below reports a safe outcome if native persistence is unavailable.
+    }
+    let parentCredential = client.runtimeCredential;
+    if (!parentCredential) {
+        const parent = await resolveRuntimeAgentCredentials({
+            projectUrl,
+            harness: credentialIdentity.harness,
+            sessionId: credentialIdentity.sessionId,
+            credentialStore: store,
+            env: options.env,
         });
+        parentCredential = parent.runtimeCredential;
     }
-    catch (err) {
+    let identity;
+    if (options.allowEnrollment !== false && parentCredential && store) {
+        try {
+            const enroll = options.enrollFn ?? runtime_credential_js_1.enrollTalosChildRuntimeCredential;
+            const enrollmentOptions = {
+                projectUrl,
+                agentSecurityUrl: resolvedConfig.agentSecurityUrl,
+                name: (0, branding_js_1.agentClientName)({
+                    harness: credentialIdentity.harness,
+                    host: (0, node_os_1.hostname)(),
+                    sessionId: credentialIdentity.sessionId,
+                    subAgentType: options.subAgentType,
+                }),
+                subAgentType: options.subAgentType,
+                idempotencyKey: `talos-child-${(0, runtime_credential_js_1.credentialAccount)(credentialIdentity)}`,
+                parentCredential,
+                identity: credentialIdentity,
+                credentialStore: store,
+                signal: options.signal,
+            };
+            let issued = false;
+            const enrolled = await withEnrollmentLock(credentialIdentity, async () => {
+                const peer = await store.load(credentialIdentity);
+                if (peer) {
+                    return {
+                        actorId: peer.actorId,
+                        credential: (0, runtime_credential_js_1.talosRuntimeCredential)(peer.credential, { subject: peer.actorId }),
+                        warnings: [],
+                    };
+                }
+                issued = true;
+                return enroll(enrollmentOptions);
+            });
+            identity = {
+                kind: "runtime",
+                subAgentType: options.subAgentType,
+                subject: enrolled.actorId,
+                runtimeCredential: enrolled.credential,
+                reason: issued
+                    ? "Enrolled a child Talos credential using the parent runtime"
+                    : "Using the child Talos credential enrolled by a concurrent process",
+                warnings: enrolled.warnings,
+            };
+        }
+        catch (error) {
+            const status = typeof error === "object" && error !== null
+                && typeof error.status === "number"
+                ? ` (HTTP ${error.status})`
+                : "";
+            identity = {
+                kind: "none",
+                subAgentType: options.subAgentType,
+                reason: `Child Talos enrollment failed${status}`,
+                warnings: [],
+            };
+        }
+    }
+    else {
         identity = {
             kind: "none",
             subAgentType: options.subAgentType,
-            reason: `Sub-agent identity resolution threw: ${err instanceof Error ? err.message : String(err)}`,
-            warnings,
+            reason: "No child Talos credential is stored and parent-authenticated enrollment is unavailable",
+            warnings: [],
         };
     }
-    for (const warning of identity.warnings) {
-        client.logger.warn("agent.auth.warning", {
-            message: warning,
-            subAgentType: options.subAgentType,
-        });
-    }
-    if (identity.kind === "none") {
-        client.logger.warn("agent.auth.none", {
-            reason: identity.reason,
-            subAgentType: options.subAgentType,
+    if (options.emitActivity !== false) {
+        client.logger.activity("agent.auth", identity.kind === "runtime" ? "ok" : "skipped", {
+            attributes: {
+                kind: identity.kind === "runtime" ? "subagent_runtime" : "subagent_none",
+                subAgentType: identity.subAgentType,
+                reason: identity.reason,
+                ...(identity.subject ? { subject: identity.subject } : {}),
+            },
         });
     }
-    client.tracer.record("agent.auth", identity.kind === "none" ? "skipped" : "ok", {
-        attributes: {
-            kind: identity.kind === "dynamic" ? "subagent_dynamic" : "subagent_none",
-            subAgentType: identity.subAgentType,
-            reason: identity.reason,
-            ...(identity.subject ? { subject: identity.subject } : {}),
-        },
-    });
     return identity;
 }
+/** {@link claimRegistration} for sub-agents, against an injected store. */
+function claimViaInjectedSubAgentStore(harness, args, registered) {
+    const existing = args.loadFn(harness, args.sessionKey, args.subAgentType);
+    if (isUsablePeer(existing, registered)) {
+        return { credentials: existing, peer: true };
+    }
+    args.saveFn(harness, args.sessionKey, args.subAgentType, registered);
+    return { credentials: registered, peer: false };
+}
 async function resolveSubAgentIdentity(args) {
     if (!args.projectUrl) {
         return {
@@ -640,8 +1365,12 @@ async function resolveSubAgentIdentity(args) {
             warnings: args.warnings,
         };
     }
-    // 1. Re-use persisted credentials if they match the current project URL.
-    const persisted = args.loadFn(args.subAgentType);
+    // 1. Re-use persisted credentials matching this `(projectUrl, harness,
+    //    subAgentType)` triple. Keying on the type alone would give two
+    //    harnesses' same-named sub-agents (both call theirs `Explore`) one
+    //    shared identity, and the audit trail could no longer tell them apart.
+    const harnessKey = args.harness?.trim() || config_js_1.UNKNOWN_HARNESS_KEY;
+    const persisted = args.loadFn(harnessKey, args.sessionKey, args.subAgentType);
     if (persisted && persisted.projectUrl === args.projectUrl) {
         return {
             kind: "dynamic",
@@ -664,16 +1393,20 @@ async function resolveSubAgentIdentity(args) {
             warnings: args.warnings,
         };
     }
-    // 3. Fresh DCR. client_name is namespaced under sub-agent so audit logs
-    //    can distinguish it from the top-level agent registration.
-    const subHarness = args.harness
-        ? `${args.harness}-subagent-${args.subAgentType}`
-        : `subagent-${args.subAgentType}`;
+    // 3. Fresh DCR. The harness and the type go over as separate fields, which is
+    //    what makes `agentClientName` emit a sub-agent name
+    //    ("… · sub-agent · <harness>/<type> @ <host>"). Folding the type into the
+    //    harness instead would register the sub-agent under an *agent* name, and
+    //    that name is the only thing tying the client back to the delegation edge
+    //    the broker keys on (harness, host, type).
     try {
         const registered = await args.registerFn({
             projectUrl: args.projectUrl,
             auth: args.iat,
-            harness: subHarness,
+            harness: args.harness,
+            subAgentType: args.subAgentType,
+            sessionId: args.sessionKey === config_js_1.SESSIONLESS_KEY ? undefined : args.sessionKey,
+            signal: args.signal,
             ...(args.delegatorSubject
                 ? {
                     delegation: {
@@ -684,13 +1417,26 @@ async function resolveSubAgentIdentity(args) {
                 }
                 : {}),
         });
-        args.saveFn(args.subAgentType, registered);
+        // Same double-checked claim as the agent path: a concurrent process of
+        // this harness may have registered the sub-agent while our POST was in
+        // flight. Adopt the peer's client and revoke ours rather than orphan one.
+        const claim = args.useSharedStore
+            ? claimSubAgentDynamicCredentials(harnessKey, args.sessionKey, args.subAgentType, registered)
+            : claimViaInjectedSubAgentStore(harnessKey, args, registered);
+        if (claim.peer) {
+            args.warnings.push(`A concurrent process registered sub-agent ${args.subAgentType} (${claim.credentials.clientId}) for this session first; adopting it and revoking ${registered.clientId}.`);
+            await args.revokeFn(registered).catch(() => {
+                /* best-effort cleanup; a failed revoke leaves an orphan, never an error */
+            });
+        }
         return {
             kind: "dynamic",
             subAgentType: args.subAgentType,
-            subject: registered.clientId,
-            credentials: registered,
-            reason: `Registered sub-agent ${args.subAgentType} via DCR (RFC 7591)`,
+            subject: claim.credentials.clientId,
+            credentials: claim.credentials,
+            reason: claim.peer
+                ? `Adopted concurrently registered sub-agent ${args.subAgentType}`
+                : `Registered sub-agent ${args.subAgentType} via DCR (RFC 7591)`,
             warnings: args.warnings,
         };
     }