dsh-plugin-t-expert 0.1.0

package/lib/teams/scheduler.js

@@ -0,0 +1,434 @@
+/**
+ * Event-driven shared task scheduler.
+ *
+ * Claude Code teammates keep polling the shared task list after a turn. DSH
+ * continuable agents instead expose explicit idle/running edges, so this
+ * scheduler closes the same loop without keeping a polling turn alive: every
+ * idle edge and every task-graph mutation attempts one atomic claim and wakes
+ * the selected durable member. A resident member that becomes idle while it
+ * still owns an open attempt is parked: only an explicit captain reassignment
+ * may rotate that capability. Automatic retry is reserved for cold recovery,
+ * when this process has not observed the durable owner settle its open attempt.
+ * @module t-team/scheduler
+ */
+import { join } from 'node:path';
+import { deliverToMember } from "./members.js";
+import { acknowledgeMailbox, beginTaskAttempt, CAPTAIN_KEY, claimMailboxDelivery, findTeamByParticipant, invalidateTaskAttempt, readTeam, readUnreadMailbox, releaseMailboxDelivery, unsatisfiedDependencies, withTeamLock, writeTeam, } from "./state.js";
+/** Per-dependency output cap in the assignment prompt. */
+export const DEPENDENCY_OUTPUT_MAX_CHARS = 2_000;
+/** Combined dependency-output budget in the assignment prompt. */
+export const DEPENDENCY_OUTPUTS_TOTAL_MAX_CHARS = 12_000;
+function taskProfileSeedId(task) {
+    const seed = task.profileSeedId?.trim();
+    return seed === undefined || seed === '' ? undefined : seed;
+}
+function teamProfileProtocol(team) {
+    return team.profile?.protocol;
+}
+/**
+ * Recursively collect `status=completed` ancestors of `taskId` in topological
+ * order (dependencies before dependents). Cycles stop that branch only.
+ */
+export function collectCompletedDependencyOutputs(tasks, taskId, warn) {
+    const byId = new Map(tasks.map(task => [task.id, task]));
+    const visiting = new Set();
+    const visited = new Set();
+    const ordered = [];
+    const walk = (id) => {
+        if (visiting.has(id)) {
+            warn?.(`t-team: dependency cycle involving "${id}" while collecting outputs; stopping this branch`);
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        const task = byId.get(id);
+        if (task !== undefined) {
+            for (const dependency of task.dependencies)
+                walk(dependency);
+            if (id !== taskId)
+                ordered.push(task);
+        }
+        visiting.delete(id);
+        visited.add(id);
+    };
+    walk(taskId);
+    return ordered
+        .filter(task => task.status === 'completed')
+        .map((task) => {
+        const profileSeedId = taskProfileSeedId(task);
+        return {
+            id: task.id,
+            subject: task.subject,
+            ...profileSeedId === undefined ? {} : { profileSeedId },
+            ...task.output === undefined ? {} : { output: task.output },
+        };
+    });
+}
+/** Format completed-dependency outputs with per-item and total truncation. */
+export function formatDependencyOutputs(items) {
+    if (items.length === 0)
+        return '(none)';
+    const formatted = items.map((item) => {
+        const seed = item.profileSeedId === undefined ? '' : ` [${item.profileSeedId}]`;
+        const raw = item.output === undefined || item.output === ''
+            ? '(no output recorded)'
+            : item.output;
+        const truncated = raw.length > DEPENDENCY_OUTPUT_MAX_CHARS;
+        const body = truncated ? `${raw.slice(0, DEPENDENCY_OUTPUT_MAX_CHARS)} [truncated]` : raw;
+        return `- ${item.id}${seed} ${item.subject}:\n  ${body}`;
+    });
+    let selected = formatted;
+    while (selected.length > 1 && selected.join('\n').length > DEPENDENCY_OUTPUTS_TOTAL_MAX_CHARS) {
+        selected = selected.slice(1);
+    }
+    const last = selected[0];
+    if (selected.length === 1 && last !== undefined && last.length > DEPENDENCY_OUTPUTS_TOTAL_MAX_CHARS) {
+        selected = [`${last.slice(0, DEPENDENCY_OUTPUTS_TOTAL_MAX_CHARS)} [truncated]`];
+    }
+    return selected.join('\n');
+}
+function stateRootOf(workspace, config) {
+    return join(workspace, config.stateDir);
+}
+function teamLockKey(stateRoot, teamId) {
+    return `team:${stateRoot}:${teamId}`;
+}
+function liveCaptain(ctx, captainSessionId, supplied) {
+    if (supplied !== undefined && supplied.id === captainSessionId)
+        return supplied;
+    return ctx.agents.get(captainSessionId);
+}
+function liveMember(ctx, member) {
+    return ctx.agents.get(member.id);
+}
+function isMemberAvailable(ctx, member) {
+    const live = liveMember(ctx, member);
+    return live === undefined || live.status === 'idle';
+}
+function ownedOpenTask(tasks, memberName) {
+    return tasks.find(task => task.assignee === memberName
+        && (task.status === 'claimed' || task.status === 'in_progress'));
+}
+function nextReadyTask(tasks, memberName) {
+    const ready = tasks.filter(task => task.status === 'pending'
+        && task.reassigning !== true
+        && unsatisfiedDependencies([...tasks], task.dependencies).length === 0);
+    return ready.find(task => task.assignee === memberName)
+        ?? ready.find(task => task.assignee === undefined);
+}
+export function assignmentPrompt(ticket, stateDir, teamId) {
+    const description = ticket.description === undefined ? '' : `\n\n${ticket.description}`;
+    const seed = ticket.profileSeedId === undefined ? '' : ` [${ticket.profileSeedId}]`;
+    const goal = ticket.teamDescription?.trim() || '(not provided)';
+    const protocol = ticket.profileProtocol?.trim() || '(none)';
+    const executionPrompt = ticket.executionPrompt?.trim();
+    const kind = ticket.kind?.trim() || 'work';
+    const contract = [
+        `Kind: ${kind}${ticket.round === undefined ? '' : ` (round ${ticket.round})`}`,
+        ticket.objective === undefined || ticket.objective === '' ? '' : `Objective: ${ticket.objective}`,
+        ticket.inScope === undefined || ticket.inScope.length === 0 ? '' : `In scope: ${ticket.inScope.join(', ')}`,
+        ticket.outOfScope === undefined || ticket.outOfScope.length === 0 ? '' : `Out of scope: ${ticket.outOfScope.join(', ')}`,
+        ticket.acceptance === undefined || ticket.acceptance.length === 0 ? '' : `Acceptance: ${ticket.acceptance.join('; ')}`,
+        ticket.verify === undefined || ticket.verify.length === 0 ? '' : `Verify: ${ticket.verify.join('; ')}`,
+        ticket.reviewedTaskId === undefined ? '' : `Reviewed task: ${ticket.reviewedTaskId}`,
+    ].filter((line) => line !== '').join('\n');
+    const structuredCompletion = ['implementation', 'repair', 'verification', 'integration'].includes(kind)
+        ? `
+Structured completion payload (keep these arrays in contract order):
+acceptanceResults: ${JSON.stringify((ticket.acceptance ?? []).map((criterion) => ({ criterion, status: 'passed', evidence: '<what proved it>' })))}
+commandsRun: ${JSON.stringify((ticket.verify ?? []).map((command) => ({ command, status: 'passed', exitCode: 0, evidence: '<observed result>' })))}
+${kind === 'implementation' || kind === 'repair' ? 'changedPaths: list the actual workspace-relative POSIX paths you changed.\n' : ''}`
+        : '';
+    return `T Team automatic task assignment from the shared task list.
+
+You are executing as configured member "${ticket.memberName}".
+Do not start a teammate's assigned task.
+
+Team goal:
+${goal}
+
+Profile protocol:
+${protocol}
+${executionPrompt === undefined || executionPrompt === '' ? '' : `
+Execution guidance:
+${executionPrompt}
+`}
+Completed dependency results:
+${formatDependencyOutputs(ticket.dependencyOutputs)}
+
+Task: ${ticket.taskId}${seed} — ${ticket.subject}${description}
+${contract === '' ? '' : `\nContract:\n${contract}\n`}
+${structuredCompletion}
+Attempt: ${ticket.attempt}
+Attempt id: ${ticket.attemptId}
+
+Call t_team_claim_task for ${ticket.taskId}; it will return this same attempt_id. Include attempt_id=${ticket.attemptId} in every t_team_update_task call. If it is rejected as stale, stop work because the task was reassigned. claimed cannot jump to completed. Mark in_progress first, then completed or failed. Include attempt_id on every update. Then send_message to captain and become idle.
+When finishing: use status=completed only when the task's success criteria are satisfied; use status=failed when blocking findings or validation failures mean downstream work must not proceed; include a concise output in either case. Quality kinds must submit structured fields: review/requirements need verdict=pass to complete (needs_revision/reject must fail with findings); implementation/repair/verification/integration need acceptanceResults and commandsRun, while implementation/repair also need in-scope changedPaths. Use status values "passed" or "failed" inside those arrays. After the work and verification finish, call t_team_update_task immediately; do not wait for captain confirmation and do not continue exploring. Do not approve your own implementation. Mail is not a formal next review. Treat the dependency results above as source material. Do not ignore them. Work only this task and only its in-scope paths in this turn.
+
+State policy: ${stateDir}/${teamId}/ is read-only diagnostics; mutate team state only through t_team_* tools.`;
+}
+function fallbackMailboxPrompt(messages) {
+    return [
+        'T Team delivered messages that were persisted while live delivery was unavailable:',
+        ...messages.map(message => `\nFrom ${message.from}:\n${message.content}`),
+        '\nHandle these messages in this turn. Task assignments still require t_team_claim_task and the current attempt_id.',
+    ].join('\n');
+}
+/** Install one scheduler and its member activity observer. */
+export function installTeamScheduler(ctx, config) {
+    const memberQueues = new Map();
+    // An idle edge in this process proves that the resident member ended its
+    // turn while the current attempt was still open. Remember that capability
+    // even after Harness disposes the continuable AgentHandle: later status or
+    // graph kicks must keep it parked. A cold process starts with an empty map,
+    // so durable open attempts are still recovered after restart.
+    const parkedAttempts = new Map();
+    const memberQueueKey = (stateRoot, teamId, memberName) => (`${stateRoot}\u0000${teamId}\u0000${memberName}`);
+    const serializeMember = async (key, operation) => {
+        const previous = memberQueues.get(key) ?? Promise.resolve();
+        let release;
+        const gate = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => gate);
+        memberQueues.set(key, tail);
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (memberQueues.get(key) === tail)
+                memberQueues.delete(key);
+        }
+    };
+    const runtime = {
+        async kickTeam(workspace, teamId, suppliedCaptain) {
+            const stateRoot = stateRootOf(workspace, config);
+            const team = await readTeam(stateRoot, teamId);
+            if (team === undefined || team.halted === true || team.phase === 'staged')
+                return;
+            const captain = liveCaptain(ctx, team.captainSessionId, suppliedCaptain);
+            if (captain === undefined)
+                return;
+            for (const member of team.members) {
+                if (member.status === 'removed')
+                    continue;
+                await runtime.kickMember(workspace, teamId, member.name, captain);
+            }
+        },
+        async kickMember(workspace, teamId, memberName, suppliedCaptain) {
+            const stateRoot = stateRootOf(workspace, config);
+            const queueKey = memberQueueKey(stateRoot, teamId, memberName);
+            await serializeMember(queueKey, async () => {
+                let team = await readTeam(stateRoot, teamId);
+                if (team === undefined || team.halted === true || team.phase === 'staged')
+                    return;
+                const captain = liveCaptain(ctx, team.captainSessionId, suppliedCaptain);
+                if (captain === undefined)
+                    return;
+                let member = team.members.find(candidate => candidate.name === memberName && candidate.status !== 'removed');
+                if (member === undefined || member.id === '' || !isMemberAvailable(ctx, member))
+                    return;
+                // A mailbox-only fallback is real pending work. Deliver it before a
+                // fresh task and acknowledge only after Harness accepts the follow-up.
+                const unread = await readUnreadMailbox(stateRoot, team.id, member.name);
+                if (unread.length > 0) {
+                    await withTeamLock(teamLockKey(stateRoot, team.id), () => (claimMailboxDelivery(stateRoot, team.id, member.name, unread.map(message => message.id))));
+                    const accepted = await deliverToMember(ctx, captain, member.id, fallbackMailboxPrompt(unread), new AbortController().signal);
+                    if (accepted) {
+                        await withTeamLock(teamLockKey(stateRoot, team.id), () => (acknowledgeMailbox(stateRoot, team.id, member.name, unread.map(message => message.id))));
+                    }
+                    else {
+                        await withTeamLock(teamLockKey(stateRoot, team.id), () => (releaseMailboxDelivery(stateRoot, team.id, member.name, unread.map(message => message.id))));
+                    }
+                    return;
+                }
+                const ticket = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                    const fresh = await readTeam(stateRoot, team.id);
+                    if (fresh === undefined || fresh.halted === true || fresh.phase === 'staged')
+                        return undefined;
+                    const currentMember = fresh.members.find(candidate => candidate.name === memberName && candidate.status !== 'removed');
+                    if (currentMember === undefined || currentMember.id === '' || !isMemberAvailable(ctx, currentMember))
+                        return undefined;
+                    const owned = ownedOpenTask(fresh.tasks, currentMember.name);
+                    // An idle edge observed by this scheduler parks the exact open
+                    // capability. Harness may dispose its AgentHandle after settlement,
+                    // so registry absence is not evidence that the owner was lost. Keep
+                    // the marker sticky across later kicks; only a durable attempt that
+                    // this process has not observed is eligible for one cold recovery.
+                    const parkedAttemptId = parkedAttempts.get(currentMember.id);
+                    const recoverOwned = owned !== undefined
+                        && (owned.attemptId === undefined || owned.attemptId !== parkedAttemptId);
+                    const task = recoverOwned ? owned : owned === undefined
+                        ? nextReadyTask(fresh.tasks, currentMember.name)
+                        : undefined;
+                    if (task === undefined) {
+                        if (currentMember.status !== 'idle') {
+                            currentMember.status = 'idle';
+                            await writeTeam(stateRoot, fresh);
+                        }
+                        return undefined;
+                    }
+                    const previousAssignee = task.assignee;
+                    const previousStatus = recoverOwned ? task.status : undefined;
+                    const previousAttempt = recoverOwned ? task.attempt : undefined;
+                    const previousAttemptId = recoverOwned ? task.attemptId : undefined;
+                    const attemptId = beginTaskAttempt(task, currentMember.name);
+                    // A recovered generation is parked before delivery. This makes each
+                    // (member, attempt) recovery idempotent even if every status poll
+                    // sees a disposed handle. Fresh pending work remains unparked so a
+                    // genuinely lost first delivery can be recovered once.
+                    if (recoverOwned)
+                        parkedAttempts.set(currentMember.id, attemptId);
+                    else
+                        parkedAttempts.delete(currentMember.id);
+                    currentMember.status = 'working';
+                    await writeTeam(stateRoot, fresh);
+                    const profileSeedId = taskProfileSeedId(task);
+                    const protocol = teamProfileProtocol(fresh);
+                    return {
+                        taskId: task.id,
+                        memberName: currentMember.name,
+                        memberId: currentMember.id,
+                        attempt: task.attempt ?? 1,
+                        attemptId,
+                        previousAssignee,
+                        recoveredOwned: recoverOwned,
+                        ...previousStatus === undefined ? {} : { previousStatus },
+                        ...previousAttempt === undefined ? {} : { previousAttempt },
+                        ...previousAttemptId === undefined ? {} : { previousAttemptId },
+                        subject: task.subject,
+                        description: task.description,
+                        teamDescription: fresh.description,
+                        ...protocol === undefined ? {} : { profileProtocol: protocol },
+                        ...profileSeedId === undefined ? {} : { profileSeedId },
+                        ...fresh.profile?.executionPrompt === undefined && config.executionPrompt === undefined
+                            ? {}
+                            : { executionPrompt: fresh.profile?.executionPrompt ?? config.executionPrompt },
+                        kind: task.kind ?? 'work',
+                        ...task.round === undefined ? {} : { round: task.round },
+                        ...task.objective === undefined ? {} : { objective: task.objective },
+                        ...task.inScope === undefined ? {} : { inScope: task.inScope },
+                        ...task.outOfScope === undefined ? {} : { outOfScope: task.outOfScope },
+                        ...task.acceptance === undefined ? {} : { acceptance: task.acceptance },
+                        ...task.verify === undefined ? {} : { verify: task.verify },
+                        ...task.reviewedTaskId === undefined ? {} : { reviewedTaskId: task.reviewedTaskId },
+                        dependencyOutputs: collectCompletedDependencyOutputs(fresh.tasks, task.id, (message) => ctx.logger.warn(message)),
+                    };
+                });
+                if (ticket === undefined)
+                    return;
+                const accepted = await deliverToMember(ctx, captain, ticket.memberId, assignmentPrompt(ticket, config.stateDir, team.id), new AbortController().signal);
+                if (accepted)
+                    return;
+                // Roll back only our exact failed dispatch. A concurrent captain
+                // handoff has already changed the capability and wins.
+                await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                    const fresh = await readTeam(stateRoot, team.id);
+                    if (fresh === undefined)
+                        return;
+                    const task = fresh.tasks.find(candidate => candidate.id === ticket.taskId);
+                    if (task?.attemptId !== ticket.attemptId)
+                        return;
+                    if (ticket.recoveredOwned && ticket.previousStatus !== undefined && ticket.previousAttemptId !== undefined) {
+                        // Recovery delivery failed. Restore the durable generation instead
+                        // of returning it to pending, then keep it parked so later status
+                        // kicks cannot spend an unbounded sequence of fresh attempts.
+                        task.status = ticket.previousStatus;
+                        task.assignee = ticket.previousAssignee;
+                        task.attempt = ticket.previousAttempt;
+                        task.attemptId = ticket.previousAttemptId;
+                        parkedAttempts.set(ticket.memberId, ticket.previousAttemptId);
+                    }
+                    else {
+                        task.status = 'pending';
+                        task.assignee = ticket.previousAssignee;
+                        task.attemptId = undefined;
+                        parkedAttempts.delete(ticket.memberId);
+                    }
+                    task.handoffId = undefined;
+                    task.reassigning = false;
+                    task.updatedAt = Date.now();
+                    const currentMember = fresh.members.find(candidate => candidate.name === ticket.memberName);
+                    if (currentMember !== undefined && currentMember.status !== 'removed')
+                        currentMember.status = 'idle';
+                    await writeTeam(stateRoot, fresh);
+                });
+            });
+        },
+    };
+    const syncMemberStatus = async (agent, status) => {
+        const workspace = agent.session.header.cwd ?? process.cwd();
+        const stateRoot = stateRootOf(workspace, config);
+        const located = await findTeamByParticipant(stateRoot, agent.id);
+        if (located === undefined) {
+            parkedAttempts.delete(agent.id);
+            return;
+        }
+        if (located.captainSessionId === agent.id) {
+            // Captain takeover is scoped to the captain's current turn. Unlike a
+            // durable member, the captain has no scheduler lane that can resume an
+            // abandoned attempt later. Returning unfinished captain-owned work to
+            // the shared pool on the idle edge prevents it from becoming a
+            // permanently parked `claimed` task after the captain answers, is
+            // interrupted, or the user switches conversations.
+            if (status === 'running')
+                return;
+            let requeued = false;
+            await withTeamLock(teamLockKey(stateRoot, located.id), async () => {
+                const fresh = await readTeam(stateRoot, located.id);
+                if (fresh === undefined || fresh.captainSessionId !== agent.id)
+                    return;
+                for (const task of fresh.tasks) {
+                    if (task.assignee !== CAPTAIN_KEY
+                        || task.status === 'completed'
+                        || task.status === 'failed'
+                        || task.status === 'cancelled')
+                        continue;
+                    invalidateTaskAttempt(task);
+                    task.reassigning = false;
+                    requeued = true;
+                }
+                if (requeued)
+                    await writeTeam(stateRoot, fresh);
+            });
+            if (requeued)
+                await runtime.kickTeam(workspace, located.id, agent);
+            return;
+        }
+        const member = located.members.find(candidate => candidate.id === agent.id && candidate.status !== 'removed');
+        if (member === undefined) {
+            parkedAttempts.delete(agent.id);
+            return;
+        }
+        await withTeamLock(teamLockKey(stateRoot, located.id), async () => {
+            const fresh = await readTeam(stateRoot, located.id);
+            const current = fresh?.members.find(candidate => candidate.id === agent.id && candidate.status !== 'removed');
+            if (fresh === undefined || current === undefined)
+                return;
+            const next = status === 'running' ? 'working' : 'idle';
+            if (next === 'idle') {
+                const owned = ownedOpenTask(fresh.tasks, current.name);
+                if (owned?.attemptId === undefined)
+                    parkedAttempts.delete(agent.id);
+                else
+                    parkedAttempts.set(agent.id, owned.attemptId);
+            }
+            else {
+                parkedAttempts.delete(agent.id);
+            }
+            if (current.status === next)
+                return;
+            current.status = next;
+            await writeTeam(stateRoot, fresh);
+        });
+        if (status === 'idle')
+            await runtime.kickMember(workspace, located.id, member.name);
+    };
+    ctx.on('agent/status', ({ agent, status }) => {
+        void syncMemberStatus(agent, status).catch((error) => {
+            ctx.logger.warn(`t-team: member status scheduling failed for ${agent.id}: ${String(error)}`);
+        });
+    });
+    return runtime;
+}

package/lib/teams/snapshot.js

@@ -0,0 +1,181 @@
+/**
+ * Team activity snapshot assembly for the activity panel.
+ *
+ * Server-side assembly mirrors the Claude Code desktop teamWatcher: read the
+ * durable team files (the truth source) and enrich with live subagent
+ * activity, so the panel always reflects the on-disk state even when a model
+ * skipped a tool "ritual" (e.g. not calling update_task on completion).
+ * @module t-team/snapshot
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { memberActivity } from "./members.js";
+import { CAPTAIN_KEY, listArchivedTeamIds, readArchivedTeam, readUnreadMailbox, readTeam, taskDepthsById, taskVisualState, } from "./state.js";
+/** The current task of a member: its first unfinished owned task. */
+function currentTaskOf(memberName, tasks) {
+    for (const task of tasks) {
+        if (task.status === 'in_progress' && task.assignee === memberName)
+            return task.id;
+    }
+    return '';
+}
+/** Compact `provider/model` route for the activity panel, or just the model. */
+export function memberModelRoute(member) {
+    if (member === undefined)
+        return '';
+    const provider = member.provider?.trim() ?? '';
+    const model = member.model?.trim() ?? '';
+    if (provider !== '' && model !== '')
+        return `${provider}/${model}`;
+    return model;
+}
+/**
+ * Assemble one team snapshot from its durable files plus live activity.
+ * @param ctx - the plugin context (injects `subagents`, used for activity).
+ * @param stateRoot - resolved absolute state root of the owning workspace.
+ * @param workspace - display name of the owning workspace.
+ * @param state - the durable team record.
+ * @returns the panel snapshot.
+ */
+export async function assembleTeamSnapshot(ctx, stateRoot, workspace, state, options = {}) {
+    const tasks = state.tasks;
+    const depths = taskDepthsById(tasks);
+    const roster = options.includeRemoved === true
+        ? state.members
+        : state.members.filter((member) => member.status !== 'removed');
+    const activity = options.historic === true
+        ? new Map()
+        : memberActivity(ctx, roster.map((member) => member.id));
+    const unreadByMember = new Map();
+    for (const member of roster) {
+        try {
+            unreadByMember.set(member.name, (await readUnreadMailbox(stateRoot, state.id, member.name)).length);
+        }
+        catch (error) {
+            ctx.logger.warn(`t-team: mailbox read failed for ${member.name}: ${String(error)}`);
+            unreadByMember.set(member.name, 0);
+        }
+    }
+    const members = roster.map((member) => {
+        const owned = tasks.filter((task) => task.assignee === member.name);
+        const done = owned.filter((task) => task.status === 'completed').length;
+        return {
+            id: member.id,
+            name: member.name,
+            role: member.role ?? '',
+            provider: member.provider?.trim() ?? '',
+            model: member.model?.trim() ?? '',
+            reasoningEffort: member.reasoningEffort?.trim() ?? '',
+            executionPrompt: member.executionPrompt ?? '',
+            status: member.status,
+            activity: options.historic === true
+                ? 'idle'
+                : member.id !== ''
+                    ? (activity.get(member.id) === 'running'
+                        ? 'working'
+                        : activity.get(member.id) === 'idle' || activity.get(member.id) === 'ready'
+                            ? 'idle'
+                            : 'unknown')
+                    : state.phase === 'staged' ? 'idle' : 'unknown',
+            progress: owned.length === 0 ? 0 : Math.round((done / owned.length) * 100),
+            done,
+            total: owned.length,
+            currentTask: currentTaskOf(member.name, tasks),
+            unread: unreadByMember.get(member.name) ?? 0,
+        };
+    });
+    const captainInbox = await readUnreadMailbox(stateRoot, state.id, CAPTAIN_KEY);
+    return {
+        workspace,
+        teamId: state.id,
+        name: state.name,
+        ...state.description !== undefined ? { description: state.description } : {},
+        captainSessionId: state.captainSessionId,
+        phase: state.phase ?? 'running',
+        ...state.phase === 'staged'
+            ? { planReviewState: state.planReviewState ?? 'awaiting_review' }
+            : {},
+        ...state.halted === true ? { halted: true } : {},
+        members,
+        tasks: tasks.map((task) => ({
+            id: task.id,
+            subject: task.subject,
+            description: task.description ?? '',
+            status: task.status,
+            state: taskVisualState(task.status, task.dependencies, tasks),
+            assignee: task.assignee ?? '',
+            model: memberModelRoute(roster.find((member) => member.name === task.assignee)),
+            dependencies: task.dependencies,
+            depth: depths.get(task.id) ?? 0,
+            ...task.kind === undefined ? {} : { kind: task.kind },
+            ...task.round === undefined ? {} : { round: task.round },
+            ...task.verdict === undefined ? {} : { verdict: task.verdict },
+        })),
+        messageCount: captainInbox.length
+            + members.reduce((count, member) => count + member.unread, 0),
+        captainInbox: captainInbox.slice(-5).map((message) => ({
+            from: message.from,
+            content: message.content,
+        })),
+    };
+}
+/**
+ * Collect every team under the given workspace state roots.
+ * @param ctx - the plugin context.
+ * @param roots - `{ workspace, stateRoot }` pairs (resolved absolute roots).
+ * @returns the snapshots in stable order (workspace, then team id).
+ */
+export async function collectTeamsActivity(ctx, roots) {
+    const snapshots = [];
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await readdir(root.stateRoot, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                continue;
+            }
+            throw error;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                const state = await readTeam(root.stateRoot, entry.name);
+                if (state === undefined)
+                    continue;
+                snapshots.push(await assembleTeamSnapshot(ctx, root.stateRoot, root.workspace, state));
+            }
+            catch {
+                ctx.logger.warn(`t-team: skipped unreadable team state "${entry.name}" in workspace "${root.workspace}"`);
+            }
+        }
+    }
+    return snapshots;
+}
+/**
+ * Collect every archived team under the given workspace state roots (the
+ * `archive/` subdirectory of each state root). Used by the historic panel
+ * path to restore full team detail after deletion.
+ * @param ctx - the plugin context.
+ * @param roots - `{ workspace, stateRoot }` pairs.
+ * @returns the archived snapshots in stable order.
+ */
+export async function collectArchivedTeamsActivity(ctx, roots) {
+    const snapshots = [];
+    for (const root of roots) {
+        for (const teamId of await listArchivedTeamIds(root.stateRoot)) {
+            try {
+                const state = await readArchivedTeam(root.stateRoot, teamId);
+                if (state === undefined)
+                    continue;
+                snapshots.push(await assembleTeamSnapshot(ctx, join(root.stateRoot, 'archive'), root.workspace, state, { includeRemoved: true, historic: true }));
+            }
+            catch {
+                ctx.logger.warn(`t-team: skipped unreadable archived team "${teamId}" in workspace "${root.workspace}"`);
+            }
+        }
+    }
+    return snapshots;
+}