@cotal-ai/manager 0.101.2 → 0.101.4

package/dist/manager.js

@@ -64,6 +64,10 @@ export const READINESS_TIMEOUT_MS = 30_000;
  *  how long it waits past the window for the proof of its last read. An operator waits on this reply,
  *  so it asks more often than the exit watch that outlives readiness. */
 const READINESS_EXIT_POLL_MS = 1_000;
+/** How long the process of a launch that waits for the operator ({@link Connector.waitsForOperator})
+ *  must run without exiting before it is ready: long enough that a harness refusing its arguments
+ *  exits first and is reported as failed. */
+const OPERATOR_READINESS_MS = 3_000;
 /** Managed same-session crash recovery follows the Codex host precedent: three restarts are allowed
  * inside a rolling two-minute window; the fourth crash is a loop and retires the seat loud. */
 const SESSION_RESTART_LIMIT = 3;
@@ -3732,7 +3736,7 @@ export class Manager {
             const refusal = material === undefined && !unshredded.length ? caughtEnvelope(e) : undefined;
             return {
                 error: `agent auth preflight failed for "${name}": ${rejectionText(e)}${leftover}`,
-                ...(refusal?.outcome === "not-executed" ? { refused: refusal.code } : {}),
+                ...(refusal?.outcome === "not-executed" ? { refused: refusal.code, ...(refusal.details ? { details: refusal.details } : {}) } : {}),
             };
         }
     }
@@ -5516,7 +5520,7 @@ export class Manager {
             // manager's agent) refuses cleanly at accept, rather than minting the collision and black-
             // holing on the broker/auth refusal (a pinned name live under another manager MUST refuse).
             if (this.nameInUse(identityName))
-                return { ok: false, error: `the name "${identityName}" is hard-pinned (${opts.resolved ? "manifest-declared" : "--name/identity override"}) but is already held by a live incarnation (managed here, an unmanaged foreground/connector session, or another manager's agent); a pinned same-name collision refuses at accept - pick another name or despawn the existing one` };
+                return { ok: false, code: "already-exists", error: `the name "${identityName}" is hard-pinned (${opts.resolved ? "manifest-declared" : "--name/identity override"}) but is already held by a live incarnation (managed here, an unmanaged foreground/connector session, or another manager's agent); a pinned same-name collision refuses at accept - pick another name or despawn the existing one` };
             name = identityName;
         }
         else {
@@ -5657,7 +5661,7 @@ export class Manager {
                 if ("error" in prep) {
                     if (prep.refused !== undefined)
                         hooks?.onUndone?.(prep.refused);
-                    return { ok: false, error: prep.error };
+                    return { ok: false, error: prep.error, ...(prep.details ? { details: prep.details } : {}) };
                 }
                 // THE HOST'S UID WINS (#1972). On the local arm this is the value passed in, unchanged. On
                 // the hosted enrollment arm the host selected it, and from here every lifecycle-keyed thing
@@ -5891,8 +5895,10 @@ export class Manager {
             // #159 B1: reply on a REAL outcome, not a timer. Wait for the agent to actually join the mesh
             // (presence) → started, the child to exit → failed (with its last output; already reaped), or
             // neither in time → uncertain. `✓ started` therefore means "it joined", never just "a process
-            // launched".
-            const readiness = await this.awaitReadiness(managed, readinessTimeoutMs);
+            // launched", except for a launch whose options make the harness wait for the operator first: that
+            // one is ready once its process runs, and its reply names the screen it waits at.
+            const operator = connector.waitsForOperator?.(launchOptions);
+            const readiness = await this.awaitReadiness(managed, readinessTimeoutMs, operator === undefined ? {} : { operator });
             // Deliberately stopped mid-launch: reaped by onExit, and the despawn/stop path owns the
             // goal terminal. Return BEFORE the failed/uncertain arms so this emits no competing
             // outcome and does not re-arm an exit watcher on an agent already gone.
@@ -5915,7 +5921,7 @@ export class Manager {
                 this.watchExit(managed);
                 if (managed.launch.carried)
                     void this.refuseLateCarriedFork(managed, readinessTimeoutMs);
-                await hooks?.onOutcome?.({ kind: "uncertain", data: { reason: readiness.detail } });
+                await hooks?.onOutcome?.({ kind: "uncertain", data: { reason: readiness.detail, ...(readiness.running ? { running: true } : {}) } });
                 return { ok: false, error: readiness.detail };
             }
             if (managed.launch.carried) {
@@ -5987,7 +5993,7 @@ export class Manager {
             // "no role", so dropping the key preserves the reply (surfaced by readiness:live).
             // A host that granted other channels than this spawn asked for: the receipt carries both.
             const acl = enrolled ? enrolledAcl({ allowSubscribe, allowPublish }, enrolled.material) : undefined;
-            const okData = { name, agent, id: managed.id, mode: handle.kind, lifecycleUid, ...(role !== undefined ? { role } : {}), ...(opts.eventsNotice !== undefined ? { eventsNotice: opts.eventsNotice } : {}), ...(acl ? { acl } : {}) };
+            const okData = { name, agent, id: managed.id, mode: handle.kind, lifecycleUid, ...(role !== undefined ? { role } : {}), ...(opts.eventsNotice !== undefined ? { eventsNotice: opts.eventsNotice } : {}), ...(acl ? { acl } : {}), ...(readiness.operator !== undefined ? { waitingFor: readiness.operator } : {}) };
             await hooks?.onOutcome?.({ kind: "succeeded", data: okData });
             return { ok: true, data: okData };
         }
@@ -6713,7 +6719,10 @@ export class Manager {
      *  catches a join/exit that landed before we subscribed). A runtime whose `attach()` throws (an external
      *  surface) streams no output or exit, so its exit leg polls the runtime's exit proof ({@link pollProvedExit}),
      *  reads it once more when the window closes, and its failure carries no last output; one that cannot prove an
-     *  exit either races presence-vs-backstop only. */
+     *  exit either races presence-vs-backstop only.
+     *  A launch that waits for the operator at `opts.operator`, a screen its connector names, is ready once a
+     *  process this runtime owns has run for {@link OPERATOR_READINESS_MS} without exiting. An uncertain verdict
+     *  says whether a process this runtime owns is still running. */
     async awaitReadiness(a, readinessTimeoutMs, opts = {}) {
         let session;
         try {
@@ -6748,11 +6757,13 @@ export class Manager {
             let timer;
             let unsubExit = () => { };
             let joinedPoll;
+            let operatorTimer;
             const finish = (r) => {
                 if (done)
                     return;
                 done = true;
                 clearTimeout(timer);
+                clearTimeout(operatorTimer);
                 if (joinedPoll !== undefined)
                     clearInterval(joinedPoll);
                 this.ep.off("presence", onPresence);
@@ -6775,6 +6786,7 @@ export class Manager {
                 if (done)
                     return;
                 clearTimeout(timer);
+                clearTimeout(operatorTimer);
                 // `stopHandle` sets `terminalizing` synchronously before it kills, and `onAgentExit` sets it
                 // through `freeSlot` when it retires the seat, so only a read before the await and the reap
                 // tells a deliberate stop from a launch failure.
@@ -6822,11 +6834,21 @@ export class Manager {
                     finish({ ok: false, detail: `${a.name} exited on launch${tail ? ` - last output: ${tail}` : ""}${exitDetail}` });
                 })();
             };
-            const uncertain = () => finish({
-                ok: false,
-                uncertain: true,
-                detail: `${a.name} (${a.id}): launch status uncertain - no process exit and no mesh presence within ${readinessTimeoutMs}ms; it may still be booting or stuck before connector startup. Inspect with \`cotal attach ${a.name}\` / \`cotal ps\`; do not stop it solely because this bounded wait elapsed.`,
-            });
+            // A process this runtime owns reports its own exit, so one still running here is running.
+            const uncertain = () => {
+                const running = s !== undefined && a.handle.status() === "running";
+                finish({
+                    ok: false,
+                    uncertain: true,
+                    running,
+                    detail: running
+                        ? `${a.name} (${a.id}): launch status uncertain - its process is running but did not join the mesh within ${readinessTimeoutMs}ms; it may still be starting or waiting at a prompt. Inspect with \`cotal attach ${a.name}\` / \`cotal ps\`; do not stop it solely because this bounded wait elapsed.`
+                        : `${a.name} (${a.id}): launch status uncertain - no process exit and no mesh presence within ${readinessTimeoutMs}ms; it may still be booting or stuck before connector startup. Inspect with \`cotal attach ${a.name}\` / \`cotal ps\`; do not stop it solely because this bounded wait elapsed.`,
+                });
+            };
+            if (opts.operator !== undefined && s)
+                operatorTimer = setTimeout(() => { if (a.handle.status() === "running")
+                    finish({ ok: true, operator: opts.operator }); }, OPERATOR_READINESS_MS);
             // The exit poll read the runtime up to a poll ago, and a window can be shorter than a poll, so
             // the window closes on a fresh read: a child that exited by then is reported as exited. Nothing
             // bounds how long a runtime's proof takes, so it gets one more poll before the launch is uncertain.
@@ -8309,8 +8331,8 @@ export class Manager {
                 else {
                     // Forward the readiness detail as the terminal's reason: this manager owns the deadline,
                     // so it owns what elapsing it MEANS. Absent, core commits its own generic line (#605).
-                    const why = o.data?.reason;
-                    ({ fact } = await settleGoalUncertain(gw.ctx, { ref, now: Date.now(), committer: { instanceId: this.managerInstanceId, epoch }, ...(typeof why === "string" && why.length > 0 ? { reason: why } : {}) }));
+                    const { reason: why, running } = (o.data ?? {});
+                    ({ fact } = await settleGoalUncertain(gw.ctx, { ref, now: Date.now(), committer: { instanceId: this.managerInstanceId, epoch }, ...(typeof why === "string" && why.length > 0 ? { reason: why } : {}), ...(running === true ? { running: true } : {}) }));
                 }
                 this.expireGoalAcceptance(ref);
                 this.emitGoalProgress(ref, epoch, { phase: "terminal", state: fact.state, ...(fact.data !== undefined ? { data: fact.data } : {}) });
@@ -8407,7 +8429,9 @@ export class Manager {
             // outcome unknown.
             if (acceptance === undefined) {
                 const details = reply.details;
-                rejectAccept(new EpEnvelopeError(undone ?? "failed-precondition", reply.error ?? "spawn refused at accept", details, effectStarted && undone === undefined ? undefined : "not-executed"));
+                // A hard-pinned name a live incarnation holds is the one refusal here that names its own code.
+                const code = undone ?? (reply.code === "already-exists" ? "already-exists" : "failed-precondition");
+                rejectAccept(new EpEnvelopeError(code, reply.error ?? "spawn refused at accept", details, effectStarted && undone === undefined ? undefined : "not-executed"));
                 return;
             }
             // H1: `run` CATCHES its own body (a throw in buildLaunch/runtime.spawn) and RESOLVES `{ok:false}`