@thehammer/danx-session-telemetry 0.1.24 → 0.1.26

package/README.md

@@ -39,9 +39,9 @@ own header comments for the per-file reasoning.
 
 | Consumer | Mechanism | Why |
 |---|---|---|
-| **danxbot worker** (root repo, `tsx src/index.ts`) | npm **workspace** link (`"workspaces": ["packages/*"]` in root `package.json`, `"@thehammer/danx-session-telemetry"` in root `dependencies`) | The worker and this package always ship from the SAME repo commit — a workspace link means the worker runs whatever source the current commit carries, with zero drift risk and no dependency on registry propagation timing. The Docker image builds `dist/` for it in a dedicated builder stage (mirroring `dashboard-builder`/`frontend-builder` in `Dockerfile`) since the final image's `npm ci --omit=dev` never installs this package's own `devDependencies` (`typescript`). |
+| **danxbot worker** (root repo, `tsx src/index.ts`) | npm **workspace** link (`"workspaces": ["packages/*"]` in root `package.json`, `"@thehammer/danx-session-telemetry"` in root `dependencies`) | The worker and this package always ship from the SAME repo commit — a workspace link means the worker runs whatever source the current commit carries, with zero drift risk and no dependency on registry propagation timing. The Docker image builds `dist/` for it in a dedicated builder stage (alongside `frontend-builder` in `Dockerfile`) since the final image's `npm ci --omit=dev` never installs this package's own `devDependencies` (`typescript`). |
 | **`danx-dashboard-mcp` desktop bridge** (separate npm-published package, DX-2954) | Ordinary npm dependency, **pinned to the exact published version** the worker's commit ships | The bridge is a genuinely separate installable artifact (`npx -y @thehammer/danx-dashboard-mcp`), so it cannot workspace-link into danxbot's own checkout — it needs the real published bytes. Pinning exact (not `^`/`~`) is what makes "worker and MCP run identical collector code for any given release" true: MCP's own version bump is the only thing that ever changes what collector code it runs. |
-| **Dashboard server / dashboard SPA** (`src/dashboard/*`, `dashboard/*`) | Same npm dependency shape as the worker (dashboard's `src/` is root-repo code, so it resolves through the SAME root workspace link as the worker; `dashboard/` is its own separate npm package — DX-2963, the first real consumer there, adds an ordinary `dashboard/package.json` dependency, resolved by Vite/Vitest/`vue-tsc` through plain node_modules resolution, no alias needed) | No `@backend`-style alias is needed for an npm dependency the way one is needed for `dashboard/`'s reach into root `src/` — that alias exists because `dashboard/` is a SEPARATE package with no other way to reach root source; a real npm dependency resolves through ordinary node_modules lookup in every one of Vite's two configs, Vitest, `vue-tsc`, and the Dockerfile builder stages (`dashboard-deps-builder` runs `cd dashboard && npm ci` from `dashboard/`'s own manifests, so a `dashboard/package.json` dependency is resolvable with zero Dockerfile change). `dashboard/` is FROZEN (`.claude/rules/ui-deprecation.md`) — this card adds no dependency there since nothing consumes it yet; DX-2963 adds the one line when it wires the real counter into `DispatchDetail.vue`/`DispatchList.vue`. |
+| **Dashboard server** (`src/dashboard/*`) | Same npm dependency shape as the worker (the dashboard server's `src/` is root-repo code, so it resolves through the SAME root workspace link as the worker) | An npm dependency resolves through ordinary node_modules lookup, so no `@backend`-style alias is needed. |
 
 ## Release order (DX-2962 AC3)
 

package/dist/.source-hash

@@ -1 +1 @@
-89cd1ca4f2b51d45e885401f25cd2013ae9a293b3f3788aa820d45ea63e2a004
+3ffba7fcfab27ba33e21879f9c097dc9eaafaf4a688857098edbd721e2f81300

package/dist/activity-observer.d.ts

@@ -9,30 +9,41 @@
  *
  * ## Why the transcript, and where the hooks come in
  *
- * Claude Code's `SubagentStart` / `SubagentStop` hooks carry strictly more (an
- * `agent_type` before the sub-agent has written anything, and — the part this
- * module cannot supply — a FINISH). They ship from the danxbot plugin in the
+ * Claude Code's `SubagentStart` / `SubagentStop` hooks carry an `agent_type`
+ * before the sub-agent has written anything and a FINISH for every sub-agent,
+ * foreground or background. They ship from the danxbot plugin in the
  * claude-plugins repo (DX-3284, `danxbot/scripts/activity-report.mjs`), run the
  * `activity` subcommand of `@thehammer/danx-dashboard-mcp`, and reach the server
  * through `POST /api/plan-sessions/me/activity` — which writes the SAME
  * `dispatch_activities` rows through the same one server writer.
  *
  * The transcript stays the producer because it needs no hook to be installed: a
- * session with no plugin, and every WORKER dispatch, still gets a start row for
- * each sub-agent from here. The hooks are an ENRICHMENT layered on the same rows:
+ * session with no plugin, and every WORKER dispatch, still gets a row for each
+ * sub-agent from here. The hooks are an ENRICHMENT layered on the same rows:
  *
  * | Signal | Sub-agent start | Sub-agent finish | Background script |
  * |---|---|---|---|
- * | Transcript (here) | file discovered | dispatch terminal (`finishOpenActivities`) | not visible |
+ * | Transcript (here) | file discovered | a background sub-agent's task notification (DX-4498); else the dispatch's terminal write (`finishOpenActivities`) | not visible |
  * | Hooks (DX-3284, operator sessions) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
  *
- * **Where "running" closes.** An operator session's sub-agent closes at its
- * `SubagentStop` hook. A WORKER dispatch has no hook reporting yet
- * (`/me/activity` refuses a worker's session id as `session_is_worker`), so its
- * sub-agents stay in the running set until the dispatch itself ends, and the
- * silent-too-long warning fires `RUNNING_ACTIVITY_SILENT_AFTER_MS` after a
- * sub-agent that has in fact finished. A worker-side `SubagentStop` report is the
- * fix, and is not built.
+ * ## What it reports about each sub-agent (DX-4498)
+ *
+ * All of it read from what Claude Code itself writes, with no cooperation from
+ * the sub-agent:
+ *
+ * | Field | Read from |
+ * |---|---|
+ * | `agentType`, `description`, `parentActivityId` | the sub-agent's `meta.json` sidecar (via `SourceDiscoveredInfo`) |
+ * | `lastActivityAt` | the timestamp of its latest `assistant` / `user` line |
+ * | `effort` | its latest `assistant` line's top-level `effort` |
+ * | `currentActivity` | its latest `tool_use` block, through {@link describeToolCall} |
+ * | `briefIssueId` | the card id its brief (the root `user` line) opens with |
+ * | `finishedAt`, `endStatus` | the task notification Claude Code writes into the SPAWNER's transcript |
+ *
+ * Model, tokens, cost, tool-call count and the claimed card are NOT here: the
+ * usage ledger already records them per reply, keyed by the same source, and
+ * the read derives them from it (two places recording one number is how they
+ * drift).
  *
  * ## Why the two producers cannot double-count
  *
@@ -47,20 +58,23 @@
  * which the subcommand uses to refuse a key that disagrees. That basename is also
  * the key the ledger credits the sub-agent's tokens under, which is how
  * per-sub-agent tokens join to the running set without this table carrying a
- * token column.
+ * token column. A task notification names the sub-agent by its bare id
+ * (`<task-id>`), which is mapped onto the same `agent-<id>` key.
  *
- * ## What this module deliberately does NOT do
+ * ## A finish is reported only when Claude Code says so
  *
- * It never reports a FINISH. A transcript gives no "this sub-agent is done"
- * signal — a finished sub-agent's file simply stops growing, which is
- * indistinguishable from a slow one. Guessing a finish from an idle gap would
- * mark a long-thinking sub-agent as complete. So open rows are closed exactly
- * once, at the dispatch's own terminal transition (`finishOpenActivities`),
- * unless the `SubagentStop` hook (DX-3284) closes a row first.
+ * A sub-agent's OWN transcript gives no "this sub-agent is done" signal — a
+ * finished sub-agent's file simply stops growing, which is indistinguishable
+ * from a slow one. Guessing a finish from an idle gap would mark a
+ * long-thinking sub-agent as complete, so this module never does. DX-4498: the
+ * one finish it reports is EXPLICIT — the `<task-notification>` Claude Code
+ * delivers to the spawner when a BACKGROUND task ends, carrying its
+ * `<status>` (`completed`, `failed`, `killed`, `stopped`). A foreground
+ * sub-agent gets no notification, so its row closes at its `SubagentStop` hook
+ * (operator sessions) or at the dispatch's own terminal transition.
  */
-import type { ActivityChange } from "./stats-wire.js";
+import { type ActivityChange, type ActivityEndStatus } from "./stats-wire.js";
 import type { EntryMeta, SourceDiscoveredInfo } from "./session-log-watcher.js";
-import type { AgentLogEntry } from "./types.js";
 /** What the observer needs from the dispatch's usage accumulator. */
 export interface ActivityObserverDeps {
     /**
@@ -84,7 +98,30 @@ export interface ActivityObserverDeps {
 export interface ActivityObserver {
     /** Wire to the watcher's `onSourceDiscovered`. */
     onSourceDiscovered: (info: SourceDiscoveredInfo) => void;
-    /** Wire to the watcher's `onEntry`. */
-    onEntry: (entry: AgentLogEntry, meta: EntryMeta) => void;
+    /** DX-4498 — wire to the watcher's `onUsageLine` (the raw line feed: the brief and task notifications are not entries). */
+    onLine: (raw: Record<string, unknown>, meta: EntryMeta) => void;
 }
+/**
+ * DX-4498 — a task notification's `(task id, end status)`, or null for a line that is not one, or one whose status is
+ * not an end (`running`). Only the two delivery shapes Claude Code itself writes are read: a `user` line whose
+ * `origin.kind` is `task-notification`, and a `queued_command` attachment with that `commandMode`. A sub-agent's
+ * reply that merely QUOTES a notification carries neither marker, so it can never end anything.
+ */
+export declare function parseTaskNotification(raw: Record<string, unknown>): {
+    taskId: string;
+    endStatus: ActivityEndStatus;
+} | null;
+/**
+ * DX-4498 — a sub-agent's current activity, from one `tool_use` block: the tool's name, plus a label only where the
+ * agent wrote one AS a label (a shell call's `description`, an `Agent` call's `description`, a `Skill` call's skill
+ * name). Never a command, a file path or a prompt: the stats wire carries ids, numbers and labels, never free-form
+ * transcript content.
+ */
+export declare function describeToolCall(name: string, input: Record<string, unknown>): string;
+/**
+ * DX-4498 — the card id a brief opens with: the first token of its first non-empty line, when that token is shaped
+ * like a card id (`DX-4498`, also `DX-4498:`). Worker briefs open with the card they are for; any other brief names
+ * none. The server keeps it only when it names a real card of the team, so a plan ref (`PLAN-2`) never reaches a reader.
+ */
+export declare function briefIssueId(brief: string): string | null;
 export declare function createActivityObserver(deps: ActivityObserverDeps): ActivityObserver;

package/dist/activity-observer.js

@@ -1,10 +1,216 @@
+/**
+ * DX-2954 — the TRANSCRIPT-side producer of a dispatch's running set.
+ *
+ * `dispatch_activities` answers "what is this dispatch running RIGHT NOW" — one
+ * row per sub-agent or background script, with `finished_at` NULL while it is
+ * still going. This module produces the sub-agent half of that set from the one
+ * signal danxbot owns end-to-end: the session-log watcher discovering a
+ * sub-agent's transcript file and then tailing it.
+ *
+ * ## Why the transcript, and where the hooks come in
+ *
+ * Claude Code's `SubagentStart` / `SubagentStop` hooks carry an `agent_type`
+ * before the sub-agent has written anything and a FINISH for every sub-agent,
+ * foreground or background. They ship from the danxbot plugin in the
+ * claude-plugins repo (DX-3284, `danxbot/scripts/activity-report.mjs`), run the
+ * `activity` subcommand of `@thehammer/danx-dashboard-mcp`, and reach the server
+ * through `POST /api/plan-sessions/me/activity` — which writes the SAME
+ * `dispatch_activities` rows through the same one server writer.
+ *
+ * The transcript stays the producer because it needs no hook to be installed: a
+ * session with no plugin, and every WORKER dispatch, still gets a row for each
+ * sub-agent from here. The hooks are an ENRICHMENT layered on the same rows:
+ *
+ * | Signal | Sub-agent start | Sub-agent finish | Background script |
+ * |---|---|---|---|
+ * | Transcript (here) | file discovered | a background sub-agent's task notification (DX-4498); else the dispatch's terminal write (`finishOpenActivities`) | not visible |
+ * | Hooks (DX-3284, operator sessions) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
+ *
+ * ## What it reports about each sub-agent (DX-4498)
+ *
+ * All of it read from what Claude Code itself writes, with no cooperation from
+ * the sub-agent:
+ *
+ * | Field | Read from |
+ * |---|---|
+ * | `agentType`, `description`, `parentActivityId` | the sub-agent's `meta.json` sidecar (via `SourceDiscoveredInfo`) |
+ * | `lastActivityAt` | the timestamp of its latest `assistant` / `user` line |
+ * | `effort` | its latest `assistant` line's top-level `effort` |
+ * | `currentActivity` | its latest `tool_use` block, through {@link describeToolCall} |
+ * | `briefIssueId` | the card id its brief (the root `user` line) opens with |
+ * | `finishedAt`, `endStatus` | the task notification Claude Code writes into the SPAWNER's transcript |
+ *
+ * Model, tokens, cost, tool-call count and the claimed card are NOT here: the
+ * usage ledger already records them per reply, keyed by the same source, and
+ * the read derives them from it (two places recording one number is how they
+ * drift).
+ *
+ * ## Why the two producers cannot double-count
+ *
+ * Every row is an upsert keyed `(dispatch_id, kind, activity_id)`, and BOTH
+ * producers derive `activity_id` from the same thing: the sub-agent's transcript
+ * file basename, `agent-<agent_id>`. The watcher has it directly; a hook has the
+ * `agent_id` and builds the same basename from it (`subagentActivityId` in
+ * danx-dashboard-mcp's `activity.ts`, which also strips an `agent-` prefix the hooks docs show
+ * on some `agent_id`s so both forms reach this key). A hook's `transcript_path` is NOT the
+ * sub-agent's file — on these events it is the MAIN session's transcript, and only
+ * `SubagentStop` also carries the sub-agent's own as `agent_transcript_path`,
+ * which the subcommand uses to refuse a key that disagrees. That basename is also
+ * the key the ledger credits the sub-agent's tokens under, which is how
+ * per-sub-agent tokens join to the running set without this table carrying a
+ * token column. A task notification names the sub-agent by its bare id
+ * (`<task-id>`), which is mapped onto the same `agent-<id>` key.
+ *
+ * ## A finish is reported only when Claude Code says so
+ *
+ * A sub-agent's OWN transcript gives no "this sub-agent is done" signal — a
+ * finished sub-agent's file simply stops growing, which is indistinguishable
+ * from a slow one. Guessing a finish from an idle gap would mark a
+ * long-thinking sub-agent as complete, so this module never does. DX-4498: the
+ * one finish it reports is EXPLICIT — the `<task-notification>` Claude Code
+ * delivers to the spawner when a BACKGROUND task ends, carrying its
+ * `<status>` (`completed`, `failed`, `killed`, `stopped`). A foreground
+ * sub-agent gets no notification, so its row closes at its `SubagentStop` hook
+ * (operator sessions) or at the dispatch's own terminal transition.
+ */
+import { CURRENT_ACTIVITY_MAX_CHARS, } from "./stats-wire.js";
+import { ISSUE_ID_MAX_LENGTH, ISSUE_ID_PATTERN } from "./claim-tracker.js";
+/** The prefix a sub-agent's source key (its transcript basename) carries before its bare agent id. */
+const SUBAGENT_SOURCE_PREFIX = "agent-";
+/**
+ * DX-4498 — how many task notifications for a source not yet discovered are held. A notification normally names a
+ * sub-agent whose file was discovered long before it ended; one that arrives first waits here. Background SHELL tasks
+ * notify the same way and are never discovered, so the map is bounded: the oldest entry is dropped beyond this.
+ */
+const MAX_PENDING_ENDS = 500;
+/** DX-4498 — Claude Code's notification statuses, as the end status the running set stores. */
+const NOTIFICATION_END_STATUS = {
+    completed: "completed",
+    failed: "failed",
+    killed: "stopped",
+    stopped: "stopped",
+};
+const NOTIFICATION = /^\s*<task-notification>\s*<task-id>([^<]+)<\/task-id>[\s\S]*?<status>([^<]+)<\/status>/;
+/**
+ * DX-4498 — a task notification's `(task id, end status)`, or null for a line that is not one, or one whose status is
+ * not an end (`running`). Only the two delivery shapes Claude Code itself writes are read: a `user` line whose
+ * `origin.kind` is `task-notification`, and a `queued_command` attachment with that `commandMode`. A sub-agent's
+ * reply that merely QUOTES a notification carries neither marker, so it can never end anything.
+ */
+export function parseTaskNotification(raw) {
+    let text;
+    if (raw.type === "user") {
+        const origin = raw.origin;
+        if (origin?.kind !== "task-notification")
+            return null;
+        text = raw.message?.content;
+    }
+    else if (raw.type === "attachment") {
+        const attachment = raw.attachment;
+        if (attachment?.type !== "queued_command" || attachment.commandMode !== "task-notification")
+            return null;
+        text = attachment.prompt;
+    }
+    else {
+        return null;
+    }
+    if (typeof text !== "string")
+        return null;
+    const match = NOTIFICATION.exec(text);
+    if (match === null)
+        return null;
+    const endStatus = NOTIFICATION_END_STATUS[match[2].trim()];
+    return endStatus === undefined ? null : { taskId: match[1].trim(), endStatus };
+}
+/**
+ * DX-4498 — a sub-agent's current activity, from one `tool_use` block: the tool's name, plus a label only where the
+ * agent wrote one AS a label (a shell call's `description`, an `Agent` call's `description`, a `Skill` call's skill
+ * name). Never a command, a file path or a prompt: the stats wire carries ids, numbers and labels, never free-form
+ * transcript content.
+ */
+export function describeToolCall(name, input) {
+    const label = (v) => (typeof v === "string" && v.trim() !== "" ? v.trim() : null);
+    let detail = null;
+    switch (name) {
+        case "Bash":
+        case "PowerShell":
+        case "Agent":
+        case "Task":
+            detail = label(input.description);
+            break;
+        case "Skill":
+            detail = label(input.skill);
+            break;
+    }
+    const text = (detail === null ? name : `${name}: ${detail}`).replace(/\s+/g, " ");
+    return text.length > CURRENT_ACTIVITY_MAX_CHARS ? `${text.slice(0, CURRENT_ACTIVITY_MAX_CHARS - 3)}...` : text;
+}
+/**
+ * DX-4498 — the card id a brief opens with: the first token of its first non-empty line, when that token is shaped
+ * like a card id (`DX-4498`, also `DX-4498:`). Worker briefs open with the card they are for; any other brief names
+ * none. The server keeps it only when it names a real card of the team, so a plan ref (`PLAN-2`) never reaches a reader.
+ */
+export function briefIssueId(brief) {
+    const firstLine = brief.split("\n").find((line) => line.trim() !== "");
+    if (firstLine === undefined)
+        return null;
+    const token = firstLine.trim().split(/\s+/)[0].replace(/[.,:;)]+$/, "");
+    return token.length <= ISSUE_ID_MAX_LENGTH && ISSUE_ID_PATTERN.test(token) ? token : null;
+}
+/** The text of a `user` line's content: the string itself, or its first text block. */
+function userText(raw) {
+    const content = raw.message?.content;
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return null;
+    const block = content.find((b) => b?.type === "text");
+    return typeof block?.text === "string" ? block.text : null;
+}
+/** The line's own timestamp in epoch ms, or null when it carries none that parses. */
+function lineTime(raw) {
+    if (typeof raw.timestamp !== "string")
+        return null;
+    const ms = Date.parse(raw.timestamp);
+    return Number.isNaN(ms) ? null : ms;
+}
 export function createActivityObserver(deps) {
     // No clock of its own, deliberately. Every stamp this module reports comes from
     // the event that caused it — the watcher's `discoveredAt` for a start, the
-    // entry's own `timestamp` for an advance — so there is no wall-clock reading
-    // anywhere that a test would need to freeze or that a replay could skew.
+    // line's own `timestamp` for an advance or an end — so there is no wall-clock
+    // reading anywhere that a test would need to freeze or that a replay could skew.
     /** Every sub-agent this observer has reported, by its ledger source key. */
     const started = new Map();
+    /**
+     * DX-4498 — per source, the newest line timestamp read so far. The effort and tool call come from the NEWEST line,
+     * which `lastActivityAt` cannot tell: it starts at the watcher's discovery time, after every line a reattached
+     * collector re-reads.
+     */
+    const newestLineAt = new Map();
+    /** DX-4498 — ends notified for a source not yet discovered (see {@link MAX_PENDING_ENDS}). */
+    const pendingEnds = new Map();
+    const report = (change) => deps.recordActivities([{ ...change }]);
+    const applyEnd = (change, end) => {
+        // The FIRST finish stands (the server's own merge); the LATEST status wins, so a resumed sub-agent's second
+        // notification names how it really ended.
+        change.finishedAt ??= end.finishedAt;
+        change.endStatus = end.endStatus;
+    };
+    const onNotification = (taskId, endStatus, at) => {
+        const source = `${SUBAGENT_SOURCE_PREFIX}${taskId}`;
+        const change = started.get(source);
+        if (change === undefined) {
+            pendingEnds.delete(source);
+            pendingEnds.set(source, { finishedAt: at, endStatus });
+            if (pendingEnds.size > MAX_PENDING_ENDS)
+                pendingEnds.delete(pendingEnds.keys().next().value);
+            return;
+        }
+        if (change.finishedAt !== null && change.endStatus === endStatus)
+            return;
+        applyEnd(change, { finishedAt: at, endStatus });
+        report(change);
+    };
     return {
         onSourceDiscovered(info) {
             // Not this dispatch's sub-agent (see `ignorePreexisting`). Never added to
@@ -14,42 +220,76 @@ export function createActivityObserver(deps) {
                 return;
             const existing = started.get(info.source);
             if (existing) {
-                // A second discovery of a source already reported can only ADD an
-                // `agentType` the first pass could not read yet (the sub-agent had not
-                // written a line naming one). Never re-stamp `startedAt`: the server
-                // takes LEAST(startedAt) anyway, but reporting a later start for a
-                // sub-agent that has been running since before this watcher attached
-                // would be wrong in the payload itself.
+                // A second discovery of a source already reported can only ADD what the
+                // first pass could not read yet (its `meta.json` sidecar was not written).
+                // Never re-stamp `startedAt`: the server takes LEAST(startedAt) anyway, but
+                // reporting a later start for a sub-agent that has been running since
+                // before this watcher attached would be wrong in the payload itself.
+                let filled = false;
                 if (existing.agentType === null && info.agentType !== null) {
                     existing.agentType = info.agentType;
-                    deps.recordActivities([{ ...existing }]);
+                    filled = true;
                 }
+                if (existing.description === null && info.description !== null) {
+                    existing.description = info.description;
+                    filled = true;
+                }
+                if (existing.parentActivityId === null && info.parentSource !== null) {
+                    existing.parentActivityId = info.parentSource;
+                    filled = true;
+                }
+                if (filled)
+                    report(existing);
                 return;
             }
             const change = {
                 kind: "agent",
                 activityId: info.source,
                 agentType: info.agentType,
-                // A sub-agent has no Bash `description`; the field exists for the
-                // background-script kind and stays null here rather than being filled
-                // with a stand-in a reader would have to distinguish from a real one.
-                description: null,
+                // DX-4498 — the label its spawning `Agent` call gave it, from the sidecar.
+                description: info.description,
                 startedAt: info.discoveredAt,
                 lastActivityAt: info.discoveredAt,
-                // Never a finish from the transcript — see the module docblock.
                 finishedAt: null,
+                parentActivityId: info.parentSource,
+                effort: null,
+                currentActivity: null,
+                endStatus: null,
+                briefIssueId: null,
             };
+            const pending = pendingEnds.get(info.source);
+            if (pending !== undefined) {
+                pendingEnds.delete(info.source);
+                applyEnd(change, pending);
+            }
             started.set(info.source, change);
-            deps.recordActivities([{ ...change }]);
+            report(change);
         },
-        onEntry(entry, meta) {
+        onLine(raw, meta) {
+            const at = lineTime(raw);
+            // A line with no timestamp moves nothing: every stamp here is the line's own, never a wall clock.
+            if (at === null)
+                return;
+            // DX-4498 — a notification ends the sub-agent it names, wherever it is read: the main transcript for one the
+            // session spawned, the spawning sub-agent's own transcript for a nested one.
+            const notification = parseTaskNotification(raw);
+            if (notification !== null) {
+                onNotification(notification.taskId, notification.endStatus, at);
+                return;
+            }
+            const change = started.get(meta.source);
+            if (!change)
+                return;
+            if (raw.type !== "assistant" && raw.type !== "user")
+                return;
+            let changed = false;
             // DX-2954 — a REPLAY counts as activity here, unlike the stall detector's
             // liveness signal. The two ask different questions: the stall detector asks
             // "is the agent alive NOW" (a re-read proves nothing), while this stamp
             // answers "when did this sub-agent last actually say something", which a
             // re-read line genuinely reports.
             //
-            // Which is exactly why the stamp is the ENTRY's OWN timestamp and never a
+            // Which is exactly why the stamp is the LINE's OWN timestamp and never a
             // wall clock. Stamping `Date.now()` would make a reattach reset every
             // pre-existing sub-agent's last activity to the moment the collector
             // restarted: the whole replay window would report as fresh, and a sub-agent
@@ -59,15 +299,50 @@ export function createActivityObserver(deps) {
             // wall-clock-for-entry-time confusion in the boot mark). Even with no
             // replay involved, a wall clock records when the 5s poll NOTICED the line,
             // not when the agent wrote it.
-            const change = started.get(meta.source);
-            if (!change)
-                return;
+            //
             // GREATEST, mirroring the server: a line read out of order, or an older
-            // line inside a replay window, never drags liveness backwards.
-            if (entry.timestamp <= change.lastActivityAt)
-                return;
-            change.lastActivityAt = entry.timestamp;
-            deps.recordActivities([{ ...change }]);
+            // line inside a replay window, never drags liveness backwards — nor the
+            // effort and tool call that ride it.
+            const newest = at >= (newestLineAt.get(meta.source) ?? 0);
+            if (newest)
+                newestLineAt.set(meta.source, at);
+            if (at > change.lastActivityAt) {
+                change.lastActivityAt = at;
+                changed = true;
+            }
+            if (raw.type === "user") {
+                // DX-4498 — the brief is the chain's root line (`parentUuid: null`), so a collector that resumes mid-file
+                // never mistakes a later prompt for it.
+                if (change.briefIssueId === null && raw.parentUuid === null) {
+                    const text = userText(raw);
+                    const id = text === null ? null : briefIssueId(text);
+                    if (id !== null) {
+                        change.briefIssueId = id;
+                        changed = true;
+                    }
+                }
+            }
+            else if (newest) {
+                if (typeof raw.effort === "string" && raw.effort !== "" && raw.effort !== change.effort) {
+                    change.effort = raw.effort;
+                    changed = true;
+                }
+                const content = raw.message?.content;
+                const toolUses = Array.isArray(content)
+                    ? content.filter((b) => b?.type === "tool_use" && typeof b.name === "string")
+                    : [];
+                const last = toolUses.at(-1);
+                if (last !== undefined) {
+                    const input = last.input !== null && typeof last.input === "object" ? last.input : {};
+                    const activity = describeToolCall(last.name, input);
+                    if (activity !== change.currentActivity) {
+                        change.currentActivity = activity;
+                        changed = true;
+                    }
+                }
+            }
+            if (changed)
+                report(change);
         },
     };
 }

package/dist/browser.d.ts

@@ -17,7 +17,7 @@
  * DX-2963 adds the first real runtime exports here: the one usage counter
  * (`usage-ledger.ts`) and the one pricing function (`pricing.ts`), both pure
  * arithmetic with no I/O — `usage-snapshot.ts` in danxbot root (bundled by the
- * frozen Vue SPA) imports through THIS subpath, never the main entry.
+ * React frontend) imports through THIS subpath, never the main entry.
  */
 export type { AgentLogEntry, AgentLineage } from "./types.js";
 export { truncStr } from "./tool-summary.js";

package/dist/session-log-watcher.d.ts

@@ -12,7 +12,7 @@
  * Claude Code writes:
  *   - Parent session:   ~/.claude/projects/<cwd-path>/<session-uuid>.jsonl
  *   - Sub-agent sessions: ~/.claude/projects/<cwd-path>/<session-uuid>/subagents/agent-<hash>.jsonl
- *                        + agent-<hash>.meta.json sidecar with {agentType, description}
+ *                        + agent-<hash>.meta.json sidecar with {agentType, description, parentAgentId (nested only), ...}
  *
  * The watcher tails the parent file and all sub-agent files in parallel, parses
  * new lines, converts them to AgentLogEntry, and emits to registered consumers.
@@ -38,7 +38,8 @@ export declare const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
 export type EntryConsumer = (entry: AgentLogEntry, meta: EntryMeta) => void;
 /**
  * DX-3964 - a consumer of the usage feed: the PARSED RAW line (assistant, user, attachment or system - nothing
- * else) with the same {@link EntryMeta} an `onEntry` consumer gets. Collector-only: see
+ * else) with the same {@link EntryMeta} an `onEntry` consumer gets. Collector-only (the usage counter and the
+ * activity observer): see
  * {@link SessionLogWatcher.onUsageLine}.
  */
 export type UsageLineConsumer = (raw: Record<string, unknown>, meta: EntryMeta) => void;
@@ -149,11 +150,16 @@ export interface SourceDiscoveredInfo {
     /** The sub-agent's ledger source key (its transcript file's basename). */
     source: string;
     /**
-     * The sub-agent's declared type, read from its own transcript. `null` when it
-     * has not written a line naming one yet — a hook-side report of the same
-     * sub-agent fills it in later without clobbering a value already stored.
+     * The sub-agent's declared type, read from its `meta.json` sidecar. `null` when
+     * Claude Code has not written the sidecar yet — it is reported again once read,
+     * and a hook-side report of the same sub-agent fills it in without clobbering a
+     * value already stored.
      */
     agentType: string | null;
+    /** DX-4498 — the label the spawning `Agent` call gave it (`meta.json` `description`); null until the sidecar is read. */
+    description: string | null;
+    /** DX-4498 — the source key of the sub-agent that spawned it (`agent-<parentAgentId>`); null for one the session spawned. */
+    parentSource: string | null;
     /** Epoch ms this watcher first saw the file. */
     discoveredAt: number;
     /**
@@ -395,7 +401,9 @@ export declare class SessionLogWatcher {
     /**
      * DX-3964 - register a usage-feed consumer: it receives the parsed raw line of every assistant, user,
      * attachment and system line, in file order, with the same `EntryMeta` as `onEntry`. The ONLY subscribers are
-     * the two `DispatchUsage` feed sites (the worker and the operator bridge): `convertJsonlEntry` and every
+     * the collector's two consumers at each of its two sites (the worker and the operator bridge): `DispatchUsage`
+     * and, DX-4498, the activity observer, which reads the sub-agent's brief and Claude Code's task notifications,
+     * neither of which is an entry. `convertJsonlEntry` and every
      * `onEntry` subscriber keep seeing exactly what they saw before, because human prompts, attachments (tens of
      * thousands of hook records) and system lines are not theirs.
      *
@@ -512,12 +520,13 @@ export declare class SessionLogWatcher {
     private emitSourceDiscovered;
     private refreshLineage;
     /**
-     * Read agentType from the `<subagentId>.meta.json` sidecar. Returns
+     * Read the `<subagentId>.meta.json` sidecar (DX-4498: its type, label and spawning sub-agent). Returns
      * undefined only for ENOENT (file not written yet). Malformed JSON or
      * permission errors are logged at WARN and return undefined — the watcher
      * must not crash on bad sidecar files, but the failure is visible in logs.
+     * A key the sidecar lacks, or carries as anything but a non-empty string, is `null`.
      */
-    private readAgentType;
+    private readSubagentMeta;
     /** Process raw text from a file tail, handling partial lines across poll ticks. */
     private processText;
     /**

package/dist/session-log-watcher.js

@@ -12,7 +12,7 @@
  * Claude Code writes:
  *   - Parent session:   ~/.claude/projects/<cwd-path>/<session-uuid>.jsonl
  *   - Sub-agent sessions: ~/.claude/projects/<cwd-path>/<session-uuid>/subagents/agent-<hash>.jsonl
- *                        + agent-<hash>.meta.json sidecar with {agentType, description}
+ *                        + agent-<hash>.meta.json sidecar with {agentType, description, parentAgentId (nested only), ...}
  *
  * The watcher tails the parent file and all sub-agent files in parallel, parses
  * new lines, converts them to AgentLogEntry, and emits to registered consumers.
@@ -622,7 +622,9 @@ export class SessionLogWatcher {
     /**
      * DX-3964 - register a usage-feed consumer: it receives the parsed raw line of every assistant, user,
      * attachment and system line, in file order, with the same `EntryMeta` as `onEntry`. The ONLY subscribers are
-     * the two `DispatchUsage` feed sites (the worker and the operator bridge): `convertJsonlEntry` and every
+     * the collector's two consumers at each of its two sites (the worker and the operator bridge): `DispatchUsage`
+     * and, DX-4498, the activity observer, which reads the sub-agent's brief and Claude Code's task notifications,
+     * neither of which is an entry. `convertJsonlEntry` and every
      * `onEntry` subscriber keep seeing exactly what they saw before, because human prompts, attachments (tens of
      * thousands of hook records) and system lines are not theirs.
      *
@@ -923,7 +925,7 @@ export class SessionLogWatcher {
             // `dispatch_activities.activity_id` holds — so a cursor, a per-source
             // token total and a running-set row all join on one key.
             const subagentId = basename(file, ".jsonl");
-            const agentType = await this.readAgentType(subagentId);
+            const meta = await this.readSubagentMeta(subagentId);
             const start = await this.resolveStart(subagentId, fullPath, firstPass);
             if (start === null) {
                 allResolved = false;
@@ -942,10 +944,11 @@ export class SessionLogWatcher {
                 replayUntil,
                 discoveredAt,
                 preexisting: firstPass,
+                meta,
                 lineage: {
                     subagent_id: subagentId,
                     parent_session_id: this.parentSessionId,
-                    agent_type: agentType,
+                    agent_type: meta?.agentType ?? undefined,
                 },
             });
             // DX-2954 — fired AFTER the tail is registered, so a consumer that throws
@@ -955,7 +958,7 @@ export class SessionLogWatcher {
             // reports is an idempotent upsert keyed on this same id, and re-reporting
             // is how a reattached collector re-learns the sub-agents that were already
             // running before it existed.
-            this.emitSourceDiscovered(subagentId, agentType, discoveredAt, firstPass);
+            this.emitSourceDiscovered(subagentId, meta, discoveredAt, firstPass);
         }
         if (allResolved)
             this.subagentDiscoveryDone = true;
@@ -994,15 +997,17 @@ export class SessionLogWatcher {
      *
      * Reporting the running set must never cost the monitoring it rides on.
      */
-    emitSourceDiscovered(source, agentType, discoveredAt, preexisting) {
+    emitSourceDiscovered(source, meta, discoveredAt, preexisting) {
         try {
             this.onSourceDiscovered?.({
                 source,
                 // ONE absent-shape on the wire, never two: this class's own reader
                 // answers `undefined` for "no meta file yet", while the stats payload and
-                // the `dispatch_activities.agent_type` column both spell absent as
-                // `null`. Normalizing here keeps every consumer from accepting both.
-                agentType: agentType ?? null,
+                // the `dispatch_activities` columns all spell absent as `null`.
+                // Normalizing here keeps every consumer from accepting both.
+                agentType: meta?.agentType ?? null,
+                description: meta?.description ?? null,
+                parentSource: meta?.parentSource ?? null,
                 discoveredAt,
                 preexisting,
             });
@@ -1022,14 +1027,16 @@ export class SessionLogWatcher {
         // yet" at discovery is the COMMON case, not an edge. Without a report here
         // the running-set row's `agent_type` would stay NULL for the whole dispatch
         // even though the watcher learned the real value one poll later.
-        const typeWasUnknown = agent_type === undefined;
-        if (agent_type === undefined) {
-            agent_type = await this.readAgentType(state.lineage.subagent_id);
+        // DX-4498 — the whole sidecar (type, label, parent) is learned in one read, so it is re-read only until it exists.
+        const metaWasUnknown = state.meta === undefined;
+        if (metaWasUnknown) {
+            state.meta = await this.readSubagentMeta(state.lineage.subagent_id);
+            agent_type = state.meta?.agentType ?? undefined;
         }
-        if (typeWasUnknown && agent_type !== undefined && state.source !== MAIN_SOURCE) {
+        if (metaWasUnknown && state.meta !== undefined && state.source !== MAIN_SOURCE) {
             // The ORIGINAL discovery stamp, never a fresh `Date.now()`: this is the
             // same activity, learning its type late, not a new one starting now.
-            this.emitSourceDiscovered(state.source, agent_type, state.discoveredAt, state.preexisting);
+            this.emitSourceDiscovered(state.source, state.meta, state.discoveredAt, state.preexisting);
         }
         if (parent_session_id === null && this.parentSessionId !== null) {
             parent_session_id = this.parentSessionId;
@@ -1041,19 +1048,26 @@ export class SessionLogWatcher {
         };
     }
     /**
-     * Read agentType from the `<subagentId>.meta.json` sidecar. Returns
+     * Read the `<subagentId>.meta.json` sidecar (DX-4498: its type, label and spawning sub-agent). Returns
      * undefined only for ENOENT (file not written yet). Malformed JSON or
      * permission errors are logged at WARN and return undefined — the watcher
      * must not crash on bad sidecar files, but the failure is visible in logs.
+     * A key the sidecar lacks, or carries as anything but a non-empty string, is `null`.
      */
-    async readAgentType(subagentId) {
+    async readSubagentMeta(subagentId) {
         if (!this.subagentsDir)
             return undefined;
         const metaPath = join(this.subagentsDir, `${subagentId}.meta.json`);
+        const text = (v) => (typeof v === "string" && v !== "" ? v : null);
         try {
-            const text = await readFile(metaPath, "utf-8");
-            const meta = JSON.parse(text);
-            return typeof meta.agentType === "string" ? meta.agentType : undefined;
+            const raw = JSON.parse(await readFile(metaPath, "utf-8"));
+            const parentAgentId = text(raw.parentAgentId);
+            return {
+                agentType: text(raw.agentType),
+                description: text(raw.description),
+                // The parent's own transcript is `agent-<parentAgentId>.jsonl`, so this is its source key.
+                parentSource: parentAgentId === null ? null : `agent-${parentAgentId}`,
+            };
         }
         catch (err) {
             const code = err.code;

package/dist/stats-wire.d.ts

@@ -104,7 +104,33 @@ export interface ActivityChange {
     lastActivityAt: number;
     /** Epoch ms when it finished, or null while it is still running. */
     finishedAt: number | null;
+    /**
+     * DX-4498 — the sub-agent that spawned this one (`agent-<parentAgentId>` from its `meta.json`), or null for a
+     * sub-agent the session itself spawned and for a background script.
+     */
+    parentActivityId: string | null;
+    /** DX-4498 — the reasoning effort its latest reply ran at (the assistant line's own `effort`); null until one is read. */
+    effort: string | null;
+    /**
+     * DX-4498 — what it is doing now: its latest tool call as `<Tool>` or `<Tool>: <label>`, where the label is only ever
+     * text the agent wrote AS a label (see {@link describeToolCall}); null until it calls a tool.
+     */
+    currentActivity: string | null;
+    /** DX-4498 — how it ended, when an explicit end event named it; null while running and for an end that named none. */
+    endStatus: ActivityEndStatus | null;
+    /** DX-4498 — the card id its brief opens with (`DX-4498
+  
+  ...`), or null when the brief names none. */
+    briefIssueId: string | null;
 }
+/**
+ * DX-4498 — how an activity ended, when something explicitly said so: Claude Code's background-task notification
+ * (`completed`, `failed`, and `killed`/`stopped` as `stopped`), or the session ending while it still ran (`stopped`).
+ */
+export declare const ACTIVITY_END_STATUSES: readonly ["completed", "failed", "stopped"];
+export type ActivityEndStatus = (typeof ACTIVITY_END_STATUSES)[number];
+/** DX-4498 — the longest `currentActivity` a collector sends (and the server stores). */
+export declare const CURRENT_ACTIVITY_MAX_CHARS = 120;
 export interface StatsPayload {
     entries: LedgerEntry[];
     /**

package/dist/stats-wire.js

@@ -21,6 +21,13 @@ export const STATS_BATCH_CAP = 500;
  * lines.
  */
 export const ACTIVITY_KINDS = ["agent", "bash"];
+/**
+ * DX-4498 — how an activity ended, when something explicitly said so: Claude Code's background-task notification
+ * (`completed`, `failed`, and `killed`/`stopped` as `stopped`), or the session ending while it still ran (`stopped`).
+ */
+export const ACTIVITY_END_STATUSES = ["completed", "failed", "stopped"];
+/** DX-4498 — the longest `currentActivity` a collector sends (and the server stores). */
+export const CURRENT_ACTIVITY_MAX_CHARS = 120;
 export function chunkEntries(entries, cap = STATS_BATCH_CAP) {
     const out = [];
     for (let i = 0; i < entries.length; i += cap)
@@ -107,10 +114,28 @@ export function collapseActivityChanges(changes) {
             // COALESCE(stored, incoming) — the FIRST finish wins; a later
             // still-running report must never resurrect a stopped activity.
             finishedAt: prior.finishedAt ?? c.finishedAt,
+            // DX-4498 — COALESCE(incoming, stored): a spawn fact, known or not, never changes once known.
+            parentActivityId: c.parentActivityId ?? prior.parentActivityId,
+            // DX-4498 — the report with the LATER liveness carries the current effort and tool call (a tie goes to the later
+            // report, which a producer queues after the one it supersedes); a report that knows neither keeps the stored ones.
+            ...latestOf(prior, c),
+            // DX-4498 — COALESCE(incoming, stored): the latest explicit end status wins (a notification read after the session's
+            // own close names how it really ended).
+            endStatus: c.endStatus ?? prior.endStatus,
+            // DX-4498 — COALESCE(stored, incoming): the brief is the transcript's first line, read once.
+            briefIssueId: prior.briefIssueId ?? c.briefIssueId,
         });
     }
     return [...byKey.values()];
 }
+/**
+ * DX-4498 — the `effort` / `currentActivity` merge both sides apply: the report with the later `lastActivityAt` wins
+ * (ties go to `incoming`), and a null never erases a stored value.
+ */
+function latestOf(stored, incoming) {
+    const [newer, older] = incoming.lastActivityAt >= stored.lastActivityAt ? [incoming, stored] : [stored, incoming];
+    return { effort: newer.effort ?? older.effort, currentActivity: newer.currentActivity ?? older.currentActivity };
+}
 const CURSOR_KEYS = new Set(["acked", "delivered", "claims", "pastEof"]);
 const CLAIM_STATE_KEYS = new Set(["held", "pending"]);
 const PENDING_KEYS = new Set(["op", "issueId"]);
@@ -238,7 +263,26 @@ const ACTIVITY_KEYS = new Set([
     "startedAt",
     "lastActivityAt",
     "finishedAt",
+    "parentActivityId",
+    "effort",
+    "currentActivity",
+    "endStatus",
+    "briefIssueId",
 ]);
+/** DX-4498 — a nullable string field of an activity: present, and either null or a non-empty string. */
+function nullableText(a, key, where, maxChars) {
+    if (!(key in a))
+        throw new StatsPayloadError(`${where}.${key} is required (null when unknown)`);
+    const v = a[key];
+    if (v === null)
+        return null;
+    if (typeof v !== "string" || v === "")
+        throw new StatsPayloadError(`${where}.${key} must be a non-empty string or null`);
+    if (maxChars !== undefined && v.length > maxChars) {
+        throw new StatsPayloadError(`${where}.${key} exceeds ${maxChars} characters`);
+    }
+    return v;
+}
 function parseActivities(raw) {
     if (!Array.isArray(raw))
         throw new StatsPayloadError("activities must be an array");
@@ -273,6 +317,18 @@ function parseActivities(raw) {
         if (a.finishedAt !== null && !isNonNegInt(a.finishedAt)) {
             throw new StatsPayloadError(`${where}.finishedAt`);
         }
+        // DX-4498 — REQUIRED, `null` when unknown: an activity without them comes from a collector that predates them, which
+        // the `stats` surface floor refuses rather than this parser defaulting them.
+        const parentActivityId = nullableText(a, "parentActivityId", where);
+        const effort = nullableText(a, "effort", where);
+        const currentActivity = nullableText(a, "currentActivity", where, CURRENT_ACTIVITY_MAX_CHARS);
+        const endStatus = nullableText(a, "endStatus", where);
+        if (endStatus !== null && !ACTIVITY_END_STATUSES.includes(endStatus)) {
+            throw new StatsPayloadError(`${where}.endStatus must be one of ${ACTIVITY_END_STATUSES.join(", ")}, or null`);
+        }
+        const briefIssueId = nullableText(a, "briefIssueId", where);
+        if (briefIssueId !== null && !isIssueId(briefIssueId))
+            throw new StatsPayloadError(`${where}.briefIssueId`);
         return {
             kind: a.kind,
             activityId: a.activityId,
@@ -281,6 +337,11 @@ function parseActivities(raw) {
             startedAt: a.startedAt,
             lastActivityAt: a.lastActivityAt,
             finishedAt: a.finishedAt,
+            parentActivityId,
+            effort,
+            currentActivity,
+            endStatus: endStatus,
+            briefIssueId,
         };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-session-telemetry",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Shared Claude Code transcript collector (DX-2962) — incremental JSONL tailing for the danxbot worker and the danx-dashboard-mcp desktop bridge, so both run identical collector code.",
   "license": "MIT",
   "type": "module",