@pinet/broker-core 0.1.2 → 0.2.1

package/dist/agent-messaging.d.ts

@@ -17,6 +17,7 @@ export interface DirectAgentDispatchInput {
     target: string;
     body: string;
     metadata?: Record<string, unknown>;
+    trustedBrokerAgentId?: string;
 }
 export interface BroadcastAgentDispatchInput {
     senderAgentId: string;

package/dist/agent-messaging.js

@@ -128,17 +128,66 @@ export function resolveDirectAgentTarget(agents, target) {
         agents.find((agent) => agent.name === target) ??
         null);
 }
+function isDescendantOf(agents, descendantId, ancestorId) {
+    let current = agents.find((agent) => agent.id === descendantId) ?? null;
+    const seen = new Set();
+    while (current?.parentAgentId) {
+        if (current.parentAgentId === ancestorId)
+            return true;
+        if (seen.has(current.parentAgentId))
+            return false;
+        seen.add(current.parentAgentId);
+        current = agents.find((agent) => agent.id === current?.parentAgentId) ?? null;
+    }
+    return false;
+}
+function canDispatchDirectAgentMessage(agents, sender, target, metadata) {
+    if (!sender)
+        return false;
+    if (!target.parentAgentId &&
+        target.supervisionState !== "supervised" &&
+        target.supervisionState !== "orphaned" &&
+        target.supervisionState !== "stopping") {
+        return true;
+    }
+    if (sender.id === metadata?.trustedBrokerAgentId) {
+        return metadata.emergency === true || metadata.targetScope === "subtree";
+    }
+    if (target.parentAgentId === sender.id)
+        return true;
+    if (sender.parentAgentId === target.id)
+        return true;
+    if (isDescendantOf(agents, target.id, sender.id))
+        return true;
+    if (isDescendantOf(agents, sender.id, target.id))
+        return true;
+    return false;
+}
 export function resolveBroadcastTargets(agents, senderAgentId, channel) {
     return agents
         .filter((agent) => agent.id !== senderAgentId)
+        .filter((agent) => !agent.parentAgentId &&
+        agent.supervisionState !== "supervised" &&
+        agent.supervisionState !== "orphaned" &&
+        agent.supervisionState !== "stopping")
         .filter((agent) => agentSubscribesToBroadcastChannel(agent, channel))
         .sort((left, right) => left.name.localeCompare(right.name));
 }
 export function dispatchDirectAgentMessage(storage, input, onDispatch) {
-    const target = resolveDirectAgentTarget(storage.getAgents(), input.target);
+    const agents = storage.getAgents();
+    const target = resolveDirectAgentTarget(agents, input.target);
     if (!target) {
         throw new Error(`Agent not found: ${input.target}`);
     }
+    const sender = agents.find((agent) => agent.id === input.senderAgentId) ?? null;
+    const policyMetadata = { ...(input.metadata ?? {}) };
+    delete policyMetadata.trustedBrokerAgentId;
+    if (input.trustedBrokerAgentId) {
+        policyMetadata.trustedBrokerAgentId = input.trustedBrokerAgentId;
+    }
+    if (!canDispatchDirectAgentMessage(agents, sender, target, policyMetadata)) {
+        throw new Error(`Agent ${input.senderAgentId} cannot message supervised agent ${target.id} without parent/subtree visibility or an explicit broker emergency override.`);
+    }
     const resolvedTarget = { id: target.id, name: target.name };
     const metadata = buildAgentMessageMetadata(input.senderAgentName, input.body, input.metadata);
     const { threadId, messageId } = deliverAgentMessage(storage, input.senderAgentId, resolvedTarget, input.body, metadata, onDispatch);

package/dist/maintenance.js

@@ -32,7 +32,11 @@ export function runBrokerMaintenancePass(db, options) {
     const agents = db
         .getAgents()
         .filter((agent) => agent.id !== brokerAgentId)
-        .filter((agent) => agent.metadata?.role !== "broker");
+        .filter((agent) => agent.metadata?.role !== "broker")
+        .filter((agent) => !agent.parentAgentId &&
+        agent.supervisionState !== "supervised" &&
+        agent.supervisionState !== "orphaned" &&
+        agent.supervisionState !== "stopping");
     const agentLoads = agents.map((agent) => ({
         agent,
         pendingInboxCount: db.getPendingInboxCount(agent.id),
@@ -53,7 +57,7 @@ export function runBrokerMaintenancePass(db, options) {
             continue;
         }
         const preferredAgent = backlog.preferredAgentId
-            ? (agents.find((agent) => agent.id === backlog.preferredAgentId) ?? null)
+            ? (db.getAgents().find((agent) => agent.id === backlog.preferredAgentId) ?? null)
             : null;
         if (backlog.preferredAgentId && !preferredAgent) {
             const knownPreferredAgent = db.getAgentById(backlog.preferredAgentId);

package/dist/message-send.d.ts

@@ -1,4 +1,4 @@
-import type { BrokerMessage, MessageAdapter, NormalizedMessageContent, ThreadInfo } from "./types.js";
+import type { BrokerMessage, MessageAdapter, NormalizedMessageContent, OutboundAttachmentFile, ThreadInfo } from "./types.js";
 export interface BrokerMessageSenderDb {
     getThread(threadId: string): ThreadInfo | null;
     createThread(threadId: string, source: string, channel: string, ownerAgent: string | null): ThreadInfo;
@@ -18,6 +18,7 @@ export interface SendBrokerMessageInput {
     channel?: string;
     content?: NormalizedMessageContent;
     blocks?: ReadonlyArray<Record<string, unknown>>;
+    files?: ReadonlyArray<OutboundAttachmentFile>;
     agentName?: string;
     agentEmoji?: string;
     agentOwnerToken?: string;

package/dist/message-send.js

@@ -60,6 +60,7 @@ export async function sendBrokerMessage(deps, input) {
         text: messageBody,
         ...(content ? { content } : {}),
         ...(input.blocks && input.blocks.length > 0 ? { blocks: input.blocks } : {}),
+        ...(input.files && input.files.length > 0 ? { files: input.files } : {}),
         ...(input.agentName ? { agentName: input.agentName } : {}),
         ...(input.agentEmoji ? { agentEmoji: input.agentEmoji } : {}),
         ...(input.agentOwnerToken ? { agentOwnerToken: input.agentOwnerToken } : {}),

package/dist/schema.d.ts

@@ -12,7 +12,7 @@ export interface TaskAssignmentAwaitingReplyInfo {
 export declare function defaultDbPath(): string;
 export declare const DEFAULT_RESUMABLE_WINDOW_MS = 15000;
 export declare const DEFAULT_DISCONNECTED_PURGE_GRACE_MS: number;
-export declare const CURRENT_BROKER_SCHEMA_VERSION = 17;
+export declare const CURRENT_BROKER_SCHEMA_VERSION = 18;
 export declare class BrokerDB implements BrokerDBInterface {
     private db;
     private readonly dbPath;
@@ -27,8 +27,14 @@ export declare class BrokerDB implements BrokerDBInterface {
     reconcileStartupAgents(resumableForMs?: number): void;
     close(): void;
     registerAgent(id: string, name: string, emoji: string, pid: number, metadata?: Record<string, unknown>, stableId?: string): AgentInfo;
+    private resolveAgentHierarchy;
     unregisterAgent(id: string): void;
     disconnectAgent(id: string, resumableForMs?: number): void;
+    private getDirectChildren;
+    getAgentDescendants(parentAgentId: string, includeDisconnected?: boolean): AgentInfo[];
+    isAgentAncestor(ancestorAgentId: string, descendantAgentId: string): boolean;
+    private notifyParentOfChildExit;
+    private markDescendantsOrphaned;
     getAgentById(id: string): AgentInfo | null;
     private getCurrentSessionOutboundCount;
     private rowToAgentWithCurrentSessionOutboundCount;
@@ -127,6 +133,7 @@ export declare class BrokerDB implements BrokerDBInterface {
     private getExistingMessageIdForIdentity;
     private getMessageByExternalId;
     private getMessageById;
+    private dropStaleSlackDeliveryRows;
     private dropStaleTransportInboxRows;
     getInbox(agentId: string, limit?: number): {
         entry: InboxEntry;

package/dist/schema.js

@@ -28,6 +28,14 @@ function rowToAgent(row) {
         lastHeartbeat: row.last_heartbeat,
         metadata: row.metadata ? JSON.parse(row.metadata) : null,
         status: row.status === "working" ? "working" : "idle",
+        parentAgentId: row.parent_agent_id,
+        rootAgentId: row.root_agent_id,
+        treeDepth: row.tree_depth ?? 0,
+        spawnedByAgentId: row.spawned_by_agent_id,
+        supervisionState: normalizeAgentSupervisionState(row.supervision_state),
+        launchId: row.launch_id,
+        subtreeRole: row.subtree_role,
+        laneId: row.lane_id,
         disconnectedAt: row.disconnected_at,
         resumableUntil: row.resumable_until,
         idleSince: row.idle_since,
@@ -78,6 +86,30 @@ function getStringMetadataValue(metadata, keys) {
     return null;
 }
 const INTERNAL_AGENT_SOURCE = "agent";
+const STALE_SLACK_MESSAGE_MAX_AGE_MS = 15 * 60 * 1000;
+// Slack ts values are epoch seconds. Small fixture/sentinel values are treated
+// as ambiguous instead of stale so replay filtering only applies to plausible
+// real Slack event timestamps.
+const MIN_PLAUSIBLE_SLACK_TIMESTAMP_SECONDS = 1_000_000_000;
+function parseSlackTimestampMs(timestamp) {
+    if (!timestamp)
+        return null;
+    const seconds = Number(timestamp);
+    if (!Number.isFinite(seconds) || seconds < MIN_PLAUSIBLE_SLACK_TIMESTAMP_SECONDS) {
+        return null;
+    }
+    return Math.trunc(seconds * 1000);
+}
+function getSlackMessageAgeMs(source, timestamp, nowMs = Date.now()) {
+    if (source !== "slack")
+        return null;
+    const timestampMs = parseSlackTimestampMs(timestamp);
+    return timestampMs === null ? null : nowMs - timestampMs;
+}
+function isStaleSlackMessageTimestamp(source, timestamp, nowMs = Date.now()) {
+    const ageMs = getSlackMessageAgeMs(source, timestamp, nowMs);
+    return ageMs !== null && ageMs > STALE_SLACK_MESSAGE_MAX_AGE_MS;
+}
 function isExternalTransportSource(source) {
     return source.trim().length > 0 && source !== INTERNAL_AGENT_SOURCE;
 }
@@ -263,6 +295,26 @@ function parseMetadataJson(value) {
         return null;
     }
 }
+const AGENT_SUPERVISION_STATES = new Set([
+    "root",
+    "supervised",
+    "orphaned",
+    "stopping",
+]);
+function normalizeAgentSupervisionState(value) {
+    return typeof value === "string" && AGENT_SUPERVISION_STATES.has(value)
+        ? value
+        : "root";
+}
+function getOptionalMetadataString(metadata, keys) {
+    for (const key of keys) {
+        const value = metadata?.[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return null;
+}
 function rowToPinetLaneParticipant(row) {
     return {
         laneId: row.lane_id,
@@ -406,7 +458,7 @@ export function defaultDbPath() {
 }
 export const DEFAULT_RESUMABLE_WINDOW_MS = 15_000;
 export const DEFAULT_DISCONNECTED_PURGE_GRACE_MS = 60 * 60_000;
-export const CURRENT_BROKER_SCHEMA_VERSION = 17;
+export const CURRENT_BROKER_SCHEMA_VERSION = 18;
 const REQUIRED_AGENT_LIFECYCLE_COLUMNS = [
     "stable_id",
     "metadata",
@@ -575,6 +627,31 @@ function addObservabilityColumns(db) {
     WHERE status = 'idle' AND idle_since IS NULL;
   `);
 }
+function addAgentHierarchyColumns(db) {
+    ensureColumn(db, "agents", "parent_agent_id", "ALTER TABLE agents ADD COLUMN parent_agent_id TEXT");
+    ensureColumn(db, "agents", "root_agent_id", "ALTER TABLE agents ADD COLUMN root_agent_id TEXT");
+    ensureColumn(db, "agents", "tree_depth", "ALTER TABLE agents ADD COLUMN tree_depth INTEGER NOT NULL DEFAULT 0");
+    ensureColumn(db, "agents", "spawned_by_agent_id", "ALTER TABLE agents ADD COLUMN spawned_by_agent_id TEXT");
+    ensureColumn(db, "agents", "supervision_state", "ALTER TABLE agents ADD COLUMN supervision_state TEXT NOT NULL DEFAULT 'root'");
+    ensureColumn(db, "agents", "launch_id", "ALTER TABLE agents ADD COLUMN launch_id TEXT");
+    ensureColumn(db, "agents", "subtree_role", "ALTER TABLE agents ADD COLUMN subtree_role TEXT");
+    ensureColumn(db, "agents", "lane_id", "ALTER TABLE agents ADD COLUMN lane_id TEXT");
+    db.exec(`
+    UPDATE agents
+    SET tree_depth = COALESCE(tree_depth, 0),
+        supervision_state = COALESCE(supervision_state, 'root')
+    WHERE tree_depth IS NULL OR supervision_state IS NULL;
+
+    CREATE INDEX IF NOT EXISTS idx_agents_parent_agent_id
+      ON agents(parent_agent_id);
+    CREATE INDEX IF NOT EXISTS idx_agents_root_agent_id
+      ON agents(root_agent_id);
+    CREATE INDEX IF NOT EXISTS idx_agents_supervision_state
+      ON agents(supervision_state, parent_agent_id);
+    CREATE INDEX IF NOT EXISTS idx_agents_lane_id
+      ON agents(lane_id);
+  `);
+}
 function addThreadOwnershipBindingColumn(db) {
     createCoreTables(db);
     ensureColumn(db, "threads", "owner_binding", "ALTER TABLE threads ADD COLUMN owner_binding TEXT");
@@ -1058,6 +1135,9 @@ function runSchemaMigrations(db) {
                 case 17:
                     migrateTaskAssignmentsToRepoScopedTracking(db);
                     break;
+                case 18:
+                    addAgentHierarchyColumns(db);
+                    break;
                 default:
                     throw new Error(`Unsupported broker schema migration target: ${nextVersion}`);
             }
@@ -1153,13 +1233,16 @@ export class BrokerDB {
                 ? JSON.parse(existingRow.metadata)
                 : undefined);
         const meta = finalMetadata ? JSON.stringify(finalMetadata) : null;
+        const hierarchy = this.resolveAgentHierarchy(agentId, finalMetadata, existingRow);
         db.prepare(`INSERT INTO agents (
          id, stable_id, name, emoji, pid,
          connected_at, last_seen, last_heartbeat,
-         metadata, status, disconnected_at, resumable_until,
-         idle_since, last_activity
+         metadata, status,
+         parent_agent_id, root_agent_id, tree_depth, spawned_by_agent_id,
+         supervision_state, launch_id, subtree_role, lane_id,
+         disconnected_at, resumable_until, idle_since, last_activity
        )
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'idle', NULL, NULL, ?, NULL)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'idle', ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, NULL)
        ON CONFLICT(id) DO UPDATE SET
          stable_id = COALESCE(excluded.stable_id, agents.stable_id),
          name = excluded.name,
@@ -1170,12 +1253,21 @@ export class BrokerDB {
          last_heartbeat = excluded.last_heartbeat,
          metadata = excluded.metadata,
          status = 'idle',
+         parent_agent_id = excluded.parent_agent_id,
+         root_agent_id = excluded.root_agent_id,
+         tree_depth = excluded.tree_depth,
+         spawned_by_agent_id = excluded.spawned_by_agent_id,
+         supervision_state = excluded.supervision_state,
+         launch_id = excluded.launch_id,
+         subtree_role = excluded.subtree_role,
+         lane_id = excluded.lane_id,
          disconnected_at = NULL,
          resumable_until = NULL,
          idle_since = excluded.idle_since,
-         last_activity = NULL`).run(agentId, persistedStableId, finalName, finalEmoji, pid, now, now, now, meta, now);
+         last_activity = NULL`).run(agentId, persistedStableId, finalName, finalEmoji, pid, now, now, now, meta, hierarchy.parentAgentId, hierarchy.rootAgentId, hierarchy.treeDepth, hierarchy.spawnedByAgentId, hierarchy.supervisionState, hierarchy.launchId, hierarchy.subtreeRole, hierarchy.laneId, now);
         return {
             id: agentId,
+            stableId: persistedStableId,
             name: finalName,
             emoji: finalEmoji,
             pid,
@@ -1184,18 +1276,76 @@ export class BrokerDB {
             lastHeartbeat: now,
             metadata: finalMetadata ?? null,
             status: "idle",
+            parentAgentId: hierarchy.parentAgentId,
+            rootAgentId: hierarchy.rootAgentId,
+            treeDepth: hierarchy.treeDepth,
+            spawnedByAgentId: hierarchy.spawnedByAgentId,
+            supervisionState: hierarchy.supervisionState,
+            launchId: hierarchy.launchId,
+            subtreeRole: hierarchy.subtreeRole,
+            laneId: hierarchy.laneId,
             idleSince: now,
             lastActivity: null,
         };
     }
+    resolveAgentHierarchy(agentId, metadata, existingRow) {
+        const requestedParentId = getOptionalMetadataString(metadata, [
+            "parentAgentId",
+            "pinetParentAgentId",
+        ]);
+        const parentId = requestedParentId ?? existingRow?.parent_agent_id ?? null;
+        const parent = parentId ? this.getAgentById(parentId) : null;
+        if (parentId && (!parent || parent.disconnectedAt)) {
+            throw new Error(`Cannot register supervised Pinet agent; parent ${parentId} is not live.`);
+        }
+        if (parent && parent.id === agentId) {
+            throw new Error("Cannot register a Pinet agent as its own parent.");
+        }
+        if (parent && this.isAgentAncestor(agentId, parent.id)) {
+            throw new Error("Cannot register a Pinet agent under one of its descendants.");
+        }
+        const supervisionState = parent
+            ? "supervised"
+            : normalizeAgentSupervisionState(getOptionalMetadataString(metadata, ["supervisionState", "pinetSupervisionState"]) ??
+                existingRow?.supervision_state);
+        const rootAgentId = parent
+            ? (parent.rootAgentId ?? parent.id)
+            : (getOptionalMetadataString(metadata, ["rootAgentId", "pinetRootAgentId"]) ??
+                existingRow?.root_agent_id ??
+                null);
+        const treeDepth = parent ? (parent.treeDepth ?? 0) + 1 : (existingRow?.tree_depth ?? 0);
+        const spawnedByAgentId = getOptionalMetadataString(metadata, ["spawnedByAgentId", "pinetSpawnedByAgentId"]) ??
+            (parent ? parent.id : (existingRow?.spawned_by_agent_id ?? null));
+        return {
+            parentAgentId: parent?.id ?? null,
+            rootAgentId,
+            treeDepth,
+            spawnedByAgentId,
+            supervisionState,
+            launchId: getOptionalMetadataString(metadata, ["launchId", "pinetLaunchId"]) ??
+                existingRow?.launch_id ??
+                null,
+            subtreeRole: getOptionalMetadataString(metadata, ["subtreeRole", "pinetSubtreeRole"]) ??
+                existingRow?.subtree_role ??
+                null,
+            laneId: getOptionalMetadataString(metadata, ["laneId", "pinetLaneId"]) ??
+                existingRow?.lane_id ??
+                null,
+        };
+    }
     unregisterAgent(id) {
         const db = this.getDb();
         const now = new Date().toISOString();
         this.withTransaction(() => {
+            const agent = this.getAgentById(id);
             this.requeueUndeliveredMessagesInternal(id, "agent_disconnected");
             db.prepare("DELETE FROM inbox WHERE agent_id = ?").run(id);
             db.prepare("UPDATE agents SET disconnected_at = ?, resumable_until = NULL WHERE id = ?").run(now, id);
             db.prepare("UPDATE threads SET owner_agent = NULL WHERE owner_agent = ?").run(id);
+            if (agent?.parentAgentId) {
+                this.notifyParentOfChildExit(agent, "unregistered");
+            }
+            this.markDescendantsOrphaned(id, "parent_unregistered");
         });
     }
     disconnectAgent(id, resumableForMs = DEFAULT_RESUMABLE_WINDOW_MS) {
@@ -1204,6 +1354,85 @@ export class BrokerDB {
         const resumableUntil = new Date(now.getTime() + resumableForMs).toISOString();
         db.prepare("UPDATE agents SET disconnected_at = ?, resumable_until = ? WHERE id = ?").run(now.toISOString(), resumableUntil, id);
     }
+    getDirectChildren(parentAgentId) {
+        const rows = this.getDb()
+            .prepare("SELECT * FROM agents WHERE parent_agent_id = ? ORDER BY connected_at ASC")
+            .all(parentAgentId);
+        return rows.map(rowToAgent);
+    }
+    getAgentDescendants(parentAgentId, includeDisconnected = false) {
+        const descendants = [];
+        const seen = new Set();
+        const queue = this.getDirectChildren(parentAgentId);
+        while (queue.length > 0) {
+            const child = queue.shift();
+            if (!child || seen.has(child.id))
+                continue;
+            seen.add(child.id);
+            if (includeDisconnected || !child.disconnectedAt) {
+                descendants.push(child);
+            }
+            queue.push(...this.getDirectChildren(child.id));
+        }
+        return descendants;
+    }
+    isAgentAncestor(ancestorAgentId, descendantAgentId) {
+        let current = this.getAgentById(descendantAgentId);
+        const seen = new Set();
+        while (current?.parentAgentId) {
+            if (current.parentAgentId === ancestorAgentId)
+                return true;
+            if (seen.has(current.parentAgentId))
+                return false;
+            seen.add(current.parentAgentId);
+            current = this.getAgentById(current.parentAgentId);
+        }
+        return false;
+    }
+    notifyParentOfChildExit(agent, reason) {
+        const parentId = agent.parentAgentId;
+        if (!parentId)
+            return;
+        const parent = this.getAgentById(parentId);
+        if (!parent || parent.disconnectedAt)
+            return;
+        const threadId = `a2a:${agent.id}:${parentId}`;
+        this.createThread(threadId, "agent", `agent:${parentId}`, parentId);
+        this.insertMessage(threadId, "agent", "inbound", agent.id, `Child worker ${agent.name} (${agent.id}) exited: ${reason}.`, [parentId], {
+            a2a: true,
+            senderAgent: agent.name,
+            pinetMailClass: "fwup",
+            subtree: true,
+            childAgentId: agent.id,
+            parentAgentId: parentId,
+            lifecycle: "child_exit",
+            reason,
+        });
+    }
+    markDescendantsOrphaned(parentAgentId, reason) {
+        const descendants = this.getAgentDescendants(parentAgentId, true);
+        if (descendants.length === 0)
+            return;
+        const db = this.getDb();
+        const update = db.prepare("UPDATE agents SET supervision_state = 'orphaned', parent_agent_id = NULL WHERE id = ?");
+        for (const child of descendants) {
+            update.run(child.id);
+            if (!child.disconnectedAt) {
+                const threadId = `a2a:${parentAgentId}:${child.id}`;
+                this.createThread(threadId, "agent", `agent:${child.id}`, child.id);
+                this.insertMessage(threadId, "agent", "inbound", parentAgentId, `Parent worker ${parentAgentId} is no longer supervising this subtree (${reason}); this worker is now orphaned and should stop or await broker recovery instructions.`, [child.id], {
+                    a2a: true,
+                    senderAgent: "Pinet lifecycle",
+                    pinetMailClass: "steering",
+                    subtree: true,
+                    parentAgentId,
+                    childAgentId: child.id,
+                    lifecycle: "parent_orphaned_child",
+                    reason,
+                });
+            }
+        }
+    }
     getAgentById(id) {
         const row = this.getAgentRowById(id);
         return row ? rowToAgent(row) : null;
@@ -1469,7 +1698,7 @@ export class BrokerDB {
         const now = new Date().toISOString();
         return this.withTransaction(() => {
             const staleRows = db
-                .prepare(`SELECT id FROM agents
+                .prepare(`SELECT * FROM agents
            WHERE (disconnected_at IS NULL AND last_heartbeat <= ?)
               OR (disconnected_at IS NOT NULL AND resumable_until IS NOT NULL AND resumable_until <= ?)`)
                 .all(cutoff, now);
@@ -1479,9 +1708,14 @@ export class BrokerDB {
             const disconnectAgent = db.prepare("UPDATE agents SET disconnected_at = COALESCE(disconnected_at, ?), resumable_until = NULL WHERE id = ?");
             const releaseClaims = db.prepare("UPDATE threads SET owner_agent = NULL WHERE owner_agent = ?");
             for (const row of staleRows) {
+                const agent = rowToAgent(row);
                 this.requeueUndeliveredMessagesInternal(row.id, "agent_disconnected");
                 disconnectAgent.run(now, row.id);
                 releaseClaims.run(row.id);
+                if (agent.parentAgentId) {
+                    this.notifyParentOfChildExit(agent, "stale_heartbeat");
+                }
+                this.markDescendantsOrphaned(row.id, "parent_stale");
             }
             return staleRows.map((row) => row.id);
         });
@@ -1493,7 +1727,7 @@ export class BrokerDB {
         const cutoff = new Date(now - graceMs).toISOString();
         return this.withTransaction(() => {
             const rows = db
-                .prepare(`SELECT id FROM agents
+                .prepare(`SELECT * FROM agents
            WHERE disconnected_at IS NOT NULL
              AND disconnected_at <= ?
              AND (resumable_until IS NULL OR resumable_until <= ?)`)
@@ -1504,12 +1738,17 @@ export class BrokerDB {
             const releaseThreads = db.prepare("UPDATE threads SET owner_agent = NULL WHERE owner_agent = ?");
             const deleteInbox = db.prepare("DELETE FROM inbox WHERE agent_id = ?");
             for (const row of rows) {
+                const agent = rowToAgent(row);
                 // Requeue undelivered messages to the backlog
                 this.requeueUndeliveredMessagesInternal(row.id, "agent_disconnected");
                 // Release thread ownership for the purged agent
                 releaseThreads.run(row.id);
                 // Clean up all inbox entries (both delivered and undelivered) for the agent
                 deleteInbox.run(row.id);
+                if (agent.parentAgentId) {
+                    this.notifyParentOfChildExit(agent, "purged");
+                }
+                this.markDescendantsOrphaned(row.id, "parent_purged");
             }
             db.prepare(`DELETE FROM agents
          WHERE disconnected_at IS NOT NULL
@@ -1779,6 +2018,7 @@ export class BrokerDB {
         return rows.map(rowToThread);
     }
     getPendingBacklog(limit = 50) {
+        this.dropStaleSlackDeliveryRows();
         const db = this.getDb();
         const rows = db
             .prepare(`SELECT * FROM unrouted_backlog
@@ -1789,6 +2029,9 @@ export class BrokerDB {
         return rows.map(rowToBacklog);
     }
     getBacklogCount(status = "pending") {
+        if (status === "pending") {
+            this.dropStaleSlackDeliveryRows();
+        }
         const db = this.getDb();
         const row = db
             .prepare("SELECT COUNT(*) AS count FROM unrouted_backlog WHERE status = ?")
@@ -1825,6 +2068,7 @@ export class BrokerDB {
     assignBacklogEntry(id, agentId) {
         const db = this.getDb();
         return this.withTransaction(() => {
+            this.dropStaleSlackDeliveryRows(agentId);
             const row = db
                 .prepare("SELECT * FROM unrouted_backlog WHERE id = ? AND status = 'pending'")
                 .get(id);
@@ -1861,6 +2105,7 @@ export class BrokerDB {
         });
     }
     recoverPendingTargetedBacklog(agentId) {
+        this.dropStaleSlackDeliveryRows(agentId);
         const agent = this.getAgentRowById(agentId);
         if (!agent || agent.disconnected_at) {
             return 0;
@@ -2607,7 +2852,75 @@ export class BrokerDB {
             .get(messageId);
         return row ? rowToBrokerMessage(row) : null;
     }
+    dropStaleSlackDeliveryRows(agentId) {
+        const db = this.getDb();
+        const nowMs = Date.now();
+        const now = new Date(nowMs).toISOString();
+        const agentClause = agentId ? " AND i.agent_id = ?" : "";
+        const inboxRows = db
+            .prepare(`SELECT i.id AS inbox_id,
+                i.agent_id AS agent_id,
+                i.message_id AS message_id,
+                m.source AS source,
+                m.metadata AS metadata,
+                m.external_ts AS external_ts
+           FROM inbox i
+           JOIN messages m ON m.id = i.message_id
+          WHERE (i.delivered = 0 OR i.read_at IS NULL)
+            AND m.direction = 'inbound'
+            AND m.source = 'slack'${agentClause}`)
+            .all(...(agentId ? [agentId] : []));
+        const staleInboxRows = inboxRows.filter((row) => {
+            const metadata = parseJsonMetadata(row.metadata);
+            const timestamp = getStringMetadataValue(metadata, ["timestamp", "ts", "externalTs", "external_ts"]) ??
+                row.external_ts;
+            return isStaleSlackMessageTimestamp(row.source, timestamp, nowMs);
+        });
+        const markInboxStale = db.prepare("UPDATE inbox SET delivered = 1, read_at = COALESCE(read_at, ?) WHERE id = ?");
+        for (const row of staleInboxRows) {
+            markInboxStale.run(now, row.inbox_id);
+            this.completeTargetedBacklogAssignment(row.message_id, row.agent_id);
+        }
+        const backlogRows = tableExists(db, "unrouted_backlog")
+            ? db
+                .prepare(`SELECT b.id AS backlog_id,
+                    m.source AS source,
+                    m.metadata AS metadata,
+                    m.external_ts AS external_ts
+               FROM unrouted_backlog b
+               JOIN messages m ON m.id = b.message_id
+              WHERE b.status = 'pending'
+                AND m.direction = 'inbound'
+                AND m.source = 'slack'`)
+                .all()
+            : [];
+        const staleBacklogIds = backlogRows
+            .filter((row) => {
+            const metadata = parseJsonMetadata(row.metadata);
+            const timestamp = getStringMetadataValue(metadata, ["timestamp", "ts", "externalTs", "external_ts"]) ??
+                row.external_ts;
+            return isStaleSlackMessageTimestamp(row.source, timestamp, nowMs);
+        })
+            .map((row) => row.backlog_id);
+        if (staleBacklogIds.length > 0) {
+            const dropBacklog = db.prepare(`UPDATE unrouted_backlog
+            SET status = 'dropped',
+                reason = 'stale_slack_message',
+                assigned_agent_id = NULL,
+                updated_at = ?
+          WHERE id = ?
+            AND status = 'pending'`);
+            for (const id of staleBacklogIds) {
+                dropBacklog.run(now, id);
+            }
+        }
+        if (staleInboxRows.length > 0 || staleBacklogIds.length > 0) {
+            console.info(`[broker-core] skipped stale Slack delivery rows older than 15m: inbox=${staleInboxRows.length} backlog=${staleBacklogIds.length}`);
+        }
+        return { inboxCount: staleInboxRows.length, backlogCount: staleBacklogIds.length };
+    }
     dropStaleTransportInboxRows(agentId) {
+        this.dropStaleSlackDeliveryRows(agentId);
         const db = this.getDb();
         const rows = db
             .prepare(`SELECT i.id AS inbox_id,
@@ -2952,7 +3265,8 @@ export class BrokerDB {
            m.id AS message_id,
            m.thread_id AS thread_id,
            m.source AS source,
-           m.metadata AS metadata
+           m.metadata AS metadata,
+           m.external_ts AS external_ts
          FROM inbox i
          JOIN messages m ON m.id = i.message_id
          WHERE i.agent_id = ?
@@ -2963,14 +3277,30 @@ export class BrokerDB {
             return 0;
         }
         const markDelivered = db.prepare("UPDATE inbox SET delivered = 1 WHERE id = ?");
+        const markStaleRead = db.prepare("UPDATE inbox SET delivered = 1, read_at = COALESCE(read_at, ?) WHERE id = ?");
+        const nowMs = Date.now();
+        const now = new Date(nowMs).toISOString();
+        let requeuedCount = 0;
+        let staleCount = 0;
         for (const row of rows) {
             const metadata = row.metadata ? JSON.parse(row.metadata) : {};
+            const timestamp = getStringMetadataValue(metadata, ["timestamp", "ts", "externalTs", "external_ts"]) ??
+                row.external_ts;
+            if (isStaleSlackMessageTimestamp(row.source, timestamp, nowMs)) {
+                markStaleRead.run(now, row.inbox_id);
+                staleCount += 1;
+                continue;
+            }
             const channel = typeof metadata.channel === "string" ? metadata.channel : "";
-            const preferredAgentId = row.source === "agent" ? row.target_agent_id : null;
+            const preferredAgentId = row.target_agent_id || null;
             this.upsertBacklogEntry(row.message_id, row.thread_id, channel, reason, "pending", preferredAgentId, null);
             markDelivered.run(row.inbox_id);
+            requeuedCount += 1;
+        }
+        if (staleCount > 0) {
+            console.info(`[broker-core] skipped stale Slack requeue rows older than 15m: inbox=${staleCount}`);
         }
-        return rows.length;
+        return requeuedCount;
     }
     getBacklogById(id) {
         const db = this.getDb();

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { PinetMailClass } from "./mail-classification.js";
 export declare const DEFAULT_EXTERNAL_THREAD_SOURCE = "external";
+export type AgentSupervisionState = "root" | "supervised" | "orphaned" | "stopping";
 export interface AgentInfo {
     id: string;
     stableId?: string | null;
@@ -11,6 +12,14 @@ export interface AgentInfo {
     lastHeartbeat: string;
     metadata: Record<string, unknown> | null;
     status: "working" | "idle";
+    parentAgentId?: string | null;
+    rootAgentId?: string | null;
+    treeDepth?: number;
+    spawnedByAgentId?: string | null;
+    supervisionState?: AgentSupervisionState;
+    launchId?: string | null;
+    subtreeRole?: string | null;
+    laneId?: string | null;
     disconnectedAt?: string | null;
     resumableUntil?: string | null;
     idleSince?: string | null;
@@ -266,9 +275,10 @@ export declare const RPC_AUTH_REQUIRED = -32001;
 export declare const RPC_AGENT_NAME_CONFLICT = -32002;
 export declare const RPC_AGENT_STABLE_ID_CONFLICT = -32003;
 import { buildCompatibilityInstanceScope as _buildCompatibilityInstanceScope, buildCompatibilityWorkspaceScope as _buildCompatibilityWorkspaceScope, buildRuntimeScopeCarrier as _buildRuntimeScopeCarrier } from "@pinet/transport-core";
-import type { InboundMessage as _InboundMessage, NormalizedMessageContent as _NormalizedMessageContent, OutboundMessage as _OutboundMessage, AdapterCapabilityRequest as _AdapterCapabilityRequest, AdapterCapabilityResult as _AdapterCapabilityResult, AdapterCapabilityEffects as _AdapterCapabilityEffects, AdapterThreadClaimEffect as _AdapterThreadClaimEffect, MessageAdapter as _MessageAdapter, RuntimeScopeCarrier as _RuntimeScopeCarrier, WorkspaceInstallScopeCarrier as _WorkspaceInstallScopeCarrier, InstanceScopeCarrier as _InstanceScopeCarrier } from "@pinet/transport-core";
+import type { InboundMessage as _InboundMessage, NormalizedMessageContent as _NormalizedMessageContent, OutboundAttachmentFile as _OutboundAttachmentFile, OutboundMessage as _OutboundMessage, AdapterCapabilityRequest as _AdapterCapabilityRequest, AdapterCapabilityResult as _AdapterCapabilityResult, AdapterCapabilityEffects as _AdapterCapabilityEffects, AdapterThreadClaimEffect as _AdapterThreadClaimEffect, MessageAdapter as _MessageAdapter, RuntimeScopeCarrier as _RuntimeScopeCarrier, WorkspaceInstallScopeCarrier as _WorkspaceInstallScopeCarrier, InstanceScopeCarrier as _InstanceScopeCarrier } from "@pinet/transport-core";
 export type InboundMessage = _InboundMessage;
 export type NormalizedMessageContent = _NormalizedMessageContent;
+export type OutboundAttachmentFile = _OutboundAttachmentFile;
 export type OutboundMessage = _OutboundMessage;
 export type AdapterCapabilityRequest = _AdapterCapabilityRequest;
 export type AdapterCapabilityResult = _AdapterCapabilityResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinet/broker-core",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "type": "module",
   "description": "Transport-neutral broker kernel primitives for pi transports",
   "author": "Will Porcellini <5994936+gugu91@users.noreply.github.com>",
@@ -43,7 +43,7 @@
     "test": "vitest run *.test.ts"
   },
   "dependencies": {
-    "@pinet/transport-core": "0.1.2"
+    "@pinet/transport-core": "0.2.1"
   },
   "types": "./dist/index.d.ts"
 }