@cotal-ai/cli 0.61.0 → 0.63.0

package/dist/commands/spawn.js

@@ -1,8 +1,8 @@
 import { spawn as spawnProcess, execFile } from "node:child_process";
 import { readFileSync, rmSync, statSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
-import { agentFilePath, connectorServers, spawnEnvAllow, deprovisionAgent, discardLaunchArtifacts, firstFreeName, isReachable, loadAgentFile, reclaimWithChild, loadCotalConfig, mintCreds, newIdentity, DEV_OWNER, parseShareSelection, principalKey, mintLifecycleUid, spawnNameError, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, CotalEndpoint, } from "@cotal-ai/core";
-import { agentActorTokenKey, agentCredsKey, agentSecretFilePaths, agentSentinelCredsKey, authDir, credsFlag, defaultAgentOverride, defaultAgentType, defaultPersonaOverride, defaultPersonaRef, launchFlags, loadMeshes, findMesh, getSpaceAuth, materializeSecretToFile, mergeLaunchOptions, parseLaunchOptions, provenance, resolveMeshTarget, serverFlag, spaceAccountPath, spaceFlag, userAuthStateDir, workspaceSecretStore, refreshRegistrationPolicy, } from "@cotal-ai/workspace";
+import { agentFilePath, connectorServers, spawnEnvAllow, deprovisionAgent, discardLaunchArtifacts, firstFreeName, isReachable, loadAgentFile, reclaimWithChild, loadCotalConfig, modelPolicyRefusal, mintCreds, newIdentity, DEV_OWNER, parseShareSelection, principalKey, mintLifecycleUid, MANAGED_HANDOFF_FILE_ENV, parseManagedLifecycleHandoff, spawnNameError, provisionAgent, provisionAgentDurables, registry, resolveAuthProvider, CotalEndpoint, } from "@cotal-ai/core";
+import { agentActorTokenKey, agentCredsKey, agentSecretFilePaths, agentSentinelCredsKey, authDir, credsFlag, defaultAgentOverride, defaultAgentType, defaultPersonaOverride, defaultPersonaRef, launchFlags, loadMeshes, findMesh, getSpaceAuth, materializeSecretToFile, mergeLaunchOptions, parseLaunchOptions, preflightOrThrow, provenance, resolveMeshTarget, resolveTargetOrThrow, serverFlag, spaceAccountPath, spaceFlag, spaceKey, userAuthStateDir, workspaceSecretStore, refreshRegistrationPolicy, resolveSeatControlTarget, } from "@cotal-ai/workspace";
 import { c } from "../ui.js";
 import { completedFlagValue, completingFlagValue, hasCompletedFlagValue, positionalsForCompletion } from "../lib/completion.js";
 import { preflightOrExit, resolveTargetOrExit } from "../lib/connect.js";
@@ -10,6 +10,7 @@ import { askManager, failIfNotOk, onInstanceOrExit, resolveControlTarget, START_
 import { listDeclaredChannels, listDeclaredRoles, listPersonas } from "../lib/personas.js";
 import { spawnManifest } from "./spawn-manifest.js";
 import { extensionNames, materializeExtension } from "../ext-loader.js";
+import { claimManagedHandoff } from "../managed-handoff.js";
 import { checkDialPolicy, checkEnforcement, checkServer, checkUserBundle, persistRemoteUserEntry, probeEnforcement, tlsIntent, userExchangeIssuer, verifyUserExchange, } from "./meshes-add.js";
 const ENROLLMENT_URL_ENV = "COTAL_ENROLLMENT_URL";
 const ENROLLMENT_FILE_ENV = "COTAL_ENROLLMENT_FILE";
@@ -100,21 +101,59 @@ export function checkEnrollmentBundle(raw, actor) {
     }
     return { bundle: { ...o, ...material.material, idp }, ...(stock ? { stock } : {}) };
 }
-async function registerEnrollmentMesh(stock, root) {
-    const serverCheck = checkServer(stock.server);
-    if (!serverCheck.ok)
-        throw new Error(serverCheck.message.replace(/^✗\s*/, ""));
+/** What a managed handoff's bootstrap refuses with at each phase that runs a check shared with the
+ *  enrollment path. Those checks' diagnostics, and the filesystem errors under them, quote the
+ *  space, the server, the exchange URL, the actor or a path named for one of them, and a handoff
+ *  refusal never echoes the document, so each sentence names only the field and the phase. */
+const HANDOFF_REFUSALS = {
+    space: "the managed handoff's space is malformed",
+    bundle: "the managed handoff's mesh fields failed the user-auth bundle check",
+    registration: "the managed handoff's space failed the local registration",
+    target: "the managed handoff's space failed target resolution",
+    server: "the managed handoff's server is not a broker URL this machine may dial",
+    exchange: "the managed handoff's exchangeUrl failed the exchange check",
+    enforcement: "the managed handoff's server failed the enforcement check",
+    policy: "the managed handoff's exchangeUrl failed the policy refresh",
+    preflight: "the managed handoff's server failed the broker preflight",
+    bearer: "the managed handoff's actorToken failed the agent auth preflight",
+};
+/** Map a parsed handoff onto the redeem consumer's shapes. Pure. */
+export function handoffEnrollmentBundle(h) {
+    const userAuth = { provider: h.authProvider, idp: h.idp, endpoints: { url: h.exchangeUrl }, remote: true };
+    try {
+        const { bundle, stock } = checkEnrollmentBundle({
+            space: h.space, actor: h.actor, owner: h.owner, lifecycleUid: h.lifecycleUid, actorToken: h.actorToken, sentinelCreds: h.sentinelCreds,
+            subscribe: h.subscribe, allowSubscribe: h.allowSubscribe, allowPublish: h.allowPublish,
+            brokerAccess: { kind: "direct", url: h.server }, authServiceUrl: h.exchangeUrl, idp: h.idp,
+            server: h.server, tlsRequired: h.tlsRequired, userAuth, ...(h.policy ? { policy: h.policy } : {}),
+        }, h.actor);
+        return { bundle, stock: stock };
+    }
+    catch {
+        throw new Error(HANDOFF_REFUSALS.bundle);
+    }
+}
+/** With `refusals`, a step that fails its check or throws refuses with its phase's sentence instead
+ *  of its diagnostic. */
+async function registerEnrollmentMesh(stock, root, refusals) {
+    const step = async (phase, run) => {
+        let check;
+        try {
+            check = await run();
+        }
+        catch (e) {
+            throw refusals ? new Error(refusals[phase]) : e;
+        }
+        if (!check.ok)
+            throw new Error(refusals?.[phase] ?? check.message.replace(/^✗\s*/, ""));
+        return check.value;
+    };
+    await step("server", () => checkServer(stock.server));
     const tlsRequired = stock.tlsRequired || tlsIntent(stock.server, false);
-    const dial = checkDialPolicy(stock.server, { tlsRequired, allowUnencryptedOverlay: false });
-    if (!dial.ok)
-        throw new Error(dial.message.replace(/^✗\s*/, ""));
-    const exchange = await verifyUserExchange(stock.userAuth.endpoints.url, userExchangeIssuer(stock.space));
-    if (!exchange.ok)
-        throw new Error(exchange.message.replace(/^✗\s*/, ""));
-    const enforcement = checkEnforcement("user", await probeEnforcement(stock.server), stock.server, stock.space, root);
-    if (!enforcement.ok)
-        throw new Error(enforcement.message.replace(/^✗\s*/, ""));
-    persistRemoteUserEntry(stock.space, stock.server, root, stock, tlsRequired, Boolean(dial.value.residual));
+    const dial = await step("server", () => checkDialPolicy(stock.server, { tlsRequired, allowUnencryptedOverlay: false }));
+    await step("exchange", () => verifyUserExchange(stock.userAuth.endpoints.url, userExchangeIssuer(stock.space)));
+    await step("enforcement", async () => checkEnforcement("user", await probeEnforcement(stock.server), stock.server, stock.space, root));
+    await step("registration", () => ({ ok: true, value: persistRemoteUserEntry(stock.space, stock.server, root, stock, tlsRequired, Boolean(dial.residual)) }));
 }
 /** Completion for `cotal spawn` — `--space <TAB>` lists the running meshes, and the first positional
  *  is a persona from the mesh this spawn would target. Resolved OFFLINE (registry + `current`, no
@@ -249,6 +288,8 @@ export const spawnFlags = [
     { name: "allow-stale", type: "string", value: "<a,b>", description: "with -f: waive named stale agents (apply-only)" },
     { name: "runtime", type: "string", value: "<name>", description: "with -f: override the manifest's runtime" },
     { name: "on", type: "string", value: "<instance>", description: "with --detach: target a specific manager instance id (multi-manager space); default = class anycast; `ps`'s instance id, not roster's `local.…` principal id" },
+    { name: "expect-owner", type: "string", value: "<u_…>", description: `with ${MANAGED_HANDOFF_FILE_ENV}: the owner the managed handoff must carry` },
+    { name: "expect-lifecycle-uid", type: "string", value: "<uid>", description: `with ${MANAGED_HANDOFF_FILE_ENV}: the lifecycle UID the managed handoff must carry` },
 ];
 /** Foreground `cotal spawn` resolves its `--agent` connector from the registry (spawn.ts below); on
  *  the published binary nothing static-imports connectors, so the resolved one is materialized as a
@@ -295,7 +336,12 @@ async function spawnDetached(values, positionals, events, launchOptions) {
     const ref = spawnPersonaRef(values.config, positionals);
     const managerConfigRef = values.config ?? (!positionals[0] && defaultPersona ? ref : undefined);
     const on = onInstanceOrExit(values.on, "cotal spawn <persona> --detach");
-    const t = await resolveControlTarget({ space: values.space, server: values.server, creds: values.creds }, "control-caller-privileged", on);
+    // From a managed seat's own shell the launch is the SEAT's, as its `cotal_spawn` tool is: the
+    // manager records the seat as the spawner, so the seat can stop the child it asked for (#718).
+    // `--on` keeps the pin on that path too.
+    const flags = { space: values.space, server: values.server, creds: values.creds };
+    const t = (values.creds === undefined ? await resolveSeatControlTarget(flags, on) : undefined)
+        ?? await resolveControlTarget(flags, "control-caller-privileged", on);
     let policy;
     try {
         policy = await refreshRegistrationPolicy(t);
@@ -373,6 +419,9 @@ async function spawnDetached(values, positionals, events, launchOptions) {
 export async function spawn(args) {
     const positionals = args.positionals;
     const values = args.values;
+    // Claimed first: custody already removed the file and its variable, so the text lives only here
+    // and no refusal below can leave it anywhere.
+    const handoffText = claimManagedHandoff();
     let enrollmentUrl;
     try {
         enrollmentUrl = enrollmentInput();
@@ -386,6 +435,56 @@ export async function spawn(args) {
         // command can start extension, bearer-preflight, or harness children.
         scrubEnrollmentEnv(process.env);
     }
+    let redeemedEnrollment;
+    if (handoffText === undefined && (values["expect-owner"] !== undefined || values["expect-lifecycle-uid"] !== undefined)) {
+        console.error(c.red(`✗ --expect-owner and --expect-lifecycle-uid apply only with ${MANAGED_HANDOFF_FILE_ENV}`));
+        process.exit(1);
+    }
+    if (handoffText !== undefined) {
+        const refusal = enrollmentUrl ? `${MANAGED_HANDOFF_FILE_ENV} cannot be combined with ${ENROLLMENT_URL_ENV}/${ENROLLMENT_FILE_ENV}`
+            : values.detach || values.file || values.creds ? `${MANAGED_HANDOFF_FILE_ENV} applies only to a foreground persona spawn without --creds`
+                : !values.space || !values.name || !values["expect-owner"] || !values["expect-lifecycle-uid"]
+                    ? `${MANAGED_HANDOFF_FILE_ENV} requires --space, --name, --expect-owner and --expect-lifecycle-uid`
+                    : !values.config ? `${MANAGED_HANDOFF_FILE_ENV} requires --config <persona-file>`
+                        : undefined;
+        if (refusal) {
+            console.error(c.red(`✗ ${refusal}`));
+            process.exit(1);
+        }
+        try {
+            loadAgentFile(resolvePath(values.config));
+        }
+        catch (e) {
+            console.error(c.red(`✗ cannot load the managed handoff persona: ${e.message}`));
+            process.exit(1);
+        }
+        try {
+            const handoff = parseManagedLifecycleHandoff(handoffText, {
+                space: values.space, owner: values["expect-owner"], actor: values.name, lifecycleUid: values["expect-lifecycle-uid"],
+            });
+            try {
+                spaceKey(handoff.space);
+            }
+            catch {
+                throw new Error(HANDOFF_REFUSALS.space);
+            }
+            const { bundle, stock } = handoffEnrollmentBundle(handoff);
+            redeemedEnrollment = { bundle, stock };
+            let registered;
+            try {
+                registered = findMesh(handoff.space) !== undefined;
+            }
+            catch {
+                throw new Error(HANDOFF_REFUSALS.registration);
+            }
+            if (!registered)
+                await registerEnrollmentMesh(stock, resolvePath(values.config, ".."), HANDOFF_REFUSALS);
+        }
+        catch (e) {
+            console.error(c.red(`✗ ${e.message}`));
+            process.exit(1);
+        }
+    }
     if (enrollmentUrl && (values.detach || values.file)) {
         console.error(c.red(`✗ ${ENROLLMENT_URL_ENV}/${ENROLLMENT_FILE_ENV} apply only to a foreground persona spawn`));
         process.exit(1);
@@ -479,7 +578,6 @@ export async function spawn(args) {
         console.error(c.red("✗ --creds is only valid with --detach (it authenticates the manager control call)"));
         process.exit(1);
     }
-    let redeemedEnrollment;
     // An enrollment may bootstrap the stock remote user-mesh record before normal target resolution.
     // Redeem only when the named space is not registered; an existing entry defers redemption until
     // after persona resolution so the response actor can be checked against the requested identity.
@@ -506,19 +604,32 @@ export async function spawn(args) {
         }
     }
     // Which mesh this spawn joins — creds + personas together, resolved from --server/--space, the
-    // selected `current` mesh, a local project, or the registry's only running mesh.
-    const target = await resolveTargetOrExit({ server: values.server, space: values.space });
+    // selected `current` mesh, a local project, or the registry's only running mesh. A handoff's
+    // resolution diagnostics quote its space, and only a remote user-auth record can host the
+    // lifecycle it carries, so any other record is refused before a later step reads it.
+    const target = handoffText === undefined
+        ? await resolveTargetOrExit({ server: values.server, space: values.space })
+        : await resolveTargetOrThrow({ server: values.server, space: values.space }).catch(() => {
+            console.error(c.red(`✗ ${HANDOFF_REFUSALS.target}`));
+            process.exit(1);
+        });
+    if (handoffText !== undefined && !(target.mode === "user" && target.userAuth?.remote)) {
+        console.error(c.red("✗ the managed handoff's space is registered here as a local mesh, so it cannot host a managed handoff"));
+        process.exit(1);
+    }
     let policy;
     try {
         policy = await refreshRegistrationPolicy(target);
     }
     catch (e) {
-        console.error(c.red(`✗ ${e.message}`));
+        console.error(c.red(`✗ ${handoffText === undefined ? e.message : HANDOFF_REFUSALS.policy}`));
         process.exit(1);
     }
     const eventsRequired = policy?.events === "required";
+    // A handoff's space is a value from the document, so its policy refusals name the field instead.
+    const policySpace = handoffText === undefined ? `space "${target.space}"` : "the managed handoff's space";
     if (eventsRequired && values["no-events"]) {
-        console.error(c.red(`✗ space "${target.space}" requires the event plane by registration policy; --no-events is not allowed`));
+        console.error(c.red(`✗ ${policySpace} requires the event plane by registration policy; --no-events is not allowed`));
         process.exit(1);
     }
     // Foreground is the operator's own in-process launch (no typed door, no epAdminReach) and is
@@ -539,7 +650,11 @@ export async function spawn(args) {
     }
     catch (e) {
         const code = e.code;
-        if (code === "ENOENT") {
+        // The not-found text names the mesh's space and server, which for a handoff are its values.
+        if (handoffText !== undefined) {
+            console.error(c.red(`✗ cannot load the managed handoff persona: ${e.message}`));
+        }
+        else if (code === "ENOENT") {
             // A refusal that names no root is why this bug cost an hour. The old text asserted an absence
             // ("no default persona yet") and prescribed a remedy (`cotal setup`) without saying WHERE it
             // had looked — so when setup seeded a cwd-derived root and spawn read the resolved mesh's,
@@ -562,6 +677,13 @@ export async function spawn(args) {
     // --name / --role override the file (name defaults from the file's frontmatter).
     const requested = values.name ?? def.name;
     const role = values.role ?? def.role;
+    // Flags win over the file, resolved once: the model policy below judges these values and the
+    // connector launches on them. Left to the connector, the model is re-read from the persona at
+    // launch, after the check, so an edit in between would launch a model the policy never saw.
+    const model = values.model ?? def.model;
+    const variant = values.variant ?? def.variant;
+    // Opaque connector options: `--opt` flags win per key over the persona's `launchOptions:`.
+    const launchOptions = mergeLaunchOptions(def.launchOptions, cliLaunchOptions);
     if (redeemedEnrollment && redeemedEnrollment.bundle.actor !== requested) {
         console.error(c.red(`✗ the enrollment is for actor "${redeemedEnrollment.bundle.actor}" but this spawn names "${requested}"`));
         process.exit(1);
@@ -569,9 +691,34 @@ export async function spawn(args) {
     // #867: same door as the detached path — the effective identity (flag or file) must be mintable
     //  before any provision work; core's own refusal names the offender and the `_` remedy.
     refuseUnmintableNameOrExit(requested, target.mode === "user");
+    // #581: the same per-role model allowlist the manager enforces on a detached spawn, judged on the
+    // effective role, model (flag over file) and launch options before anything is provisioned or launched.
+    try {
+        const refusal = modelPolicyRefusal(loadCotalConfig(target.root), {
+            persona: `persona "${ref}" (${path})`,
+            role, model, variant,
+            modelFlag: values.model !== undefined,
+            variantFlag: values.variant !== undefined,
+            launchOptions,
+        });
+        if (refusal) {
+            console.error(c.red(`✗ ${refusal}`));
+            process.exit(1);
+        }
+    }
+    catch (e) {
+        console.error(c.red(`✗ ${e.message}`));
+        process.exit(1);
+    }
     // Preflight: fail with one sentence if the mesh is down or won't take our creds, instead of
     // crashing mid-connect with a raw NATS Authorization Violation.
-    await preflightOrExit(target);
+    if (handoffText === undefined)
+        await preflightOrExit(target);
+    else
+        await preflightOrThrow(target).catch(() => {
+            console.error(c.red(`✗ ${HANDOFF_REFUSALS.preflight}`));
+            process.exit(1);
+        });
     // A second `cotal spawn` of the same agent would otherwise join under a duplicate mesh identity:
     // auto-number the name past anyone already present (best-effort — this path bypasses the manager's
     // race-free reservation; see uniqueMeshName). Everything below (creds path, launch) uses `name`.
@@ -610,7 +757,6 @@ export async function spawn(args) {
         console.error(c.red(`✗ ${e.message}`));
         process.exit(1);
     }
-    const variant = values.variant ?? def.variant;
     if (variant && !connector.supportsModelVariant) {
         console.error(c.red(`✗ ${agentType} connector does not support model variants (variant)`));
         process.exit(1);
@@ -651,7 +797,7 @@ export async function spawn(args) {
     // mode the owner is resolved inside the provisioning call below.
     if (launchEvents && !connector.eventChannel) {
         console.error(c.red(eventsRequired
-            ? `✗ space "${space}" requires the event plane by registration policy, but connector "${connector.name}" does not publish one`
+            ? `✗ ${policySpace} requires the event plane by registration policy, but connector "${connector.name}" does not publish one`
             : `✗ connector "${connector.name}" does not publish an AG-UI event plane; pass --no-events to launch it without one`));
         process.exit(1);
     }
@@ -663,12 +809,12 @@ export async function spawn(args) {
     const remoteProvisioningUrl = target.mode === "user" && target.userAuth?.remote
         ? target.userAuth.endpoints?.agentProvisioningUrl
         : undefined;
-    if (target.mode === "user" && target.userAuth?.remote && !remoteProvisioningUrl && !enrollmentUrl) {
+    if (target.mode === "user" && target.userAuth?.remote && !remoteProvisioningUrl && !enrollmentUrl && !redeemedEnrollment) {
         console.error(c.red(`✗ mesh "${target.space}" runs elsewhere and advertises no agent-provisioning endpoint, so agents cannot be provisioned from this machine`));
         console.error(c.dim(`  a user-mode agent's credentials are granted where the mesh's signer lives; ask the mesh operator to advertise one (\`cotal up --agent-provisioning-url …\`), or run the agent there`));
         process.exit(1);
     }
-    if (target.mode === "user" && target.userAuth?.remote && enrollmentUrl) {
+    if (target.mode === "user" && target.userAuth?.remote && (enrollmentUrl || redeemedEnrollment)) {
         if (!redeemedEnrollment) {
             try {
                 const provider = resolveAuthProvider();
@@ -695,7 +841,7 @@ export async function spawn(args) {
             console.error(c.red("✗ the enrollment's authServiceUrl does not match the registered mesh exchange"));
             process.exit(1);
         }
-        const remote = await provisionRemoteUserForeground(target, name, { body: enrolled, exchangeUrl: enrolled.authServiceUrl });
+        const remote = await provisionRemoteUserForeground(target, name, { body: enrolled, exchangeUrl: enrolled.authServiceUrl }, handoffText === undefined ? undefined : HANDOFF_REFUSALS);
         userAuth = remote.userAuth;
         userCleanup = remote.cleanup;
         remoteUserAuth = true;
@@ -850,11 +996,9 @@ export async function spawn(args) {
             lifecycleUid,
             servers: server,
             configPath: path,
-            // Model override (wins over the agent file's `model:`) — launch-grammar parity with --detach.
-            model: values.model,
+            model,
             variant,
-            // Opaque connector options: `--opt` flags win per key over the persona's `launchOptions:`.
-            launchOptions: mergeLaunchOptions(def.launchOptions, cliLaunchOptions),
+            launchOptions,
             subscribe,
             allowSubscribe,
             allowPublish,
@@ -981,16 +1125,26 @@ function checkRemoteAgentMaterial(v, actor) {
  *  Deliberately NOT reusing the local path's cleanup: nothing here created broker state locally, so
  *  teardown is the mesh's business (its lifecycle owns the row and the durables). The spawned
  *  agent's material is shredded on exit; the row is not revoked from here, because this machine
- *  holds no authority to revoke it. */
-async function provisionRemoteUserForeground(target, name, source) {
+ *  holds no authority to revoke it. For a managed handoff, `refusals` replaces the sentences of the
+ *  local-state, material and bearer steps, which quote the space, the actor or the exchange URL. */
+async function provisionRemoteUserForeground(target, name, source, refusals) {
     const { space } = target;
-    const dir = userAuthStateDir(target.root, space);
     const store = workspaceSecretStore(target.root);
     const composition = { injected: false, root: target.root };
     const fail = (msg) => {
         console.error(c.red(`✗ ${msg}`));
         process.exit(1);
     };
+    // Resolved first, as by every consumer of the space's local state: each resolution migrates a
+    // pre-hex or root-scoped layout, or refuses an ambiguous one, before any request or material.
+    let paths;
+    try {
+        userAuthStateDir(target.root, space);
+        paths = agentSecretFilePaths(target.root, space, name);
+    }
+    catch (e) {
+        return fail(refusals?.registration ?? e.message);
+    }
     let provider;
     try {
         provider = resolveAuthProvider();
@@ -1022,9 +1176,9 @@ async function provisionRemoteUserForeground(target, name, source) {
     }
     const checked = checkRemoteAgentMaterial(body, name);
     if (!checked.ok)
-        return fail(checked.message);
+        return fail(refusals?.bundle ?? checked.message);
     const material = checked.material;
-    const { actorToken: tokenPath, sentinelCreds: sentinelPath, health: healthPath } = agentSecretFilePaths(target.root, space, name);
+    const { actorToken: tokenPath, sentinelCreds: sentinelPath, health: healthPath } = paths;
     try {
         // Land both secrets 0600 through the store, exactly as the local path does — the bearer
         // re-exec and the launch handoff read FILES.
@@ -1066,12 +1220,20 @@ async function provisionRemoteUserForeground(target, name, source) {
         };
     }
     catch (e) {
-        await store.delete(agentActorTokenKey(space, name, composition)).catch(() => { });
-        await store.delete(agentSentinelCredsKey(space, name, composition)).catch(() => { });
-        rmSync(tokenPath, { force: true });
-        rmSync(sentinelPath, { force: true });
-        rmSync(healthPath, { force: true });
-        return fail(`agent auth preflight failed for "${name}": ${e.message}`);
+        let cause = e;
+        try {
+            await store.delete(agentActorTokenKey(space, name, composition)).catch(() => { });
+            await store.delete(agentSentinelCredsKey(space, name, composition)).catch(() => { });
+            rmSync(tokenPath, { force: true });
+            rmSync(sentinelPath, { force: true });
+            rmSync(healthPath, { force: true });
+        }
+        catch (shred) {
+            // Material may be left behind, which outranks the failure that started the shred, and an
+            // escaped error would bypass the refusal below.
+            cause = shred;
+        }
+        return fail(refusals?.bearer ?? `agent auth preflight failed for "${name}": ${cause.message}`);
     }
 }
 /** Foreground USER-MODE onboarding — the CLI-side twin of the manager's user spawn provisioning: