@cotal-ai/manager 0.90.1 → 0.92.0

package/dist/commands.js

@@ -1,14 +1,17 @@
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { Kvm } from "@nats-io/kv";
-import { dialerFor, isReachable, epAuthBucket, recordsBucket, instancePinnedInstrumentCapabilities, mintCreds, mintLifecycleUid, newIdentity, remoteManagerActors, remoteManagerRegistrationProof, resolveAuthProvider, standaloneConnectOpts, DEFAULT_SERVER, DEFAULT_SPACE, DEV_OWNER, registry, } from "@cotal-ai/core";
-import { authDir, canonicalLocalProcessPath, consumeManagerShutdownIntent, findCotalRoot, getSpaceAuth, hasUserAuthState, isWorkspaceTargetError, listenForLocalStop, loadManagerInstanceIdentity, loadSpaceAccountAuth, parsePositiveIntegerFlag, publishManagerSpareCapability, reclaimDeadPreUpgradeRecord, removePidPair, resolveMeshTarget, soleSpaceOf, userAuthStateDir, workspaceSecretStore, writePidPair, c, MANAGER_DELIVERY_AWARE_MARKER, MANAGER_PIDFILE, refreshRegistrationPolicy, } from "@cotal-ai/workspace";
+import * as prompts from "@clack/prompts";
+import { dialerFor, isReachable, epAuthBucket, recordsBucket, mintCreds, newIdentity, remoteManagerActors, remoteManagerRegistrationProof, resolveAuthProvider, standaloneConnectOpts, DEFAULT_SERVER, DEFAULT_SPACE, DEV_OWNER, registry, parseCommandArgs, token, writePrivateRecord, } from "@cotal-ai/core";
+import { authDir, canonicalLocalProcessPath, claimServicePid, consumeManagerShutdownIntent, findCotalRoot, getSpaceAuth, hasUserAuthState, isWorkspaceTargetError, listenForLocalStop, loadManagerInstanceIdentity, loadSpaceAccountAuth, parsePositiveIntegerFlag, publishManagerSpareCapability, reclaimDeadPreUpgradeRecord, removePidPair, resolveMeshTarget, soleSpaceOf, userAuthStateDir, workspaceSecretStore, writePidPair, c, MANAGER_DELIVERY_AWARE_MARKER, MANAGER_PIDFILE, untilInputEnds, brokerAddressForDisplay, CommandFailure, inputDisabledByFlag, isCommandFailure, jsonFlag, plainFlag, presentationOf, renderReport, resolveNativeServiceTarget, terminalWidth, writeResult, refreshRegistrationPolicy, publishServiceStartup, serviceStartupPath, publishServiceStopReceipt, publishServedContract, protectedCredentialReference, readLocalRecordSource, deprecatedDaemonEntry, } from "@cotal-ai/workspace";
 import { Manager } from "./manager.js";
+import { acceptManagerServiceStop, armManagerServiceObserver, bindManagerServiceIdentity, managerServiceChild } from "./service-child.js";
 import { MANAGER_ENDPOINT } from "./manager-service-contract.js";
 import { makeManagerEndpointHolderEvictor } from "./endpoint-evict.js";
 import { makeManagerHolderLivenessProbe } from "./holder-liveness.js";
 import { GateReconcileRefused, reconcileEndpointGate } from "./reconcile-gate.js";
-import { InstanceDeregisterRefused, deregisterEndpointInstance, makeInstanceProbe } from "./deregister-instance.js";
+import { endpointDeregisterAction } from "./operator-deregister.js";
 import { loadRoster } from "./roster.js";
 import { loadLaunchSpec, materializePersona, launchAgentToStartOpts } from "./launch.js";
 import {} from "./runtime/index.js";
@@ -17,6 +20,35 @@ import { drainSeats } from "@cotal-ai/seat";
 import { currentRegistrationProof, loadOrCreateRemoteManagerIdentity, materialCredential, remoteStandingBundleRenewal, remoteManagedAgentEnrollmentMaterial, remoteManagedAgentEnrollmentRequest, remoteManagedAgentPrepareRetirementRequest, remoteManagedAgentRetirementPrepared, remoteManagerAdminAuthorizationRequest, remoteManagerAdminAuthorized, remoteManagerAuthorityRequest, remoteManagerGoalIndexEntries, remoteManagerGoalIndexScanRequest, remoteManagerMaintenanceRequest, remoteManagerMaintenanceResult, remoteRetainedAgentValidationRequest, retainedAgentAuthority, remoteRunHosting } from "./remote-authority.js";
 import { registerRemoteManagerAuthority } from "./remote-register.js";
 import { managerClusterArtifacts } from "./manager-service-contract.js";
+/** Read the resume commit token from its protected handoff file once, check it against the
+ *  digest named on argv, then unlink it. Errors name the field only; the value is never echoed. */
+export function readResumeCommitFile(path, sha256) {
+    if (!path.startsWith("/") || path.length > 4096 || /[\u0000-\u001f\u007f]/u.test(path) || !/^[0-9a-f]{64}$/.test(sha256))
+        throw new CommandFailure("refused", "USAGE_INVALID", "--resume-commit-file needs an absolute protected path and --resume-commit-sha256 its full digest");
+    protectedCredentialReference(path);
+    const bytes = readLocalRecordSource(path, 128, true);
+    if (bytes === undefined)
+        throw new CommandFailure("refused", "TARGET_UNAVAILABLE", "the --resume-commit-file handoff is absent; it was not regenerated");
+    const value = bytes.toString("utf8");
+    if (!/^[a-f0-9]{64}$/.test(value) || createHash("sha256").update(value).digest("hex") !== sha256)
+        throw new CommandFailure("refused", "CONFLICT", "the --resume-commit-file handoff does not match --resume-commit-sha256; its contents were not echoed");
+    rmSync(path);
+    return value;
+}
+/** The resume commit token from one input form only. `supervise` keeps the deprecated argv
+ *  token for older callers; the native child accepts only the file form. */
+function resumeCommitToken(v, allowArgv) {
+    const file = v["resume-commit-file"] !== undefined || v["resume-commit-sha256"] !== undefined;
+    if (file && v["resume-commit-token"] !== undefined)
+        throw new CommandFailure("refused", "USAGE_INVALID", "use either --resume-commit-token or --resume-commit-file with --resume-commit-sha256, not both");
+    if (!allowArgv && v["resume-commit-token"] !== undefined)
+        throw new CommandFailure("refused", "USAGE_INVALID", "the native manager child takes the resume commit token only as a protected file");
+    if (!file)
+        return v["resume-commit-token"];
+    if (v["resume-commit-file"] === undefined || v["resume-commit-sha256"] === undefined)
+        throw new CommandFailure("refused", "USAGE_INVALID", "--resume-commit-file and --resume-commit-sha256 are required together");
+    return readResumeCommitFile(v["resume-commit-file"], v["resume-commit-sha256"]);
+}
 /**
  * RECORD THIS PROCESS as the running manager, and un-record it on a clean exit.
  *
@@ -52,10 +84,11 @@ export function recordManagerPid(root, space) {
     const markerPath = canonicalLocalProcessPath(MANAGER_DELIVERY_AWARE_MARKER, ctx);
     const mine = String(process.pid);
     // #969/#1238: publish the pair by rename so a later teardown never sees a torn pairing.
+    // Both records are created 0o600 under fresh names and renamed into place (writePidPair).
     writePidPair(pidPath, process.pid);
     // Written together and removed together: the marker proves the LIVE pid is a non-hosting build,
-    // and it is only meaningful while it names that same pid.
-    writeFileSync(markerPath, mine);
+    // and it is only meaningful while it names that same pid. A symlink at the marker is refused.
+    writePrivateRecord(markerPath, mine);
     return () => {
         for (const p of [markerPath, pidPath]) {
             try {
@@ -160,6 +193,13 @@ function stampConsole() {
     console.log = (...args) => originalLog(new Date().toISOString(), ...args);
     console.error = (...args) => originalError(new Date().toISOString(), ...args);
 }
+function superviseExecution(v) {
+    if (v.execution !== undefined && v.execution !== "runtime" && v.execution !== "none")
+        throw new CommandFailure("refused", "USAGE_INVALID", '--execution must be "runtime" or "none"');
+    if (v.execution === "none" && ["runtime", "spawn", "roster", "launch", "resume-attempt", "resume-commit-token", "resume-commit-file", "resume-commit-sha256"].some((key) => v[key] !== undefined))
+        throw new CommandFailure("refused", "USAGE_INVALID", "execution: none forbids runtime and startup workload flags");
+    return v.execution ?? "runtime";
+}
 /** Run a manager daemon in this process (the long-lived supervisor), then block.
  *  `pty` ships with the manager; every other runtime needs a registered provider. The published
  *  CLI lazy-loads installed providers, while library roots import their integrations explicitly.
@@ -170,26 +210,35 @@ function stampConsole() {
 // `--runtime` forces the manager runtime; honored only on the `supervise` path (default
 // pty). `cmux` gives each teammate its own cmux tab — `cotal supervise --runtime cmux` is
 // the cmux-tab manager.
-async function runManager(args, defaultRuntime) {
+async function runManager(args, defaultRuntime, service) {
     stampConsole();
     const v = args.values;
-    let runtime = defaultRuntime;
+    const managerRoot = service?.root ?? findCotalRoot();
+    const execution = superviseExecution(v);
+    let runtime = execution === "none" ? undefined : defaultRuntime;
     if (defaultRuntime === "auto" && v.runtime) {
         runtime = v.runtime;
     }
     let target;
     try {
-        target = superviseTarget(v);
+        target = superviseTarget(v, managerRoot);
+        if (execution === "none" && target.remoteUser)
+            throw new Error("execution: none on supervise requires a genuine hosting user-auth root, not a participant registration");
     }
     catch (e) {
+        if (service)
+            throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native manager child did not confirm startup; inspect the original protected launch records before another start");
         console.error(c.red(`✗ ${e.message}`));
         process.exit(1);
     }
     const { space, server } = target;
+    // Claim before hosted registration/issuance or local endpoint initialization. Starting
+    // custody proves only this process; no startup/serving phase exists and no contender is adopted.
+    const releaseStartingCustody = service ? claimServicePid({ root: managerRoot, space }, MANAGER_PIDFILE) : undefined;
     let remoteAuthority;
     if (target.remoteUser) {
         try {
-            const root = findCotalRoot();
+            const root = managerRoot;
             const state = loadOrCreateRemoteManagerIdentity(root, space);
             const provider = resolveAuthProvider();
             // Every provider call shares this one context: a call that resolved the root again could land on
@@ -275,7 +324,17 @@ async function runManager(args, defaultRuntime) {
                     state, owner: material.owner, registrationProof: retainedRegistrationProof,
                     accountPublicKey: standing.accountPublicKey, processEpoch: registered.processEpoch,
                     requestRunAdmission: (request) => provider.requestRemoteRunAdmission({ ...providerCall, request }),
+                    requestRunSubmission: async (request) => {
+                        if (!provider.requestRemoteRunSubmission)
+                            throw new Error("auth provider does not implement keyed submission protocol");
+                        return provider.requestRemoteRunSubmission({ ...providerCall, request });
+                    },
                     requestRunAttempt: (request) => provider.requestRemoteRunAttempt({ ...providerCall, request }),
+                    requestRunCancel: async (request) => {
+                        if (!provider.requestRemoteRunCancel)
+                            throw new Error("auth provider does not implement the observed run-cancel protocol");
+                        return provider.requestRemoteRunCancel({ ...providerCall, request });
+                    },
                     requestRunRevoke: async (request) => {
                         if (provider.requestRemoteRunRevoke === undefined)
                             throw new Error(`the registered auth provider "${provider.name}" does not implement closed hosted-run revoke`);
@@ -369,6 +428,8 @@ async function runManager(args, defaultRuntime) {
             };
         }
         catch (e) {
+            if (service)
+                throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native manager child did not confirm hosted authority preparation; it was not retried");
             console.error(c.red(`✗ remote supervision for space "${space}" was refused: ${e.message}. ` +
                 `Foreground \`cotal spawn\` remains available; detached/managed agents require a live host-approved manager-service authority.`));
             process.exit(1);
@@ -376,14 +437,24 @@ async function runManager(args, defaultRuntime) {
     }
     // Parse the roster + launch spec before touching the network — a malformed file should fail fast,
     // before the manager comes up or any agent is spawned.
-    const roster = v.roster ? loadRoster(v.roster) : [];
-    const launchSpec = v.launch ? loadLaunchSpec(v.launch) : undefined;
+    const roster = service ? service.roster ?? [] : v.roster ? loadRoster(v.roster) : [];
+    const launchSpec = service ? service.launchSpec : v.launch ? loadLaunchSpec(v.launch) : undefined;
     if (v["resume-attempt"] && (v.roster || v.launch || v.spawn)) {
         console.error(c.red("✗ --resume-attempt cannot be combined with --roster, --launch, or --spawn; retained agents resume only through the attempt-bound admin control op"));
         process.exit(1);
     }
-    if (v["resume-commit-token"] && !v["resume-attempt"]) {
-        console.error(c.red("✗ --resume-commit-token requires --resume-attempt"));
+    if ((v["resume-commit-token"] || v["resume-commit-file"] || v["resume-commit-sha256"]) && !v["resume-attempt"]) {
+        console.error(c.red("✗ a resume commit token requires --resume-attempt"));
+        process.exit(1);
+    }
+    let resumeDurableCommitToken;
+    try {
+        resumeDurableCommitToken = resumeCommitToken(v, !service);
+    }
+    catch (e) {
+        if (service)
+            throw e;
+        console.error(c.red(`✗ ${e.message}`));
         process.exit(1);
     }
     // The registration policy is read AFTER every local refusal above and before the first dial: a
@@ -394,6 +465,8 @@ async function runManager(args, defaultRuntime) {
         eventsRequired = (await refreshRegistrationPolicy(target))?.events === "required";
     }
     catch (e) {
+        if (service)
+            throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native manager child did not confirm startup; inspect the original protected launch records before another start");
         console.error(c.red(`✗ ${e.message}`));
         process.exit(1);
     }
@@ -414,6 +487,8 @@ async function runManager(args, defaultRuntime) {
         maxSessions = parsePositiveIntegerFlag("--max-sessions", v["max-sessions"]);
     }
     catch (e) {
+        if (service)
+            throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native manager child did not confirm startup; inspect the original protected launch records before another start");
         console.error(c.red(`✗ ${e.message}`));
         process.exit(1);
     }
@@ -430,40 +505,66 @@ async function runManager(args, defaultRuntime) {
             servers: server,
             eventsRequired,
             runtime,
+            execution,
             consolePort,
             wsPort,
             attachHost,
             maxSessions,
             installedExtensions: true,
             resumeAttemptId: v["resume-attempt"],
-            resumeDurableCommitToken: v["resume-commit-token"],
+            resumeDurableCommitToken,
             remoteAuthority,
+            ...(service ? { workspaceRoot: managerRoot, onServiceIdentity: bindManagerServiceIdentity(service) } : {}),
         });
     }
     catch (e) {
+        if (service)
+            throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native manager child did not confirm startup; inspect the original protected launch records before another start");
         console.error(c.red(`✗ ${e.message}`));
         process.exit(1);
     }
-    const managerRoot = findCotalRoot();
     const managerContext = { root: managerRoot, space };
-    let releasePidRecord;
+    // Until the settled record exists, a release only drops a managed child's exact starting slot.
+    // A failed start or a stop that wins the start leaves no settled legacy record behind.
+    let releaseSettledRecord;
+    const releasePidRecord = () => { releaseSettledRecord?.(); releaseStartingCustody?.(); };
     // Signals and cooperative requests share the sparing default. Only the process-bound
-    // `cotal down --with-agents` intent authorizes an agent reap.
+    // `cotal down --with-agents` intent authorizes an agent reap; a managed child accepts only its
+    // request-bound native stop handoff.
     let shuttingDown = false;
     // A start that failed under a pending stop leaves the exit to its own error once that stop settles.
     let startFailed = false;
     let stopped;
+    let disposeObserver;
     const shutdown = () => {
         if (shuttingDown)
             return;
+        let request;
+        let withAgents;
+        if (service) {
+            try {
+                request = acceptManagerServiceStop(mgr, service);
+                withAgents = request.withAgents;
+            }
+            catch {
+                console.error(c.yellow("! the managed manager stop handoff was not accepted; inspect its original request and phase records"));
+                return;
+            }
+        }
+        else {
+            const decision = consumeManagerShutdownIntent({ root: managerRoot, space });
+            if (decision.warning)
+                console.error(c.yellow(`! ${decision.warning}`));
+            withAgents = decision.withAgents;
+        }
         shuttingDown = true;
-        const decision = consumeManagerShutdownIntent({ root: managerRoot, space });
-        if (decision.warning)
-            console.error(c.yellow(`! ${decision.warning}`));
-        stopped = mgr.stop({ withAgents: decision.withAgents })
+        disposeObserver?.();
+        stopped = mgr.stop({ withAgents })
             .then(() => {
             publishManagerSpareCapability(managerContext, false);
-            releasePidRecord?.();
+            releasePidRecord();
+            if (service && request)
+                publishServiceStopReceipt(service.context, request, "completed");
             if (!startFailed)
                 process.exit(0);
         })
@@ -472,7 +573,17 @@ async function runManager(args, defaultRuntime) {
             // under this instance's lease. A record removed under a failed stop is the orphan defect the
             // pidfile contract exists to prevent. The process still exits: stop() has closed what it could,
             // and the shuttingDown latch would otherwise leave it deaf to every later signal (#2290).
-            console.error(c.red(`✗ ${e.message}`));
+            if (service) {
+                if (request) {
+                    try {
+                        publishServiceStopReceipt(service.context, request, "failed");
+                    }
+                    catch { /* Missing terminal evidence stays unknown to the original controller. */ }
+                }
+                console.error(c.red("✗ the native managed manager stop did not confirm completion; its phase evidence was retained"));
+            }
+            else
+                console.error(c.red(`✗ ${e.message}`));
             if (!startFailed)
                 process.exit(1);
         });
@@ -502,13 +613,22 @@ async function runManager(args, defaultRuntime) {
     if (shuttingDown)
         return;
     // The control capability precedes the pid record, so a stop cannot observe a ready manager
-    // before its cooperative endpoint exists. A failed start still publishes no pid record.
-    releasePidRecord = recordManagerPid(managerRoot, space);
+    // before its cooperative endpoint exists. A failed start still publishes no pid record. A
+    // managed child already owns its exact starting PID slot; it settles that same process here.
+    releaseSettledRecord = recordManagerPid(managerRoot, space);
     publishManagerSpareCapability(managerContext, mgr.spareSeats);
-    console.log(c.green("✓ manager up") +
-        c.dim(` (space ${space} · ${mgr.runtimeKind})`) +
-        `\n  console: ${mgr.consoleUrl}` +
-        c.dim("\n  spawn: cotal spawn --detach <persona>   ·   stop: cotal stop --name <n>   (Ctrl-C to shut down)"));
+    if (!service)
+        console.log(c.green("✓ manager up") +
+            c.dim(` (space ${space} · ${mgr.runtimeKind})`) +
+            `\n  console: ${mgr.consoleUrl}` +
+            c.dim("\n  spawn: cotal spawn --detach <persona>   ·   stop: cotal stop --name <n>   (Ctrl-C to shut down)"));
+    if (service) {
+        // The served-contract binding precedes the serving receipt, so a serving child always has it.
+        const served = managerClusterArtifacts();
+        publishServedContract(service.context, { endpoint: MANAGER_ENDPOINT, clusterDigest: served.closureDigest, document: served.document });
+        publishServiceStartup(serviceStartupPath(service.context), { phase: "manager-serving", ...service.context });
+        disposeObserver = armManagerServiceObserver(mgr, service);
+    }
     // Declarative boot: bring up each rostered agent through the same spawn path as a detached spawn.
     // A failed entry is logged but non-fatal — healthy agents stay up and the operator can
     // fix the roster without the supervisor crash-looping.
@@ -548,7 +668,7 @@ async function runManager(args, defaultRuntime) {
     // transient persona, then spawn it with its resolved ACLs/identity. Staggered like `--spawn` so
     // heavy cold-starts don't pile up. A failed entry is logged, non-fatal — healthy agents stay up.
     if (launchSpec) {
-        const root = findCotalRoot();
+        const root = managerRoot;
         for (let i = 0; i < launchSpec.agents.length; i++) {
             const la = launchSpec.agents[i];
             let configPath;
@@ -574,8 +694,33 @@ async function runManager(args, defaultRuntime) {
     }
     await new Promise(() => { });
 }
+function validateMaintenanceArguments(args, mode) {
+    presentationOf(args.values);
+    if (args.positionals.length)
+        throw new CommandFailure("refused", "USAGE_INVALID", `manager ${mode} takes named options, not additional positional targets`);
+    if (mode === "seats" && !args.values.drain && (args.values.yes !== undefined || args.values["dry-run"] !== undefined))
+        throw new CommandFailure("refused", "USAGE_INVALID", "manager seats --yes and --dry-run require --drain");
+    for (const key of mode === "reconcile" ? ["endpoint", "instance"] : []) {
+        const value = args.values[key];
+        if (value !== undefined && (typeof value !== "string" || !value || value.length > 200 || token(value) !== value))
+            throw new CommandFailure("refused", "USAGE_INVALID", `--${key} needs one full native token; prefixes and normalized replacements are not used`);
+    }
+}
+async function confirmMaintenance(args, target, review, question) {
+    if (args.values.yes === true)
+        return true;
+    const presentation = presentationOf(args.values);
+    if (presentation === "json" || !process.stdin.isTTY || !process.stdout.isTTY || inputDisabledByFlag() || process.env.COTAL_NO_PROMPT === "1")
+        throw new CommandFailure("refused", "USAGE_INVALID", "manager maintenance requires --yes outside an interactive terminal", { target, remedy: "inspect the same operation with --dry-run before confirming its scope" });
+    console.log(renderReport(review, presentation, terminalWidth(process.stdout)));
+    const answer = await untilInputEnds((signal) => prompts.confirm({ message: question, initialValue: false, signal }));
+    if (!prompts.isCancel(answer) && answer)
+        return true;
+    writeResult(presentation, { command: "manager", target, result: { kind: "manager-maintenance-cancelled", changed: false }, noOp: true }, () => ({ sections: [{ title: "Manager maintenance cancelled", blocks: [{ kind: "lines", lines: ["The maintenance action was not submitted. No repair or seat drain was performed."] }] }] }));
+    return false;
+}
 /**
- * `cotal reconcile-gate` — the guarded exit from an issuance gate left FROZEN by a crashed
+ * `cotal manager reconcile` — the guarded exit from an issuance gate left FROZEN by a crashed
  * re-registration whose freeze-holder is dead (#391).
  *
  * WHY THIS IS A CLI COMMAND AND NOT AN ADMIN VERB ON THE MANAGER ENDPOINT: the wedged state IS
@@ -586,161 +731,163 @@ async function runManager(args, defaultRuntime) {
  * Read-only until the guard passes: it observes and probes before it constructs the barrier.
  */
 async function runReconcileGate(args) {
+    validateMaintenanceArguments(args, "reconcile");
     const v = args.values;
-    const space = spaceFor(v);
-    const servers = v.server ?? DEFAULT_SERVER;
+    const presentation = presentationOf(args.values), root = findCotalRoot(), space = spaceFor(v, root);
+    const selected = resolveNativeServiceTarget(root, space, v.server);
     const endpoint = v.endpoint ?? MANAGER_ENDPOINT;
-    const root = findCotalRoot();
-    // The instanceId is the manager's PERSISTED identity by default — the same one the crashed
-    // incarnation registered under. An explicit --instance covers a non-manager endpoint.
     const instanceId = v.instance ?? loadManagerInstanceIdentity(root, space)?.instanceId;
-    if (!instanceId)
-        throw new Error(`no persisted manager instance identity under ${root} for space "${space}" — pass --instance <id> for a non-manager endpoint`);
-    const auth = await getSpaceAuth(workspaceSecretStore(root), space);
+    if (!instanceId || instanceId.length > 200 || token(instanceId) !== instanceId)
+        throw new CommandFailure("refused", "TARGET_NOT_FOUND", "no full persisted manager instance resolves this repair target", { target: { root, space, endpoint }, remedy: "choose --instance with the full native service instance ID from this root" });
+    const target = { root: selected.root, space: selected.space, endpoint, instanceId };
+    const review = { space: selected.space, sections: [{ title: "Review issuance-gate repair", blocks: [{ kind: "fields", rows: [["Space", space], ["Signing root", root], ["Endpoint", endpoint], ["Full instance", instanceId], ["Broker", brokerAddressForDisplay(selected.server) ?? "private broker address"], ["Frozen registration", "not checked"], ["Holder liveness", "not checked"], ["Effects", "revoke and verify-evict the dead registration family, then reopen its pinned gate"]] }, { kind: "lines", lines: ["The native guard must prove the freeze-holder gone. Unknown liveness refuses. This command does not start a manager or discard the gate. A failed repair may retain partial progress in its native cursor."] }] }] };
+    if (args.values["dry-run"]) {
+        writeResult(presentation, { command: "manager", target, result: { kind: "manager-gate-repair-preview", dryRun: true, submitted: false, guardEvidence: "not-checked", credentialIssued: false } }, () => review);
+        return;
+    }
+    if (!await confirmMaintenance(args, target, review, "Attempt the displayed gate repair under its native liveness guard?"))
+        return;
+    let auth;
+    try {
+        auth = await getSpaceAuth(workspaceSecretStore(root), space);
+    }
+    catch (error) {
+        if (isCommandFailure(error))
+            throw error;
+        throw new CommandFailure("refused", "DEPENDENCY_UNAVAILABLE", "this root's space signing material could not be read; no gate repair was submitted", { target });
+    }
     if (!auth)
-        throw new Error(`no space auth for "${space}" here — run this on the mesh root that holds the space's auth material`);
-    console.error(c.dim(`• reconciling the ${endpoint} issuance gate for ${instanceId} on ${servers} (space ${space})`));
-    const identity = newIdentity();
-    const creds = await mintCreds(auth, identity, "endpoint-serve-executor", {
-        endpointServeExecutor: { endpoint, instanceId },
-    });
-    const nc = await dialerFor(servers)({ servers, ...standaloneConnectOpts({ creds, tls: false }), maxReconnectAttempts: 0 });
+        throw new CommandFailure("refused", "PERMISSION_DENIED", "gate repair requires this root's native space signing material; no participant or broader caller was substituted", { target });
+    let nc;
+    try {
+        const identity = newIdentity();
+        const creds = await mintCreds(auth, identity, "endpoint-serve-executor", { endpointServeExecutor: { endpoint, instanceId } });
+        nc = await dialerFor(selected.server)({ servers: selected.server, ...standaloneConnectOpts({ creds, tls: selected.tlsRequired }), maxReconnectAttempts: 0 });
+    }
+    catch {
+        throw new CommandFailure("refused", "DEPENDENCY_UNAVAILABLE", "the scoped repair connection could not be established; no gate repair was submitted and no alternate broker was tried", { target });
+    }
     try {
         const kv = await new Kvm(nc).open(epAuthBucket(space));
         const recordsKv = await new Kvm(nc).open(recordsBucket(space));
-        const report = await reconcileEndpointGate({
-            kv, space, endpoint, instanceId,
-            probeHolder: makeManagerHolderLivenessProbe({ space, servers, auth, log: (l) => console.error(c.dim(`  ${l}`)) }),
-            evictHolders: makeManagerEndpointHolderEvictor({ space, servers, auth, log: (l) => console.error(c.dim(`  ${l}`)) }),
-            log: (l) => console.error(`  ${l}`),
-            recordsKv,
+        const native = await reconcileEndpointGate({
+            kv, space, endpoint, instanceId, recordsKv,
+            probeHolder: makeManagerHolderLivenessProbe({ space, servers: selected.server, tlsRequired: selected.tlsRequired, auth, log: () => { } }),
+            evictHolders: makeManagerEndpointHolderEvictor({ space, servers: selected.server, tlsRequired: selected.tlsRequired, auth, log: () => { } }),
+            log: () => { },
         });
-        console.log(c.green(`✓ ${endpoint}/${instanceId}: gate reopened at generation ${report.reopenedAtGeneration}`) +
-            ` (processEpoch ${report.after.processEpoch}, registrationRevision ${report.after.registrationRevision}; ${report.revoked.length} credential(s) revoked this attempt, ${report.holdersVerifiedThisAttempt.length} holder(s) verify-evicted this attempt, ${report.holdersVerifiedBeforeAttempt.length} already verified, ${report.holdersRemaining.length} remaining; repair cursor ${report.repairCursorCleanup}). Start the manager to let its normal takeover run.`);
+        const result = { kind: "manager-gate-repair", opId: native.opId, freezeToken: native.freezeToken, holderPrincipal: native.holderPrincipal, liveness: native.liveness.state, before: native.before, after: native.after, familyRows: native.familyRows, revokedCredentialIds: native.revoked, holdersVerifiedBeforeAttempt: native.holdersVerifiedBeforeAttempt, holdersVerifiedThisAttempt: native.holdersVerifiedThisAttempt, holdersRemaining: native.holdersRemaining, reopenedAtGeneration: native.reopenedAtGeneration, repairCursorCleanup: native.repairCursorCleanup, managerStarted: false };
+        writeResult(presentation, { command: "manager", target, result, ...(native.repairCursorCleanup === "retained" ? { completeness: "partial", partial: { message: "The native gate reopened, but its freeze-bound repair cursor was retained. No cursor cleanup success was inferred." } } : {}) }, (row) => ({ sections: [{ title: "Issuance gate reopened", blocks: [{ kind: "fields", rows: [["Space", space], ["Endpoint", endpoint], ["Full instance", instanceId], ["Native operation", row.opId], ["Holder", row.holderPrincipal], ["Liveness", row.liveness], ["Gate generation", String(row.reopenedAtGeneration)], ["Process epoch", String(row.after.processEpoch)], ["Registration revision", String(row.after.registrationRevision)], ["Revoked this attempt", String(row.revokedCredentialIds.length)], ["Verified this attempt", String(row.holdersVerifiedThisAttempt.length)], ["Already verified", String(row.holdersVerifiedBeforeAttempt.length)], ["Unverified holders", String(row.holdersRemaining.length)], ["Repair cursor", row.repairCursorCleanup], ["Manager", "not started"]] }, { kind: "lines", lines: ["This receipt describes the native gate repair. It does not establish that a manager is now running or serving."] }] }] }));
     }
-    catch (e) {
-        // A refusal is the DESIGNED outcome for every state this does not repair, so it prints the
-        // condition by name — an operator must never have to guess which guard fired.
-        if (e instanceof GateReconcileRefused) {
-            console.error(c.red(`✗ refused (${e.condition}): ${e.message}`));
-            process.exitCode = 2;
-            return;
-        }
-        throw e;
+    catch (error) {
+        if (isCommandFailure(error))
+            throw error;
+        const beforeEffects = error instanceof GateReconcileRefused && ["no-gate", "not-frozen", "wrong-op-kind", "holder-alive", "holder-unknown", "liveness-unestablishable"].includes(error.condition);
+        // The guard's own sentence names the freeze-holder and the next step for this condition.
+        if (beforeEffects)
+            throw new CommandFailure("refused", "LIFECYCLE_BLOCKED", `the native gate-repair guard refused (${error.condition}); the repair did not pass its pre-effect guard`, { target: { ...target, condition: error.condition }, native: { code: error.condition, detail: error.message }, remedy: "inspect the selected gate and the delivery liveness oracle; a timeout is not proof that its holder is gone" });
+        throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native gate repair did not confirm completion; revocation, eviction or reopen work may have occurred. No mutation was retried", { target: { ...target, ...(error instanceof GateReconcileRefused ? { condition: error.condition } : {}) }, remedy: "re-observe this gate and its operation-bound native repair cursor before another explicit repair" });
     }
     finally {
         await nc.drain().catch(() => nc.close());
     }
 }
-/**
- * `cotal deregister-instance` — remove the service registration of an instance whose host is gone.
- *
- * WHY A LOCAL OPERATOR COMMAND AND NOT AN ADMIN VERB ON THE ENDPOINT: the record to remove belongs
- * to an instance that by definition answers nothing, so there is no one to ask. It runs against the
- * records KV with a credential minted from the space seed on this machine, needing nothing from the
- * dead instance.
- *
- * TWO CREDENTIALS, because they are two different authorities and neither implies the other:
- *  - a `control-caller-privileged` instrument PINNED to the instance, which is what can ask the
- *    instance's own rail whether anything is there (the guard);
- *  - an `endpoint-serve-executor` pinned to the same instance, which carries that registration's
- *    two records keys (the delete). NAMED RESIDUAL: this is the existing registration profile, so
- *    it also carries the endpoint's governance head and the rest of the serve-mint footprint —
- *    wider than the two keys used here. It is minted locally by an operator who already holds the
- *    space seed, is one-shot, and never leaves this command; narrowing the profile is a
- *    `provision.ts` change with its own review.
- */
-async function runDeregisterInstance(args) {
-    const v = args.values;
-    const space = spaceFor(v);
-    const servers = v.server ?? DEFAULT_SERVER;
-    const endpoint = v.endpoint ?? MANAGER_ENDPOINT;
-    const root = findCotalRoot();
-    // Same default as `reconcile-gate`: this folder's own persisted manager instance. A FOREIGN
-    // corpse (another machine's instance, the case this exists for) is named explicitly, and `cotal
-    // ps` prints the whole id for exactly that.
-    const instanceId = v.instance ?? loadManagerInstanceIdentity(root, space)?.instanceId;
-    if (!instanceId)
-        throw new Error(`no persisted manager instance identity under ${root} for space "${space}" - pass --instance <id> (the whole id, as \`cotal ps\` prints it)`);
-    const auth = await getSpaceAuth(workspaceSecretStore(root), space);
-    if (!auth)
-        throw new Error(`no space auth for "${space}" here - run this on the mesh root that holds the space's auth material`);
-    console.error(c.dim(`• deregistering ${endpoint}/${instanceId} on ${servers} (space ${space})`));
-    // The GUARD's credential: a one-shot privileged instrument pinned to this one instance, so its
-    // describe and its interest probe ride that instance's own `inst` rails and nothing wider.
-    const probeIdentity = newIdentity();
-    const probeUid = mintLifecycleUid();
-    const probeCreds = await mintCreds(auth, probeIdentity, "control-caller-privileged", {
-        lifecycleUid: probeUid,
-        endpointCapabilities: instancePinnedInstrumentCapabilities("privileged", instanceId),
-    });
-    const probeCaller = { owner: DEV_OWNER, actor: probeIdentity.id, uid: probeUid };
-    const probeNc = await dialerFor(servers)({ servers, ...standaloneConnectOpts({ creds: probeCreds, tls: false }), maxReconnectAttempts: 0 });
-    const probeInstance = makeInstanceProbe(probeNc, { space, endpoint, instanceId, caller: probeCaller });
-    // The DELETE's credential: the executor whose grants name exactly this registration's two
-    // records keys. Minted only after the connection above exists, and used only after the guard.
-    const execIdentity = newIdentity();
-    const execCreds = await mintCreds(auth, execIdentity, "endpoint-serve-executor", {
-        endpointServeExecutor: { endpoint, instanceId },
-    });
-    const execNc = await dialerFor(servers)({ servers, ...standaloneConnectOpts({ creds: execCreds, tls: false }), maxReconnectAttempts: 0 });
+/** List local custodian records; drain only through the native creation-identity guards. */
+async function runSeats(args) {
+    validateMaintenanceArguments(args, "seats");
+    const root = custodyRoot(), presentation = presentationOf(args.values), drain = args.values.drain === true;
+    const target = { scope: "local-custody-store", root };
+    const view = (result) => ({ sections: [
+            { title: result.preview ? "Review local seat drain" : "Retained local seats", blocks: result.entries.length ? [{ kind: "table", columns: [{ key: "name", label: "Agent" }, { key: "state", label: "Observed state" }, { key: "id", label: "Full seat identity" }, { key: "custodian", label: "Custodian PID" }, { key: "child", label: "Child PID" }], rows: result.entries.map((entry) => ({ name: entry.name ?? "not reported", state: { text: entry.state, tone: entry.state === "refused" ? "failed" : entry.state === "childless" ? "waiting" : "label" }, id: entry.id, custodian: entry.custodianPid === null ? "not reported" : String(entry.custodianPid), child: entry.childPid === null ? "not reported" : String(entry.childPid) })) }] : [{ kind: "lines", lines: ["No retained seat records were found in this local store."] }] },
+            { blocks: [{ kind: "fields", rows: [["Store", root], ["Scope", "all safely childless records in this store when the native drain runs"], ["Live children", "kept"], ["Native diagnostic bodies", "omitted"]] }, { kind: "lines", lines: ["A custody record is not agent progress or mesh membership. The native drain re-reads creation identities; the review is not a reservation. A refused drain can include an unconfirmed custodian effect."] }] },
+        ] });
+    const project = (entries) => entries.map((entry) => ({ id: entry.id, name: entry.name ?? null, state: entry.state, custodianPid: entry.custodianPid ?? null, childPid: entry.childPid ?? null }));
+    let before;
     try {
-        const kv = await new Kvm(execNc).open(recordsBucket(space));
-        const authKv = await new Kvm(execNc).open(epAuthBucket(space));
-        const report = await deregisterEndpointInstance({
-            kv, authKv, endpoint, instanceId, probeInstance, log: (l) => console.error(`  ${l}`),
-        });
-        console.log(c.green(`✓ ${endpoint}/${instanceId} deregistered`) +
-            ` (spec revision ${report.removedSpecRevision}${report.removedStatusRevision !== undefined ? `, status revision ${report.removedStatusRevision}` : ""}).` +
-            ` It is gone from every class scatter in space "${space}"; if that host ever comes back, its manager registers again on start.`);
+        before = project(await drainSeats(root));
     }
-    catch (e) {
-        // A refusal is the DESIGNED outcome for every state this does not repair, so it prints its
-        // condition by name rather than leaving the operator to guess which guard fired.
-        if (e instanceof InstanceDeregisterRefused) {
-            console.error(c.red(`✗ refused (${e.condition}): ${e.message}`));
-            process.exitCode = 2;
-            return;
-        }
-        throw e;
+    catch {
+        throw new CommandFailure("refused", process.platform === "linux" ? "DEPENDENCY_UNAVAILABLE" : "UNSUPPORTED", "the native local custody inventory could not be read; no drain was submitted", { target });
     }
-    finally {
-        await execNc.drain().catch(() => execNc.close());
-        await probeNc.drain().catch(() => probeNc.close());
+    const refused = before.some((entry) => entry.state === "refused");
+    if (!drain || args.values["dry-run"] || refused) {
+        writeResult(presentation, { command: "manager", target, result: { kind: drain ? "manager-seat-drain-preview" : "manager-seat-census", entries: before, preview: drain, drainSubmitted: false }, ...(refused ? { completeness: "partial", ...(drain ? { failure: new CommandFailure("refused", "LIFECYCLE_BLOCKED", "some native custody records are unresolved; no drain was submitted", { target, remedy: "inspect those full seat IDs before requesting a drain" }) } : { partial: { message: "Some native custody records are unresolved; this is an incomplete local observation, not proof that those seats are gone." } }) } : {}) }, view);
+        return;
     }
-}
-/**
- * `cotal seats`: the custody records an earlier Linux manager left when the pty runtime still
- * started a detached custodian per seat (#1391). Read-only unless `--drain`, which retires each seat
- * whose agent has exited and keeps every seat whose agent still runs. A refusal exits non-zero: it is
- * a record nothing could prove safe to remove, so an operator has to look at it.
- */
-async function runSeats(args) {
-    const root = custodyRoot();
-    const entries = await drainSeats(root, { drain: args.values.drain === true });
-    if (entries.length === 0) {
-        console.log(`no seat custody records under ${root}`);
+    if (!before.some((entry) => entry.state === "childless")) {
+        writeResult(presentation, { command: "manager", target, result: { kind: "manager-seat-drain", entries: before, preview: false, drainSubmitted: false }, noOp: true }, view);
+        return;
+    }
+    if (!await confirmMaintenance(args, target, view({ entries: before, preview: true }), "Drain all safely childless records in the displayed local store? Live children stay."))
         return;
+    let entries;
+    try {
+        entries = project(await drainSeats(root, { drain: true }));
+    }
+    catch {
+        throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native seat drain did not return its complete census; effects were not retried", { target, remedy: "re-read the local seat census before another drain" });
     }
-    for (const e of entries)
-        console.log(`${e.id}  ${e.state.padEnd(10)}  ${e.name ?? "-"}  ${e.detail}`);
-    const count = (state) => entries.filter((e) => e.state === state).length;
-    console.error(c.dim(`• ${entries.length} record(s) under ${root}: ${count("live-child")} live-child, ${count("childless")} childless, ${count("drained")} drained, ${count("refused")} refused`));
-    if (count("refused") > 0)
-        process.exitCode = 1;
+    const incomplete = entries.some((entry) => entry.state === "refused"), changed = entries.filter((entry) => entry.state === "drained").map((entry) => ({ kind: "seat-record-drained", id: entry.id }));
+    writeResult(presentation, { command: "manager", target, result: { kind: "manager-seat-drain", entries, preview: false, drainSubmitted: true }, ...(incomplete ? { completeness: "partial", failure: new CommandFailure("unknown", "OPERATION_UNKNOWN", "some native drains did not confirm completion; confirmed removals are retained, but an unresolved custodian effect was not treated as unchanged", { target, changed, remedy: "re-read the full seat IDs; no drain was retried" }) } : { noOp: changed.length === 0 }) }, view);
 }
+const maintenanceOutputFlags = [jsonFlag, plainFlag,
+    { name: "yes", short: "y", type: "boolean", description: "confirm the selected guarded gate repair or childless-seat drain" },
+    { name: "dry-run", type: "boolean", description: "review the selected maintenance scope without submitting repair or drain effects" },
+];
 /** The manager's commands: the `supervise` daemon runner, and the guarded `reconcile-gate` repair.
  *  Self-registered on import; the `cotal` binary resolves them from the registry. */
 const managerCommands = [
     {
         kind: "command",
-        name: "supervise",
+        name: "__service-manager",
+        hidden: true,
+        prepareMeshTarget: false,
+        group: "Manager",
+        summary: "native manager child with protected launch identity and request-bound stop receipts",
+        flags: [
+            { name: "root", type: "string", description: "explicit registered mesh root" },
+            { name: "space", type: "string", description: "explicit registered space" },
+            { name: "server", type: "string", description: "registered broker URL without credentials" },
+            { name: "runtime", type: "string", description: "explicit native seat runtime" },
+            { name: "console-port", type: "string", description: "explicit native console port; zero allocates a port" },
+            { name: "console-host", type: "string", description: "explicit native console bind host" },
+            { name: "ws-port", type: "string", description: "the prepared broker websocket port" },
+            { name: "max-sessions", type: "string", description: "explicit positive native session ceiling" },
+            { name: "launch", type: "string", description: "private native launch spec for this selected space" },
+            { name: "launch-sha256", type: "string", description: "full digest pinned by the saved service definition" },
+            { name: "roster", type: "string", description: "absolute roster file whose agents start at launch" },
+            { name: "service-instance", type: "string", description: "full controller-assigned instance ID" },
+            { name: "launch-request", type: "string", description: "full original launch request ID" },
+            { name: "state-directory", type: "string", description: "owned private launch state directory" },
+            { name: "resume-attempt", type: "string", description: "maintenance resume attempt this launch serves" },
+            { name: "resume-commit-file", type: "string", description: "protected one-read resume commit handoff file" },
+            { name: "resume-commit-sha256", type: "string", description: "full digest of the resume commit handoff" },
+        ],
+        validate: (args) => { managerServiceChild(args); },
+        requiredExtensions: (args) => typeof args.values.runtime === "string" && args.values.runtime !== "pty" ? [{ kind: "runtime", name: args.values.runtime }] : [],
+        run: async (args) => {
+            const service = managerServiceChild(args);
+            try {
+                await runManager(args, "auto", service);
+            }
+            catch {
+                throw new CommandFailure("unknown", "OPERATION_UNKNOWN", "the native manager child did not establish its complete startup receipt; no replacement was launched and no diagnostic body was copied to stdout");
+            }
+        },
+    },
+    {
+        kind: "command",
+        // The manager daemon `up` launches. `supervise` is the same entry for persisted callers, plus the
+        // deprecation warning; help and completion list neither.
+        name: "__daemon-manager",
+        hidden: true,
         group: "Manager",
         summary: "run a manager - [--runtime <name>] (default pty; extension runtimes are explicit-only) [--space <s>] [--server <url>] [--console-port <n>] [--max-sessions <n>] [--roster <file>] [--launch <spec>] [--resume-attempt <id>]",
         flags: [
             { name: "space", type: "string", value: "<s>", description: "space to supervise (default: this folder's auth space; env COTAL_SPACE when unset)" },
             { name: "server", type: "string", value: "<url>", description: "broker URL (default: the local mesh; env COTAL_SERVER when unset)" },
             { name: "runtime", type: "string", value: "<name>", description: "agent runtime (default pty; others come from installed extensions)" },
+            { name: "execution", type: "string", value: "<runtime|none>", description: "runtime by default; none requires a fresh hosting user-auth control instance and no runtime or startup workload" },
             { name: "console-port", type: "string", value: "<n>", description: "protocol-console port" },
             { name: "console-host", type: "string", value: "<host>", description: "bind host for the console endpoint (default: loopback)" },
             { name: "ws-port", type: "string", value: "<n>", description: "broker ws listener port for the console session client" },
@@ -748,10 +895,15 @@ const managerCommands = [
             { name: "roster", type: "string", value: "<file>", description: "declarative roster to boot at startup" },
             { name: "launch", type: "string", value: "<spec>", description: "resolved mesh-manifest launch spec (cotal up -f / spawn -f)" },
             { name: "resume-attempt", type: "string", value: "<id>", description: "maintenance restore attempt accepted by resumePreserved" },
-            { name: "resume-commit-token", type: "string", value: "<token>", description: "durable resume commit evidence for crash recovery" },
+            { name: "resume-commit-token", type: "string", value: "<token>", description: "deprecated: durable resume commit evidence on argv; prefer --resume-commit-file" },
+            { name: "resume-commit-file", type: "string", value: "<path>", description: "protected one-read resume commit handoff file" },
+            { name: "resume-commit-sha256", type: "string", value: "<hex>", description: "full digest of the resume commit handoff" },
             { name: "spawn", type: "string", value: "<names>", description: "comma-separated personas to pre-spawn at startup" },
         ],
+        validate: (args) => { superviseExecution(args.values); },
         requiredExtensions: (args) => {
+            if (superviseExecution(args.values) === "none")
+                return [];
             const runtime = args.values.runtime;
             return typeof runtime === "string" && runtime !== "pty" ? [{ kind: "runtime", name: runtime }] : [];
         },
@@ -761,8 +913,11 @@ const managerCommands = [
         kind: "command",
         name: "reconcile-gate",
         group: "Manager",
+        outputs: ["json", "plain"],
+        prepareMeshTarget: false,
+        validate: (args) => validateMaintenanceArguments(args, "reconcile"),
         summary: "reconcile an issuance gate left frozen by a crashed re-registration when boot cannot self-heal it - verifies the freeze-holder is gone, then completes the dead op (refuses if it is alive or unprovable) [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]",
-        flags: [
+        flags: [...maintenanceOutputFlags,
             { name: "space", type: "string", value: "<s>", description: "space to reconcile in (default: this folder's auth space)" },
             { name: "server", type: "string", value: "<url>", description: "broker URL (default: the local mesh)" },
             { name: "endpoint", type: "string", value: "<e>", description: `endpoint whose gate is frozen (default: ${MANAGER_ENDPOINT})` },
@@ -773,24 +928,90 @@ const managerCommands = [
     {
         kind: "command",
         name: "deregister-instance",
-        group: "Manager",
-        summary: "remove the service registration of an instance whose host is gone - removes only what the broker affirms gone (nothing subscribed on its rail), and refuses if it answers or is merely quiet [--space <s>] [--server <url>] [--endpoint <e>] [--instance <id>]",
-        flags: [
+        group: "Manager", hidden: true, reads: true, prepareMeshTarget: false,
+        summary: "legacy spelling; use endpoint deregister <class> <full-instance-id>",
+        outputs: ["json", "plain"],
+        flags: [jsonFlag, plainFlag,
             { name: "space", type: "string", value: "<s>", description: "space the instance is registered in (default: this folder's auth space)" },
             { name: "server", type: "string", value: "<url>", description: "broker URL (default: the local mesh)" },
             { name: "endpoint", type: "string", value: "<e>", description: `endpoint the instance serves (default: ${MANAGER_ENDPOINT})` },
             { name: "instance", type: "string", value: "<id>", description: "instance id to deregister, the whole id as `cotal ps` prints it (default: this folder's persisted manager instance)" },
         ],
-        run: runDeregisterInstance,
+        validate: () => { throw new CommandFailure("refused", "USAGE_INVALID", "the legacy deregistration spelling no longer executes", { remedy: "use cotal endpoint deregister <class> <full-instance-id> [--space <space>] [--yes|--dry-run]" }); },
+        run: async () => { throw new CommandFailure("refused", "USAGE_INVALID", "use cotal endpoint deregister <class> <full-instance-id> instead"); },
     },
     {
         kind: "command",
         name: "seats",
         group: "Manager",
         summary: "list the pty seat custodians an earlier Linux manager left on this machine - [--drain] retires each seat whose agent has exited and never signals one whose agent still runs",
-        flags: [{ name: "drain", type: "boolean", description: "retire every seat whose agent has exited; a seat whose agent still runs is kept" }],
+        outputs: ["json", "plain"],
+        reads: true,
+        prepareMeshTarget: false,
+        flags: [...maintenanceOutputFlags,
+            { name: "drain", type: "boolean", description: "retire safely childless records in this local store; live children stay" },
+        ],
+        validate: (args) => validateMaintenanceArguments(args, "seats"),
         run: runSeats,
     },
 ];
-registry.register(...managerCommands);
+const maintenance = [
+    { name: "reconcile", source: "reconcile-gate", summary: "repair an owned manager issuance gate from its mesh root" },
+    { name: "seats", source: "seats", summary: "inspect retained local seats; --drain removes only childless records" },
+].map((mode) => {
+    const source = managerCommands.find((command) => command.name === mode.source);
+    if (!source)
+        throw new Error(`manager command ${mode.source} is not registered`);
+    const command = { ...source, flags: source.flags?.map((flag) => flag.name === "space" ? { ...flag, short: "s" } : flag) };
+    return { ...mode, command };
+});
+const maintenanceFlags = new Map();
+for (const mode of maintenance)
+    for (const flag of mode.command.flags ?? []) {
+        const shared = maintenanceOutputFlags.some((common) => common.name === flag.name);
+        maintenanceFlags.set(flag.name, { ...flag, description: shared ? flag.description : `${mode.name}: ${flag.description ?? ""}` });
+    }
+function managerInvocation(args) {
+    const parsed = parseCommandArgs(managerGroup, [...args.raw]);
+    const mode = parsed.positionals[0];
+    if (mode === undefined) {
+        if (Object.keys(parsed.values).some((key) => !["json", "plain"].includes(key)))
+            throw new CommandFailure("refused", "USAGE_INVALID", "choose manager reconcile or manager seats before its options");
+        return undefined;
+    }
+    const child = maintenance.find((item) => item.name === mode);
+    if (!child)
+        throw new CommandFailure("refused", "USAGE_INVALID", "manager takes reconcile or seats");
+    const index = parsed.positionalIndices?.[0];
+    if (index === undefined)
+        throw new Error("the manager subcommand has no parsed argument index");
+    const words = args.raw.filter((_, position) => position !== index);
+    return { command: child.command, args: parseCommandArgs(child.command, words) };
+}
+const managerGroup = {
+    kind: "command",
+    name: "manager",
+    aliases: ["mgr"],
+    group: "Manager",
+    summary: "inspect retained local seats or repair an owned manager gate",
+    usage: "cotal manager [reconcile [--yes|--dry-run] | seats [--drain [--yes|--dry-run]]] [--json|--plain]",
+    positionals: "[reconcile | seats]",
+    outputs: ["json", "plain"],
+    flags: [...maintenanceFlags.values()],
+    subcommands: maintenance.map((mode) => ({ name: mode.name, summary: mode.summary, flagNames: mode.command.flags?.map((flag) => flag.name), outputs: mode.command.outputs, usage: mode.name === "seats" ? "cotal manager seats [--drain [--yes|--dry-run]] [--json|--plain]" : "cotal manager reconcile [--space <space>] [--server <url>] [--instance <id>] [--yes|--dry-run] [--json|--plain]" })),
+    reads: true,
+    prepareMeshTarget: false,
+    validate: (args) => { presentationOf(args.values); const invocation = managerInvocation(args); return invocation?.command.validate?.(invocation.args); },
+    async run(args) {
+        const invocation = managerInvocation(args);
+        if (invocation)
+            return invocation.command.run(invocation.args);
+        writeResult(presentationOf(args.values), { command: "manager", target: null, result: { kind: "manager-maintenance-commands", operations: maintenance.map(({ name, summary }) => ({ name, summary })), managerStarted: false } }, () => ({ sections: [
+                { title: "Manager maintenance", blocks: [{ kind: "commands", items: maintenance.map((mode) => ({ command: `cotal mgr ${mode.name}`, description: mode.summary })) }] },
+                { blocks: [{ kind: "lines", lines: [{ text: "These commands start no manager. Repair and drain default to cancellation; scripted maintenance requires --yes. Preview the scope with --dry-run.", tone: "hint" }] }] },
+            ] }));
+    },
+};
+const daemonManager = managerCommands.find((command) => command.name === "__daemon-manager");
+registry.register(...managerCommands.map((command) => command.name === "seats" || command.name === "reconcile-gate" ? { ...command, hidden: true } : command), deprecatedDaemonEntry("supervise", daemonManager), managerGroup, endpointDeregisterAction);
 //# sourceMappingURL=commands.js.map