@cotal-ai/connector-core 0.133.13 → 0.135.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/dist/agent.d.ts +71 -4
  2. package/dist/agent.d.ts.map +1 -1
  3. package/dist/agent.js +228 -33
  4. package/dist/agent.js.map +1 -1
  5. package/dist/briefing.d.ts +27 -0
  6. package/dist/briefing.d.ts.map +1 -0
  7. package/dist/briefing.js +58 -0
  8. package/dist/briefing.js.map +1 -0
  9. package/dist/config.d.ts +1 -1
  10. package/dist/config.d.ts.map +1 -1
  11. package/dist/config.js.map +1 -1
  12. package/dist/control.d.ts +3 -2
  13. package/dist/control.d.ts.map +1 -1
  14. package/dist/control.js +1 -1
  15. package/dist/control.js.map +1 -1
  16. package/dist/docs-bundle.bin +0 -0
  17. package/dist/docs-bundle.generated.d.ts +1 -1
  18. package/dist/docs-bundle.generated.d.ts.map +1 -1
  19. package/dist/docs-bundle.generated.js +13 -6
  20. package/dist/docs-bundle.generated.js.map +1 -1
  21. package/dist/docs-index.bin +0 -0
  22. package/dist/gateway.d.ts.map +1 -1
  23. package/dist/gateway.js +6 -2
  24. package/dist/gateway.js.map +1 -1
  25. package/dist/index.d.ts +2 -0
  26. package/dist/index.d.ts.map +1 -1
  27. package/dist/index.js +2 -0
  28. package/dist/index.js.map +1 -1
  29. package/dist/manager-call.d.ts +7 -1
  30. package/dist/manager-call.d.ts.map +1 -1
  31. package/dist/manager-call.js +39 -1
  32. package/dist/manager-call.js.map +1 -1
  33. package/dist/once.d.ts +53 -0
  34. package/dist/once.d.ts.map +1 -0
  35. package/dist/once.js +126 -0
  36. package/dist/once.js.map +1 -0
  37. package/dist/orientation.d.ts +11 -3
  38. package/dist/orientation.d.ts.map +1 -1
  39. package/dist/orientation.js +29 -8
  40. package/dist/orientation.js.map +1 -1
  41. package/dist/tool-specs.d.ts +14 -1
  42. package/dist/tool-specs.d.ts.map +1 -1
  43. package/dist/tool-specs.js +197 -50
  44. package/dist/tool-specs.js.map +1 -1
  45. package/package.json +3 -3
package/dist/agent.js CHANGED
@@ -1,10 +1,11 @@
1
1
  import { AsyncLocalStorage } from "node:async_hooks";
2
2
  import { EventEmitter } from "node:events";
3
3
  import { hostname } from "node:os";
4
- import { normalizeMentions, RUN_LAUNCH_DEADLINE_MS, subjectMatches, isConcreteChannel, assertValidChannel, channelInAllow, eventChannelPrincipal, resolvePeer as resolvePeerInRoster, peerLabel, CotalEndpoint, acquireLocalConsumer, BASELINE_LIFECYCLE_ENDPOINT, BIND_SPLIT_REISSUES, assertLifecycleToken, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest, EP_UNANSWERED, controlReplyFrom, controlReplyFromThrown, runAgentBearer, partsToText, assertValidRole, turnNoticeFilter, } from "@cotal-ai/core";
4
+ import { normalizeMentions, RUN_LAUNCH_DEADLINE_MS, subjectMatches, isConcreteChannel, isChannelFamily, assertValidChannel, channelInAllow, eventChannelPrincipal, resolvePeer as resolvePeerInRoster, peerLabel, CotalEndpoint, acquireLocalConsumer, BASELINE_LIFECYCLE_ENDPOINT, BIND_SPLIT_REISSUES, assertLifecycleToken, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest, EP_UNANSWERED, controlReplyFrom, controlReplyFromThrown, runAgentBearer, partsToText, assertValidRole, turnNoticeFilter, renderOnceTask, } from "@cotal-ai/core";
5
5
  import { TURN_PULL_RETRY_MS } from "./turn-poll.js";
6
+ import { ONCE_HANDOFF_MS, claimOnceHandoff, confirmOnceHandoff, endOnceHandoff, exitOnceSeat, onOnceHandoffTimeout, onceHandoffState, sealOnceHandoff, stopOnceHandoffTimer } from "./once.js";
6
7
  import { attributionSafe } from "./framing.js";
7
- import { invokeUserManager } from "./manager-call.js";
8
+ import { invokeUserManager, withUserManagerListing } from "./manager-call.js";
8
9
  /** Client-side floor for a spawn action's submit + follow. The manager acceptance carries the exact
9
10
  * connector-selected readiness budget, and core extends the follow through that budget plus
10
11
  * delivery margin. This floor still outlives the manager's generic 30s default and protects
@@ -108,17 +109,35 @@ const STATIC_SLOT_OBSERVATION_DETAIL = "ai.cotal.manager.static-slot-observation
108
109
  const MAX_SETTLED_TURNS = 32;
109
110
  /** The refusal for a yield on a turn the run settled first, so a seat that was shown the turn
110
111
  * learns why the run will not take its result instead of being told no turn exists. */
111
- function settledTurnError(goalId, deadlineAt) {
112
- return `turn "${goalId}" was already settled by the run (deadline ${new Date(deadlineAt).toISOString()}), so this yield was not recorded`;
112
+ function settledTurnError(goalId, t) {
113
+ const deadline = t.deadlineAt !== undefined ? ` (deadline ${new Date(t.deadlineAt).toISOString()})` : "";
114
+ return `turn "${goalId}" was already settled ${t.once !== undefined ? "by its manager" : "by the run"}${deadline}, so this yield was not recorded`;
113
115
  }
114
116
  /** Largest epoch-ms a `Date` can hold; past it `toISOString()` throws. */
115
117
  const MAX_DATE_MS = 8.64e15;
116
- /** A `turn-pending` row as the manager contract declares it, with a deadline a `Date` can format. */
118
+ /** A `turn-pending` row as the manager contract declares it, with a deadline a `Date` can format.
119
+ * Only a once task's row may omit its deadline. */
117
120
  function isPendingTurn(t) {
118
121
  const r = t;
119
- return typeof r === "object" && r !== null && typeof r.goalId === "string" && typeof r.payload === "string" &&
120
- Number.isSafeInteger(r.acceptedAt) && r.acceptedAt >= 0 &&
121
- Number.isSafeInteger(r.deadlineAt) && r.deadlineAt >= 1 && r.deadlineAt <= MAX_DATE_MS;
122
+ if (typeof r !== "object" || r === null || typeof r.goalId !== "string" || typeof r.payload !== "string")
123
+ return false;
124
+ if (!Number.isSafeInteger(r.acceptedAt) || r.acceptedAt < 0)
125
+ return false;
126
+ if (r.once !== undefined && r.once !== true)
127
+ return false;
128
+ if (r.deadlineAt === undefined)
129
+ return r.once === true;
130
+ return Number.isSafeInteger(r.deadlineAt) && r.deadlineAt >= 1 && r.deadlineAt <= MAX_DATE_MS;
131
+ }
132
+ /** Who a once task came from, as the manager wrote it beside the prompt. */
133
+ function onceSpawner(payload) {
134
+ try {
135
+ const spawner = JSON.parse(payload).once?.spawner;
136
+ return typeof spawner === "string" && spawner.length > 0 ? spawner : undefined;
137
+ }
138
+ catch {
139
+ return undefined;
140
+ }
122
141
  }
123
142
  import { createHash, randomUUID } from "node:crypto";
124
143
  /** #662: what an id-less channel delivery shares with its stream copy. Both are the same published
@@ -233,6 +252,7 @@ export class MeshAgent extends EventEmitter {
233
252
  ep;
234
253
  config;
235
254
  launchEnv;
255
+ options;
236
256
  inbox = [];
237
257
  /** Ids already SURFACED to the model (handled) — bounded, commit-aware dedup ACROSS a drain. The
238
258
  * live↔durable transition window can deliver the two copies of one message far enough apart that the
@@ -259,6 +279,9 @@ export class MeshAgent extends EventEmitter {
259
279
  protectedPullOnlyIds = new Set();
260
280
  protectedDropIds = new Set();
261
281
  dropUnsafe = false;
282
+ /** How many times the endpoint saw this session's stored copies at their limit (#5404) since a
283
+ * cotal_inbox reply last carried the notice. */
284
+ _storedCopiesFull = 0;
262
285
  _connected = false;
263
286
  /** Raw NATS transport liveness, separate from `_connected` (the full Cotal bind/readiness). */
264
287
  _transportConnected = false;
@@ -385,6 +408,7 @@ export class MeshAgent extends EventEmitter {
385
408
  constructor(config, env, options = {}) {
386
409
  super();
387
410
  this.config = config;
411
+ this.options = options;
388
412
  this.launchEnv = env === undefined ? undefined : { ...env };
389
413
  // Seed per-channel attention from the operator's file default (one-way: the runtime never writes
390
414
  // back — the persona file is a shared template). muted/quiet are validated disjoint at file load.
@@ -437,6 +461,7 @@ export class MeshAgent extends EventEmitter {
437
461
  // A warning is a condition the endpoint is already surviving. Log it through the same bounded
438
462
  // operator sink, but never turn it into connectionIssue: readiness is still true.
439
463
  this.ep.on("warning", (e) => this.handleEndpointWarning(e));
464
+ this.ep.on("stored-copies-full", () => { this._storedCopiesFull++; });
440
465
  // Two guards, and the comments sit out here so neither anchors a mutation on prose. An
441
466
  // in-flight initial bind or rebuild can finish after stop() cleared local state, and shutdown is
442
467
  // terminal for this MeshAgent, so a late endpoint edge must not resurrect transport. Separately,
@@ -575,6 +600,17 @@ export class MeshAgent extends EventEmitter {
575
600
  get stopping() {
576
601
  return this._stopping;
577
602
  }
603
+ /** How many times this session's stored copies reached their limit since a cotal_inbox reply last
604
+ * said so, so older channel posts may have been dropped before they reached it (#5404). Zero when
605
+ * there is nothing to say. */
606
+ get storedCopiesFull() {
607
+ return this._storedCopiesFull;
608
+ }
609
+ /** A reply carrying the stored-copy notice went out, read when the count was `seen`. Clear what
610
+ * it covered; a limit seen while that reply was being built stays for the next one. */
611
+ clearStoredCopiesFull(seen) {
612
+ this._storedCopiesFull = Math.max(0, this._storedCopiesFull - seen);
613
+ }
578
614
  /** Session-local channel degradation, independent of transport liveness. */
579
615
  get channelDeliveryIssue() {
580
616
  return this.dropUnsafe
@@ -1605,7 +1641,7 @@ export class MeshAgent extends EventEmitter {
1605
1641
  pendingWake(skip) {
1606
1642
  // An unsurfaced run turn is directed-strength: it wakes regardless of attention, exactly like
1607
1643
  // a DM — a run is waiting on this seat, and holding it costs the run its deadline.
1608
- const turns = [...this.activeTurns.values()].filter((t) => !t.surfaced).length;
1644
+ const turns = [...this.activeTurns.values()].filter((t) => !t.surfaced && this.offerable(t)).length;
1609
1645
  return turns + this.inboxWake(skip);
1610
1646
  }
1611
1647
  /** The inbox half of {@link pendingWake}: buffered items that should wake the agent, without run
@@ -2005,17 +2041,35 @@ export class MeshAgent extends EventEmitter {
2005
2041
  * runtime; from here it just joins the mesh as a lateral peer. `opts.agent` picks
2006
2042
  * the harness (absent it, the persona's `agent:` pin, else the manager's default), `opts.model` /
2007
2043
  * `opts.variant` override the persona file's model selectors, `opts.prompt` submits the new
2008
- * peer's first turn, `opts.runtime` chooses the terminal runtime of this one seat, and `opts.cwd` roots it at a different folder/repo
2044
+ * peer's first turn (or, with `opts.once`, is its one task, after which the manager stops it), `opts.runtime` chooses the terminal runtime of this one seat, and `opts.cwd` roots it at a different folder/repo
2009
2045
  * than the manager's workspace — the same knobs the operator's `cotal spawn --detach` carries, so
2010
2046
  * the agent and operator spawn doors share one control-op contract. (Session `resume` is
2011
2047
  * intentionally NOT forwarded here: forking a host-local `~/.claude` transcript is an
2012
- * operator-local intent, kept off the peer-facing spawn door — see #159.) */
2048
+ * operator-local intent, kept off the peer-facing spawn door — see #159.)
2049
+ *
2050
+ * Channels: `opts.join` names concrete channels the new peer joins on top of its persona's read
2051
+ * set, each checked here against THIS agent's read ACL before anything is sent (a spawn never
2052
+ * widens). The request also carries this agent's own read/post ACL as `callerAcl`; the manager
2053
+ * consults it only for a persona that names no channel field, so such a helper is scoped to its
2054
+ * spawner. The joined set is never copied: without `join`, a channel-less persona starts on none. */
2013
2055
  async spawn(name, role, opts) {
2014
2056
  await this.requireConnected();
2015
2057
  const raw = opts?.model;
2016
2058
  if (raw !== undefined && !raw.trim())
2017
2059
  return { ok: false, error: "model: must not be empty" };
2018
2060
  const requested = raw?.trim();
2061
+ for (const ch of opts?.join ?? []) {
2062
+ try {
2063
+ assertValidChannel(ch);
2064
+ }
2065
+ catch (e) {
2066
+ return { ok: false, error: `join: ${e.message}` };
2067
+ }
2068
+ if (!isConcreteChannel(ch))
2069
+ return { ok: false, error: `join: "${ch}" must be a concrete channel (no wildcard)` };
2070
+ if (!channelInAllow(this.config.allowSubscribe, ch))
2071
+ return { ok: false, error: `join: "${ch}" is not within your read ACL (allowSubscribe) [${this.config.allowSubscribe.join(", ")}]; a spawn can only hand on channels you may read yourself` };
2072
+ }
2019
2073
  let instance;
2020
2074
  try {
2021
2075
  const selected = opts?.instance ?? this.openManagerInstance();
@@ -2026,7 +2080,7 @@ export class MeshAgent extends EventEmitter {
2026
2080
  }
2027
2081
  if (this.config.userAuth && instance !== undefined && this.config.managerInstanceId !== undefined && instance !== this.config.managerInstanceId)
2028
2082
  return { ok: false, error: "the requested manager instance differs from this credential's instance authority" };
2029
- const args = { name, role, agent: opts?.agent, model: requested || undefined, variant: opts?.variant, launchOptions: opts?.launchOptions, cwd: opts?.cwd, prompt: opts?.prompt, events: opts?.events, runtime: opts?.runtime };
2083
+ const args = { name, role, agent: opts?.agent, model: requested || undefined, variant: opts?.variant, launchOptions: opts?.launchOptions, cwd: opts?.cwd, prompt: opts?.prompt, events: opts?.events, runtime: opts?.runtime, join: opts?.join, callerAcl: { allowSubscribe: this.config.allowSubscribe, allowPublish: this.config.allowPublish }, once: opts?.once };
2030
2084
  // P2 item 2 (2b): spawn is an ACTION — follow the acceptance to the terminal so cotal_spawn
2031
2085
  // stays synchronous (the MCP reply carries the live outcome, not the pre-launch acceptance).
2032
2086
  const reply = await this.managerInvoke("spawn", args, { deadlineMs: SPAWN_TIMEOUT_MS, follow: true, ...(instance !== undefined ? { instanceId: instance } : {}) });
@@ -2095,6 +2149,23 @@ export class MeshAgent extends EventEmitter {
2095
2149
  return { ok: false, error: `inspect returned a non-string model for "${name}"` };
2096
2150
  return { ok: true, model };
2097
2151
  }
2152
+ /** The registry listing as this session's manager-call credential sees it (SPEC 13.20), asked
2153
+ * over a connection opened on that credential and described on this session's own. On a static
2154
+ * mesh manager calls ride this session's credential, and a host-issued bearer has no manager-call
2155
+ * credential: `none` says which. `unbound`: that credential carries no listing binding. */
2156
+ async listManagerEndpoints(input, instance) {
2157
+ const user = this.config.userAuth;
2158
+ if (!user)
2159
+ return { none: "manager calls ride this session's own credential on this mesh, so the session view covers them" };
2160
+ if (!user.bearerCmd)
2161
+ return { none: "this session's bearer comes from its host, which issues no manager-call bearer, so the manager view has no credential" };
2162
+ const managerInstanceId = instance ?? this.config.managerInstanceId;
2163
+ const token = await this.managerCallBearer([...user.bearerCmd, "--manager-call", ...(managerInstanceId ? ["--manager-instance", managerInstanceId] : [])]).catch((e) => {
2164
+ throw e instanceof Error ? new Error(e.message.replace("--manager-instance <instanceId>", "the instance argument")) : e;
2165
+ });
2166
+ const exp = bearerExpiryMs(token);
2167
+ return withUserManagerListing({ ...this.config, managerInstanceId }, token, exp === undefined ? undefined : exp / 1000, async (nc, listing) => listing === undefined ? { unbound: true } : this.ep.listEndpointsOver(nc, listing, input));
2168
+ }
2098
2169
  /** Manager-call bearers this session holds, by the exact bearer argv (so by selected manager;
2099
2170
  * the space, owner, actor and lifecycle are this session's own). One exchange serves every call
2100
2171
  * until {@link MANAGER_BEARER_MARGIN_MS} before the bearer expires, and concurrent calls share it.
@@ -2405,6 +2476,12 @@ export class MeshAgent extends EventEmitter {
2405
2476
  armTurnRelay() {
2406
2477
  if (!this.hasTurnRelay())
2407
2478
  return;
2479
+ // A once task whose dispatch outlived its bound is sealed and reported by this seat's newest
2480
+ // MeshAgent, which is the one connected.
2481
+ onOnceHandoffTimeout((uid, goalId) => {
2482
+ if (uid === this.onceUid() && sealOnceHandoff(uid, goalId))
2483
+ void this.reportUnconfirmed(goalId);
2484
+ });
2408
2485
  if (!this.turnNoticeArmed) {
2409
2486
  let caller;
2410
2487
  try {
@@ -2473,11 +2550,23 @@ export class MeshAgent extends EventEmitter {
2473
2550
  for (const t of turns) {
2474
2551
  if (this.activeTurns.has(t.goalId) || this.yieldedSincePull.has(t.goalId))
2475
2552
  continue;
2476
- this.activeTurns.set(t.goalId, { goalId: t.goalId, payload: t.payload, acceptedAt: t.acceptedAt, deadlineAt: t.deadlineAt, surfaced: false });
2477
- fresh += 1;
2553
+ // A once task this process already handed over stays handed over: a rebuilt MeshAgent
2554
+ // finds its state in the process registry and neither offers it again nor loses its yield.
2555
+ const once = t.once ? { spawner: onceSpawner(t.payload) } : undefined;
2556
+ const surfaced = once !== undefined && onceHandoffState(this.onceUid(), t.goalId) === "confirmed";
2557
+ this.activeTurns.set(t.goalId, { goalId: t.goalId, payload: t.payload, acceptedAt: t.acceptedAt, ...(t.deadlineAt !== undefined ? { deadlineAt: t.deadlineAt } : {}), ...(once ? { once } : {}), surfaced });
2558
+ if (!surfaced)
2559
+ fresh += 1;
2560
+ if (once !== undefined && !surfaced && this.options.onceClaimBound)
2561
+ this.boundOnceClaim(t.goalId);
2478
2562
  }
2479
2563
  if (fresh > 0)
2480
2564
  this.requestWake();
2565
+ // A manager that does not hold this once seat, and has settled its task, tells it to end itself.
2566
+ if (r.data.stop === true) {
2567
+ this.log("the manager does not hold this once seat and its task has ended; ending this seat");
2568
+ void exitOnceSeat();
2569
+ }
2481
2570
  }
2482
2571
  finally {
2483
2572
  this.turnPollBusy = false;
@@ -2546,9 +2635,13 @@ export class MeshAgent extends EventEmitter {
2546
2635
  // A turn past its deadline is already settled at the manager, which refuses its yield, though
2547
2636
  // this cache holds it until the next pull settles it here.
2548
2637
  const now = Date.now();
2549
- const waiting = [...this.activeTurns.values()].filter((t) => !t.surfaced && t.deadlineAt > now).sort((a, b) => a.acceptedAt - b.acceptedAt);
2638
+ const waiting = [...this.activeTurns.values()].filter((t) => !t.surfaced && (t.deadlineAt === undefined || t.deadlineAt > now) && this.offerable(t)).sort((a, b) => a.acceptedAt - b.acceptedAt);
2550
2639
  if (!waiting.length)
2551
2640
  return undefined;
2641
+ // A once seat holds its task and nothing else (the manager refuses it any other turn).
2642
+ const once = waiting.find((t) => t.once !== undefined);
2643
+ if (once !== undefined)
2644
+ return { text: renderOnceTask({ goalId: once.goalId, payload: once.payload, spawner: once.once?.spawner, deadlineAt: once.deadlineAt }), goalIds: [once.goalId], once: true };
2552
2645
  const blocks = waiting.map((t) => {
2553
2646
  let context = t.payload;
2554
2647
  let ask = "";
@@ -2559,7 +2652,7 @@ export class MeshAgent extends EventEmitter {
2559
2652
  ask = renderAskRequest(p);
2560
2653
  }
2561
2654
  catch { /* opaque payload — surface it as it came */ }
2562
- return `— turn ${t.goalId} (deadline ${new Date(t.deadlineAt).toISOString()}):\n${context}${ask}`;
2655
+ return `— turn ${t.goalId}${t.deadlineAt !== undefined ? ` (deadline ${new Date(t.deadlineAt).toISOString()})` : ""}:\n${context}${ask}`;
2563
2656
  });
2564
2657
  const text = `🎯 Cotal — a run handed you ${waiting.length === 1 ? "its turn" : `${waiting.length} turns`}:\n` +
2565
2658
  `${blocks.join("\n")}\n` +
@@ -2575,10 +2668,90 @@ export class MeshAgent extends EventEmitter {
2575
2668
  return;
2576
2669
  for (const id of goalIds) {
2577
2670
  const t = this.activeTurns.get(id);
2671
+ // A sealed once task is not surfaced: its handoff ended unconfirmed and has been reported.
2672
+ if (t?.once !== undefined && !confirmOnceHandoff(this.onceUid(), id))
2673
+ continue;
2578
2674
  if (t)
2579
2675
  t.surfaced = true;
2580
2676
  }
2581
2677
  }
2678
+ /** Take the permit to hand these turns to the harness, at the dispatch site, after every gate
2679
+ * that can return without sending and right before the native send, with no await between. All
2680
+ * or nothing for the once task among them: false means another caller holds it or its handoff
2681
+ * already ended, and the caller sends no once task. Run turns need no permit and are offered
2682
+ * again as before. */
2683
+ claimTurns(goalIds) {
2684
+ // A once task settled since the caller's peek is still a once task: its handoff has ended, and
2685
+ // it takes no permit.
2686
+ return claimOnceHandoff(this.onceUid(), goalIds.filter((id) => (this.activeTurns.get(id) ?? this.settledTurns.get(id))?.once !== undefined));
2687
+ }
2688
+ /** The adapter gave up on a dispatch that carried these turns. A claimed once task is sealed and
2689
+ * reported to the manager; it is never offered again, because the harness may have it. */
2690
+ releaseTurns(goalIds) {
2691
+ for (const id of goalIds) {
2692
+ if (this.activeTurns.get(id)?.once === undefined)
2693
+ continue;
2694
+ if (sealOnceHandoff(this.onceUid(), id))
2695
+ void this.reportUnconfirmed(id);
2696
+ }
2697
+ }
2698
+ /** The dispatch carrying these turns left the seat, and its acceptance arrives with the model's
2699
+ * response: stop the once task's handoff timer, which measures the dispatch only. */
2700
+ noteTurnsDispatched(goalIds) {
2701
+ for (const id of goalIds)
2702
+ if (this.activeTurns.get(id)?.once !== undefined)
2703
+ stopOnceHandoffTimer(this.onceUid(), id);
2704
+ }
2705
+ /** Seal and report a once task still unclaimed {@link ONCE_HANDOFF_MS} after this seat pulled it. */
2706
+ boundOnceClaim(goalId) {
2707
+ const timer = setTimeout(() => {
2708
+ if (!this.activeTurns.has(goalId) || onceHandoffState(this.onceUid(), goalId) !== "pending")
2709
+ return;
2710
+ this.log(`once task ${goalId}: pulled ${ONCE_HANDOFF_MS}ms ago and never handed to the session; reporting it unconfirmed`);
2711
+ if (this.claimTurns([goalId]))
2712
+ this.releaseTurns([goalId]);
2713
+ }, ONCE_HANDOFF_MS);
2714
+ timer.unref?.();
2715
+ }
2716
+ /** A turn the harness may be handed: any run turn, and a once task whose handoff has not begun. */
2717
+ offerable(t) {
2718
+ return t.once === undefined || onceHandoffState(this.onceUid(), t.goalId) === "pending";
2719
+ }
2720
+ /** The key a once task's handoff state is kept under in this process. */
2721
+ onceUid() {
2722
+ return this.config.lifecycleUid ?? this.config.name;
2723
+ }
2724
+ /** Tell the manager a once task's handoff was not confirmed (`turn-unconfirmed`), so it fails the
2725
+ * task and stops this seat. Retried with backoff for one handoff bound while the manager cannot
2726
+ * be reached; any answer that is not transient ends the retry. A report that has not landed by
2727
+ * then ends this seat instead, and the manager's proof of that exit settles the task. A seat that
2728
+ * cannot end itself keeps reporting, at most a minute apart, until a manager answers or this
2729
+ * process ends. */
2730
+ async reportUnconfirmed(goalId) {
2731
+ const until = Date.now() + ONCE_HANDOFF_MS;
2732
+ let delay = 1_000;
2733
+ let exitTried = false;
2734
+ for (;;) {
2735
+ const r = await this.managerInvoke("turn-unconfirmed", { goalId }, { target: { mode: "self" } })
2736
+ .catch((e) => ({ ok: false, error: e.message, code: undefined }));
2737
+ const transient = !r.ok && (r.code === undefined || r.code === "unavailable" || r.code === "deadline-exceeded");
2738
+ if (!transient) {
2739
+ this.log(`once task ${goalId}: its handoff was not confirmed; reported to the manager (${r.ok ? "the task failed" : r.error ?? "refused"})`);
2740
+ return;
2741
+ }
2742
+ if (!exitTried && Date.now() + delay > until) {
2743
+ exitTried = true;
2744
+ this.log(`once task ${goalId}: its handoff was not confirmed and the manager could not be told; ending this seat so its exit settles the task`);
2745
+ if (await exitOnceSeat())
2746
+ return;
2747
+ this.log(`once task ${goalId}: this seat cannot end itself; reporting until a manager answers`);
2748
+ }
2749
+ if (this._stopping)
2750
+ return;
2751
+ await new Promise((resolve) => setTimeout(resolve, delay));
2752
+ delay = Math.min(delay * 2, exitTried ? 60_000 : 10_000);
2753
+ }
2754
+ }
2582
2755
  /** Yield one active turn back to the run (`turn-yield`, self-mode). Without `turn` it targets
2583
2756
  * the OLDEST surfaced turn — the one the current session turn is working on. The entry is
2584
2757
  * dropped locally only when the manager's answer settles it, by this yield or by a terminal
@@ -2598,9 +2771,9 @@ export class MeshAgent extends EventEmitter {
2598
2771
  : [...this.activeTurns.values()].filter((x) => x.surfaced).sort((a, b) => a.acceptedAt - b.acceptedAt)[0];
2599
2772
  if (!t) {
2600
2773
  const id = opts.turn ?? [...this.settledTurns.keys()].at(-1);
2601
- const deadlineAt = id === undefined ? undefined : this.settledTurns.get(id);
2602
- if (id !== undefined && deadlineAt !== undefined)
2603
- return { ok: false, error: settledTurnError(id, deadlineAt) };
2774
+ const settled = id === undefined ? undefined : this.settledTurns.get(id);
2775
+ if (id !== undefined && settled !== undefined)
2776
+ return { ok: false, error: settledTurnError(id, settled) };
2604
2777
  return { ok: false, error: opts.turn !== undefined ? `no active turn "${opts.turn}" on this seat` : "no turn is active — nothing to yield" };
2605
2778
  }
2606
2779
  // The surfaced gate holds for an explicit id too: a yield for a payload the session has not
@@ -2617,7 +2790,7 @@ export class MeshAgent extends EventEmitter {
2617
2790
  // only `succeeded` is a yield that landed.
2618
2791
  if (r.data?.state !== "succeeded") {
2619
2792
  this.settleTurn(t);
2620
- return { ok: false, error: settledTurnError(t.goalId, t.deadlineAt) };
2793
+ return { ok: false, error: settledTurnError(t.goalId, t) };
2621
2794
  }
2622
2795
  this.activeTurns.delete(t.goalId);
2623
2796
  // A poll that ran while this yield was in flight saw the turn gone and took it for the run's
@@ -2627,8 +2800,11 @@ export class MeshAgent extends EventEmitter {
2627
2800
  }
2628
2801
  /** Drop an active turn the run settled without this seat's yield, remembering its deadline. */
2629
2802
  settleTurn(t) {
2803
+ // A once task settled without this seat (its deadline, or a stop) ends its handoff too.
2804
+ if (t.once !== undefined)
2805
+ endOnceHandoff(this.onceUid(), t.goalId);
2630
2806
  this.activeTurns.delete(t.goalId);
2631
- this.settledTurns.set(t.goalId, t.deadlineAt);
2807
+ this.settledTurns.set(t.goalId, { ...(t.deadlineAt !== undefined ? { deadlineAt: t.deadlineAt } : {}), ...(t.once !== undefined ? { once: true } : {}) });
2632
2808
  if (this.settledTurns.size > MAX_SETTLED_TURNS)
2633
2809
  this.settledTurns.delete(this.settledTurns.keys().next().value);
2634
2810
  }
@@ -2948,7 +3124,9 @@ export class MeshAgent extends EventEmitter {
2948
3124
  }
2949
3125
  /** Discoverable channel list: every channel with traffic or a registry entry, tagged with
2950
3126
  * its one-line description, replay policy, and whether WE are subscribed (self only — never
2951
- * other peers' membership). The companion to cotal_join. */
3127
+ * other peers' membership). The companion to cotal_join. Each pattern WE follow is a row too,
3128
+ * marked `follow`: a family (`team.>`) with the health of its own stored copies, any other pattern
3129
+ * as live only. */
2952
3130
  async listChannels() {
2953
3131
  const mine = this.ep.joinedChannels();
2954
3132
  const pending = this.ep.pendingDurableLeaves();
@@ -2990,18 +3168,19 @@ export class MeshAgent extends EventEmitter {
2990
3168
  // be established (the reader lacks the grant, or the responder errored) renders "unknown",
2991
3169
  // distinct from the degraded of a daemon that answered but holds no membership for this owner —
2992
3170
  // and from the undefined of a channel where health does not apply (not durable-class, not
2993
- // joined, open mode).
2994
- const health = (channel, joined) => joined && this.ep.channelDeliveryClass(channel) === "durable"
2995
- ? !leaseReadable
2996
- ? "unknown"
2997
- : daemonMemberships === undefined
2998
- ? "degraded"
2999
- : daemonMemberships.some((m) => m.channel === channel) && leaseLive
3000
- ? "active"
3001
- : "degraded"
3002
- : undefined;
3171
+ // joined, open mode). A channel or family is held by its own row or a family row above it (#5404),
3172
+ // since that family's stored copies cover it.
3173
+ const held = (channel) => !leaseReadable
3174
+ ? "unknown"
3175
+ : daemonMemberships !== undefined && leaseLive && daemonMemberships.some((m) => m.channel === channel || (isChannelFamily(m.channel) && subjectMatches(m.channel, channel)))
3176
+ ? "active"
3177
+ : "degraded";
3178
+ // Health applies where stored copies were asked for: the channel itself or a family over it. A
3179
+ // channel read only through a pattern with * or the root > is live only and has none.
3180
+ const health = (channel, stored) => stored && this.ep.channelDeliveryClass(channel) === "durable" ? held(channel) : undefined;
3003
3181
  const rows = (await this.ep.listChannels()).map((c) => {
3004
3182
  const joined = mine.some((p) => subjectMatches(p, c.channel));
3183
+ const stored = mine.some((p) => p === c.channel || (isChannelFamily(p) && subjectMatches(p, c.channel)));
3005
3184
  return {
3006
3185
  channel: c.channel,
3007
3186
  description: c.config?.description,
@@ -3010,12 +3189,27 @@ export class MeshAgent extends EventEmitter {
3010
3189
  // A live sub was refused while a Plane-3 durable membership stayed open; its §7 tombstone is
3011
3190
  // still retrying. Surface it so the channel is never shown as ordinary "not subscribed" (ux).
3012
3191
  durableUnclosed: unclosed.has(c.channel),
3013
- deliveryHealth: health(c.channel, joined),
3192
+ deliveryHealth: health(c.channel, stored),
3014
3193
  messages: c.messages,
3015
3194
  mode: this.channelMode(c.channel) ?? "normal",
3016
3195
  event: this.eventChannelOf(c.channel),
3017
3196
  };
3018
3197
  });
3198
+ for (const pattern of mine) {
3199
+ if (isConcreteChannel(pattern))
3200
+ continue;
3201
+ const family = isChannelFamily(pattern);
3202
+ rows.push({
3203
+ channel: pattern,
3204
+ replay: this.ep.channelReplay(pattern),
3205
+ joined: true,
3206
+ durableUnclosed: unclosed.has(pattern),
3207
+ deliveryHealth: family ? held(pattern) : undefined,
3208
+ messages: 0,
3209
+ mode: "normal",
3210
+ follow: family ? "family" : "live",
3211
+ });
3212
+ }
3019
3213
  // A channel in refused-sub durable cleanup can have NO traffic AND no registry entry, so listChannels()
3020
3214
  // omits it — UNION it in so the durable-unclosed state can never disappear by omission (ux/security).
3021
3215
  const present = new Set(rows.map((r) => r.channel));
@@ -3032,6 +3226,7 @@ export class MeshAgent extends EventEmitter {
3032
3226
  messages: 0,
3033
3227
  mode: this.channelMode(ch) ?? "normal",
3034
3228
  event: this.eventChannelOf(ch),
3229
+ ...(isChannelFamily(ch) ? { follow: "family" } : {}),
3035
3230
  });
3036
3231
  }
3037
3232
  return rows;