@intentic/sandbox-contract 1.337.0 → 1.339.0

package/src/index.ts

@@ -1,15 +1,16 @@
 import { getEventIteratorSchemaDetails, isContractProcedure } from "@orpc/contract";
 import type { z } from "zod";
+import { RAW_JSON_ROUTES } from "./protocol/raw/raw-json-routes.js";
 import { RAW_ROUTE_LIST } from "./protocol/raw/raw-routes.js";
 import type { ContractRoute } from "./protocol/routes.js";
-import { contractRoutes, requestPathFor, routeForProcedure, routeNameForRequest, routeShapes, servedRoute } from "./protocol/routes.js";
+import { contractRoutes, rawRouteFingerprintsOf, requestPathFor, routeForProcedure, routeNameForRequest, routeShapes, servedRoute } from "./protocol/routes.js";
 import { accountsContract } from "./contracts/accounts.contract.js";
 import { activityContract } from "./contracts/activity.contract.js";
 import { agentContract } from "./contracts/agent.contract.js";
 import { agentsContract } from "./contracts/agents.contract.js";
 import { approvalsContract } from "./contracts/approvals.contract.js";
-import { auditContract } from "./contracts/audit.contract.js";
 import { areasContract } from "./contracts/areas.contract.js";
+import { auditContract } from "./contracts/audit.contract.js";
 import { automationsContract } from "./contracts/automations.contract.js";
 import { capabilitiesContract } from "./contracts/capabilities.contract.js";
 import { choresContract } from "./contracts/chores.contract.js";
@@ -19,7 +20,6 @@ import { diffContract } from "./contracts/diff.contract.js";
 import { endpointsContract } from "./contracts/endpoints.contract.js";
 import { exitContract } from "./contracts/exit.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
-import { personasContract } from "./contracts/personas.contract.js";
 import { gitContract } from "./contracts/git.contract.js";
 import { historyContract } from "./contracts/history.contract.js";
 import { intenticContract } from "./contracts/intentic.contract.js";
@@ -27,17 +27,20 @@ import { inventoryContract } from "./contracts/inventory.contract.js";
 import { issuesContract } from "./contracts/issues.contract.js";
 import { logsContract } from "./contracts/logs.contract.js";
 import { loopsContract } from "./contracts/loops.contract.js";
+import { needsContract } from "./contracts/needs.contract.js";
+import { netdiskContract } from "./contracts/netdisk.contract.js";
+import { offloadContract } from "./contracts/offload.contract.js";
+import { orgContract } from "./contracts/org.contract.js";
 import { pagesContract } from "./contracts/pages.contract.js";
 import { panelsContract } from "./contracts/panels.contract.js";
+import { personasContract } from "./contracts/personas.contract.js";
 import { portsContract } from "./contracts/ports.contract.js";
-import { runsContract } from "./contracts/runs.contract.js";
-import { publicContract } from "./contracts/public.contract.js";
-import { netdiskContract } from "./contracts/netdisk.contract.js";
+import { privacyContract } from "./contracts/privacy.contract.js";
 import { providersContract } from "./contracts/providers.contract.js";
+import { publicContract } from "./contracts/public.contract.js";
 import { pushContract } from "./contracts/push.contract.js";
-import { privacyContract } from "./contracts/privacy.contract.js";
+import { runsContract } from "./contracts/runs.contract.js";
 import { safetyContract } from "./contracts/safety.contract.js";
-import { needsContract } from "./contracts/needs.contract.js";
 import { secretsContract } from "./contracts/secrets.contract.js";
 import { sessionsContract } from "./contracts/sessions.contract.js";
 import { settingsContract } from "./contracts/settings.contract.js";
@@ -46,267 +49,12 @@ import { skillsContract } from "./contracts/skills.contract.js";
 import { systemContract } from "./contracts/system.contract.js";
 import { translatorContract } from "./contracts/translator.contract.js";
 import { usageContract } from "./contracts/usage.contract.js";
-import { offloadContract } from "./contracts/offload.contract.js";
 import { vpnContract } from "./contracts/vpn.contract.js";
 import { workflowsContract } from "./contracts/workflows.contract.js";
 import { workspaceContract } from "./contracts/workspace.contract.js";
 
-export { accountsContract } from "./contracts/accounts.contract.js";
-export { activityContract } from "./contracts/activity.contract.js";
-export { auditContract } from "./contracts/audit.contract.js";
-export { agentContract } from "./contracts/agent.contract.js";
-export { agentsContract } from "./contracts/agents.contract.js";
-export { approvalsContract } from "./contracts/approvals.contract.js";
-export { areasContract } from "./contracts/areas.contract.js";
-export { automationsContract } from "./contracts/automations.contract.js";
-export { capabilitiesContract } from "./contracts/capabilities.contract.js";
-export { choresContract } from "./contracts/chores.contract.js";
-export { ciContract } from "./contracts/ci.contract.js";
-export { complianceContract } from "./contracts/compliance.contract.js";
-export {
-    endpointsContract,
-    type HostModelServer,
-    HostModelServerSchema,
-    type HostModelServers,
-    HostModelServersSchema,
-    LocalModelFitSchema,
-    type LocalModelFitResponse,
-    type LocalModelPrefetch,
-    LocalModelPrefetchSchema,
-    type TrialHealth,
-    TrialStatusSchema,
-    type TrialStatusResponse,
-} from "./contracts/endpoints.contract.js";
-export { exitContract } from "./contracts/exit.contract.js";
-export { extensionsContract } from "./contracts/extensions.contract.js";
-export { personasContract } from "./contracts/personas.contract.js";
-export { diffContract } from "./contracts/diff.contract.js";
-export { gitContract } from "./contracts/git.contract.js";
-export { historyContract } from "./contracts/history.contract.js";
-// Not part of `sandboxContract` below: spoken over a device's WebSocket, with the machine implementing it.
-export { deviceContract } from "./contracts/device.contract.js";
-// Same inversion, spoken over a browser extension's socket, with the extension implementing it.
-export { webextContract } from "./contracts/webext.contract.js";
-// Same inversion, spoken over a phone app's socket as JSON-RPC (protocol/doors/phone-protocol.ts), with the app implementing it.
-export { phoneContract } from "./contracts/phone.contract.js";
-// Same inversion again: spoken over a runner's WebSocket, with the runner implementing it.
-export { runnerContract } from "./contracts/runner.contract.js";
-export { intenticContract } from "./contracts/intentic.contract.js";
-export { inventoryContract } from "./contracts/inventory.contract.js";
-export { issuesContract } from "./contracts/issues.contract.js";
-export { logsContract } from "./contracts/logs.contract.js";
-export { CONNECT_TOKEN_HEADER, EXTENSION_TOKEN_HEADER, REQUEST_ID_HEADER } from "./protocol/headers.js";
-export * from "./protocol/edge-verdict.js";
-export * from "./protocol/vitals.js";
-export { loopsContract } from "./contracts/loops.contract.js";
-export { panelsContract } from "./contracts/panels.contract.js";
-export { portsContract } from "./contracts/ports.contract.js";
-export { runsContract } from "./contracts/runs.contract.js";
-export { pagesContract, PageAppCallResultSchema, PageAppCallSchema, PageErrorsResultSchema, PageErrorsSchema } from "./contracts/pages.contract.js";
-export { publicContract } from "./contracts/public.contract.js";
-export { providersContract, type RunnableProviders, RunnableProvidersSchema } from "./contracts/providers.contract.js";
-export { pushContract } from "./contracts/push.contract.js";
-export { privacyContract } from "./contracts/privacy.contract.js";
-export { safetyContract } from "./contracts/safety.contract.js";
-export { needsContract } from "./contracts/needs.contract.js";
-export { secretsContract } from "./contracts/secrets.contract.js";
-export { sessionsContract } from "./contracts/sessions.contract.js";
-export { settingsContract } from "./contracts/settings.contract.js";
-export { shareContract } from "./contracts/share.contract.js";
-export { skillsContract } from "./contracts/skills.contract.js";
-export { systemContract } from "./contracts/system.contract.js";
-export { translatorContract } from "./contracts/translator.contract.js";
-export { type PlanLimitsHeld, type PlanLimitsRefreshed, PlanLimitsRefreshedSchema, usageContract } from "./contracts/usage.contract.js";
-export { netdiskContract } from "./contracts/netdisk.contract.js";
-export { offloadContract } from "./contracts/offload.contract.js";
-export { vpnContract } from "./contracts/vpn.contract.js";
-export { workflowsContract } from "./contracts/workflows.contract.js";
-export { workspaceContract } from "./contracts/workspace.contract.js";
-export * from "./events/agent-events.js";
-export * from "./events/agent-ui.js";
-export * from "./events/agent-words.js";
-export * from "./events/requests.js";
-export * from "./events/resume.js";
-export * from "./events/sandbox-notice.js";
-export * from "./events/system-events.js";
-export * from "./events/transcript.js";
-export * from "./events/land-breakage.js";
-export * from "./events/land-conflict.js";
-export * from "./events/verify-nudge.js";
-export * from "./events/errands.js";
-export * from "./events/need-wake.js";
-export * from "./events/watch-wake.js";
-export * from "./policy/request-status.js";
-export * from "./events/child-run.js";
-export * from "./policy/turned-away.js";
-export * from "./text/mentions.js";
-export * from "./text/pages.js";
-export * from "./text/transcript-page.js";
-export * from "./protocol/sse.js";
-export * from "./protocol/routes.js";
-export { type ControlReach, defaultFloor, type RouteAccess, type RouteMeta, routeAccess } from "./protocol/route-meta.js";
-export { RAW_ROUTE_LIST, RAW_ROUTES, type RawRouteKey, type RawRouteParams, rawRoutePath, rawRouteUrl } from "./protocol/raw/raw-routes.js";
-export * from "./protocol/raw/raw-json-routes.js";
-export { fillRoutePath, type RoutePathParams } from "./protocol/raw/route-path.js";
-export { tunnelBulkRoutes } from "./protocol/tunnel-bulk.js";
-export type { SandboxCallInput, SandboxGroup, SandboxHandlerInput, SandboxHandlerOutput, SandboxProcedure } from "./protocol/procedure-types.js";
-export * from "./policy/control-scopes.js";
 // The container's directory layout, re-exported since extensions can't import @intentic/constants directly.
 export { HISTORY_ROOT, HOST_STATE_ROOT, STATE_DIR, WORKSPACE_ROOT } from "@intentic/constants";
-export * from "./state/workspace-state.js";
-export * from "./state/runtime-state.js";
-export * from "./state/state-portability.js";
-export * from "./state/history-state.js";
-export * from "./state/fix-stance.js";
-export * from "./state/landed-commit.js";
-export * from "./state/fix-attempt-plan.js";
-// Provider vocabulary bottom-up: agent-runtimes, provider-specs, agent-catalog; three modules since the dependency
-// points one way.
-export * from "./models/agent-runtimes.js";
-export * from "./models/provider-specs.js";
-export * from "./models/agent-catalog.js";
-export * from "./policy/capability-env.js";
-export * from "./policy/command-classes.js";
-export * from "./policy/command-run.js";
-export * from "./policy/device-programs.js";
-export * from "./policy/sandbox-power.js";
-export * from "./policy/safety-policy.js";
-export * from "./policy/reserved-servers.js";
-export * from "./policy/credential-material.js";
-export * from "./policy/capability-secrets.js";
-export * from "./policy/secret-hosts.js";
-export * from "./ids/conversation-ids.js";
-export * from "./text/documents.js";
-export * from "./protocol/doors/host-protocol.js";
-export * from "./protocol/doors/webext-protocol.js";
-export * from "./protocol/doors/webext-links.js";
-export * from "./protocol/doors/phone-protocol.js";
-export * from "./protocol/doors/phone-links.js";
-export * from "./protocol/doors/runner-protocol.js";
-export * from "./protocol/doors/listener-protocol.js";
-export * from "./protocol/container-requirements.js";
-export * from "./ids/hostnames.js";
-export { SANDBOX_ID } from "./ids/sandbox-id.js";
-export * from "./ids/project-dir.js";
-export * from "./policy/overlay-lint.js";
-export * from "./models/model-label.js";
-export * from "./models/model-order.js";
-export * from "./models/model-offer.js";
-export * from "./models/model-pins.js";
-export * from "./models/model-roles.js";
-export * from "./models/model-setups.js";
-export * from "./models/plan-pools.js";
-export * from "./text/path-refs.js";
-export * from "./text/archives.js";
-export * from "./policy/output-fields.js";
-export * from "./policy/approvals-execution.js";
-export * from "./policy/message-limits.js";
-// Wire shapes, one module per subject area, mirroring `contracts/`; a `{param}` in the route path merges into the same
-// flat object, split back into path/body/query. `schemas/internal.ts` is absent: it's vocabulary, not a wire shape.
-export * from "./schemas/activity.js";
-export * from "./schemas/audit.js";
-export * from "./schemas/agent.js";
-export * from "./schemas/areas.js";
-export * from "./policy/fence-paths.js";
-export * from "./policy/persona-home.js";
-export * from "./schemas/agents.js";
-export * from "./schemas/speaker.js";
-export * from "./schemas/speech.js";
-export * from "./schemas/voice.js";
-export * from "./schemas/approvals.js";
-export * from "./schemas/automations.js";
-export * from "./schemas/agents-list.js";
-export * from "./schemas/capabilities.js";
-export * from "./schemas/chat-route.js";
-export * from "./schemas/ci.js";
-export * from "./schemas/providers/claude-gate.js";
-export * from "./schemas/codebase-health.js";
-export * from "./schemas/context-trim.js";
-export * from "./schemas/devices.js";
-export * from "./schemas/device-swaps.js";
-export * from "./schemas/intentic-os.js";
-export * from "./schemas/project-delivery.js";
-export * from "./schemas/device-artifacts.js";
-export * from "./schemas/run-targets.js";
-export * from "./schemas/engines.js";
-export * from "./schemas/environment.js";
-export * from "./schemas/exit.js";
-export * from "./schemas/extension-updates.js";
-export * from "./schemas/providers/fast-mode.js";
-export * from "./schemas/diff.js";
-export * from "./schemas/git/git.js";
-export * from "./schemas/git/git-scope.js";
-export * from "./schemas/git/git-history.js";
-export * from "./schemas/history.js";
-export * from "./schemas/hosts.js";
-export * from "./schemas/loopback-catch.js";
-export * from "./schemas/peer-enrollment.js";
-export * from "./schemas/intentic.js";
-export * from "./schemas/inventory.js";
-export * from "./schemas/issues.js";
-export * from "./schemas/logs.js";
-export * from "./schemas/loops.js";
-export * from "./schemas/maintenance.js";
-export * from "./schemas/marketplace.js";
-export * from "./schemas/members.js";
-export * from "./schemas/metrics.js";
-export * from "./schemas/panels.js";
-export * from "./schemas/personas.js";
-export * from "./schemas/privacy.js";
-export * from "./schemas/providers/plan-limits.js";
-export * from "./schemas/providers/handoff.js";
-export * from "./schemas/platform-link.js";
-export * from "./schemas/project-bring-back.js";
-export * from "./schemas/ports.js";
-export * from "./schemas/providers/provider-oauth.js";
-export * from "./schemas/providers/provider-subscriptions.js";
-export * from "./schemas/public.js";
-export * from "./schemas/push.js";
-export * from "./schemas/git/remote-refs.js";
-export * from "./schemas/needs.js";
-export * from "./schemas/secrets.js";
-export * from "./schemas/netdisk.js";
-export * from "./schemas/sessions.js";
-export * from "./schemas/settings.js";
-export * from "./schemas/data-protection.js";
-export * from "./schemas/ai-literacy.js";
-export * from "./schemas/compliance.js";
-export * from "./schemas/settings-history.js";
-export * from "./schemas/share.js";
-export * from "./schemas/shared.js";
-export * from "./schemas/short-codes.js";
-export * from "./schemas/system-prompt.js";
-export * from "./schemas/system.js";
-export * from "./schemas/state-plan.js";
-export * from "./schemas/restart-intent.js";
-export * from "./schemas/updates.js";
-export * from "./schemas/terminal.js";
-export * from "./schemas/turn-break.js";
-export * from "./schemas/keep-warm.js";
-export * from "./schemas/providers/usage.js";
-export * from "./schemas/vpn.js";
-export * from "./schemas/offload.js";
-export * from "./schemas/webext.js";
-export * from "./schemas/phone.js";
-export * from "./schemas/workflows.js";
-export * from "./schemas/workspace/workspace-graph.js";
-export * from "./schemas/workspace/workspace-repos.js";
-export * from "./schemas/workspace/workspace-search.js";
-export * from "./schemas/workspace/workspace-setup.js";
-export * from "./schemas/workspace/workspace-tree.js";
-export * from "./schemas/workspace/workspace-upload.js";
-export * from "./state/arrival.js";
-export * from "./state/definition.js";
-export * from "./policy/search-globs.js";
-export * from "./state/starter.js";
-export * from "./text/title.js";
-export * from "./state/update-probation.js";
-export * from "./state/versions.js";
-export * from "./text/model-answer.js";
-export * from "./text/shell-regions.js";
-export * from "./text/workflow-faults.js";
-export * from "./text/emoji.js";
-export * from "./time/zone.js";
 
 // The aggregated contract; implemented server-side by per-domain route factories, consumed by the browser's typed oRPC
 // client. Mounted at the sandbox root, alongside plain Hono routes like /health and /workspace/raw.
@@ -316,8 +64,8 @@ export const sandboxContract = {
     agent: agentContract,
     agents: agentsContract,
     approvals: approvalsContract,
-    audit: auditContract,
     areas: areasContract,
+    audit: auditContract,
     automations: automationsContract,
     capabilities: capabilitiesContract,
     chores: choresContract,
@@ -325,39 +73,40 @@ export const sandboxContract = {
     compliance: complianceContract,
     diff: diffContract,
     endpoints: endpointsContract,
+    exit: exitContract,
     extensions: extensionsContract,
-    personas: personasContract,
-    privacy: privacyContract,
-    safety: safetyContract,
-    sessions: sessionsContract,
-    settings: settingsContract,
-    share: shareContract,
-    skills: skillsContract,
-    intentic: intenticContract,
     git: gitContract,
     history: historyContract,
-    workspace: workspaceContract,
+    intentic: intenticContract,
     inventory: inventoryContract,
     issues: issuesContract,
     logs: logsContract,
     loops: loopsContract,
+    needs: needsContract,
+    netdisk: netdiskContract,
+    offload: offloadContract,
+    org: orgContract,
     pages: pagesContract,
     panels: panelsContract,
+    personas: personasContract,
     ports: portsContract,
-    runs: runsContract,
-    public: publicContract,
+    privacy: privacyContract,
     providers: providersContract,
+    public: publicContract,
     push: pushContract,
-    needs: needsContract,
+    runs: runsContract,
+    safety: safetyContract,
     secrets: secretsContract,
+    sessions: sessionsContract,
+    settings: settingsContract,
+    share: shareContract,
+    skills: skillsContract,
     system: systemContract,
     translator: translatorContract,
     usage: usageContract,
     vpn: vpnContract,
-    offload: offloadContract,
-    exit: exitContract,
-    netdisk: netdiskContract,
     workflows: workflowsContract,
+    workspace: workspaceContract,
 };
 
 // Every route in this build, and the names advertised on the hello frame; bound here, not in routes.ts, to avoid a
@@ -373,6 +122,19 @@ export const SANDBOX_ROUTE_NAMES: readonly string[] = SANDBOX_ROUTES.map((route)
 let fingerprints: Readonly<Record<string, string>> | undefined;
 export const sandboxRouteFingerprints = (): Readonly<Record<string, string>> => (fingerprints ??= routeShapes(sandboxContract));
 
+// The hand-written routes beside the procedures, advertised on their own field of the hello frame rather than mixed
+// into `routes`: a browser older than this build reads an unknown name in `routes` as evidence that IT is the stale
+// side, and every raw name arriving there at once would have had it say so on every connection. Absent, as from every
+// daemon before the field, means no evidence — the same "assume it answers" an unknown route surface gets.
+export const RAW_ROUTE_NAMES: readonly string[] = RAW_ROUTE_LIST.map((route) => route.name);
+
+// Each raw JSON route's shape, memoised like the procedures' for the same reason: the walk turns every schema into JSON
+// Schema, which is startup time a browser should only spend when it has a disagreement to explain. The routes that
+// carry no schemas at all (a WebSocket upgrade, a byte stream) are named above but fingerprinted nowhere, and an
+// unfingerprinted route is compared on nothing.
+let rawFingerprints: Readonly<Record<string, string>> | undefined;
+export const rawRouteFingerprints = (): Readonly<Record<string, string>> => (rawFingerprints ??= rawRouteFingerprintsOf(RAW_JSON_ROUTES));
+
 // The contract route a concrete browser request belongs to, bound to this build's route table.
 export const sandboxRouteName = (method: string, pathWithQuery: string): string | undefined =>
     routeNameForRequest(SANDBOX_ROUTES, method, pathWithQuery);

package/src/models/agent-lanes.ts

@@ -0,0 +1,152 @@
+import type { AgentAttention } from "../schemas/agents.js";
+import type { AutomationApproval } from "../schemas/automations.js";
+import { parentOf } from "./agent-starter.js";
+import {
+    type AgentStanding,
+    blocked,
+    heardByParent,
+    limitScheduled,
+    onlyOwnerCanAnswer,
+    scheduledSend,
+    turnInFlight,
+    turnWorking,
+    watching,
+} from "./agent-standing.js";
+
+// The lane every surface files a conversation in, and what of a fleet calls the person. Moved here from the editor
+// (_editor/web/src/models/agent-status/agentStatus-lanes.ts, which re-exports it) on 2026-10-16, so the daemon's
+// `agents.attention` (what the desktop app's status bar and `ic sandbox attention` read) counts by the board's own rules.
+
+// Whether what a child agent stopped on is the reader's to answer rather than its parent's, given the lanes both stand
+// in and when the parent last moved. An ask only the owner can answer always is; anything else it stopped on (a spent
+// allowance, a failure, a stop, a question, a land conflict) is its parent's news while the parent supervises, and the
+// reader's once it no longer does: nothing running there to hear it and nothing armed to wake it, which is a parent out
+// of Active. That holds only until the parent moves past it (heardByParent). After that the stop is the family's
+// history, drawn in the tray, and no longer something the reader owes a press. The sandbox draws the same line for a
+// child's land news (subagents/child-lands.ts): the parent's while it has a live turn, the owner's after.
+export const callsOwner = (
+    child: AgentStanding & { readonly updatedAt: number },
+    family: { readonly child: FleetLane; readonly parent: FleetLane; readonly parentAt: number },
+): boolean => onlyOwnerCanAnswer(child) || (family.child === "attention" && family.parent !== "active" && !heardByParent(child, family.parentAt));
+
+export type FleetLane = "attention" | "active" | "finished";
+
+// Nothing owed to the user. The one "no attention" block in the app: a client-only card has no daemon account of
+// what a turn asked, and two copies of this would let two surfaces place the same conversation differently.
+export const NO_ATTENTION: AgentAttention = {
+    plan: false,
+    question: false,
+    permission: false,
+    capability: false,
+    credential: false,
+    conflict: false,
+};
+
+// The lane projection every surface must agree with (see the header). Pure reading of the state machine:
+// "finished" needs no explicit timer since auto-land already flips a cleanly-completed turn to landed/idle within
+// ms, and any follow-up message moves the card back to active. Unread stays a badge, not a lane.
+export const laneOf = (agent: AgentStanding): FleetLane => {
+    // A spent allowance nothing is booked for reaches Attention through `blocked` alone, no branch of its own, and ahead
+    // of the `watching` branch below: a watch is the agent's own plan for waiting, a spent allowance an obstacle in
+    // the way of it, and a watch firing into a shut window runs nothing (turn-admission.ts holds its words back).
+    if (blocked(agent) || agent.status === "awaiting" || agent.status === "conflict") {
+        return "attention";
+    }
+    // Settled from the press, ahead of the in-flight check below, rather than routed through Active: a waved-away turn
+    // is one the user is already done with (unlike `stopping`, which rests in Attention), and a land spends no model at
+    // all. Active means a turn in progress, so a land must end in the lane it was pressed in.
+    if (agent.status === "dismissing" || agent.status === "landing") {
+        return "finished";
+    }
+    // `resuming` is why in-flight must outrank the settled readings below: without this order the card would drop
+    // into Finished for the seconds a credential takes to re-mint, then climb back out.
+    if (turnInFlight(agent) || agent.status === "draft") {
+        return "active";
+    }
+    // An armed watch is Active, not Finished: nothing is running, but the conversation restarts itself later, and
+    // filing it Finished would announce as over work that resumes at 3am. Active rather than Attention since nothing
+    // is owed by the user. Checked after the in-flight readings: an agent that armed a watch and is now running again
+    // is running.
+    if (watching(agent)) {
+        return "active";
+    }
+    // A stranded turn booked to go again is Active: at the reset, or on the resume pass's next beat for a move to another
+    // account. Reached only because `blocked` let it through; stated explicitly or the card would fall through to
+    // Finished, which would announce as over work that resumes by itself.
+    if (limitScheduled(agent)) {
+        return "active";
+    }
+    // Messages booked for later are the same: the conversation starts again by itself, at a time or once the agent it
+    // waits for has landed, so filing it Finished would announce as done work that has not started yet.
+    if (scheduledSend(agent)) {
+        return "active";
+    }
+    // `landed`/`idle`/`ready` all finish here: `ready` is work held on the branch because auto-land is off, still
+    // finished rather than attention since nothing is failing. `resumed` lands here too: nothing running, nothing
+    // owed.
+    return "finished";
+};
+
+// How many cards the board's Attention lane draws for one fleet, as the board folds child agents under their parents
+// (models/fleet/board/childFold.ts): an agent in Attention is a card of its own, except a child agent whose parent is in the
+// fleet, which rides under its family's one card and lifts that card to Attention only when it calls the reader
+// (callsOwner). A family counts once however many of its children call, and not again when its own card is in
+// Attention already; a child with words left in its composer keeps a card of its own, as on the board. The rail
+// badge's count, for this sandbox's fleet and another's alike, so the badge cannot disagree with the lane it names.
+export const attentionCards = (agents: readonly CallerStanding[]): number => new Set(attentionCalls(agents).map((call) => call.card)).size;
+
+// Enough of a fleet's agent to say whether it calls the reader, and through which card.
+export type CallerStanding = AgentStanding & {
+    readonly id: string;
+    readonly updatedAt: number;
+    readonly startedBy?: string | undefined;
+    readonly unsent?: boolean | undefined;
+};
+
+// Every agent calling the reader, each with the card it is drawn on: its own, or its family's where it rides one. The
+// count above is the cards; the browser tab's chime wants the callers, so a second child calling under a family already
+// in Attention is news although the lane's count does not move.
+export const attentionCalls = (agents: readonly CallerStanding[]): readonly { readonly id: string; readonly card: string }[] => {
+    type Standing = (typeof agents)[number];
+    const byId = new Map(agents.map((agent) => [agent.id, agent] as const));
+    const parentIn = (agent: Standing): Standing | undefined => {
+        const id = parentOf(agent.startedBy);
+        return id === undefined ? undefined : byId.get(id);
+    };
+    // The card a child rides under: its eldest ancestor in this fleet, walked with a guard against a record naming its
+    // own descendant as its parent.
+    const familyOf = (agent: Standing): string => {
+        const seen = new Set([agent.id]);
+        let top = agent;
+        for (let above = parentIn(top); above !== undefined && !seen.has(above.id); above = parentIn(top)) {
+            seen.add(above.id);
+            top = above;
+        }
+        return top.id;
+    };
+    const calls: { readonly id: string; readonly card: string }[] = [];
+    for (const agent of agents) {
+        const parent = parentIn(agent);
+        if (parent === undefined || agent.unsent === true) {
+            if (laneOf(agent) === "attention") {
+                calls.push({ id: agent.id, card: agent.id });
+            }
+        } else if (callsOwner(agent, { child: laneOf(agent), parent: laneOf(parent), parentAt: parent.updatedAt })) {
+            calls.push({ id: agent.id, card: familyOf(agent) });
+        }
+    }
+    return calls;
+};
+
+// What one fleet owes the person and how much of it is under way, as the desktop app's status bar and the sandbox
+// switcher count it: the Attention lane's cards as the board draws them (attentionCards) plus held automation wakes,
+// which lead that lane with no card of their own; and the turns producing something right now (turnWorking).
+export interface FleetAttention {
+    readonly needsYou: number;
+    readonly working: number;
+}
+
+export const fleetAttention = (agents: readonly CallerStanding[], held: readonly Pick<AutomationApproval, "id">[]): FleetAttention => ({
+    needsYou: attentionCards(agents) + held.length,
+    working: agents.filter(turnWorking).length,
+});