@nanmicoder/dsh-agent-teams 0.1.22 → 0.1.24-rc.1

package/lib/command.js

@@ -1,4 +1,5 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { agentTeamsSource } from "./harness-compat.js";
 import { parseProfileInvocation, resolveProfileTaskPlanning } from "./profiles.js";
 export const AGENT_TEAMS_COMMAND = 'agent-teams';
 const PROFILE_COMMAND_PREFIX = `${AGENT_TEAMS_COMMAND}-`;
@@ -125,7 +126,7 @@ export function installAgentTeamsGestureBoundary(ctx, getProfiles = () => ({}))
             invocation = invokedAgentTeamsInvocation(messages, getProfiles);
         }
         catch (error) {
-            return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text: `AgentTeams profile parsing failed: ${String(error)}` }], source: { kind: 'agent-teams-command' } })] };
+            return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text: `AgentTeams profile parsing failed: ${String(error)}` }], source: agentTeamsSource({ kind: 'agent-teams-command' }) })] };
         }
         if (invocation === undefined)
             return decision;
@@ -138,6 +139,6 @@ export function installAgentTeamsGestureBoundary(ctx, getProfiles = () => ({}))
         const text = !known
             ? `AgentTeams profile "${invocation.profile}" does not exist. Available profiles: ${Object.keys(profiles).join(', ') || '(none)'}. Do not create a team.`
             : buildActivationDirective(invocation.goal, invocation.profile, resolveProfileTaskPlanning(matched?.[1]));
-        return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'agent-teams-command', ...invocation.goal === '' ? {} : { goal: invocation.goal }, ...invocation.profile === undefined ? {} : { profile: invocation.profile } } })] };
+        return { kind: 'enter', messages: [...decision.messages, createUserMessage({ content: [{ type: 'text', text }], source: agentTeamsSource({ kind: 'agent-teams-command', ...invocation.goal === '' ? {} : { goal: invocation.goal }, ...invocation.profile === undefined ? {} : { profile: invocation.profile } }) })] };
     });
 }

package/lib/git-artifact-stamp.json

@@ -1,5 +1,5 @@
 {
   "schema": 1,
-  "source": "c90a0becc42c4a394f223739e76e01c8c4b6ba4dd1700e08cb65c81949a1f33c",
-  "output": "1373527d718f862f5fae89f40dc6bd3347cef086159d596ff2519c5f5182bd4b"
+  "source": "983fb392dfa483a3095fd1e7ad67bfd5786d467c77244865d22e7ca7b046e2ad",
+  "output": "bb2031aa6d907a929ad81d99ab74f6f2c2136ce1f3a1e9bb68006453bff43908"
 }

package/lib/harness-compat.js

@@ -1,6 +1,7 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import * as dshSession from '@deepseek-ai/dsh-session';
 import { SubagentError } from '@deepseek-ai/dsh-subagent';
-import { CAPTAIN_TOOL_NAMES } from "./tool-names.js";
+import { BUILTIN_DENY_TOOLS, resolveMemberToolFilter } from "./tool-policies.js";
 /**
  * Exact protocol exported by dsh-subagent/internal in Alpha.5 and rc.1.
  * That subpath does not exist in Alpha.2, so importing it statically prevents
@@ -12,12 +13,95 @@ const hostPromptQueue = Symbol.for('dsh.subagent.queuePrompt');
 // 0.1.5 keeps queueHostSubagentPrompt but replaces its symbol with this
 // delivery-mode-aware implementation (packages/subagent/subagent/src/internal.ts).
 const hostPromptDeliver = Symbol.for('dsh.subagent.deliverPrompt');
+export function usesManagedActivations(runtime) {
+    return typeof runtime.startActivation === 'function';
+}
+export async function startMember(runtime, spec) {
+    const host = runtime;
+    if (typeof host.startActivation === 'function') {
+        const { persona: _persona, toolFilter: _filter, ...request } = spec.request;
+        const activation = await host.startActivation.call(runtime, { ...spec, request, delivery: 'parent' });
+        // Preserve native settlement as the missing-report/error fallback on both
+        // fresh and resumed activations. mailbox.ts deduplicates successful reports.
+        void activation.result.catch(() => undefined);
+        return activation;
+    }
+    if (typeof host.startContinuable !== 'function')
+        return unsupported('missing member creation API');
+    return host.startContinuable.call(runtime, spec);
+}
+/** Wrap every available creation API, restoring only this plugin's own methods. */
+export function guardSubagentCreation(ctx, check) {
+    const runtime = ctx.subagents;
+    ctx.effect(() => {
+        const disposers = [];
+        for (const key of ['start', 'startContinuable', 'startActivation']) {
+            const original = runtime[key];
+            if (typeof original !== 'function')
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(runtime, key);
+            const guarded = async (...args) => {
+                const request = key === 'start' ? args[1] : args[0].request;
+                check(request.parent);
+                return Reflect.apply(original, ctx.subagents, args);
+            };
+            Object.defineProperty(runtime, key, { value: guarded, writable: true, configurable: true });
+            disposers.push(() => {
+                if (Object.getOwnPropertyDescriptor(runtime, key)?.value !== guarded)
+                    return;
+                if (descriptor === undefined)
+                    Reflect.deleteProperty(runtime, key);
+                else
+                    Object.defineProperty(runtime, key, descriptor);
+            });
+        }
+        return () => { for (const dispose of disposers)
+            dispose(); };
+    }, 'agent-teams: member delegation budget');
+}
 function boundary(runtime) {
     return runtime;
 }
 function unsupported(detail) {
     throw new Error(`agent-teams: unsupported Harness subagent contract (${detail}); use an explicitly tested Harness version and a coherent dependency installation`);
 }
+/** Package identity a released plugin-wrapper source names on older hosts. */
+export const AGENT_TEAMS_PLUGIN_NAME = '@nanmicoder/dsh-agent-teams';
+/**
+ * First stored format generation whose migration edges admit producer-owned
+ * source kinds. The released v2→v3 payload audit validates every message source
+ * against a closed list of released kinds, so a stored format older than this
+ * must carry a released source or the whole session becomes unreadable once a
+ * newer host opens it (#160).
+ */
+export const RELEASED_SOURCE_VOCABULARY_VERSION = 3;
+/** Stored session format generation of the running host; 0 when it exposes none. */
+export function hostSessionFormatVersion() {
+    const version = dshSession.SESSION_FORMAT_VERSION;
+    return typeof version === 'number' && Number.isSafeInteger(version) && version >= 0 ? version : 0;
+}
+/**
+ * Source for one AgentTeams-authored message on the running host.
+ *
+ * Current hosts mint producer-owned kinds: the Harness documents message
+ * sources as a merge-extensible vocabulary without a catch-all, so this plugin
+ * declares its own. Hosts that still store a pre-v3 generation are a different
+ * contract — their released v2→v3 migration rejects any source outside the
+ * released vocabulary, which is exactly how a plugin kind written on an older
+ * supported host poisons its session log for every later host. On those hosts
+ * the released plugin wrapper is used instead; the goal and profile already
+ * travel in the message text.
+ * @param modern - the producer-owned source to use where the host admits it.
+ * @returns a source accepted by the running host and by its migration chain.
+ */
+export function agentTeamsSource(modern) {
+    if (hostSessionFormatVersion() >= RELEASED_SOURCE_VOCABULARY_VERSION)
+        return modern;
+    // Released-format hosts persist plugin-authored messages as this wrapper; the
+    // current vocabulary retired it, so the cast stays confined to this branch
+    // and `modern` is the only shape a current host ever sees.
+    return { kind: 'plugin', plugin: AGENT_TEAMS_PLUGIN_NAME };
+}
 /**
  * 0.1.6 moved startup admission to serial agent/created. Older created events
  * have no source and precede session-start; ignore those until the old hook.
@@ -63,7 +147,7 @@ export function installContinuableMemberSetup(ctx, setup) {
     const installed = new WeakSet();
     const active = new Set();
     ctx.effect(() => {
-        const stop = onAgentReady(ctx, (agent, vetoable) => {
+        const attach = (agent, vetoable) => {
             if (installed.has(agent))
                 return;
             // Deliberately synchronous: awaiting here loses the first-request race.
@@ -101,18 +185,30 @@ export function installContinuableMemberSetup(ctx, setup) {
                 dispose();
                 throw error;
             }
-        });
-        return () => {
+        };
+        const stop = onAgentReady(ctx, attach);
+        const cleanup = () => {
             stop();
             for (const dispose of [...active])
                 dispose();
         };
+        try {
+            // Reloads keep Agents alive but dispose the previous plugin's setup.
+            // Subscribe first, then hydrate the live registry; attach is idempotent.
+            for (const agent of ctx.agents.list())
+                attach(agent, false);
+        }
+        catch (error) {
+            cleanup();
+            throw error;
+        }
+        return cleanup;
     }, 'agent-teams: member lifecycle compatibility');
 }
 /** Queue a distinct host-authored turn; never substitute model-message steer. */
 export async function queueMemberPrompt(runtime, parent, childId, content, signal) {
     const host = boundary(runtime);
-    const source = { kind: 'agent-teams' };
+    const source = agentTeamsSource({ kind: 'agent-teams' });
     if (typeof host.followup === 'function') {
         return host.followup.call(runtime, parent, childId, content, { source, signal });
     }
@@ -127,7 +223,7 @@ export async function queueMemberPrompt(runtime, parent, childId, content, signa
 /** Coordination joins the nearest step, including waking an idle/cold child. */
 export async function steerMemberPrompt(runtime, parent, childId, content, signal, live) {
     const host = boundary(runtime);
-    const source = { kind: 'agent-teams' };
+    const source = agentTeamsSource({ kind: 'agent-teams' });
     const deliver = host[hostPromptDeliver];
     if (typeof deliver === 'function')
         return deliver.call(runtime, parent, childId, content, source, signal, 'steer');
@@ -247,15 +343,12 @@ export function restrictableToolNames(agent) {
  * forwarding a name the host dropped aborts every member spawn (#163, #164).
  * Depth enforcement itself does not depend on these names —
  * installMemberDelegationGuard bounds descendant creation by parent chain.
+ *
+ * This is the legacy filter of a member without a configured tool policy; a
+ * selected policy resolves through `resolveMemberToolFilter` instead (#59).
  */
 export function memberToolFilter(maxDepth, knownTools) {
-    const depthDeny = maxDepth === 0 ? ['subagent', 'send_message'] : [];
-    return {
-        deny: [
-            ...CAPTAIN_TOOL_NAMES,
-            ...(knownTools === undefined ? depthDeny : depthDeny.filter(name => knownTools.has(name))),
-        ],
-    };
+    return resolveMemberToolFilter(undefined, { maxDepth, knownTools });
 }
 /**
  * Names a `tools.restrict()` rejection reported as unknown, or an empty list
@@ -270,33 +363,55 @@ function unknownToolNames(error) {
     return [...message.matchAll(/"([^"]+)"/g)].map(match => match[1]);
 }
 /**
- * Start one member, dropping any filter name the host reports as unknown and
- * retrying.
+ * Start one member, dropping only the built-in filter names the host reports
+ * as unknown and retrying.
  *
  * Resolving the filter against the registry view ({@link memberToolFilter})
  * only covers hosts that expose one. A rejected filter still leaves the member
  * without a session for the lifetime of the team, so the start must survive the
  * cases that resolution cannot see — no registry view, a name that is known but
  * not restrictable, a composition that mounted differently than expected. The
- * host names the offenders in its rejection, so they are removed and the start
- * retried; the retry only runs while the deny list strictly shrinks, and any
- * failure that is not an unknown-name report propagates untouched.
+ * host names the offenders in its rejection, so the relaxable ones are removed
+ * and the start retried.
+ *
+ * Only `relaxableDeny` names may be dropped, and only from `deny`. The default
+ * is exactly the built-in captain-only and depth entries (#163/#164); a name an
+ * owner-declared tool policy contributed is never removed, because silently
+ * spawning a member with a different filter than the owner declared is contract
+ * drift, not recovery. Dropping a denied name the host does not register
+ * changes nothing; dropping an allowed name would loosen the policy, so `allow`
+ * is never relaxed and the four required coordination tools can never be
+ * removed.
  * @param start - performs one start attempt for the given `toolFilter`.
  * @param filter - the filter to attempt first.
+ * @param relaxableDeny - built-in deny names the retry may drop.
  * @returns the started member.
  */
-export async function startMemberWithLenientFilter(start, filter) {
-    let deny = [...filter.deny];
+export async function startMemberWithLenientFilter(start, filter, relaxableDeny = BUILTIN_DENY_TOOLS) {
+    const current = {
+        ...filter.allow === undefined ? {} : { allow: [...filter.allow] },
+        deny: [...filter.deny],
+    };
     for (;;) {
         try {
-            return await start({ deny });
+            return await start(current);
         }
         catch (error) {
             const unknown = unknownToolNames(error);
-            const remaining = deny.filter(name => !unknown.includes(name));
-            if (unknown.length === 0 || remaining.length === deny.length)
+            if (unknown.length === 0)
+                throw error;
+            const droppable = unknown.filter(name => relaxableDeny.includes(name) && current.deny.includes(name));
+            if (droppable.length === 0)
                 throw error;
-            deny = remaining;
+            current.deny = current.deny.filter(name => !droppable.includes(name));
         }
     }
 }
+/** Targeted recursive cancellation renamed with the unified activation manager. */
+export async function drainMemberChildren(runtime, parent, ids) {
+    const host = runtime;
+    const drain = host.drainChildren ?? host.drainContinuableChildren;
+    if (typeof drain !== 'function')
+        return unsupported('missing targeted child drain');
+    await drain.call(runtime, parent, ids);
+}

package/lib/index.js

@@ -27,7 +27,9 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { collectArchivedTeamsActivity, collectTeamsActivity } from "./snapshot.js";
 import { findTeamByCaptain } from "./state.js";
+import { leadIdentityOfAsync } from "./lineage.js";
 import { formatProfilesForPrompt } from "./profiles.js";
+import { parseToolPolicies } from "./tool-policies.js";
 import { installTeamCapabilities } from "./capabilities.js";
 import { TEAM_TOOL_NAMES } from "./tool-names.js";
 import { authenticatedWebRoutes, readJsonRequest, RequestBodyError } from "./web-routes.js";
@@ -44,10 +46,20 @@ const fallbackRouteConfig = z.union([
     z.object({ provider: z.string().required(), model: z.string().required() }),
     z.const(undefined),
 ]);
+// Same Schemastery defaulting trap for a tool policy: an `allow`-only policy
+// would materialize `deny: []` and fail a `.min(1)` on an absent list. Model
+// each accepted combination explicitly, so a policy that declares only one
+// side stays valid while an empty side is still rejected.
+const toolPolicyConfig = z.union([
+    z.object({ allow: z.array(z.string()).min(1).required(), deny: z.const(undefined) }),
+    z.object({ allow: z.const(undefined), deny: z.array(z.string()).min(1).required() }),
+    z.object({ allow: z.array(z.string()).min(1).required(), deny: z.array(z.string()).min(1).required() }),
+]);
 export const Config = z.object({
     stateDir: z.string().default('.agent-teams'),
     memberProvider: z.string().default('spawn'),
     memberModel: z.string(),
+    memberLlmProvider: z.string(),
     executionPrompt: z.string(),
     fallback: fallbackRouteConfig,
     profiles: z.dict(z.object({
@@ -63,6 +75,8 @@ export const Config = z.object({
             reasoning_effort: z.string(),
             executionPrompt: z.string(),
             fallback: fallbackRouteConfig,
+            // Owner-declared tool-policy id this profile member selects (#59).
+            tool_policy: z.string(),
         })).min(1).required(),
         taskPlanning: z.union([z.const('captain'), z.const('seed')]),
         reviewPolicy: z.object({
@@ -80,6 +94,7 @@ export const Config = z.object({
             dependencies: z.array(z.string()),
         })),
     })).default({}),
+    toolPolicies: z.dict(toolPolicyConfig).default({}),
     memberMaxDepth: z.natural().default(0),
     maxMembers: z.natural().min(1).default(8),
     promptSectionOrder: z.natural().default(117),
@@ -89,7 +104,7 @@ export const Config = z.object({
 export function usageSectionText(toolNames, profilesText = '') {
     return `AgentTeams captain protocol:
 1. Inspect current team state when needed, using agent_teams_status. Continue existing work without duplicating its roster/tasks. Create only when no current team exists, with the user's goal as description and approval="required"; automatic approval requires an explicit request to run immediately. Staged plans never spawn or schedule work.
-2. Add each needed role once; members inherit your model route unless another is requested/needed. A requested profile goes to create({profile}); it supplies its roster. Seed profiles also supply tasks; captain-planning profiles require your DAG. Do not duplicate either.
+2. Add each needed role once; members inherit your model route unless another is requested/needed. A requested profile goes to create({profile}); it supplies its roster. Seed profiles also supply tasks; captain-planning profiles require your DAG. Do not duplicate either. A member may also select one owner-declared tool policy by id (tool_policy on add_member, a plan member, or a profile member): it is the only way to change which global tools that member sees and may invoke, and you can never pass raw allow/deny lists.
 3. Build the complete smallest useful DAG while staged. For an ordinary research/audit plan, pass the roster and dependency graph together in create({plan:{members,tasks}}) to avoid repeated setup rounds. Every task needs a subject; pass kind and assignee explicitly when the plan specifies them. Titles, descriptions and member roles do not set these fields. Dependencies represent prerequisites. Give every required contributor a task or explicit message. Present the plan and end your turn for review; never approve in that planning turn. Approve only after a later explicit user approval or the Web action.
 4. Respect Web approve/return/discard control messages. On return, ask what to change before editing; after the answer, use one atomic agent_teams_edit_plan batch (edit downstream references before removals), summarize and await review again. Never inspect or edit .agent-teams state files or plugin source code to revise plans. Discard does not authorize a replacement.
 5. The scheduler dispatches ready tasks after approval. Delegate; do not duplicate slow work or send messages merely to start a stage. Handle reports/user work, then yield when waiting is all that remains: reports wake you automatically. Use status after a delivery or user request, never busy-poll or wait for unassigned members.
@@ -105,11 +120,15 @@ export function apply(ctx, config) {
         stateDir: config.stateDir ?? '.agent-teams',
         memberProvider: config.memberProvider ?? 'spawn',
         memberModel: config.memberModel,
+        memberLlmProvider: config.memberLlmProvider,
         executionPrompt: config.executionPrompt,
         fallback: config.fallback,
         memberMaxDepth: config.memberMaxDepth ?? 0,
         maxMembers: config.maxMembers ?? 8,
         profiles: config.profiles ?? {},
+        // Owner configuration is validated once, at mount: an empty or malformed
+        // policy must never reach a member creation path.
+        toolPolicies: parseToolPolicies(config.toolPolicies),
     };
     // Provider registration is a sibling plugin's effect (`subagent-spawn` /
     // `subagent-fork` rows), which can land after this mount under the Loader's
@@ -166,6 +185,9 @@ export function apply(ctx, config) {
                 const url = new URL(req.url ?? '/', 'http://x');
                 const roots = workspaceRegistry.list().map((workspace) => ({
                     workspace: workspace.title,
+                    // The panel audits the same current bytes as agent_teams_status, so it
+                    // cannot advertise a passing gate over a changed revision (#161).
+                    workspacePath: workspace.path,
                     stateRoot: join(workspace.path, resolved.stateDir),
                 }));
                 // ?archived=1 serves teams moved to archive/ (post-delete review).
@@ -213,7 +235,7 @@ export function apply(ctx, config) {
                 }
                 const workspace = captain.session.header.cwd ?? process.cwd();
                 const stateRoot = join(workspace, resolved.stateDir);
-                const team = await findTeamByCaptain(stateRoot, captain.id);
+                const team = await findTeamByCaptain(stateRoot, captain.id, await leadIdentityOfAsync(ctx, captain.session));
                 if (team === undefined || team.id !== teamId) {
                     res.writeHead(404, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
                     res.end(JSON.stringify({ error: 'team not found for this captain' }));
@@ -270,7 +292,7 @@ export function apply(ctx, config) {
                 }
                 const workspace = captain.session.header.cwd ?? process.cwd();
                 const stateRoot = join(workspace, resolved.stateDir);
-                const team = await findTeamByCaptain(stateRoot, captain.id);
+                const team = await findTeamByCaptain(stateRoot, captain.id, await leadIdentityOfAsync(ctx, captain.session));
                 if (team === undefined || team.id !== teamId) {
                     res.writeHead(404, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
                     res.end(JSON.stringify({ error: 'team not found for this captain' }));
@@ -330,6 +352,7 @@ export function apply(ctx, config) {
                             ...typeof payload['executionPrompt'] === 'string' || payload['executionPrompt'] === null
                                 ? { executionPrompt: payload['executionPrompt'] }
                                 : {},
+                            ...typeof payload['tool_policy'] === 'string' ? { toolPolicy: payload['tool_policy'] } : {},
                         };
                     }
                     else if (action === 'update_task') {

package/lib/lineage.js

@@ -0,0 +1,198 @@
+/** Maximum fork-chain depth resolved for one identity (cycle- and length-bounded). */
+export const LINEAGE_MAX_DEPTH = 32;
+/**
+ * Official optional service access. `ctx.get` is the reflection accessor for a
+ * service a plugin does not declare in `inject`; a missing service yields
+ * `undefined` instead of a contract error, and a getter that still refuses is
+ * contained here.
+ */
+function optionalService(ctx, name) {
+    const get = ctx.get;
+    if (typeof get !== 'function')
+        return undefined;
+    try {
+        return get.call(ctx, name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Ancestry this process already resolved for one session. */
+const ancestryCache = new Map();
+/** The live session for one id: resident agent first, then the live session store. */
+export function liveSession(ctx, id) {
+    const branded = id;
+    const agent = ctx.agents.get(branded);
+    if (agent !== undefined)
+        return agent.session;
+    return optionalService(ctx, 'sessions')?.get?.(branded);
+}
+/** Whether one session is a top-level conversation rather than a subagent child. */
+export function isTopLevelSession(session) {
+    return session.header.origin !== 'subagent' && (session.header.delegationDepth ?? 0) === 0;
+}
+/** Durable parent of one session id: the live header, else the stored header. */
+async function durableParent(ctx, id) {
+    const live = liveSession(ctx, id);
+    if (live !== undefined)
+        return live.header.parentSession;
+    const persistence = optionalService(ctx, 'sessionPersistence');
+    try {
+        const snapshot = await persistence?.stat?.(id);
+        const parent = snapshot?.header?.parentSession;
+        return parent;
+    }
+    catch {
+        // Unreadable stored metadata ends this chain; authorization then fails
+        // closed on the identity the caller itself provides.
+        return undefined;
+    }
+}
+/**
+ * Durable ancestry of one session, nearest first. The calling session's own
+ * header supplies the first hop; later hops come from resident sessions or
+ * stored headers, so a fork resolves through sessions that are not loaded.
+ * @param ctx - the plugin context (injects `agents`).
+ * @param session - the calling session.
+ * @returns ancestor session ids, bounded by {@link LINEAGE_MAX_DEPTH}.
+ */
+export async function resolveAncestry(ctx, session) {
+    const ancestry = [];
+    const seen = new Set([session.id]);
+    let parent = session.header.parentSession;
+    while (parent !== undefined && ancestry.length < LINEAGE_MAX_DEPTH && !seen.has(parent)) {
+        seen.add(parent);
+        ancestry.push(parent);
+        parent = await durableParent(ctx, parent);
+    }
+    ancestryCache.set(session.id, ancestry);
+    return ancestry;
+}
+/**
+ * Ancestry resolvable without awaiting: the calling session's durable first
+ * hop, then resident sessions, then whatever the async resolver cached.
+ */
+export function sessionAncestry(ctx, session) {
+    const cached = ancestryCache.get(session.id);
+    if (cached !== undefined)
+        return cached;
+    const ancestry = [];
+    const seen = new Set([session.id]);
+    let parent = session.header.parentSession;
+    while (parent !== undefined && ancestry.length < LINEAGE_MAX_DEPTH && !seen.has(parent)) {
+        seen.add(parent);
+        ancestry.push(parent);
+        parent = liveSession(ctx, parent)?.header.parentSession;
+    }
+    return ancestry;
+}
+/** Resolve one session's lead identity synchronously (prompt-assembly path). */
+export function leadIdentityOf(ctx, session) {
+    return {
+        sessionId: session.id,
+        ancestry: sessionAncestry(ctx, session),
+        inheritsLead: isTopLevelSession(session),
+    };
+}
+/** Resolve one session's lead identity durably (authorization paths). */
+export async function leadIdentityOfAsync(ctx, session) {
+    return {
+        sessionId: session.id,
+        ancestry: await resolveAncestry(ctx, session),
+        inheritsLead: isTopLevelSession(session),
+    };
+}
+/** Whether one identity leads (or inherits the lead of) a team's recorded captain. */
+export function teamLeadMatch(team, lead) {
+    const members = team.members ?? [];
+    // A listed member is never a lead, retired or not: a member session is a
+    // subagent child of its captain, so its parent chain contains the captain id
+    // too, and membership revocation must never hand that session lead authority.
+    // Member participation itself stays governed by the removed filter in the
+    // team lookups.
+    if (members.some(member => member.id === lead.sessionId))
+        return false;
+    if (team.captainSessionId === lead.sessionId)
+        return true;
+    if (!lead.inheritsLead)
+        return false;
+    // Descending from a member (a fork of one) is not lead identity either.
+    if (members.some(member => lead.ancestry.includes(member.id)))
+        return false;
+    return lead.ancestry.includes(team.captainSessionId);
+}
+/**
+ * Whether one live session id leads a team: the recorded captain itself, or a
+ * top-level fork descendant of it. Members never match through their parent
+ * chain, and a member's fork does not match either.
+ */
+export function sessionLeadsTeam(ctx, team, sessionId) {
+    if (team.members?.some(member => member.id === sessionId) === true)
+        return false;
+    if (team.captainSessionId === sessionId)
+        return true;
+    const session = liveSession(ctx, sessionId);
+    return session !== undefined && teamLeadMatch(team, leadIdentityOf(ctx, session));
+}
+/** Durable {@link sessionLeadsTeam}: resolves the caller's chain through stored headers. */
+export async function sessionLeadsTeamAsync(ctx, team, sessionId) {
+    if (team.members?.some(member => member.id === sessionId) === true)
+        return false;
+    if (team.captainSessionId === sessionId)
+        return true;
+    const session = liveSession(ctx, sessionId);
+    return session !== undefined && teamLeadMatch(team, await leadIdentityOfAsync(ctx, session));
+}
+/**
+ * Nearest live lead session of a team: the recorded captain while it is
+ * resident, otherwise the closest live fork descendant of it. Captain-directed
+ * reports use this so a human working in a fork still receives them, while the
+ * durable mail record stays addressed to the recorded captain.
+ * @param ctx - the plugin context (injects `agents`).
+ * @param team - current team state.
+ * @returns the live lead agent, or undefined when no lead session is resident.
+ */
+export function nearestLiveLead(ctx, team, live) {
+    // The recorded captain is the delivery parent whenever it is resident; a
+    // registry without `list` (or with rows the lineage cannot read) only means
+    // the fork fallback is unavailable, never that this lookup fails.
+    const exact = ctx.agents.get(team.captainSessionId);
+    if (exact !== undefined)
+        return exact;
+    let candidates;
+    try {
+        candidates = live ?? ctx.agents.list();
+    }
+    catch {
+        return undefined;
+    }
+    let best;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const agent of candidates) {
+        try {
+            const identity = leadIdentityOf(ctx, agent.session);
+            if (!teamLeadMatch(team, identity))
+                continue;
+            const distance = identity.ancestry.indexOf(team.captainSessionId);
+            if (distance < 0 || distance >= bestDistance)
+                continue;
+            best = agent;
+            bestDistance = distance;
+        }
+        catch {
+            continue;
+        }
+    }
+    return best;
+}
+/**
+ * Diagnostic note for a caller that matched no team but is a fork, so an
+ * operator can distinguish "no team exists" from "a team exists that this
+ * session does not lead".
+ */
+export function forkLineageNote(session) {
+    const parent = session.header.parentSession;
+    if (parent === undefined)
+        return '';
+    return ` (this session is a fork of ${parent}; no active team in this workspace is led by that session or by a lead session in its lineage)`;
+}