@plurnk/plurnk-service 3.3.0 → 4.1.0

package/dist/server/Daemon.js

@@ -4,6 +4,7 @@ import { readFile } from "node:fs/promises";
 import { resolve, dirname } from "node:path";
 import { Share } from "@plurnk/plurnk-digest";
 import EvidenceReader from "@plurnk/plurnk-service/evidence";
+import ChannelWrite, {} from "../core/ChannelWrite.js";
 import Paths from "../Paths.js";
 import Engine from "../core/Engine.js";
 import ExecutorRegistry from "../core/ExecutorRegistry.js";
@@ -15,14 +16,16 @@ import { projectModelRoute, routeForSpec, specForRoute } from "./model-route.js"
 import { discoverDaemonModules } from "./module-discovery.js";
 import EffectPolicy from "../schemes/EffectPolicy.js";
 import QuestionTool, { questionRuntimeDecl } from "../schemes/QuestionTool.js";
-import DrainSupervisor from "./DrainSupervisor.js";
+import DrainSupervisor, {} from "./DrainSupervisor.js";
 import MessageAbandonment from "./MessageAbandonment.js";
 import Retention, { retentionPolicy } from "./Retention.js";
 import TurnDispositionHandler from "../core/TurnDispositionHandler.js";
 import { Validator } from "@plurnk/plurnk-contracts";
 import LogEntry from "./logEntry.js";
 import HttpListener from "./HttpListener.js";
+import Credentials from "./Credentials.js";
 import Envelope, { projectWorkerRow } from "./envelope.js";
+import WorkerReferences from "./WorkerReferences.js";
 import ClientInput from "./client-input.js";
 import Turn from "../core/Turn.js";
 import WorkspacePlugins from "./WorkspacePlugins.js";
@@ -60,6 +63,13 @@ import { daemonFailure, modelRouteLabel } from "./daemon-results.js";
 import WorkerModelResolver from "./WorkerModelResolver.js";
 import ClientReads from "./ClientReads.js";
 import ConfigurationDiagnostics from "./ConfigurationDiagnostics.js";
+// {§connection-lifecycle} A client operation cancelled mid-way settles its loop with what happened.
+const clientOperationCancelled = (reason) => {
+    const said = typeof reason === "string" ? reason : "cancelled";
+    return Results.failure("daemon:client", "operation-cancelled", 499, `The client operation was cancelled: ${said}.`, {}, {
+        reason: said, stage: "client-action", retryable: false,
+    });
+};
 const clientActionFailure = (error) => {
     if (error instanceof OperationFailureError)
         return error.result;
@@ -71,6 +81,7 @@ const clientActionFailure = (error) => {
 };
 export default class Daemon {
     static validateConfiguration() {
+        Credentials.posture();
         FileCreationPolicy.serviceScope();
         EffectPolicy.validateConfiguration();
         ProposalPolicies.read();
@@ -99,6 +110,13 @@ export default class Daemon {
     // {§http-host} — the one listener, bound by the service before durable admission; null in
     // tests that never open a transport.
     #http;
+    // {§credential-authority} {§methods-credentials} — the one authority over credentials presented to
+    // the listener, holding the operator's secret under the posture `PLURNK_AUTH` names.
+    credentials;
+    // The file beside the database where a minted operator secret is written for same-user clients;
+    // null for a daemon started without its database path.
+    #secretPath;
+    #secretMinted;
     #discoveryCwd;
     #started = false; // {§module-lifecycle}: one discovery/module boot; no listener
     #modules = [];
@@ -107,6 +125,11 @@ export default class Daemon {
     #mounted = new Set();
     #moduleLifetimes = [];
     #moduleActions = new Map();
+    // {§connection-lifecycle} Each running client operation's loop, its own cancellation scope and its settlement.
+    #clientLoops = new Map();
+    // {§worker-lifecycle-total-reap} Every client operation's scope descends from this one, which shutdown aborts:
+    // an operation still dispatching, and every execution an operation started, ends with the daemon.
+    #clientOperations = new AbortController();
     #residency;
     #functionality;
     // {§retention-policy} — the operator's retention, run on a cadence and at shutdown.
@@ -127,6 +150,10 @@ export default class Daemon {
         this.#dbPath = dbPath;
         this.#http = http;
         this.#configuration = configuration;
+        const posture = Credentials.posture();
+        this.credentials = new Credentials({ operatorSecret: posture.secret });
+        this.#secretPath = dbPath === undefined ? null : Credentials.secretPath(dbPath);
+        this.#secretMinted = posture.minted;
         this.#storage = new WorkspaceStorage(db, hostPaths);
         this.#lifecycle = new LoopLifecycle(db);
         this.#schemes = schemes ?? new SchemeRegistry();
@@ -165,13 +192,15 @@ export default class Daemon {
         // {§functionality-coordinator} — the one owner above every family
         // adapter; Core hosts it, modules register adapters through the seam.
         this.#functionality = new Functionality({
+            signal: this.#residency.signal,
             registerModuleAction: (registration) => this.registerModuleAction(registration),
             registerWorkspaceCapabilityProvider: (owner, provider) => this.registerWorkspaceCapabilityProvider(owner, provider),
             readWorkspaceModuleState: (workspaceId, owner) => this.readWorkspaceModuleState(workspaceId, owner),
             replaceWorkspaceCapabilities: (replacement, options) => this.replaceWorkspaceCapabilities(replacement, options),
             readWorkerModuleState: (workerId, owner) => this.#residency.readWorkerModuleState(workerId, owner),
             replaceWorkerModuleState: (workerId, owner, state) => this.#residency.replaceWorkerModuleState(workerId, owner, state),
-            withWorkspaceGate: (workspaceId, owner, gate, run) => this.#residency.exclusively(workspaceId, owner, gate, run),
+            withWorkspaceGate: (workspaceId, owner, gate, run, signal) => this.#residency.exclusively(workspaceId, owner, gate, run, signal),
+            atWorkspaceBoundary: (workspaceId, run) => this.#workspaceGate.atBoundary(workspaceId, run),
             retainWorkspace: (workspaceId) => this.#residency.retain(workspaceId),
             preparationChanged: (workspaceId, preparation) => this.#broadcast({ workspaceId }, "workspace/preparation", { workspaceId, preparation })
         });
@@ -181,8 +210,10 @@ export default class Daemon {
         this.#functionality.register(this.#members);
         // {§env-functionality} — Core's own family: the environment a Worker's commands run in.
         // {§env-scheme} — the family's face: reads project the dispatching Worker's effective
-        // environment, writes go through the family's own admission at the Worker's layer.
-        this.#functionality.register(new EnvFunctionality(EnvFunctionality.defaultsReader(Paths.packageRoot, this.#nodeModulesPath), new EnvScheme((workspaceId, workerId) => EnvFunctionality.resolve(this.#db, workspaceId, workerId), (verb, params, identity) => this.#functionality.invoke("env", verb, params, identity, "operation"))));
+        // environment, writes go through the family's own admission at the Worker's layer. The runtime
+        // worker keeps none: its environment is the workspace's ({§actor-boundary-client-operations}).
+        this.#functionality.register(new EnvFunctionality(EnvFunctionality.defaultsReader(Paths.packageRoot, this.#nodeModulesPath), new EnvScheme((workspaceId, workerId) => EnvFunctionality.resolve(this.#db, workspaceId, workerId), (verb, params, identity) => this.#functionality.invoke("env", verb, params, identity, "operation"), async (workspaceId, workerId) => (await this.#db.runtime_worker_get.get({ workspace_id: workspaceId }))?.id === workerId
+            ? "workspace" : "worker")));
         this.#engine = new Engine({
             db, lifecycle: this.#lifecycle, schemes: this.#schemes, mimetypes: this.#mimetypes,
             // {§tokenomics-agnostic-ruler} — stored and catalog curation weights
@@ -200,13 +231,13 @@ export default class Daemon {
             // daemon owns provider + the law-file system prompt; the worker scheme
             // handler carries neither. Fire-and-forget: the returned drain runs
             // independently (the sister is its own worker). {§machine-processes}
-            injectWorker: async ({ workspaceId, workerId, sourceLoopId, prompt, spawn, environment, attachments }) => {
+            injectWorker: async ({ workspaceId, workerId, sourceLoopId, prompt, spawn, environment, attachments, opener }) => {
                 await this.#assertModelWorker(workspaceId, workerId);
                 const sender = await this.#db.drain_message_source.get({ loop_id: sourceLoopId });
                 if (sender === undefined || sender.workspace_id !== workspaceId) {
                     throw new Error(`injectWorker: source loop ${sourceLoopId} does not belong to workspace ${workspaceId}`);
                 }
-                const source = await this.#workerPromptSource(workspaceId, sender.worker_id, workerId);
+                const source = await this.#messageSource(workspaceId, sourceLoopId, sender.worker_id, workerId);
                 const systemPrompt = await readFile(Paths.instructionsSystem, "utf8");
                 let providerSpec;
                 let childProviderSpec;
@@ -239,14 +270,14 @@ export default class Daemon {
                         effort: effort,
                         effort_source: "default"
                     });
-                    // {§env-option} — explicit child overrides replace copied values and enable them.
-                    // Names were admitted at the operation; a refusal here is a defect and throws.
-                    for (const [alias, value] of Object.entries(environment ?? {})) {
-                        await this.#functionality.invoke("env", "replace", { alias, definition: { value } }, { workspaceId, workerId }, "operation");
-                        await this.#functionality.invoke("env", "enable", { alias }, { workspaceId, workerId }, "operation");
-                    }
                 }
-                const { action, loopId } = await ContentUse.read(this.#db, async () => {
+                // {§env-option} — a created worker's explicit overrides replace copied values and enable them.
+                // Names were admitted at the operation; a refusal here is a defect and throws.
+                for (const [alias, value] of Object.entries(environment ?? {})) {
+                    await this.#functionality.invoke("env", "replace", { alias, definition: { value } }, { workspaceId, workerId }, "operation");
+                    await this.#functionality.invoke("env", "enable", { alias }, { workspaceId, workerId }, "operation");
+                }
+                const { action, loopId, messageId } = await ContentUse.read(this.#db, async () => {
                     const delivered = await this.#prepareMessage(workspaceId, workerId, prompt, attachments);
                     return this.inject({
                         workspaceId,
@@ -255,15 +286,20 @@ export default class Daemon {
                         evidence: delivered.evidence,
                         sourceLoopId,
                         ...(source === undefined ? {} : { source }),
+                        ...(opener === undefined ? {} : { opener }),
                         providerSpec,
                         effort,
                         childProviderSpec,
                         systemPrompt
                     });
                 });
-                return { action, loopId };
+                // {§worker-obligations} — the message's durable address, as Open Work names it.
+                const message = await this.#db.drain_message_path.get({ id: messageId });
+                if (message === undefined)
+                    throw new Error(`injectWorker: message ${messageId} has no address`);
+                return { action, loopId, message: message.path };
             },
-            acquireWorkspaceTurn: async (workspaceId, workerId, signal) => this.#workspaceGate.acquireTurn(workspaceId, workerId, signal),
+            withWorkspaceTurn: (workspaceId, workerId, run, signal) => this.#workspaceGate.withTurn(workspaceId, workerId, run, signal),
             // {§functionality-hotload} — skills and plugins change out of band.
             // Republish under the workspace turn gate before packet assembly so
             // the first subsequent model turn sees their exact result.
@@ -284,7 +320,7 @@ export default class Daemon {
             // {§message-abandonment} — the daemon answers, 499, what an ended loop left unanswered.
             completeAbandonedMessages: (workspaceId, workerId, loopId, status) => MessageAbandonment.complete(this.#engine, this.#db, workspaceId, workerId, loopId, status),
             lifecycle: this.#lifecycle,
-            injectPrompt: (loopId, prompt, openPaths, source, evidence, messageAddress) => this.#engine.injectIntoLoop(loopId, prompt, openPaths, source, evidence, messageAddress),
+            injectPrompt: (loopId, prompt, openPaths, source, evidence, messageAddress, opener) => this.#engine.injectIntoLoop(loopId, prompt, openPaths, source, evidence, messageAddress, opener),
             assertInjectionCompatibility: async ({ workerId, loopId, providerSpec, providerSpecExplicit, effort, childProviderSpec, turnCeiling }) => {
                 // An omitted selector keeps the loop's durable provider; only an
                 // explicit selection is checked against it (a deliberate switch).
@@ -420,6 +456,11 @@ export default class Daemon {
         await this.#assertModelWorker(args.workspaceId, args.workerId);
         return MessageResources.read(this.#db, args);
     }
+    // {§message-idempotency}
+    async messageAdmission(args) {
+        const workspaceId = ClientInput.assertId("messageAdmission", "workspaceId", args.workspaceId);
+        return await MessageResources.admission(this.#db, workspaceId, args.address, args.body);
+    }
     // {§methods-loop-run} — drive/steer a loop. The module supplies only workspace/worker/prompt;
     // the provider and the law-file system prompt are core's and stay inside. Returns immediately — the
     // loop runs async and its outcome arrives on the event source (loop/terminated). `cancelDrain` (public)
@@ -575,12 +616,6 @@ export default class Daemon {
             });
         }
     }
-    // {§methods-model-worker} — the workspace's model worker (created on first use), distinct from the client
-    // worker so the model's packets never carry client-action rows. The module binds its threads to this.
-    async ensureModelWorker(workspaceId) {
-        const checked = ClientInput.assertId("worker.ensure-model", "workspaceId", workspaceId);
-        return await Envelope.ensureModelWorker(this.#db, checked);
-    }
     async ensureRuntimeWorker(workspaceId) {
         const checked = ClientInput.assertId("worker.ensure-runtime", "workspaceId", workspaceId);
         if (await this.#db.envelope_get_workspace.get({ id: checked }) === undefined) {
@@ -757,7 +792,12 @@ export default class Daemon {
             });
         }
     }
-    async #workerPromptSource(workspaceId, sourceWorkerId, targetWorkerId) {
+    // {§actor-boundary-client-operations} A message speaks for its loop's actor: a person's operation for that
+    // person, as a thread message does; any other loop for its worker.
+    async #messageSource(workspaceId, sourceLoopId, sourceWorkerId, targetWorkerId) {
+        const person = await this.#db.envelope_client_operation_person.get({ loop_id: sourceLoopId });
+        if (person !== undefined)
+            return person.person;
         if (sourceWorkerId === targetWorkerId)
             return undefined;
         const source = await this.#db.envelope_get_worker_by_id.get({ id: sourceWorkerId });
@@ -766,81 +806,93 @@ export default class Daemon {
         }
         return WorkerControlAddress.render(source.name);
     }
-    // {§methods-op-mirror} — execute parsed ops on behalf of a client as a
-    // client-origin turn (the log is core's, a client op is a first-class citizen), dispatched through
-    // the engine, then emitted as log/entry on the event source. One seam op backs the whole op_*
-    // family (read/edit/copy/find/kill/look/move/send/exec); the module parses at its edge with the
-    // grammar package and hands over the statement, then fans the emitted entry out to its own clients.
     // {§functionality-model-mutation} — await every queued Functionality
     // publication (a Worker's accepted mutation publishes at its turn boundary).
     async settleFunctionality(workspaceId) {
         await this.#functionality.settle(workspaceId);
     }
-    async dispatchAsClient(args) {
-        const workspaceId = ClientInput.assertId("operation.dispatch", "workspaceId", args.workspaceId);
-        const workerId = ClientInput.assertId("operation.dispatch", "workerId", args.workerId);
-        const { statement } = args;
-        await this.#assertWorkerOwned(workspaceId, workerId);
-        const releaseCapabilities = await this.#residency.acquire(workspaceId);
-        try {
-            const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
-            try {
-                const result = await this.#dispatchClientStatement({ workspaceId, workerId, loopId: clientLoopId, statement });
-                await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
-                return result;
-            }
-            catch (error) {
-                await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
-                throw error;
-            }
-        }
-        finally {
-            releaseCapabilities();
-        }
-    }
-    // The client-interface action contract: one AG-UI action owns one administrative
-    // loop, regardless of how many statements op.parse produced. Each statement is one
-    // ordinary operation turn; a proposal may keep that turn and loop open across
-    // interrupt/resume until settlement.
     executorTags(workspaceId) {
         return this.#engine.executorTags(workspaceId);
     }
-    executorJsonBodyTags(workspaceId) {
-        return this.#engine.executorJsonBodyTags(workspaceId);
-    }
+    // {§connection-lifecycle} A person's client operation: one administrative loop in the workspace's runtime
+    // worker, attributed to its actor, reading `log:///` in the worker that person acts for
+    // ({§actor-boundary-client-operations}).
     async dispatchClientAction(args) {
         const workspaceId = ClientInput.assertId("operation.dispatch-batch", "workspaceId", args.workspaceId);
-        const workerId = ClientInput.assertId("operation.dispatch-batch", "workerId", args.workerId);
+        const actor = ClientInput.assertActor("operation.dispatch-batch", args.actor);
+        const contextWorkerId = args.contextWorkerId === undefined
+            ? undefined
+            : ClientInput.assertId("operation.dispatch-batch", "contextWorkerId", args.contextWorkerId);
+        if (contextWorkerId !== undefined)
+            await this.#assertModelWorker(workspaceId, contextWorkerId);
         const { statements } = args;
         if (statements.length === 0)
             return [];
-        await this.#assertWorkerOwned(workspaceId, workerId);
-        // {§actor-boundary-attached-functionality} The client retains its journal;
-        // the workspace supplies policy and the shared runtime environment.
+        return await this.#clientOperation({ workspaceId, actor, contextWorkerId, onLoop: args.onLoop }, async (dispatch) => {
+            const results = [];
+            for (const statement of statements)
+                results.push(await dispatch(statement));
+            return results;
+        });
+    }
+    // {§connection-lifecycle} One client operation: the runtime worker's administrative loop with its own
+    // cancellation scope, settled when the operation ends. Nothing else in the runtime worker shares the scope.
+    async #clientOperation(operation, body) {
+        const { workspaceId, actor, contextWorkerId } = operation;
+        const workerId = await RuntimeWorker.ensure(this.#db, workspaceId);
         const releaseCapabilities = await this.#residency.acquire(workspaceId);
         try {
-            const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
+            const loopId = await Envelope.ensureClientLoop(this.#db, workerId, actor);
+            const scope = new AbortController();
+            const signal = AbortSignal.any([scope.signal, this.#clientOperations.signal]);
+            const settled = Promise.withResolvers();
+            this.#clientLoops.set(loopId, { workspaceId, scope, settled: settled.promise });
+            const unbind = this.#engine.bindLoopSignal(loopId, signal);
             try {
-                const results = [];
-                for (const statement of statements) {
-                    results.push(await this.#dispatchClientStatement({ workspaceId, workerId, loopId: clientLoopId, statement }));
-                }
-                await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
-                return results;
+                operation.onLoop?.({ workerId, loopId });
+                const result = await body(async (statement) => {
+                    signal.throwIfAborted();
+                    return await this.#dispatchClientStatement({
+                        workspaceId, workerId, loopId, statement,
+                        contextWorkerId: contextWorkerId ?? null,
+                    });
+                });
+                signal.throwIfAborted();
+                await Envelope.closeClientLoop(this.#db, loopId, { status: 200 });
+                return result;
             }
             catch (error) {
-                await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
-                throw error;
+                // A cancelled operation settles cancelled, however its statement in flight ended.
+                const failure = signal.aborted ? new OperationFailureError(clientOperationCancelled(signal.reason)) : error;
+                await Envelope.closeClientLoop(this.#db, loopId, clientActionFailure(failure));
+                throw failure;
+            }
+            finally {
+                unbind();
+                this.#clientLoops.delete(loopId);
+                settled.resolve();
             }
         }
         finally {
             releaseCapabilities();
         }
     }
+    // {§connection-lifecycle} Cancel exactly one client operation: its dispatch while it runs, and every execution its
+    // rows started that still runs. The rest of the runtime worker runs on.
+    async cancelLoop(args) {
+        const workspaceId = ClientInput.assertId("operation.cancel", "workspaceId", args.workspaceId);
+        const loopId = ClientInput.assertId("operation.cancel", "loopId", args.loopId);
+        const operation = this.#clientLoops.get(loopId);
+        const dispatching = operation !== undefined && operation.workspaceId === workspaceId && !operation.scope.signal.aborted;
+        if (dispatching)
+            operation.scope.abort(args.reason ?? "user_cancelled");
+        const executions = await ChannelWrite.findOpenSubscriptionsForClientLoop(this.#db, { workspaceId, loopId });
+        const reaped = await Promise.all(executions.map((subscriptionId) => this.#engine.cancelSubscription(subscriptionId)));
+        return dispatching || reaped.includes(true);
+    }
     async #dispatchClientStatement(args) {
-        const { workspaceId, workerId, loopId, statement } = args;
-        const release = await this.#workspaceGate.acquireTurn(workspaceId, workerId);
-        try {
+        const { workspaceId, workerId, loopId, statement, contextWorkerId } = args;
+        return this.#workspaceGate.withTurn(workspaceId, workerId, async () => {
             await this.#residency.reconcile(workspaceId);
             const { id: turnId } = await Turn.open(this.#db, {
                 loopId,
@@ -852,7 +904,8 @@ export default class Daemon {
                 const entryIds = [];
                 const result = await this.#engine.dispatch({
                     statement, workspaceId, workerId, loopId, turnId, sequence: 1,
-                    origin: "client", onDispatch: (logEntryId) => { entryIds.push(logEntryId); args.onDispatch?.(logEntryId); }
+                    origin: "client", client: { contextWorkerId },
+                    onDispatch: (logEntryId) => { entryIds.push(logEntryId); }
                 });
                 await Turn.complete(this.#db, turnId, result.status);
                 turnOpen = false;
@@ -873,51 +926,7 @@ export default class Daemon {
                 }
                 throw cause;
             }
-        }
-        finally {
-            release();
-        }
-    }
-    // {§op-look} — the pure READ-projection query on the seam: resolve a READ through the
-    // full scheme resolver and return its content, writing NO log row — the client's out-of-band
-    // inspection primitive (the module rewrites LOOK→READ and parses at its edge, exactly like
-    // dispatchClientAction). Its closed observation segment supplies the numeric loop coordinate
-    // required by extension context and relative log:/// addresses without impersonating an active
-    // client lifecycle. It creates no turn or log row. Engine.look enforces READ-only.
-    // {§op-look} — the segment is the acting worker's; the READ resolves as the perspective worker.
-    async look(args) {
-        const workspaceId = ClientInput.assertId("operation.look", "workspaceId", args.workspaceId);
-        const workerId = ClientInput.assertId("operation.look", "workerId", args.workerId);
-        const perspective = args.perspectiveWorkerId === undefined
-            ? workerId
-            : ClientInput.assertId("operation.look", "perspectiveWorkerId", args.perspectiveWorkerId);
-        const { statement } = args;
-        await this.#assertWorkerOwned(workspaceId, workerId);
-        if (perspective !== workerId)
-            await this.#assertWorkerOwned(workspaceId, perspective);
-        const releaseCapabilities = await this.#residency.acquire(workspaceId);
-        try {
-            const releaseWorkspace = await this.#workspaceGate.acquireTurn(workspaceId, workerId);
-            try {
-                await this.#residency.reconcile(workspaceId);
-                const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
-                try {
-                    const result = await this.#engine.look({ statement, workspaceId, workerId: perspective, loopId: clientLoopId });
-                    await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
-                    return result;
-                }
-                catch (error) {
-                    await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
-                    throw error;
-                }
-            }
-            finally {
-                releaseWorkspace();
-            }
-        }
-        finally {
-            releaseCapabilities();
-        }
+        }, this.#clientLoops.get(loopId)?.scope.signal);
     }
     // {§methods} — the module's render surface beyond the journal. Thin delegations
     // into core's envelope / membership / provider machinery; the module fans the results into its own views.
@@ -935,14 +944,23 @@ export default class Daemon {
         return {
             aliases: aliases.map((a) => {
                 const isActive = active === a.alias;
+                // {§agui-provider-routes} — the route a worker seeded from this alias gets: what it would read back.
+                let effort;
+                try {
+                    effort = ProviderInstantiate.configuredEffort(a);
+                }
+                catch (cause) {
+                    const invalid = new ConfigurationError("PLURNK_PROVIDERS_EFFORT", cause instanceof Error ? cause.message : String(cause), { cause });
+                    throw new OperationFailureError(Results.configurationFailure(invalid), { cause });
+                }
                 return {
-                    alias: a.alias, provider: a.provider, model: a.model, active: isActive,
+                    ...projectModelRoute(a, effort, "default"), alias: a.alias, active: isActive,
                     inputCapacity: isActive && this.#provider !== null ? this.#provider.inputCapacity : null
                 };
             })
         };
     }
-    // {§model-catalog} The catalog is a bounded, worldless local projection.
+    // {§model-catalog} The catalog is a bounded, daemon-local projection.
     // It performs no provider I/O and never changes the worker's selection.
     listModels(query) {
         return listModelCatalog(query);
@@ -970,7 +988,16 @@ export default class Daemon {
         }));
         return Validator.assertClientDisplayCapabilities([...schemes, ...mimetypes]);
     }
-    listWorkspaces() { return Envelope.listWorkspaces(this.#db); }
+    async listWorkspaces() {
+        return (await Envelope.listWorkspaces(this.#db)).map((row) => ({ ...row, project_label: this.#projectLabel(row.project_root) }));
+    }
+    // {§workspace-label} — the folder as the daemon spells it for display: the spelling a default name takes.
+    #projectLabel(projectRoot) {
+        return projectRoot === null ? null : this.#hostPaths.abbreviateUserPath(projectRoot);
+    }
+    #labelled(envelope) {
+        return { ...envelope, projectLabel: this.#projectLabel(envelope.projectRoot) };
+    }
     listWorkers(workspaceId, query = {}) {
         const origin = query.origin;
         if (origin !== undefined && !["model", "client", "_plurnk"].includes(origin)) {
@@ -995,26 +1022,27 @@ export default class Daemon {
         if (hasId === hasName) {
             throw daemonFailure("daemon:worker", "identity-invalid", 400, "Worker observation requires exactly one id or name.", { retryable: false });
         }
+        // {§worker-name-minting} — a lookup is no minting door: it resolves any name a listing returns,
+        // the runtime worker's `_plurnk` among them.
         const row = hasId
             ? await this.#db.envelope_get_worker_by_id.get({
                 id: ClientInput.assertId("worker.read", "id", args.identity.id)
             })
             : await this.#db.envelope_get_worker_by_name.get({
                 workspace_id: workspaceId,
-                name: ClientInput.assertOptionalWorkerName("worker.read", "name", args.identity.name)
+                name: ClientInput.assertOptionalName("worker.read", "name", args.identity.name)
             });
         if (row === undefined || row.workspace_id !== workspaceId)
             return null;
         const { workspace_id: _workspaceId, ...projection } = projectWorkerRow(row);
         return projection;
     }
-    // {§methods-worker-descendants}
-    async descendantAccounting(args) {
-        const workspaceId = ClientInput.assertId("worker.descendants", "workspaceId", args.workspaceId);
-        const workerId = ClientInput.assertId("worker.descendants", "workerId", args.workerId);
+    // {§methods-worker-accounting}
+    async workerAccounting(args) {
+        const workspaceId = ClientInput.assertId("worker.accounting", "workspaceId", args.workspaceId);
+        const workerId = ClientInput.assertId("worker.accounting", "workerId", args.workerId);
         await this.#assertWorkerOwned(workspaceId, workerId);
-        const loopId = args.loopId === null ? null : ClientInput.assertId("worker.descendants", "loopId", args.loopId);
-        return this.#engine.descendantAccounting(workerId, loopId);
+        return this.#engine.workerAccounting(workerId);
     }
     async listWorkerLoops(args) {
         const workspaceId = ClientInput.assertId("worker.loops", "workspaceId", args.workspaceId);
@@ -1028,20 +1056,22 @@ export default class Daemon {
             status: row.status,
             prompt: row.prompt,
             promptSource: row.promptSource,
+            claimedAt: row.claimedAt,
             terminatedAt: row.terminatedAt,
             packetCount: row.packetCount,
             waitUntil: row.waitUntil,
+            invocation: row.invocation === null || row.invocationWorkerId === null ? null : { workerId: row.invocationWorkerId, address: row.invocation },
             // {§validation-topology}: a stored result is chapter 3's (`loops_terminal_result_contract`); it is parsed, not re-asserted.
             terminalResult: row.terminalResult === null ? null : JSON.parse(row.terminalResult)
         }));
     }
-    // {§methods-workspace-prompts}: root-conversation loop seeds, newest-first.
+    // {§methods-workspace-prompts}: root-worker loop seeds, newest-first.
     // {§share} — one workspace's share. The daemon names its own database; the caller names an absolute folder.
     async shareWorkspace({ workspaceId, folder }) {
         const checkedWorkspaceId = ClientInput.assertId("workspace.share", "workspaceId", workspaceId);
         const checkedFolder = ClientInput.assertShareFolder("workspace.share", folder);
         if (this.#dbPath === undefined)
-            throw new Error("share: this daemon was started without its database path");
+            throw new Error("this daemon was started without its database path");
         return await Share.write({ openEvidence: EvidenceReader.open, dbPath: this.#dbPath, folder: checkedFolder, workspaceId: checkedWorkspaceId });
     }
     listPrompts(workspaceId, limit, workerId) {
@@ -1050,6 +1080,13 @@ export default class Daemon {
         const checkedWorkerId = workerId === undefined ? null : ClientInput.assertId("workspace.prompts", "workerId", workerId);
         return Envelope.listPromptsForWorkspace(this.#db, checkedWorkspaceId, checkedLimit ?? Knob.integer("PLURNK_SERVICE_PROMPTS_PAGE", 1), checkedWorkerId);
     }
+    // {§methods-workspace-activate} — the demand a turn makes, without the turn: a cold workspace activates,
+    // a concurrent demand shares that activation, and the release leaves it warm under the residency policy.
+    async activateWorkspace(args) {
+        const workspaceId = ClientInput.assertId("workspace.activate", "workspaceId", args.workspaceId);
+        const release = await this.#residency.acquire(workspaceId);
+        release();
+    }
     workspacePreparationStatus(workspaceId) {
         return this.#functionality.preparationStatus(ClientInput.assertId("workspace preparation", "workspaceId", workspaceId));
     }
@@ -1063,81 +1100,105 @@ export default class Daemon {
     async createWorkspace(args) {
         // The seam fails hard on malformed semantic input so every module inherits one wall:
         // the settings bag ({§operator-config-workspace-settings}) and absolute projectRoot.
-        const name = ClientInput.assertOptionalName("workspace.create", "name", args.name);
+        const explicit = ClientInput.assertOptionalWorkspaceName("workspace.create", "name", args.name);
         const projectRoot = ClientInput.assertProjectRoot("workspace.create", args.projectRoot);
         const settings = ClientInput.parseSettings(args.settings);
+        // {§workspace-name} — with a project root and no name, the workspace is named after the root with
+        // the daemon's home abbreviated to `~`, and that name selects the existing workspace when one exists:
+        // a default is a convention shared by every client, never a second workspace.
+        const derived = explicit === undefined && projectRoot !== null ? this.#hostPaths.abbreviateUserPath(projectRoot) : undefined;
+        const selected = async () => {
+            if (derived === undefined)
+                return undefined;
+            const existing = await this.#db.envelope_get_workspace_by_name.get({ name: derived });
+            return existing === undefined ? undefined : this.#labelled(await Envelope.attachToWorkspace(this.#db, existing.id));
+        };
         return observed(// {§observability-boundary}
         "workspace.create", {}, async (span) => {
-            const envelope = await Envelope.createClientEnvelope(this.#db, { name, projectRoot, settings });
+            const already = await selected();
+            if (already !== undefined) {
+                span.setAttribute("workspace.id", already.workspaceId);
+                return already;
+            }
+            let envelope;
+            try {
+                envelope = this.#labelled(await Envelope.createClientEnvelope(this.#db, { name: explicit ?? derived, projectRoot, settings }));
+            }
+            catch (error) {
+                // A concurrent default launch created it first: select what it created.
+                const raced = derived !== undefined ? await selected() : undefined;
+                if (raced === undefined)
+                    throw error;
+                span.setAttribute("workspace.id", raced.workspaceId);
+                return raced;
+            }
             span.setAttribute("workspace.id", envelope.workspaceId);
-            this.#broadcast("all", "workspace/created", { id: envelope.workspaceId, name: envelope.workspaceName, projectRoot: envelope.projectRoot });
+            this.#broadcast("all", "workspace/created", { id: envelope.workspaceId, name: envelope.workspaceName, projectRoot: envelope.projectRoot, projectLabel: envelope.projectLabel });
             return envelope;
         });
     }
+    // {§methods-workspace-attach} Selection is passive and never searches by the stored project folder.
     async attachWorkspace(args) {
-        // attachToWorkspace owns the reserved-name + worker-ownership invariants; the seam just delegates.
-        const workspaceId = ClientInput.assertId("workspace.attach", "workspaceId", args.workspaceId);
-        const workerId = args.workerId === undefined
-            ? undefined
-            : ClientInput.assertId("workspace.attach", "workerId", args.workerId);
-        const workerName = ClientInput.assertOptionalWorkerName("workspace.attach", "workerName", args.workerName);
-        return Envelope.attachToWorkspace(this.#db, workspaceId, { workerId, workerName });
+        const selectors = ["workspaceId", "name", "projectRoot"].filter((key) => Object.hasOwn(args, key));
+        if (selectors.length !== 1 || args[selectors[0]] == null) {
+            throw daemonFailure("daemon:workspace", "identity-invalid", 400, "Workspace selection requires exactly one ID, name or project root.", { retryable: false });
+        }
+        if (Object.hasOwn(args, "workspaceId")) {
+            const workspaceId = ClientInput.assertId("workspace.attach", "workspaceId", args.workspaceId);
+            return this.#labelled(await Envelope.attachToWorkspace(this.#db, workspaceId));
+        }
+        const name = Object.hasOwn(args, "name")
+            ? ClientInput.assertOptionalName("workspace.attach", "name", args.name)
+            : this.#hostPaths.abbreviateUserPath(ClientInput.assertProjectRoot("workspace.attach", args.projectRoot));
+        const existing = await this.#db.envelope_get_workspace_by_name.get({ name });
+        if (existing === undefined) {
+            throw daemonFailure("daemon:workspace", "workspace-not-found", 404, `Workspace ${JSON.stringify(name)} does not exist.`, { name });
+        }
+        return this.#labelled(await Envelope.attachToWorkspace(this.#db, existing.id));
     }
-    // {§rollback} {§methods-workspace-rollback} — the compensations are the acting client's own
-    // operations, in its worker, settled under its owner the moment they propose.
+    // {§worker-external-reference} The adapter interprets the key; core retains its target by identity.
+    async readWorkerReference(args) {
+        return WorkerReferences.read(this.#db, args);
+    }
+    async ensureWorkerReference(args) {
+        const { binding, created } = await WorkerReferences.ensure(this.#db, args);
+        if (created) {
+            const env = await this.attachWorkspace(binding);
+            this.#broadcast("all", "workspace/created", { id: env.workspaceId, name: env.workspaceName, projectRoot: env.projectRoot, projectLabel: env.projectLabel });
+        }
+        return binding;
+    }
+    async listWorkerReferences({ workspaceId, workerId, namespace }) {
+        await this.#assertWorkerOwned(workspaceId, workerId);
+        return (await this.#db.worker_reference_list.all({ namespace, worker_id: workerId })).map(({ reference }) => reference);
+    }
+    // {§rollback} {§methods-workspace-rollback} — the compensations are one client operation of the acting person
+    // ({§connection-lifecycle}): attributed to that person and, being that person's decision, never routed for review.
     async rollback(args) {
         const workspaceId = ClientInput.assertId("workspace.rollback", "workspaceId", args.workspaceId);
         const workerId = ClientInput.assertId("workspace.rollback", "workerId", args.workerId);
-        const clientWorkerId = ClientInput.assertId("workspace.rollback", "clientWorkerId", args.clientWorkerId);
+        const actor = ClientInput.assertActor("workspace.rollback", args.actor);
         if (typeof args.to !== "string")
             throw daemonFailure("daemon:rollback", "coordinate-invalid", 400, "The rollback coordinate must be a string.", {});
         await this.#assertWorkerOwned(workspaceId, workerId);
-        await this.#assertWorkerOwned(workspaceId, clientWorkerId);
-        const client = await this.#db.envelope_get_worker_by_id.get({ id: clientWorkerId });
-        if (client === undefined)
-            throw daemonFailure("daemon:worker", "worker-not-found", 404, `Worker ${clientWorkerId} does not exist.`, { workerId: clientWorkerId });
-        const owner = { workspaceId, address: client.owner };
-        const report = await Rollback.run({
+        const report = await this.#clientOperation({ workspaceId, actor, contextWorkerId: workerId }, (dispatch) => Rollback.run({
             db: this.#db,
             projectRoot: async (id) => (await this.#db.envelope_get_workspace.get({ id }))?.project_root ?? null,
             executorTags: (id) => this.#engine.executorTags(id),
-            apply: async (statement) => {
-                const releaseCapabilities = await this.#residency.acquire(workspaceId);
-                try {
-                    const clientLoopId = await Envelope.ensureClientLoop(this.#db, clientWorkerId);
-                    try {
-                        const result = await this.#dispatchClientStatement({
-                            workspaceId, workerId: clientWorkerId, loopId: clientLoopId, statement,
-                            // A proposal pauses the dispatch until it is resolved; this is the owner's own act.
-                            onDispatch: (logEntryId) => setImmediate(() => {
-                                void this.resolveProposal(logEntryId, { decision: "accept" }, owner).catch(() => undefined);
-                            }),
-                        });
-                        await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
-                        return result;
-                    }
-                    catch (error) {
-                        await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
-                        throw error;
-                    }
-                }
-                finally {
-                    releaseCapabilities();
-                }
-            },
-        }, { workspaceId, workerId, to: args.to });
+            apply: async (statement) => await dispatch(statement),
+        }, { workspaceId, workerId, to: args.to }));
         return Validator.assertRollbackReport(report);
     }
     async renameWorkspace(workspaceId, name) {
         const checkedWorkspaceId = ClientInput.assertId("workspace.rename", "workspaceId", workspaceId);
-        const checkedName = ClientInput.assertOptionalName("workspace.rename", "name", name);
+        const checkedName = ClientInput.assertOptionalWorkspaceName("workspace.rename", "name", name);
         if (checkedName === undefined)
-            throw new Error("ClientInput.assertOptionalName accepted a required name as undefined");
+            throw new Error("ClientInput.assertOptionalWorkspaceName accepted a required name as undefined");
         return { id: checkedWorkspaceId, name: await Envelope.updateWorkspaceName(this.#db, checkedWorkspaceId, checkedName) };
     }
-    // {§methods-conversation-worker}: a fresh conversation is a model-origin worker with an empty private log.
-    // AG-UI threads map to these workers while the workspace world remains shared ({§machine-processes}).
-    async createConversationWorker(args) {
+    // {§methods-worker-create}: a fresh worker is model-origin, with an empty private log.
+    // {§machine-processes} Workers have independent histories within a shared workspace.
+    async createWorker(args) {
         const workspaceId = ClientInput.assertId("worker.create", "workspaceId", args.workspaceId);
         const name = ClientInput.assertOptionalWorkerName("worker.create", "name", args.name);
         const workspace = await this.#db.envelope_get_workspace.get({ id: workspaceId });
@@ -1164,24 +1225,14 @@ export default class Daemon {
         const worker = await Envelope.createModelWorker(this.#db, workspaceId, name, parentWorkerId, args.owner);
         return { workerId: worker.id, workerName: worker.name };
     }
-    // {§worker-scheme-fork} — branch a worker's log while sharing the workspace world.
+    // {§worker-scheme-fork} — branch a worker's log while sharing its workspace.
     // Core owns the workspace check and immutable worker-name admission.
     async forkWorker(args) {
         const workspaceId = ClientInput.assertId("run.fork", "workspaceId", args.workspaceId);
         const workerId = ClientInput.assertId("run.fork", "workerId", args.workerId);
         const name = ClientInput.assertOptionalWorkerName("run.fork", "name", args.name);
-        const owner = await this.#db.envelope_get_worker_by_id.get({ id: workerId });
-        if (owner === undefined) {
-            throw daemonFailure("daemon:worker", "worker-not-found", 404, `Worker ${workerId} does not exist.`, { workerId });
-        }
-        if (owner.workspace_id !== workspaceId) {
-            throw daemonFailure("daemon:worker", "workspace-mismatch", 409, `Worker ${workerId} does not belong to workspace ${workspaceId}.`, {
-                workerId,
-                workspaceId,
-                actualWorkspaceId: owner.workspace_id,
-                retryable: false
-            });
-        }
+        // {§machine-processes-worker-origin} A branch is a model's: only a model worker's log forks.
+        await this.#assertModelWorker(workspaceId, workerId);
         if (name !== undefined) {
             const taken = await this.#db.envelope_get_worker_by_name.get({ workspace_id: workspaceId, name });
             if (taken !== undefined) {
@@ -1251,7 +1302,7 @@ export default class Daemon {
         const { name, scope, inputSchema, outputSchema, handler } = registration;
         if (name.length === 0)
             throw new Error("registerModuleAction: action name must not be empty");
-        if (scope !== "worldless" && scope !== "workspace" && scope !== "worker") {
+        if (scope !== "daemon" && scope !== "workspace" && scope !== "worker") {
             throw new Error(`module action '${name}' has invalid scope '${String(scope)}'`);
         }
         if (inputSchema === null || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
@@ -1273,8 +1324,8 @@ export default class Daemon {
         if (registration.residency !== "required" && registration.residency !== "none") {
             throw new Error(`module action '${name}' must declare its residency requirement`);
         }
-        if (scope === "worldless" && registration.residency !== "none") {
-            throw new Error(`worldless module action '${name}' cannot require workspace residency`);
+        if (scope === "daemon" && registration.residency !== "none") {
+            throw new Error(`daemon module action '${name}' cannot require workspace residency`);
         }
         if (this.#moduleActions.has(name))
             throw new Error(`module action '${name}' is already registered`);
@@ -1306,7 +1357,7 @@ export default class Daemon {
                 throw daemonFailure("daemon:module-action", "worker-not-found", 404, `Worker ${workerId} does not exist in workspace ${workspaceId}.`, { workspaceId, workerId, retryable: false });
             }
         }
-        if (registration.residency === "required" && context.scope !== "worldless") {
+        if (registration.residency === "required" && context.scope !== "daemon") {
             releaseCapabilities = await this.#residency.acquire(context.workspaceId);
         }
         else if (context.scope === "workspace") {
@@ -1372,6 +1423,9 @@ export default class Daemon {
         await this.#residency.replace(replacement, options);
     }
     get engine() { return this.#engine; }
+    // {§credential-authority} — the file holding this boot's minted operator secret; null when the
+    // secret is configured, the posture is off, or the daemon has no database path.
+    get secretFile() { return this.#secretMinted ? this.#secretPath : null; }
     configurationNotices() { return this.#configuration.notices(); }
     get provider() { return this.#provider; }
     get schemes() { return this.#schemes; }
@@ -1391,6 +1445,7 @@ export default class Daemon {
         await this.#configuration.capture("wait", () => TurnDispositionHandler.configuredWaitSeconds());
         await this.#configuration.capture("execution", () => Exec.validateConfiguration());
         this.#retention = await this.#configuration.capture("retention", () => new Retention(this.#db, retentionPolicy()));
+        this.#clientOperations = new AbortController();
         this.#started = true;
         // {§db-space-reclamation} — the file is brought to the policy's auto-vacuum mode before any work.
         if (this.#retention !== null) {
@@ -1475,6 +1530,18 @@ export default class Daemon {
                 this.#moduleLifetimes.push(module);
             await module.setup?.(setupSeam);
         }
+        // {§credential-authority} — the posture is never an inference: a listening daemon that
+        // authenticates needs a module that issues, and it writes a minted secret where same-user
+        // clients read it before any mount is admitted; a configured or absent secret leaves no file.
+        if (this.#http !== null && this.credentials.operatorSecret !== null && this.credentials.face() === null) {
+            throw new Error("PLURNK_AUTH=1, and no module publishes an authorization server to issue credentials: install the client interface, or set PLURNK_AUTH=0");
+        }
+        if (this.#secretPath !== null) {
+            if (this.#secretMinted && this.credentials.operatorSecret !== null)
+                await Credentials.writeSecret(this.#secretPath, this.credentials.operatorSecret);
+            else
+                await Credentials.removeSecret(this.#secretPath);
+        }
         await this.#schemes.ready();
         this.#residency.publish();
         await this.#recoverLifecycle();
@@ -1516,15 +1583,7 @@ export default class Daemon {
         this.#http.admit();
     }
     async #recoverLifecycle() {
-        await this.#db.recovery_fail_active_loops.run({});
-        await this.#db.recovery_settle_open_provider_requests.run({});
-        await this.#db.recovery_fail_open_model_calls.run({});
-        await this.#db.recovery_fail_open_turns.run({});
-        await this.#db.recovery_fail_ownerless_proposals.run({});
-        await this.#db.recovery_remove_ownerless_client_interactions.run({});
-        await this.#db.recovery_error_orphan_subscription_channels.run({});
-        await this.#db.recovery_fail_orphan_subscriptions.run({});
-        await this.#db.recovery_resume_unblocked_parks.run({});
+        await this.#db.recovery_settle_process_owners({});
         const orphanSources = await this.#db.recovery_orphan_message_sources.all({});
         const invalidOrphan = orphanSources.find(({ origin }) => origin !== "model");
         if (invalidOrphan !== undefined) {
@@ -1572,6 +1631,7 @@ export default class Daemon {
         this.#engine.cancelAllProposals("daemon_stopping");
         this.#engine.cancelDerivations(derivationAbort);
         this.#drains.beginStop("daemon_stopping");
+        this.#clientOperations.abort("daemon_stopping");
         this.#residency.beginStop();
         const shutdown = deadline ?? new StopDeadline();
         // Stop accepting external work immediately, but do not await listener
@@ -1604,6 +1664,10 @@ export default class Daemon {
         // process may exit with the WAL in place (SQLite recovers) rather than
         // leak as a live-but-wedged tree.
         const drainResult = await shutdown.settle("drains idle", () => this.#drains.idle());
+        const clientResult = await shutdown.settle("client operations idle", async () => {
+            await Promise.all([...this.#clientLoops.values()].map(({ settled }) => settled));
+        });
+        const residencyResult = await shutdown.settle("workspace Functionality transitions", () => this.#residency.settle());
         // A boundary publication queued behind the last turn settles before
         // modules close and before the DB goes away ({§functionality-publication}).
         const functionalityResult = await shutdown.settle("functionality publications", () => this.#functionality.settle());
@@ -1627,8 +1691,10 @@ export default class Daemon {
         const closeErrors = [
             moduleStopResult,
             moduleCloseResult,
+            residencyResult,
             functionalityResult,
             drainResult,
+            clientResult,
             streamingResult,
             derivationResult,
             collectResult,