@openscout/protocol 0.2.61 → 0.2.63

package/dist/actors.d.ts

@@ -1,7 +1,7 @@
 import type { ActorKind, AdvertiseScope, AgentState, MetadataMap, ScoutId } from "./common.js";
 export type AgentClass = "general" | "builder" | "reviewer" | "researcher" | "operator" | "bridge" | "system";
 export type AgentCapability = "chat" | "invoke" | "deliver" | "speak" | "listen" | "bridge" | "summarize" | "review" | "execute";
-export type AgentHarness = "codex" | "claude" | "native" | "worker" | "bridge" | "http";
+export type AgentHarness = "codex" | "claude" | "native" | "worker" | "bridge" | "http" | "pi";
 export type WakePolicy = "manual" | "on_demand" | "keep_warm";
 export interface ActorIdentity {
     id: ScoutId;

package/dist/agent-identity.d.ts

@@ -1,5 +1,5 @@
 import type { ScoutId } from "./common.js";
-export type AgentIdentityDimension = "workspace" | "profile" | "harness" | "node";
+export type AgentIdentityDimension = "workspace" | "profile" | "harness" | "model" | "node";
 export interface AgentIdentity {
     raw: string;
     label: string;
@@ -8,6 +8,7 @@ export interface AgentIdentity {
     workspaceQualifier?: string;
     profile?: string;
     harness?: string;
+    model?: string;
 }
 export interface AgentIdentityCandidate {
     agentId: ScoutId;
@@ -16,6 +17,7 @@ export interface AgentIdentityCandidate {
     workspaceQualifier?: string;
     profile?: string;
     harness?: string;
+    model?: string;
     aliases?: string[];
 }
 export interface AgentIdentityInput {
@@ -24,6 +26,7 @@ export interface AgentIdentityInput {
     workspaceQualifier?: string;
     profile?: string;
     harness?: string;
+    model?: string;
 }
 export interface AgentIdentityAlias {
     alias: string;
@@ -32,6 +35,7 @@ export interface AgentIdentityAlias {
 export declare function normalizeAgentIdentitySegment(value: string): string;
 export declare const normalizeAgentSelectorSegment: typeof normalizeAgentIdentitySegment;
 export declare const SCOUT_DISPATCHER_AGENT_ID = "scout";
+export declare const OPENSCOUT_COORDINATOR_AGENT_ID = "openscout";
 export declare const BUILT_IN_AGENT_DEFINITION_IDS: ReadonlySet<string>;
 export declare function isBuiltInAgentDefinitionId(value: string | null | undefined): boolean;
 export declare function isReservedAgentDefinitionId(value: string | null | undefined): boolean;

package/dist/agent-identity.js

@@ -6,6 +6,7 @@ const DIMENSION_ALIASES = {
     persona: "profile",
     harness: "harness",
     runtime: "harness",
+    model: "model",
     node: "node",
     host: "node",
 };
@@ -25,6 +26,7 @@ export function normalizeAgentIdentitySegment(value) {
 }
 export const normalizeAgentSelectorSegment = normalizeAgentIdentitySegment;
 export const SCOUT_DISPATCHER_AGENT_ID = "scout";
+export const OPENSCOUT_COORDINATOR_AGENT_ID = "openscout";
 export const BUILT_IN_AGENT_DEFINITION_IDS = new Set([
     SCOUT_DISPATCHER_AGENT_ID,
     "builder",
@@ -54,6 +56,7 @@ function canonicalizeIdentity(input) {
         : undefined;
     const profile = input.profile ? normalizeAgentIdentitySegment(input.profile) : undefined;
     const harness = input.harness ? normalizeAgentIdentitySegment(input.harness) : undefined;
+    const model = input.model ? normalizeAgentIdentitySegment(input.model) : undefined;
     const nodeQualifier = input.nodeQualifier
         ? normalizeAgentIdentitySegment(input.nodeQualifier)
         : undefined;
@@ -65,6 +68,7 @@ function canonicalizeIdentity(input) {
         ...(workspaceQualifier ? { workspaceQualifier } : {}),
         ...(profile ? { profile } : {}),
         ...(harness ? { harness } : {}),
+        ...(model ? { model } : {}),
         ...(nodeQualifier ? { nodeQualifier } : {}),
     };
 }
@@ -96,6 +100,9 @@ function parseSegmentedIdentity(raw) {
             else if (key === "harness") {
                 next.harness = value;
             }
+            else if (key === "model") {
+                next.model = value;
+            }
             else if (key === "node") {
                 next.nodeQualifier = value;
             }
@@ -127,14 +134,60 @@ function parseSegmentedIdentity(raw) {
     }
     return constructAgentIdentity(next, { raw });
 }
+function parseShorthandIdentity(raw) {
+    const hashIndex = raw.indexOf("#");
+    const questionIndex = raw.indexOf("?");
+    if (hashIndex === -1 && questionIndex === -1) {
+        return null;
+    }
+    if (raw.indexOf("#", hashIndex + 1) !== -1 || raw.indexOf("?", questionIndex + 1) !== -1) {
+        return null;
+    }
+    if (hashIndex !== -1 && questionIndex !== -1 && questionIndex < hashIndex) {
+        return null;
+    }
+    const baseEnd = Math.min(...[hashIndex, questionIndex].filter((index) => index >= 0));
+    const base = raw.slice(0, baseEnd);
+    if (!base) {
+        return null;
+    }
+    const parsedBase = parseSegmentedIdentity(base);
+    if (!parsedBase) {
+        return null;
+    }
+    const harnessRaw = hashIndex >= 0
+        ? raw.slice(hashIndex + 1, questionIndex >= 0 ? questionIndex : raw.length)
+        : "";
+    const modelRaw = questionIndex >= 0 ? raw.slice(questionIndex + 1) : "";
+    if ((hashIndex >= 0 && !harnessRaw) || (questionIndex >= 0 && !modelRaw)) {
+        return null;
+    }
+    if (harnessRaw.includes("#") || harnessRaw.includes("?") || modelRaw.includes("#") || modelRaw.includes("?")) {
+        return null;
+    }
+    if ((parsedBase.harness && harnessRaw) || (parsedBase.model && modelRaw)) {
+        return null;
+    }
+    return constructAgentIdentity({
+        definitionId: parsedBase.definitionId,
+        nodeQualifier: parsedBase.nodeQualifier,
+        workspaceQualifier: parsedBase.workspaceQualifier,
+        profile: parsedBase.profile,
+        harness: harnessRaw || parsedBase.harness,
+        model: modelRaw || parsedBase.model,
+    }, { raw });
+}
 export function parseAgentIdentity(value) {
     const raw = trimIdentityPrefix(value);
     if (!raw) {
         return null;
     }
-    if (raw.includes("@") || raw.includes("#")) {
+    if (raw.includes("@")) {
         return null;
     }
+    if (raw.includes("#") || raw.includes("?")) {
+        return parseShorthandIdentity(raw);
+    }
     return parseSegmentedIdentity(raw);
 }
 export function formatAgentIdentity(input, options = {}) {
@@ -153,6 +206,9 @@ export function formatAgentIdentity(input, options = {}) {
     if (canonical.harness) {
         segments.push(`harness:${canonical.harness}`);
     }
+    if (canonical.model) {
+        segments.push(`model:${canonical.model}`);
+    }
     if (canonical.nodeQualifier) {
         segments.push(`node:${canonical.nodeQualifier}`);
     }
@@ -171,13 +227,14 @@ export function constructAgentIdentity(input, options = {}) {
         ...(canonical.workspaceQualifier ? { workspaceQualifier: canonical.workspaceQualifier } : {}),
         ...(canonical.profile ? { profile: canonical.profile } : {}),
         ...(canonical.harness ? { harness: canonical.harness } : {}),
+        ...(canonical.model ? { model: canonical.model } : {}),
     };
 }
 export function extractAgentIdentities(text) {
     return extractAgentMentions(text).parsed;
 }
 export function extractAgentMentions(text) {
-    const matches = Array.from(text.matchAll(/(^|\s)@([a-z0-9][a-z0-9._/:-]*)/gi));
+    const matches = Array.from(text.matchAll(/(^|[\s([{'"`])@([a-z0-9][a-z0-9._/:-]*(?:#[a-z0-9][a-z0-9._/:-]*)?(?:\?[a-z0-9][a-z0-9._/:-]*)?)(?=$|[\s)\]}",.!?:;'"`])/gi));
     const identities = new Map();
     const unparsed = [];
     for (const match of matches) {
@@ -202,6 +259,7 @@ function candidateAliases(candidate) {
         workspaceQualifier: candidate.workspaceQualifier,
         profile: candidate.profile,
         harness: candidate.harness,
+        model: candidate.model,
     });
     if (!canonical) {
         return [];
@@ -218,6 +276,9 @@ function candidateAliases(candidate) {
         canonical.harness
             ? formatAgentIdentity({ definitionId: canonical.definitionId, harness: canonical.harness })
             : "",
+        canonical.model
+            ? formatAgentIdentity({ definitionId: canonical.definitionId, model: canonical.model })
+            : "",
         canonical.nodeQualifier
             ? formatAgentIdentity({ definitionId: canonical.definitionId, nodeQualifier: canonical.nodeQualifier })
             : "",
@@ -226,7 +287,11 @@ function candidateAliases(candidate) {
     return Array.from(new Set(aliases.map((alias) => trimIdentityPrefix(alias)).filter(Boolean)));
 }
 function explicitCandidateAliases(candidate) {
-    return Array.from(new Set((candidate.aliases ?? [])
+    const canonical = candidateCanonicalIdentity(candidate);
+    const implicitAliases = canonical?.definitionId === OPENSCOUT_COORDINATOR_AGENT_ID
+        ? [SCOUT_DISPATCHER_AGENT_ID]
+        : [];
+    return Array.from(new Set([...(candidate.aliases ?? []), ...implicitAliases]
         .map((alias) => normalizeAgentIdentitySegment(trimIdentityPrefix(alias)))
         .filter(Boolean)));
 }
@@ -251,6 +316,7 @@ function candidateCanonicalIdentity(candidate) {
         workspaceQualifier: candidate.workspaceQualifier,
         profile: candidate.profile,
         harness: candidate.harness,
+        model: candidate.model,
     });
 }
 function candidateDimensionValue(candidate, dimension) {
@@ -264,8 +330,42 @@ function candidateDimensionValue(candidate, dimension) {
         return canonical.profile;
     if (dimension === "harness")
         return canonical.harness;
+    if (dimension === "model")
+        return canonical.model;
     return canonical.nodeQualifier;
 }
+function modelAliasKeys(value) {
+    const normalized = value ? normalizeAgentIdentitySegment(value) : "";
+    if (!normalized) {
+        return [];
+    }
+    const parts = normalized.split("-").filter(Boolean);
+    const aliases = new Set([normalized]);
+    if (parts.length > 1 && ["claude", "gpt", "openai", "anthropic"].includes(parts[0])) {
+        aliases.add(parts.slice(1).join("-"));
+    }
+    for (const family of ["sonnet", "opus", "haiku", "mini", "nano", "pro"]) {
+        const index = parts.indexOf(family);
+        if (index >= 0) {
+            aliases.add(family);
+            aliases.add(parts.slice(index).join("-"));
+        }
+    }
+    return Array.from(aliases).filter(Boolean);
+}
+function modelMatches(identityModel, candidate) {
+    if (!identityModel) {
+        return true;
+    }
+    return modelAliasKeys(candidate.model).includes(identityModel);
+}
+function definitionMatchesIdentity(identityDefinitionId, candidateDefinitionId) {
+    if (identityDefinitionId === candidateDefinitionId) {
+        return true;
+    }
+    return identityDefinitionId === SCOUT_DISPATCHER_AGENT_ID
+        && candidateDefinitionId === OPENSCOUT_COORDINATOR_AGENT_ID;
+}
 export function agentIdentityMatches(identity, candidate) {
     const aliasKeys = identityAliasKeys(identity);
     const candidateAliasKeys = explicitCandidateAliases(candidate).map(canonicalizeAliasValue);
@@ -278,8 +378,9 @@ export function agentIdentityMatches(identity, candidate) {
         workspaceQualifier: candidate.workspaceQualifier,
         profile: candidate.profile,
         harness: candidate.harness,
+        model: candidate.model,
     });
-    if (!canonical || identity.definitionId !== canonical.definitionId) {
+    if (!canonical || !definitionMatchesIdentity(identity.definitionId, canonical.definitionId)) {
         return false;
     }
     if (identity.nodeQualifier && identity.nodeQualifier !== canonical.nodeQualifier) {
@@ -294,6 +395,9 @@ export function agentIdentityMatches(identity, candidate) {
     if (identity.harness && identity.harness !== canonical.harness) {
         return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
     }
+    if (identity.model && !modelMatches(identity.model, candidate)) {
+        return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
+    }
     return true;
 }
 export function resolveAgentIdentity(identity, candidates) {
@@ -319,7 +423,11 @@ export function diagnoseAgentIdentity(identity, candidates) {
     if (matches.length === 0) {
         return { kind: "unknown" };
     }
-    if (!identity.nodeQualifier && !identity.workspaceQualifier && !identity.profile && !identity.harness) {
+    if (!identity.nodeQualifier
+        && !identity.workspaceQualifier
+        && !identity.profile
+        && !identity.harness
+        && !identity.model) {
         const exactIdMatch = matches.find((candidate) => normalizeAgentIdentitySegment(candidate.agentId) === identity.definitionId);
         if (exactIdMatch) {
             return { kind: "resolved", match: exactIdMatch };
@@ -366,6 +474,7 @@ function buildIdentitySubset(candidate, dimensions) {
             : {}),
         ...(dimensions.includes("profile") && canonical.profile ? { profile: canonical.profile } : {}),
         ...(dimensions.includes("harness") && canonical.harness ? { harness: canonical.harness } : {}),
+        ...(dimensions.includes("model") && canonical.model ? { model: canonical.model } : {}),
         ...(dimensions.includes("node") && canonical.nodeQualifier ? { nodeQualifier: canonical.nodeQualifier } : {}),
     });
 }
@@ -389,7 +498,7 @@ export function formatMinimalAgentIdentity(candidate, candidates, options = {})
     if (peers.length <= 1) {
         return formatAgentIdentity({ definitionId: canonical.definitionId }, options);
     }
-    const orderedDimensions = ["workspace", "profile", "harness", "node"];
+    const orderedDimensions = ["workspace", "profile", "harness", "model", "node"];
     const selectedDimensions = [];
     let remainingPeers = peers.filter((peer) => peer !== candidate);
     for (const dimension of orderedDimensions) {

package/dist/events.d.ts

@@ -27,6 +27,9 @@ export type AgentRegisteredEvent = ControlEventBase<"agent.registered", {
 export type AgentEndpointUpsertedEvent = ControlEventBase<"agent.endpoint.upserted", {
     endpoint: AgentEndpoint;
 }>;
+export type AgentEndpointDeletedEvent = ControlEventBase<"agent.endpoint.deleted", {
+    endpointId: string;
+}>;
 export type ConversationUpsertedEvent = ControlEventBase<"conversation.upserted", {
     conversation: ConversationDefinition;
 }>;
@@ -61,4 +64,4 @@ export type CollaborationEventAppendedEvent = ControlEventBase<"collaboration.ev
 export type ScoutDispatchedEvent = ControlEventBase<"scout.dispatched", {
     dispatch: ScoutDispatchRecord;
 }>;
-export type ControlEvent = NodeUpsertedEvent | ActorRegisteredEvent | AgentRegisteredEvent | AgentEndpointUpsertedEvent | ConversationUpsertedEvent | BindingUpsertedEvent | MessagePostedEvent | InvocationRequestedEvent | FlightUpdatedEvent | DeliveryPlannedEvent | DeliveryAttemptedEvent | DeliveryStateChangedEvent | CollaborationUpsertedEvent | CollaborationEventAppendedEvent | ScoutDispatchedEvent;
+export type ControlEvent = NodeUpsertedEvent | ActorRegisteredEvent | AgentRegisteredEvent | AgentEndpointUpsertedEvent | AgentEndpointDeletedEvent | ConversationUpsertedEvent | BindingUpsertedEvent | MessagePostedEvent | InvocationRequestedEvent | FlightUpdatedEvent | DeliveryPlannedEvent | DeliveryAttemptedEvent | DeliveryStateChangedEvent | CollaborationUpsertedEvent | CollaborationEventAppendedEvent | ScoutDispatchedEvent;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from "./collaboration.js";
 export * from "./messages.js";
 export * from "./invocations.js";
 export * from "./scout-dispatch.js";
+export * from "./scout-delivery.js";
 export * from "./deliveries.js";
 export * from "./transports.js";
 export * from "./events.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export * from "./collaboration.js";
 export * from "./messages.js";
 export * from "./invocations.js";
 export * from "./scout-dispatch.js";
+export * from "./scout-delivery.js";
 export * from "./deliveries.js";
 export * from "./transports.js";
 export * from "./events.js";

package/dist/scout-delivery.d.ts

@@ -0,0 +1,73 @@
+import type { ConversationDefinition } from "./conversations.js";
+import type { MetadataMap, ScoutId } from "./common.js";
+import type { FlightRecord, InvocationExecutionPreference } from "./invocations.js";
+import type { MessageRecord } from "./messages.js";
+import type { ScoutCallerContext, ScoutDispatchRecord, ScoutRoutePolicy, ScoutRouteTarget } from "./scout-dispatch.js";
+export type ScoutDeliverIntent = "tell" | "consult";
+export type ScoutDeliverRouteKind = "dm" | "channel" | "broadcast";
+export type ScoutDeliveryRemediationKind = "choose_target" | "register_target" | "wake_target" | "retry_later";
+export type ScoutDeliverRejectReason = "unknown_target" | "ambiguous_target" | "invalid_target" | "missing_target";
+export interface ScoutDeliverRequest {
+    id?: ScoutId;
+    caller?: ScoutCallerContext;
+    requesterId?: ScoutId;
+    requesterNodeId?: ScoutId;
+    body: string;
+    intent: ScoutDeliverIntent;
+    target?: ScoutRouteTarget;
+    targetLabel?: string;
+    targetAgentId?: ScoutId;
+    routePolicy?: ScoutRoutePolicy;
+    channel?: string;
+    replyToMessageId?: ScoutId;
+    speechText?: string;
+    ensureAwake?: boolean;
+    execution?: InvocationExecutionPreference;
+    createdAt?: number;
+    collaborationRecordId?: ScoutId;
+    messageMetadata?: MetadataMap;
+    invocationMetadata?: MetadataMap;
+}
+export interface ScoutDeliveryReceipt {
+    requestId: ScoutId;
+    routeKind: ScoutDeliverRouteKind;
+    requesterId: ScoutId;
+    requesterNodeId: ScoutId;
+    targetAgentId?: ScoutId;
+    targetLabel?: string;
+    conversationId: ScoutId;
+    messageId: ScoutId;
+    flightId?: ScoutId;
+    acceptedAt: number;
+}
+export interface ScoutDeliveryRemediationAction {
+    kind: ScoutDeliveryRemediationKind;
+    detail: string;
+    targetAgentId?: ScoutId;
+    targetLabel?: string;
+    dispatchId?: ScoutId;
+}
+export interface ScoutDeliverAcceptedResponse {
+    kind: "delivery";
+    accepted: true;
+    routeKind: ScoutDeliverRouteKind;
+    receipt: ScoutDeliveryReceipt;
+    conversation: ConversationDefinition;
+    message: MessageRecord;
+    targetAgentId?: ScoutId;
+    flight?: FlightRecord;
+}
+export interface ScoutDeliverQuestionResponse {
+    kind: "question";
+    accepted: false;
+    question: ScoutDispatchRecord;
+    remediation?: ScoutDeliveryRemediationAction;
+}
+export interface ScoutDeliverRejectedResponse {
+    kind: "rejected";
+    accepted: false;
+    reason: ScoutDeliverRejectReason;
+    rejection: ScoutDispatchRecord;
+    remediation?: ScoutDeliveryRemediationAction;
+}
+export type ScoutDeliverResponse = ScoutDeliverAcceptedResponse | ScoutDeliverQuestionResponse | ScoutDeliverRejectedResponse;

package/dist/scout-delivery.js

@@ -0,0 +1 @@
+export {};

package/dist/scout-dispatch.d.ts

@@ -1,9 +1,43 @@
-import type { AdvertiseScope, DeliveryTransport, ScoutId } from "./common.js";
-export type ScoutDispatchKind = "ambiguous" | "unknown" | "unparseable";
+import type { WakePolicy } from "./actors.js";
+import type { AdvertiseScope, DeliveryTransport, MetadataMap, ScoutId } from "./common.js";
+export type ScoutDispatchKind = "ambiguous" | "unknown" | "unparseable" | "unavailable";
 export type ScoutCandidateEndpointState = "online" | "offline" | "unknown";
+export type ScoutRouteTargetKind = "agent_id" | "agent_label" | "channel" | "broadcast";
+export type ScoutRouteAmbiguousPolicy = "reject" | "ask";
+export interface ScoutCallerContext {
+    actorId?: ScoutId;
+    nodeId?: ScoutId;
+    displayName?: string;
+    handle?: string;
+    currentDirectory?: string;
+    metadata?: MetadataMap;
+}
+export type ScoutRouteTarget = {
+    kind: "agent_id";
+    agentId: ScoutId;
+    value?: string;
+} | {
+    kind: "agent_label";
+    label: string;
+    value?: string;
+} | {
+    kind: "channel";
+    channel: string;
+    value?: string;
+} | {
+    kind: "broadcast";
+    value?: string;
+};
+export interface ScoutRoutePolicy {
+    preferLocalNodeId?: ScoutId;
+    ambiguous?: ScoutRouteAmbiguousPolicy;
+    allowStaleDirectId?: boolean;
+}
+export type ScoutDispatchUnavailableReason = "manual_wake_required" | "retired" | "stale_registration" | "unknown";
 export interface ScoutDispatchCandidate {
     agentId: ScoutId;
     displayName: string;
+    label: string;
     authorityNodeId?: ScoutId;
     homeNodeId?: ScoutId;
     advertiseScope?: AdvertiseScope;
@@ -15,11 +49,22 @@ export interface ScoutDispatchCandidate {
     endpointState: ScoutCandidateEndpointState;
     transport?: DeliveryTransport | null;
 }
+export interface ScoutDispatchUnavailableTarget {
+    agentId: ScoutId;
+    displayName: string;
+    reason: ScoutDispatchUnavailableReason;
+    detail: string;
+    wakePolicy?: WakePolicy | null;
+    endpointState: ScoutCandidateEndpointState;
+    transport?: DeliveryTransport | null;
+    projectRoot?: string | null;
+}
 export interface ScoutDispatchEnvelope {
     kind: ScoutDispatchKind;
     askedLabel: string;
     detail: string;
     candidates: ScoutDispatchCandidate[];
+    target?: ScoutDispatchUnavailableTarget;
     dispatchedAt: number;
     dispatcherNodeId: ScoutId;
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@openscout/protocol",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "description": "Typed protocol for the OpenScout local control plane",
   "type": "module",
   "exports": {
     ".": {
       "types": "./src/index.ts",
-      "bun": "./dist/index.js",
+      "bun": "./src/index.ts",
       "default": "./dist/index.js"
     }
   },

package/src/actors.ts

@@ -32,7 +32,8 @@ export type AgentHarness =
   | "native"
   | "worker"
   | "bridge"
-  | "http";
+  | "http"
+  | "pi";
 
 export type WakePolicy = "manual" | "on_demand" | "keep_warm";
 

package/src/agent-identity.test.ts

@@ -14,6 +14,7 @@ import {
   resolveAgentAlias,
   resolveAgentIdentity,
   resolveAgentSelector,
+  OPENSCOUT_COORDINATOR_AGENT_ID,
   SCOUT_DISPATCHER_AGENT_ID,
 } from "./agent-identity.js";
 
@@ -58,6 +59,23 @@ describe("agent identity grammar", () => {
       harness: "codex",
       nodeQualifier: "mini",
     });
+
+    expect(parseAgentIdentity("@lattices#codex?5.5")).toEqual({
+      raw: "lattices#codex?5.5",
+      label: "@lattices.harness:codex.model:5-5",
+      definitionId: "lattices",
+      harness: "codex",
+      model: "5-5",
+    });
+
+    expect(parseAgentIdentity("@lattices.main#claude?sonnet")).toEqual({
+      raw: "lattices.main#claude?sonnet",
+      label: "@lattices.main.harness:claude.model:sonnet",
+      definitionId: "lattices",
+      workspaceQualifier: "main",
+      harness: "claude",
+      model: "sonnet",
+    });
   });
 
   test("parses 3-segment positional as definitionId.workspaceQualifier.nodeQualifier", () => {
@@ -72,6 +90,8 @@ describe("agent identity grammar", () => {
     expect(parseAgentIdentity("")).toBeNull();
     expect(parseAgentIdentity("@arc.profile:")).toBeNull();
     expect(parseAgentIdentity("@arc@mini#main")).toBeNull();
+    expect(parseAgentIdentity("@arc#")).toBeNull();
+    expect(parseAgentIdentity("@arc?sonnet#claude")).toBeNull();
     expect(parseAgentIdentity("@arc.a.b.c")).toBeNull(); // 3+ positionals rejected
   });
 
@@ -81,14 +101,16 @@ describe("agent identity grammar", () => {
       workspaceQualifier: "Super Refactor",
       profile: "Dev Browser",
       harness: "Claude",
+      model: "GPT-5.5",
       nodeQualifier: "Mini.local",
     })).toEqual({
-      raw: "arc.super-refactor.profile:dev-browser.harness:claude.node:mini-local",
-      label: "@arc.super-refactor.profile:dev-browser.harness:claude.node:mini-local",
+      raw: "arc.super-refactor.profile:dev-browser.harness:claude.model:gpt-5-5.node:mini-local",
+      label: "@arc.super-refactor.profile:dev-browser.harness:claude.model:gpt-5-5.node:mini-local",
       definitionId: "arc",
       workspaceQualifier: "super-refactor",
       profile: "dev-browser",
       harness: "claude",
+      model: "gpt-5-5",
       nodeQualifier: "mini-local",
     });
   });
@@ -99,13 +121,14 @@ describe("agent identity grammar", () => {
       workspaceQualifier: "main",
       profile: "dev-browser",
       harness: "claude",
+      model: "sonnet",
       nodeQualifier: "mini",
-    })).toBe("@arc.main.profile:dev-browser.harness:claude.node:mini");
+    })).toBe("@arc.main.profile:dev-browser.harness:claude.model:sonnet.node:mini");
   });
 
   test("extracts unique identities from text", () => {
     expect(extractAgentIdentities(
-      "Compare @arc.main.profile:dev-browser with @hudson, then ping @arc.main.profile:dev-browser.",
+      "Compare @arc.main.profile:dev-browser with @hudson, then ping @arc.main.profile:dev-browser and @lattices#codex?5.5.",
     )).toEqual([
       {
         raw: "arc.main.profile:dev-browser",
@@ -119,6 +142,13 @@ describe("agent identity grammar", () => {
         label: "@hudson",
         definitionId: "hudson",
       },
+      {
+        raw: "lattices#codex?5.5",
+        label: "@lattices.harness:codex.model:5-5",
+        definitionId: "lattices",
+        harness: "codex",
+        model: "5-5",
+      },
     ]);
   });
 
@@ -202,6 +232,27 @@ describe("agent identity resolution", () => {
       harness: "codex",
       nodeQualifier: "backup-mac-mini",
     },
+    {
+      agentId: "lattices.codex-55",
+      definitionId: "lattices",
+      workspaceQualifier: "main",
+      harness: "codex",
+      model: "gpt-5.5",
+    },
+    {
+      agentId: "lattices.codex-54",
+      definitionId: "lattices",
+      workspaceQualifier: "main",
+      harness: "codex",
+      model: "gpt-5.4",
+    },
+    {
+      agentId: "lattices.sonnet",
+      definitionId: "lattices",
+      workspaceQualifier: "main",
+      harness: "claude",
+      model: "claude-sonnet-4-6",
+    },
   ];
 
   test("prefers explicit default aliases for bare identities", () => {
@@ -240,6 +291,16 @@ describe("agent identity resolution", () => {
     expect(resolveAgentIdentity(identity!, candidates)).toEqual(candidates[3]);
   });
 
+  test("resolves shorthand harness and model qualifiers", () => {
+    const codex = parseAgentIdentity("@lattices#codex?5.5");
+    expect(codex).not.toBeNull();
+    expect(resolveAgentIdentity(codex!, candidates)).toEqual(candidates[6]);
+
+    const sonnet = parseAgentIdentity("@lattices#claude?sonnet");
+    expect(sonnet).not.toBeNull();
+    expect(resolveAgentIdentity(sonnet!, candidates)).toEqual(candidates[8]);
+  });
+
   test("resolves aliases through the explicit alias table", () => {
     const identity = resolveAgentAlias("@huddy", [
       {
@@ -278,6 +339,7 @@ describe("agent identity resolution", () => {
 describe("scout dispatcher reservation", () => {
   test("reserves the scout definition id", () => {
     expect(SCOUT_DISPATCHER_AGENT_ID).toBe("scout");
+    expect(OPENSCOUT_COORDINATOR_AGENT_ID).toBe("openscout");
     expect(isReservedAgentDefinitionId("scout")).toBe(true);
     expect(isReservedAgentDefinitionId("Scout")).toBe(true);
     expect(isReservedAgentDefinitionId("SCOUT ")).toBe(true);
@@ -287,6 +349,31 @@ describe("scout dispatcher reservation", () => {
     expect(isReservedAgentDefinitionId(null)).toBe(false);
     expect(isReservedAgentDefinitionId(undefined)).toBe(false);
   });
+
+  test("resolves @scout to the stable OpenScout coordinator", () => {
+    const identity = parseAgentIdentity("@scout");
+    expect(identity).not.toBeNull();
+    const candidates = [
+      {
+        agentId: "openscout.main.mini",
+        definitionId: "openscout",
+        nodeQualifier: "mini",
+        workspaceQualifier: "main",
+      },
+      {
+        agentId: "ranger.main.mini",
+        definitionId: "ranger",
+        nodeQualifier: "mini",
+        workspaceQualifier: "main",
+      },
+    ];
+    const result = diagnoseAgentIdentity(identity!, candidates);
+    expect(result.kind).toBe("resolved");
+    if (result.kind === "resolved") {
+      expect(result.match.agentId).toBe("openscout.main.mini");
+    }
+    expect(formatMinimalAgentIdentity(candidates[0]!, candidates)).toBe("@scout");
+  });
 });
 
 describe("agent identity diagnosis", () => {

package/src/agent-identity.ts

@@ -1,6 +1,6 @@
 import type { ScoutId } from "./common.js";
 
-export type AgentIdentityDimension = "workspace" | "profile" | "harness" | "node";
+export type AgentIdentityDimension = "workspace" | "profile" | "harness" | "model" | "node";
 
 export interface AgentIdentity {
   raw: string;
@@ -10,6 +10,7 @@ export interface AgentIdentity {
   workspaceQualifier?: string;
   profile?: string;
   harness?: string;
+  model?: string;
 }
 
 export interface AgentIdentityCandidate {
@@ -19,6 +20,7 @@ export interface AgentIdentityCandidate {
   workspaceQualifier?: string;
   profile?: string;
   harness?: string;
+  model?: string;
   aliases?: string[];
 }
 
@@ -28,6 +30,7 @@ export interface AgentIdentityInput {
   workspaceQualifier?: string;
   profile?: string;
   harness?: string;
+  model?: string;
 }
 
 export interface AgentIdentityAlias {
@@ -43,6 +46,7 @@ const DIMENSION_ALIASES: Record<string, AgentIdentityDimension> = {
   persona: "profile",
   harness: "harness",
   runtime: "harness",
+  model: "model",
   node: "node",
   host: "node",
 };
@@ -66,6 +70,7 @@ export function normalizeAgentIdentitySegment(value: string): string {
 export const normalizeAgentSelectorSegment = normalizeAgentIdentitySegment;
 
 export const SCOUT_DISPATCHER_AGENT_ID = "scout";
+export const OPENSCOUT_COORDINATOR_AGENT_ID = "openscout";
 
 export const BUILT_IN_AGENT_DEFINITION_IDS: ReadonlySet<string> = new Set([
   SCOUT_DISPATCHER_AGENT_ID,
@@ -99,6 +104,7 @@ function canonicalizeIdentity(input: AgentIdentityInput): AgentIdentityInput | n
     : undefined;
   const profile = input.profile ? normalizeAgentIdentitySegment(input.profile) : undefined;
   const harness = input.harness ? normalizeAgentIdentitySegment(input.harness) : undefined;
+  const model = input.model ? normalizeAgentIdentitySegment(input.model) : undefined;
   const nodeQualifier = input.nodeQualifier
     ? normalizeAgentIdentitySegment(input.nodeQualifier)
     : undefined;
@@ -112,6 +118,7 @@ function canonicalizeIdentity(input: AgentIdentityInput): AgentIdentityInput | n
     ...(workspaceQualifier ? { workspaceQualifier } : {}),
     ...(profile ? { profile } : {}),
     ...(harness ? { harness } : {}),
+    ...(model ? { model } : {}),
     ...(nodeQualifier ? { nodeQualifier } : {}),
   };
 }
@@ -144,6 +151,8 @@ function parseSegmentedIdentity(raw: string): AgentIdentity | null {
         next.profile = value;
       } else if (key === "harness") {
         next.harness = value;
+      } else if (key === "model") {
+        next.model = value;
       } else if (key === "node") {
         next.nodeQualifier = value;
       }
@@ -173,16 +182,70 @@ function parseSegmentedIdentity(raw: string): AgentIdentity | null {
   return constructAgentIdentity(next, { raw });
 }
 
+function parseShorthandIdentity(raw: string): AgentIdentity | null {
+  const hashIndex = raw.indexOf("#");
+  const questionIndex = raw.indexOf("?");
+  if (hashIndex === -1 && questionIndex === -1) {
+    return null;
+  }
+  if (raw.indexOf("#", hashIndex + 1) !== -1 || raw.indexOf("?", questionIndex + 1) !== -1) {
+    return null;
+  }
+  if (hashIndex !== -1 && questionIndex !== -1 && questionIndex < hashIndex) {
+    return null;
+  }
+
+  const baseEnd = Math.min(
+    ...[hashIndex, questionIndex].filter((index) => index >= 0),
+  );
+  const base = raw.slice(0, baseEnd);
+  if (!base) {
+    return null;
+  }
+
+  const parsedBase = parseSegmentedIdentity(base);
+  if (!parsedBase) {
+    return null;
+  }
+
+  const harnessRaw = hashIndex >= 0
+    ? raw.slice(hashIndex + 1, questionIndex >= 0 ? questionIndex : raw.length)
+    : "";
+  const modelRaw = questionIndex >= 0 ? raw.slice(questionIndex + 1) : "";
+  if ((hashIndex >= 0 && !harnessRaw) || (questionIndex >= 0 && !modelRaw)) {
+    return null;
+  }
+  if (harnessRaw.includes("#") || harnessRaw.includes("?") || modelRaw.includes("#") || modelRaw.includes("?")) {
+    return null;
+  }
+  if ((parsedBase.harness && harnessRaw) || (parsedBase.model && modelRaw)) {
+    return null;
+  }
+
+  return constructAgentIdentity({
+    definitionId: parsedBase.definitionId,
+    nodeQualifier: parsedBase.nodeQualifier,
+    workspaceQualifier: parsedBase.workspaceQualifier,
+    profile: parsedBase.profile,
+    harness: harnessRaw || parsedBase.harness,
+    model: modelRaw || parsedBase.model,
+  }, { raw });
+}
+
 export function parseAgentIdentity(value: string): AgentIdentity | null {
   const raw = trimIdentityPrefix(value);
   if (!raw) {
     return null;
   }
 
-  if (raw.includes("@") || raw.includes("#")) {
+  if (raw.includes("@")) {
     return null;
   }
 
+  if (raw.includes("#") || raw.includes("?")) {
+    return parseShorthandIdentity(raw);
+  }
+
   return parseSegmentedIdentity(raw);
 }
 
@@ -207,6 +270,9 @@ export function formatAgentIdentity(
   if (canonical.harness) {
     segments.push(`harness:${canonical.harness}`);
   }
+  if (canonical.model) {
+    segments.push(`model:${canonical.model}`);
+  }
   if (canonical.nodeQualifier) {
     segments.push(`node:${canonical.nodeQualifier}`);
   }
@@ -231,6 +297,7 @@ export function constructAgentIdentity(
     ...(canonical.workspaceQualifier ? { workspaceQualifier: canonical.workspaceQualifier } : {}),
     ...(canonical.profile ? { profile: canonical.profile } : {}),
     ...(canonical.harness ? { harness: canonical.harness } : {}),
+    ...(canonical.model ? { model: canonical.model } : {}),
   };
 }
 
@@ -240,7 +307,7 @@ export function extractAgentIdentities(text: string): AgentIdentity[] {
 
 export function extractAgentMentions(text: string): { parsed: AgentIdentity[]; unparsed: string[] } {
   const matches = Array.from(
-    text.matchAll(/(^|\s)@([a-z0-9][a-z0-9._/:-]*)/gi),
+    text.matchAll(/(^|[\s([{'"`])@([a-z0-9][a-z0-9._/:-]*(?:#[a-z0-9][a-z0-9._/:-]*)?(?:\?[a-z0-9][a-z0-9._/:-]*)?)(?=$|[\s)\]}",.!?:;'"`])/gi),
   );
   const identities = new Map<string, AgentIdentity>();
   const unparsed: string[] = [];
@@ -269,6 +336,7 @@ function candidateAliases(candidate: AgentIdentityCandidate): string[] {
     workspaceQualifier: candidate.workspaceQualifier,
     profile: candidate.profile,
     harness: candidate.harness,
+    model: candidate.model,
   });
   if (!canonical) {
     return [];
@@ -286,6 +354,9 @@ function candidateAliases(candidate: AgentIdentityCandidate): string[] {
     canonical.harness
       ? formatAgentIdentity({ definitionId: canonical.definitionId, harness: canonical.harness })
       : "",
+    canonical.model
+      ? formatAgentIdentity({ definitionId: canonical.definitionId, model: canonical.model })
+      : "",
     canonical.nodeQualifier
       ? formatAgentIdentity({ definitionId: canonical.definitionId, nodeQualifier: canonical.nodeQualifier })
       : "",
@@ -296,8 +367,12 @@ function candidateAliases(candidate: AgentIdentityCandidate): string[] {
 }
 
 function explicitCandidateAliases(candidate: AgentIdentityCandidate): string[] {
+  const canonical = candidateCanonicalIdentity(candidate);
+  const implicitAliases = canonical?.definitionId === OPENSCOUT_COORDINATOR_AGENT_ID
+    ? [SCOUT_DISPATCHER_AGENT_ID]
+    : [];
   return Array.from(new Set(
-    (candidate.aliases ?? [])
+    [...(candidate.aliases ?? []), ...implicitAliases]
       .map((alias) => normalizeAgentIdentitySegment(trimIdentityPrefix(alias)))
       .filter(Boolean),
   ));
@@ -327,6 +402,7 @@ function candidateCanonicalIdentity(candidate: AgentIdentityCandidate): AgentIde
     workspaceQualifier: candidate.workspaceQualifier,
     profile: candidate.profile,
     harness: candidate.harness,
+    model: candidate.model,
   });
 }
 
@@ -342,9 +418,55 @@ function candidateDimensionValue(
   if (dimension === "workspace") return canonical.workspaceQualifier;
   if (dimension === "profile") return canonical.profile;
   if (dimension === "harness") return canonical.harness;
+  if (dimension === "model") return canonical.model;
   return canonical.nodeQualifier;
 }
 
+function modelAliasKeys(value: string | undefined): string[] {
+  const normalized = value ? normalizeAgentIdentitySegment(value) : "";
+  if (!normalized) {
+    return [];
+  }
+
+  const parts = normalized.split("-").filter(Boolean);
+  const aliases = new Set<string>([normalized]);
+  if (parts.length > 1 && ["claude", "gpt", "openai", "anthropic"].includes(parts[0]!)) {
+    aliases.add(parts.slice(1).join("-"));
+  }
+
+  for (const family of ["sonnet", "opus", "haiku", "mini", "nano", "pro"]) {
+    const index = parts.indexOf(family);
+    if (index >= 0) {
+      aliases.add(family);
+      aliases.add(parts.slice(index).join("-"));
+    }
+  }
+
+  return Array.from(aliases).filter(Boolean);
+}
+
+function modelMatches(
+  identityModel: string | undefined,
+  candidate: AgentIdentityCandidate,
+): boolean {
+  if (!identityModel) {
+    return true;
+  }
+  return modelAliasKeys(candidate.model).includes(identityModel);
+}
+
+function definitionMatchesIdentity(
+  identityDefinitionId: string,
+  candidateDefinitionId: string,
+): boolean {
+  if (identityDefinitionId === candidateDefinitionId) {
+    return true;
+  }
+
+  return identityDefinitionId === SCOUT_DISPATCHER_AGENT_ID
+    && candidateDefinitionId === OPENSCOUT_COORDINATOR_AGENT_ID;
+}
+
 export function agentIdentityMatches(
   identity: AgentIdentity,
   candidate: AgentIdentityCandidate,
@@ -361,8 +483,9 @@ export function agentIdentityMatches(
     workspaceQualifier: candidate.workspaceQualifier,
     profile: candidate.profile,
     harness: candidate.harness,
+    model: candidate.model,
   });
-  if (!canonical || identity.definitionId !== canonical.definitionId) {
+  if (!canonical || !definitionMatchesIdentity(identity.definitionId, canonical.definitionId)) {
     return false;
   }
 
@@ -378,6 +501,9 @@ export function agentIdentityMatches(
   if (identity.harness && identity.harness !== canonical.harness) {
     return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
   }
+  if (identity.model && !modelMatches(identity.model, candidate)) {
+    return candidateAliases(candidate).includes(trimIdentityPrefix(identity.label));
+  }
 
   return true;
 }
@@ -419,7 +545,13 @@ export function diagnoseAgentIdentity<T extends AgentIdentityCandidate>(
     return { kind: "unknown" };
   }
 
-  if (!identity.nodeQualifier && !identity.workspaceQualifier && !identity.profile && !identity.harness) {
+  if (
+    !identity.nodeQualifier
+    && !identity.workspaceQualifier
+    && !identity.profile
+    && !identity.harness
+    && !identity.model
+  ) {
     const exactIdMatch = matches.find(
       (candidate) => normalizeAgentIdentitySegment(candidate.agentId) === identity.definitionId,
     );
@@ -491,6 +623,7 @@ function buildIdentitySubset(
       : {}),
     ...(dimensions.includes("profile") && canonical.profile ? { profile: canonical.profile } : {}),
     ...(dimensions.includes("harness") && canonical.harness ? { harness: canonical.harness } : {}),
+    ...(dimensions.includes("model") && canonical.model ? { model: canonical.model } : {}),
     ...(dimensions.includes("node") && canonical.nodeQualifier ? { nodeQualifier: canonical.nodeQualifier } : {}),
   });
 }
@@ -523,7 +656,7 @@ export function formatMinimalAgentIdentity<T extends AgentIdentityCandidate>(
     return formatAgentIdentity({ definitionId: canonical.definitionId }, options);
   }
 
-  const orderedDimensions: AgentIdentityDimension[] = ["workspace", "profile", "harness", "node"];
+  const orderedDimensions: AgentIdentityDimension[] = ["workspace", "profile", "harness", "model", "node"];
   const selectedDimensions: AgentIdentityDimension[] = [];
   let remainingPeers = peers.filter((peer) => peer !== candidate);
 

package/src/events.ts

@@ -33,6 +33,10 @@ export type AgentEndpointUpsertedEvent = ControlEventBase<"agent.endpoint.upsert
   endpoint: AgentEndpoint;
 }>;
 
+export type AgentEndpointDeletedEvent = ControlEventBase<"agent.endpoint.deleted", {
+  endpointId: string;
+}>;
+
 export type ConversationUpsertedEvent = ControlEventBase<"conversation.upserted", {
   conversation: ConversationDefinition;
 }>;
@@ -83,6 +87,7 @@ export type ControlEvent =
   | ActorRegisteredEvent
   | AgentRegisteredEvent
   | AgentEndpointUpsertedEvent
+  | AgentEndpointDeletedEvent
   | ConversationUpsertedEvent
   | BindingUpsertedEvent
   | MessagePostedEvent

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./collaboration.js";
 export * from "./messages.js";
 export * from "./invocations.js";
 export * from "./scout-dispatch.js";
+export * from "./scout-delivery.js";
 export * from "./deliveries.js";
 export * from "./transports.js";
 export * from "./events.js";

package/src/scout-delivery.ts

@@ -0,0 +1,100 @@
+import type { ConversationDefinition } from "./conversations.js";
+import type { MetadataMap, ScoutId } from "./common.js";
+import type { FlightRecord, InvocationExecutionPreference } from "./invocations.js";
+import type { MessageRecord } from "./messages.js";
+import type {
+  ScoutCallerContext,
+  ScoutDispatchRecord,
+  ScoutRoutePolicy,
+  ScoutRouteTarget,
+} from "./scout-dispatch.js";
+
+export type ScoutDeliverIntent = "tell" | "consult";
+
+export type ScoutDeliverRouteKind = "dm" | "channel" | "broadcast";
+
+export type ScoutDeliveryRemediationKind =
+  | "choose_target"
+  | "register_target"
+  | "wake_target"
+  | "retry_later";
+
+export type ScoutDeliverRejectReason =
+  | "unknown_target"
+  | "ambiguous_target"
+  | "invalid_target"
+  | "missing_target";
+
+export interface ScoutDeliverRequest {
+  id?: ScoutId;
+  caller?: ScoutCallerContext;
+  requesterId?: ScoutId;
+  requesterNodeId?: ScoutId;
+  body: string;
+  intent: ScoutDeliverIntent;
+  target?: ScoutRouteTarget;
+  targetLabel?: string;
+  targetAgentId?: ScoutId;
+  routePolicy?: ScoutRoutePolicy;
+  channel?: string;
+  replyToMessageId?: ScoutId;
+  speechText?: string;
+  ensureAwake?: boolean;
+  execution?: InvocationExecutionPreference;
+  createdAt?: number;
+  collaborationRecordId?: ScoutId;
+  messageMetadata?: MetadataMap;
+  invocationMetadata?: MetadataMap;
+}
+
+export interface ScoutDeliveryReceipt {
+  requestId: ScoutId;
+  routeKind: ScoutDeliverRouteKind;
+  requesterId: ScoutId;
+  requesterNodeId: ScoutId;
+  targetAgentId?: ScoutId;
+  targetLabel?: string;
+  conversationId: ScoutId;
+  messageId: ScoutId;
+  flightId?: ScoutId;
+  acceptedAt: number;
+}
+
+export interface ScoutDeliveryRemediationAction {
+  kind: ScoutDeliveryRemediationKind;
+  detail: string;
+  targetAgentId?: ScoutId;
+  targetLabel?: string;
+  dispatchId?: ScoutId;
+}
+
+export interface ScoutDeliverAcceptedResponse {
+  kind: "delivery";
+  accepted: true;
+  routeKind: ScoutDeliverRouteKind;
+  receipt: ScoutDeliveryReceipt;
+  conversation: ConversationDefinition;
+  message: MessageRecord;
+  targetAgentId?: ScoutId;
+  flight?: FlightRecord;
+}
+
+export interface ScoutDeliverQuestionResponse {
+  kind: "question";
+  accepted: false;
+  question: ScoutDispatchRecord;
+  remediation?: ScoutDeliveryRemediationAction;
+}
+
+export interface ScoutDeliverRejectedResponse {
+  kind: "rejected";
+  accepted: false;
+  reason: ScoutDeliverRejectReason;
+  rejection: ScoutDispatchRecord;
+  remediation?: ScoutDeliveryRemediationAction;
+}
+
+export type ScoutDeliverResponse =
+  | ScoutDeliverAcceptedResponse
+  | ScoutDeliverQuestionResponse
+  | ScoutDeliverRejectedResponse;

package/src/scout-dispatch.ts

@@ -1,12 +1,45 @@
-import type { AdvertiseScope, DeliveryTransport, ScoutId } from "./common.js";
+import type { WakePolicy } from "./actors.js";
+import type { AdvertiseScope, DeliveryTransport, MetadataMap, ScoutId } from "./common.js";
 
-export type ScoutDispatchKind = "ambiguous" | "unknown" | "unparseable";
+export type ScoutDispatchKind = "ambiguous" | "unknown" | "unparseable" | "unavailable";
 
 export type ScoutCandidateEndpointState = "online" | "offline" | "unknown";
 
+export type ScoutRouteTargetKind = "agent_id" | "agent_label" | "channel" | "broadcast";
+
+export type ScoutRouteAmbiguousPolicy = "reject" | "ask";
+
+export interface ScoutCallerContext {
+  actorId?: ScoutId;
+  nodeId?: ScoutId;
+  displayName?: string;
+  handle?: string;
+  currentDirectory?: string;
+  metadata?: MetadataMap;
+}
+
+export type ScoutRouteTarget =
+  | { kind: "agent_id"; agentId: ScoutId; value?: string }
+  | { kind: "agent_label"; label: string; value?: string }
+  | { kind: "channel"; channel: string; value?: string }
+  | { kind: "broadcast"; value?: string };
+
+export interface ScoutRoutePolicy {
+  preferLocalNodeId?: ScoutId;
+  ambiguous?: ScoutRouteAmbiguousPolicy;
+  allowStaleDirectId?: boolean;
+}
+
+export type ScoutDispatchUnavailableReason =
+  | "manual_wake_required"
+  | "retired"
+  | "stale_registration"
+  | "unknown";
+
 export interface ScoutDispatchCandidate {
   agentId: ScoutId;
   displayName: string;
+  label: string;
   authorityNodeId?: ScoutId;
   homeNodeId?: ScoutId;
   advertiseScope?: AdvertiseScope;
@@ -19,11 +52,23 @@ export interface ScoutDispatchCandidate {
   transport?: DeliveryTransport | null;
 }
 
+export interface ScoutDispatchUnavailableTarget {
+  agentId: ScoutId;
+  displayName: string;
+  reason: ScoutDispatchUnavailableReason;
+  detail: string;
+  wakePolicy?: WakePolicy | null;
+  endpointState: ScoutCandidateEndpointState;
+  transport?: DeliveryTransport | null;
+  projectRoot?: string | null;
+}
+
 export interface ScoutDispatchEnvelope {
   kind: ScoutDispatchKind;
   askedLabel: string;
   detail: string;
   candidates: ScoutDispatchCandidate[];
+  target?: ScoutDispatchUnavailableTarget;
   dispatchedAt: number;
   dispatcherNodeId: ScoutId;
 }