@50arms/session-telemetry 0.0.0-stage → 0.1.66

package/dist/activity-observer.js

@@ -0,0 +1,917 @@
+/**
+ * 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 50arms plugin in the
+ * claude-plugins repo (DX-3284; DX-4235 moved them into the plugin's hooks module), which calls
+ * `50arms_api`, 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 foreground sub-agent's own `tool_result` in the spawner's transcript (DX-5576); a background sub-agent's task notification (DX-4498); else the dispatch's terminal write (`finishOpenActivities`) as the fallback | 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`); the description through {@link redactLabel} |
+ * | `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} |
+ * | `briefProfile` | DX-5898: the leading word of its brief (the root `user` line) when shaped like a profile name, else null; the server matches it against the team's profiles |
+ * | `briefIssueId` | the card its spawning `Agent` call names: the first card id in its `description` (redacted), else the first anywhere in its brief (the root `user` line) — see {@link firstIssueId} (DX-4508) |
+ * | `finishedAt`, `endStatus` | what Claude Code writes into the SPAWNER's transcript: a foreground spawn's `tool_result` (DX-5576) or a background spawn's task notification (DX-4498) |
+ *
+ * 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: `agent-` plus the id with one leading `agent-` stripped (the hooks docs
+ * show the prefix on some `agent_id`s), so both forms reach this key. That rule lives in the 50arms plugin's hooks module
+ * (claude-plugins repo). 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 plugin 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. The finishes it
+ * reports are EXPLICIT, and a row ends one of three ways:
+ *
+ * 1. A FOREGROUND spawn's `tool_result` in the spawner's transcript (DX-5576), written when the sub-agent is done: its status is
+ *    `completed`, `failed` for an errored result, `stopped` for an interrupted or rejected one ({@link foregroundEndStatus}).
+ * 2. A BACKGROUND spawn's `<task-notification>` (DX-4498), which Claude Code delivers to the spawner when the task ends, carrying
+ *    its `<status>` (`completed`, `failed`, `killed`, `stopped`). A foreground spawn gets no notification.
+ * 3. The fallback, for a row neither signal reached: the `SubagentStop` hook (operator sessions) or the dispatch's own terminal
+ *    write, which sets `finishedAt` but names no status.
+ *
+ * Whichever lands first sets `finishedAt`; a later signal only fills the status, unless it is a later end (DX-6815: a sub-agent resumed after its finish ends again), which replaces the finish.
+ */
+import { ACTIVITY_MESSAGE_MAX_CHARS, CURRENT_ACTIVITY_MAX_CHARS, GIT_OBJECT_ID, PROFILE_WORD_MAX_LENGTH, } from "./stats-wire.js";
+import { DASHBOARD_API_TOOL_NAMES, ISSUE_ID_MAX_LENGTH, ISSUE_ID_PATTERN } from "./claim-tracker.js";
+import { SUBAGENT_TOOL_NAMES } from "./real-work.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-5333 - how many entries each map of spawn calls, spawn results and reported ends keeps; the oldest is dropped beyond this. */
+const MAX_PENDING_SPAWNS = 500;
+/** Insert `key` as the newest entry (a repeated key is renewed, not left in its old place) and drop the oldest beyond `cap`. */
+function setCapped(map, key, value, cap) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > cap)
+        map.delete(map.keys().next().value);
+}
+/** 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",
+};
+/**
+ * DX-5576 - the texts Claude Code writes as an errored `tool_result` when the user stops a call, anchored to the start so a real error that
+ * merely quotes them stays `failed`: `[Request interrupted by user for tool use]` (an interrupt) and `The user doesn't want to proceed with this
+ * tool use. The tool use was rejected` / `The user doesn't want to take this action right now. STOP what you are doing...` (a rejection),
+ * the last read from a real local transcript.
+ */
+const FOREGROUND_STOPPED = /^\s*(?:\[Request interrupted by user|The user doesn't want to (?:proceed|take this action))/i;
+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 — what {@link redactLabel} puts in place of a path-shaped token. */
+const REDACTED_PATH = "[path]";
+/** DX-4498 — what {@link redactLabel} puts in place of a secret-shaped token, or an assignment's value. */
+const REDACTED_SECRET = "[redacted]";
+/** An `ENV_NAME=value` token: its value may be a credential. */
+/** DX-5333: a value that is only `=` padding (`<base64>==`) is not an assignment value; the whole token is then classified as a bare run. */
+const ASSIGNMENT_TOKEN = /^([A-Za-z_][A-Za-z0-9_]*)=(?!=*$).+$/;
+/** The characters a key, token, hash or id is written in (a base64 key may also carry `/`, `+` and trailing `=`). */
+const OPAQUE_TOKEN = /^[A-Za-z0-9_+.-]+={0,2}$/;
+/** An AWS secret access key is exactly this long. */
+const AWS_SECRET_CHARS = 40;
+const BASE64_KEY = /^[A-Za-z0-9/+]+={0,2}$/;
+/** The shortest opaque run of letters and digits treated as a key, token, hash or id (a card id or short SHA is far shorter). */
+const OPAQUE_TOKEN_MIN_CHARS = 20;
+/** Punctuation a token may be wrapped in, which never stops it from being read as opaque. */
+export const WRAPPING_PUNCTUATION = /^[("'`[]+|[)"'`\],.:;!?]+$/g;
+/** The names an `ENV_NAME=value` assignment, a JSON key or a command-line flag carries a credential under. */
+// DX-5333: `pass` counts only after `_` or `-` (`DB_PASS`), so `bypass` and `compass` are not credential names.
+const SECRET_NAME = "(?:secret|token|passw(?:or)?d|passwd|passphrase|pwd|(?<=[_-])pass(?![a-z])|api[_-]?key|credential|private[_-]?key|signature)";
+/**
+ * Token shapes that are secrets by their prefix alone, even with no digit in the body (`ghp_...`, `sk_live_...`): GitHub, Stripe,
+ * Anthropic/OpenAI-style, Slack, npm and AWS access-key ids. A trailing `=` (base64 padding) is allowed.
+ */
+const KNOWN_SECRET_TOKEN = /^(?:gh[pousr]_|github_pat_|sk_(?:live|test)_|rk_(?:live|test)_|sk-|xox[abprs]-|npm_|hf_|glpat-)[A-Za-z0-9_-]{16,}={0,2}$|^AKIA[A-Z0-9]{16}$/;
+/** DX-5333 - a UUID: an id a brief names, never a credential. */
+const UUID_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** DX-5333 - a `claude-...` model id (a dated model name). */
+const MODEL_ID_TOKEN = /^claude-[a-z0-9.-]+$/;
+/** DX-5333 - a bare file name with an extension (`1792303009664-120f12_x.ts`); a path is already out of the opaque shape. */
+const FILE_NAME_TOKEN = /^[A-Za-z0-9_.-]+\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+/**
+ * DX-5333 — the ONE test for "this bare token is a key, token or hash": 20+ characters holding a letter and a digit, written
+ * either as a plain opaque run or as a base64 key (which may hold `/` and `+` and end in `=`; an AWS secret is one). A base64
+ * run must also mix upper and lower case. DX-5333 - a known secret shape (see {@link KNOWN_SECRET_TOKEN}) is masked first; a UUID, a
+ * `claude-*` model id and a file name with an extension are kept, since a brief that names them is worthless without them.
+ */
+function isOpaqueSecret(bare) {
+    if (KNOWN_SECRET_TOKEN.test(bare))
+        return true;
+    if (UUID_TOKEN.test(bare) || MODEL_ID_TOKEN.test(bare) || FILE_NAME_TOKEN.test(bare))
+        return false;
+    if (bare.length < OPAQUE_TOKEN_MIN_CHARS || !/[0-9]/.test(bare) || !/[A-Za-z]/.test(bare))
+        return false;
+    if (OPAQUE_TOKEN.test(bare))
+        return true;
+    if (!BASE64_KEY.test(bare) || !/[a-z]/.test(bare) || !/[A-Z]/.test(bare))
+        return false;
+    // `=` padding marks base64 outright; a `/` or `+` alone could be a path, so only the 40-character AWS secret shape counts.
+    return bare.endsWith("=") || bare.length === AWS_SECRET_CHARS;
+}
+/** Both redactors' token classifier: `options` says what each redactor leaves alone (paths, non-credential assignments, git ids) before the shared secret test. */
+function redactTokenWith(token, options) {
+    if (options.pathsRead && /[\/\\]/.test(token))
+        return REDACTED_PATH;
+    // DX-5333: a URL query pair (`?sid=...`, `&sig=...`) is an assignment behind its `?` or `&`.
+    const lead = /^[?&]*/.exec(token)[0];
+    const assignment = ASSIGNMENT_TOKEN.exec(token.slice(lead.length));
+    if (assignment !== null) {
+        if (options.assignmentNames === null || options.assignmentNames.test(assignment[1]))
+            return `${lead}${assignment[1]}=${REDACTED_SECRET}`;
+        // DX-5333: a secret VALUE is masked whatever the name it sits under (`FOO=ghp_...`, `sid=...`, `Cookie: session=...`).
+        const value = token.slice(lead.length + assignment[1].length + 1).replace(WRAPPING_PUNCTUATION, "");
+        return isOpaqueSecret(value) ? `${lead}${assignment[1]}=${REDACTED_SECRET}` : token;
+    }
+    const bare = token.replace(WRAPPING_PUNCTUATION, "");
+    // A git commit id is not a secret, and a brief that names a commit loses its meaning without it.
+    if (options.keepGitIds && GIT_OBJECT_ID.test(bare))
+        return token;
+    return isOpaqueSecret(bare) ? REDACTED_SECRET : token;
+}
+const redactToken = (token) => redactTokenWith(token, { pathsRead: true, assignmentNames: null, keepGitIds: false });
+/**
+ * DX-4498 — an agent-written label as the stats wire may carry it: on one line, with every path-shaped token (any token
+ * holding a `/` or `\`) read as `[path]`, and every secret-shaped token (an `ENV_NAME=value` value, or an opaque run of
+ * 20+ letters and digits such as a key, token or full SHA) read as `[redacted]`. A label is free text the agent wrote
+ * for a person to read (real shell descriptions name absolute paths), and it reaches every reader of the team, so this
+ * is the one way any label leaves a transcript. Empty for a blank label.
+ */
+export function redactLabel(label) {
+    return label
+        .split(/\s+/)
+        .filter((token) => token !== "")
+        .map(redactToken)
+        .join(" ");
+}
+/**
+ * DX-5333 round 5 - the run scanner: the last pass over {@link redactSecrets}'s text. A "run" is a stretch of the characters a key,
+ * token, hash, path or file name is written in; every other character (whitespace, quotes, brackets, `,;:*<>&?|\` and the like) is a
+ * boundary kept as it was, so JSON, markup and prose around a secret keep their shape. A run is masked when it is itself a secret
+ * ({@link isOpaqueSecret}); else it is cut at `=` and each side judged (`--flag=ghp_...`), then at `/` and each part judged with the
+ * stricter {@link isPathPartSecret} (`path/ghp_...`, while a hyphenated branch or directory name in a path survives).
+ */
+const RUN = /[A-Za-z0-9_+\/.=-]+/g;
+// DX-5333 round 6: index loops, not a lazy regex (`a` + 100k dots + `a` was quadratic).
+function trimRun(run) {
+    let start = 0;
+    let end = run.length;
+    while (start < end && run[start] === ".")
+        start++;
+    while (end > start && run[end - 1] === ".")
+        end--;
+    return [run.slice(0, start), run.slice(start, end), run.slice(end)];
+}
+/** A path part is a secret when it is a known secret shape, or a long unbroken letters-and-digits run (a hash, a key); hyphens and dots mark a name. */
+function isPathPartSecret(part) {
+    if (GIT_OBJECT_ID.test(part))
+        return false;
+    if (KNOWN_SECRET_TOKEN.test(part))
+        return true;
+    return part.length >= OPAQUE_TOKEN_MIN_CHARS && /^[A-Za-z0-9_]+$/.test(part) && /[0-9]/.test(part) && /[A-Za-z]/.test(part) && !UUID_TOKEN.test(part);
+}
+function maskRun(run) {
+    const [lead, core, tail] = trimRun(run);
+    if (core === "")
+        return run;
+    // A git commit id is not a secret, and a brief that names a commit loses its meaning without it.
+    if (GIT_OBJECT_ID.test(core))
+        return run;
+    if (isOpaqueSecret(core))
+        return `${lead}${REDACTED_SECRET}${tail}`;
+    if (core.includes("="))
+        return `${lead}${core.split("=").map(maskRun).join("=")}${tail}`;
+    if (core.includes("/"))
+        return `${lead}${core.split("/").map((part) => (isPathPartSecret(part) ? REDACTED_SECRET : part)).join("/")}${tail}`;
+    return run;
+}
+/** A URL's `user:password@` part: the password is read as a secret wherever the URL sits (bare, or after `DATABASE_URL=`). */
+// DX-5333 round 7: the password is everything up to the LAST `@` of the authority (the part before the first `/`), so a `#` or `?` inside it
+// is masked (`u:abc#def@host`) and `?email=a@b.com` after the path is not swallowed. When no `@` precedes the first `/`, the password may hold a `/`
+// (`u:pa/ss@host`) but then stops at `?` or `#`. DX-5333: `:<digits>/` is a port followed by a path (`localhost:5567/@vite/client`), never a password.
+const URL_CREDENTIALS = /((?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}:\/\/[^\s:/@]{0,128}:)(?!\d+\/)(?:[^\s/]{1,256}|[^\s?#]{1,256})(@)/g;
+/** A URL's `token@` userinfo with no colon (`https://ghp_...@github.com`): masked only when the userinfo is itself a secret, so `ssh://git@host` stays. */
+const URL_USERINFO_TOKEN = /((?<![A-Za-z0-9+.-])[A-Za-z][A-Za-z0-9+.-]{0,31}:\/\/)([^\s:/@]{1,256})(@)/g;
+/** A PEM private key block, BEGIN line to END line (to the end of the text when the END line was cut off). */
+const PEM_PRIVATE_KEY = /-----BEGIN [A-Z ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY(?: BLOCK)?-----|$)/g;
+/** An `Authorization` header or assignment: the scheme word stays, the credential after it goes. */
+const AUTHORIZATION_VALUE = /(\bauthorization["']?\s*[:=]\s*["']?(?:(?:bearer|basic|token)\s+)?)[^\s"']+/gi;
+/** A bearer credential written outside a header. */
+const BEARER_VALUE = /(\bbearer\s+)(?!\[redacted\])[^\s"']+/gi;
+/**
+ * A credential-named key (plain, or quoted as JSON) followed by `:` or `=`, with its value (quoted, or unquoted).
+ * DX-5333 round 7: an unquoted value runs to whitespace, a quote, a comma or a semicolon, so `password=pa)ss` is masked whole. It also
+ * stops at a closer (`) } ] >`) only when the key is directly enclosed by an opener (`{password: x}`, `(token=x)`, `[password=x]`), so the
+ * closer stays. An existing `[redacted]` is kept only as the WHOLE value; `[redacted]hunter2` is masked entirely, enclosed too (the enclosed
+ * fallback takes a leading `[redacted]` whole, or its `]` would end the value and leave `hunter2` in clear).
+ */
+const NAMED_KEY = String.raw `["']?[\w-]{0,64}${SECRET_NAME}[\w-]{0,64}["']?\s*[:=]\s*`;
+const NAMED_VALUE = new RegExp(String.raw `(?<=[({\[<]\s{0,16})(${NAMED_KEY})(\[redacted\](?![^\s"',;)}\]>])|"[^"]*"|'[^']*'|(?:\[redacted\])?[^\s"',;)}\]>]+)|(${NAMED_KEY})(\[redacted\](?![^\s"',;])|"[^"]*"|'[^']*'|[^\s"',;]+)`, "gi");
+/** DX-5333: a passphrase is several words (`passphrase: correct horse`): its unquoted value runs to the end of the line, bounded. */
+const PASSPHRASE_VALUE = /(\bpassphrase["']?\s*[:=][ \t]*)(?![ \t])(?!\[redacted\])[^\n"']{1,200}/gi;
+/** A masked value keeps the quotes it was written in, so a JSON body stays JSON. */
+const maskedValue = (_match, enclosedName, enclosedValue, name2, value2) => {
+    const name = enclosedName ?? name2 ?? "";
+    const value = enclosedValue ?? value2 ?? "";
+    const quote = value[0] === '"' || value[0] === "'" ? value[0] : "";
+    return `${name}${quote}${REDACTED_SECRET}${quote}`;
+};
+/** A credential-named command-line flag followed by its value after a space (`--password x`). */
+const FLAG_VALUE = new RegExp(String.raw `(--[\w-]{0,64}${SECRET_NAME}[\w-]{0,64}\s+)(?!-)[^\s]+`, "gi");
+/**
+ * DX-5333 — a message as the stats wire may carry it: every credential read as `[redacted]` — a URL's password, an
+ * `Authorization`/bearer value, the value of a credential-named assignment, JSON key or `--flag` (`password: x`,
+ * `"password": "x"`, `--password x`), and every opaque run of 20+ characters (a key, a token, a base64 secret that may hold
+ * `/` or end in `=`; a git commit id is kept) — with the text's own whitespace, line breaks, paths and prose kept: a brief is
+ * read to replay the work, and its paths are the work. NUL characters are removed (Postgres refuses them, which would wedge
+ * the write that carries the message). Cut to {@link ACTIVITY_MESSAGE_MAX_CHARS}. The server applies the same function again
+ * on receipt.
+ *
+ * The order of the chain matters: NUL goes first, the PEM block next (its body lines would otherwise be read token by token), then
+ * the structured patterns (URL credentials, headers, named values, flags), and the per-token classifier last, over what is
+ * left. The server re-runs the whole chain on text already masked here, so every step must leave `[redacted]` alone (idempotent).
+ */
+export function redactSecrets(text) {
+    // DX-5333: cut the raw text first so the passes below never run over more than the wire carries.
+    const redacted = (text.length > ACTIVITY_MESSAGE_MAX_CHARS ? text.slice(0, ACTIVITY_MESSAGE_MAX_CHARS) : text)
+        .replace(/\u0000/g, "")
+        .replace(PEM_PRIVATE_KEY, REDACTED_SECRET)
+        .replace(URL_CREDENTIALS, `$1${REDACTED_SECRET}$2`)
+        .replace(URL_USERINFO_TOKEN, (match, scheme, user, at) => (isOpaqueSecret(user) ? `${scheme}${REDACTED_SECRET}${at}` : match))
+        .replace(AUTHORIZATION_VALUE, `$1${REDACTED_SECRET}`)
+        .replace(BEARER_VALUE, `$1${REDACTED_SECRET}`)
+        .replace(PASSPHRASE_VALUE, `$1${REDACTED_SECRET}`)
+        .replace(NAMED_VALUE, maskedValue)
+        .replace(FLAG_VALUE, `$1${REDACTED_SECRET}`)
+        .replace(RUN, maskRun);
+    return redacted.length > ACTIVITY_MESSAGE_MAX_CHARS ? redacted.slice(0, ACTIVITY_MESSAGE_MAX_CHARS) : redacted;
+}
+/** DX-4498 — a transcript value read as a label: {@link redactLabel}'s text, or null for a non-string or blank one. */
+export function labelOf(value) {
+    if (typeof value !== "string")
+        return null;
+    const label = redactLabel(value);
+    return label === "" ? null : label;
+}
+/**
+ * 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), through {@link labelOf}. Never a command, a file path, a secret or a prompt: the stats wire carries ids,
+ * numbers and redacted labels, never free-form transcript content.
+ */
+export function describeToolCall(name, input) {
+    let detail = null;
+    switch (name) {
+        case "Bash":
+        case "PowerShell":
+        case "Agent":
+        case "Task":
+            detail = labelOf(input.description);
+            break;
+        case "Skill":
+            detail = labelOf(input.skill);
+            break;
+    }
+    const text = detail === null ? name : `${name}: ${detail}`;
+    return text.length > CURRENT_ACTIVITY_MAX_CHARS ? `${text.slice(0, CURRENT_ACTIVITY_MAX_CHARS - 3)}...` : text;
+}
+/**
+ * DX-4508 — the first card-id-shaped token in a text (`DX-4498`, also `DX-4498:`, `(DX-4498)`), or null when it has
+ * none. A sub-agent's card is the one its spawning `Agent` call names: its `description` ("Review DX-4498 code gates")
+ * first, else its brief ("Quality gate for card DX-4421 ..."), where the first-word rule DX-4498 shipped missed most
+ * real briefs. Only the SHAPE is checked: the server keeps the id only when it is a real card of the team, so a plan ref
+ * (`PLAN-2`) or rule ref (`R-45`) never reaches a reader.
+ */
+export function firstIssueId(text) {
+    for (const token of text.split(/\s+/)) {
+        const bare = token.replace(WRAPPING_PUNCTUATION, "");
+        if (bare.length <= ISSUE_ID_MAX_LENGTH && ISSUE_ID_PATTERN.test(bare))
+            return bare;
+    }
+    return null;
+}
+/** DX-5898: the shape of an agent profile's name (`gate-designer`); anything else leading a brief is prose, never stored. */
+const PROFILE_WORD_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * DX-5898 - the leading word of a sub-agent's brief when it has a profile name's shape (`gate-designer DX-5875` -> `gate-designer`), else
+ * null. An orchestrator briefs a profile sub-agent as `<profile> <CARD-ID>` (DX-5899); the collector cannot know the team's profiles, so it
+ * keeps only the raw word and the server matches it against the profiles the team may see when it reads the row. A brief that opens with an
+ * ordinary word equal to a profile's name therefore gives a false match: the shape check and that server match are the only filters.
+ */
+export function leadingProfileWord(text) {
+    const first = text.trim().split(/\s+/)[0] ?? "";
+    const bare = first.replace(WRAPPING_PUNCTUATION, "");
+    return bare.length <= PROFILE_WORD_MAX_LENGTH && PROFILE_WORD_PATTERN.test(bare) ? bare : null;
+}
+/**
+ * DX-5333 — whether a `user` line is a message the coordinator (the parent session) sent: Claude Code writes a `SendMessage`
+ * follow-up to a running sub-agent as `isMeta: true` with `origin.kind: "coordinator"`. Any other meta line is Claude Code's own.
+ */
+function isCoordinatorLine(raw) {
+    return raw.origin?.kind === "coordinator";
+}
+/** 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;
+}
+/** The text blocks of an `assistant` line's content, joined; empty when it has none. */
+function assistantText(raw) {
+    const content = raw.message?.content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .filter((b) => b?.type === "text" && typeof b.text === "string")
+        .map((b) => b.text)
+        .join("\n\n")
+        .trim();
+}
+/** DX-5333 — whether an assistant line carries a tool call. */
+function hasToolUse(raw) {
+    const content = raw.message?.content;
+    return Array.isArray(content) && content.some((b) => b?.type === "tool_use");
+}
+/** DX-5333 — the API message id an assistant line belongs to (Claude Code writes each content block as its own line). */
+function assistantMessageId(raw) {
+    return raw.message?.id;
+}
+/** A follow-up message delivered to a sub-agent as a queued command (Claude Code's `SendMessage`), or null for any other line. */
+function queuedCommandText(raw) {
+    if (raw.type !== "attachment")
+        return null;
+    const attachment = raw.attachment;
+    if (attachment?.type !== "queued_command" || attachment.commandMode === "task-notification")
+        return null;
+    return typeof attachment.prompt === "string" ? attachment.prompt : null;
+}
+/** DX-5333 — the `50arms_api` call that creates a card problem: `POST /api/issues/<id>/problems`. */
+const PROBLEM_CREATE_PATH = /^\/api\/issues\/[^/?#]+\/problems\/?(?:[?#].*)?$/;
+/** The `tool_use` blocks of an `assistant` line's content that are problem-create calls, as their ids. */
+function problemCreateCallIds(raw) {
+    const content = raw.message?.content;
+    if (!Array.isArray(content))
+        return [];
+    const ids = [];
+    for (const block of content) {
+        if (block?.type !== "tool_use" || typeof block.id !== "string" || typeof block.name !== "string")
+            continue;
+        if (!DASHBOARD_API_TOOL_NAMES.has(block.name))
+            continue;
+        const input = block.input;
+        if (typeof input?.method === "string" && input.method.toUpperCase() === "POST" && typeof input.path === "string" && PROBLEM_CREATE_PATH.test(input.path)) {
+            ids.push(block.id);
+        }
+    }
+    return ids;
+}
+/** DX-5333 - the ids of the Agent / Task `tool_use` blocks of an `assistant` line. */
+function spawnCallIdsOf(raw) {
+    const content = raw.message?.content;
+    if (!Array.isArray(content))
+        return [];
+    const ids = [];
+    for (const block of content) {
+        if (block?.type === "tool_use" && typeof block.id === "string" && typeof block.name === "string" && SUBAGENT_TOOL_NAMES.has(block.name))
+            ids.push(block.id);
+    }
+    return ids;
+}
+/** The `tool_result` blocks of a `user` line's content, as `(tool_use_id, text)`. */
+function toolResults(raw) {
+    const content = raw.message?.content;
+    if (!Array.isArray(content))
+        return [];
+    const out = [];
+    for (const block of content) {
+        if (block?.type !== "tool_result" || typeof block.tool_use_id !== "string")
+            continue;
+        const body = block.content;
+        const text = typeof body === "string"
+            ? body
+            : Array.isArray(body)
+                ? body.map((b) => (b?.type === "text" ? String(b.text) : "")).join("")
+                : "";
+        out.push({ toolUseId: block.tool_use_id, text, isError: block.is_error === true });
+    }
+    return out;
+}
+/**
+ * DX-5576 - how a foreground spawn ended, from its own `tool_result` (a foreground spawn gets no task notification): an errored result
+ * is `failed`, or `stopped` when the user interrupted or rejected the call, any other result is `completed`.
+ */
+function foregroundEndStatus(result) {
+    if (!result.isError)
+        return "completed";
+    return FOREGROUND_STOPPED.test(result.text) ? "stopped" : "failed";
+}
+/** DX-5333 - whether a spawn's `tool_result` is the notice of a background launch (`toolUseResult.status` `async_launched`; a nested spawner's line has no `toolUseResult`, so its text is read), not a completion. */
+function isAsyncLaunch(raw, resultText) {
+    if (raw.toolUseResult?.status === "async_launched")
+        return true;
+    return /^\s*async agent launched/i.test(resultText);
+}
+/** The number of the problem a successful `50arms_api` problem-create answer names (`{ok, status: 201, body: {ref_num}}`, DX-5516: the n of its `PBLM-n`, never its row id), or null. */
+function createdProblemRefNum(resultText) {
+    try {
+        const answer = JSON.parse(resultText);
+        const refNum = answer.body?.ref_num;
+        return answer.ok === true && answer.status === 201 && typeof refNum === "number" && Number.isInteger(refNum) && refNum > 0 ? refNum : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** How many problem-create calls awaiting their answer are remembered; the oldest is dropped beyond this. */
+const MAX_PENDING_PROBLEM_CALLS = 200;
+/** DX-5333 - a transcript line's text field with any NUL removed (the wire parser refuses one, and a refused write is re-sent forever). */
+const withoutNul = (value) => value.replace(/\u0000/g, "");
+function optionalLineText(value) {
+    if (typeof value !== "string")
+        return null;
+    const text = withoutNul(value);
+    return text === "" ? null : text;
+}
+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 (its `lastWriteAt` for the activity stamp), the
+    // 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 }]);
+    /**
+     * DX-5333 — sub-agents this observer saw START (not one already running when the collector attached): only their first
+     * line's checkout is still the commit they started from. Maps the source to the working directories already tried.
+     */
+    const awaitingStartSha = new Map();
+    /** DX-5333 — problem-create calls not yet answered, by their `tool_use` id, with the sub-agent that made them. */
+    const pendingProblemCalls = new Map();
+    /**
+     * DX-5333 — a text-only assistant line is the sub-agent's report only if nothing follows it in the same turn. Claude Code
+     * does not always fill `stop_reason` on that line (a short reply stays `null`), and writes a message's text and tool call
+     * as separate lines, so the line is held here until the next line decides it: a tool call of the same message withdraws it,
+     * any other line (or the sub-agent's reported end) confirms it. Keyed by activity; one candidate per sub-agent.
+     */
+    const pendingReports = new Map();
+    /**
+     * DX-5333 — foreground sub-agents by the `tool_use` id of the spawn call. The spawner's `tool_result` for that call is written
+     * when the sub-agent is done, so it ENDS the row (DX-5576: `finishedAt` and the status {@link foregroundEndStatus} reads from the
+     * result) and confirms a held report that no later line of the sub-agent's own transcript will.
+     */
+    const foregroundSpawns = new Map();
+    /** DX-5333 - the `tool_use` ids of Agent / Task calls, so an early result is buffered for a spawn and never for another tool. */
+    const spawnCallIds = new Map();
+    /**
+     * DX-5333 - a spawn's result read before its sub-agent was discovered (`meta.json` lands after the `.jsonl`), by the call id, with the
+     * result line's time and the end status it gives (DX-5576), applied when the sub-agent is registered. Capped like {@link MAX_PENDING_ENDS}.
+     */
+    const earlyResults = new Map();
+    /**
+     * DX-5333 - activities whose end was reported (a foreground spawn's result, or a task-notification), with the reporting line's
+     * time. The spawner's file is read before the sub-agent's, so at the poll's end every line up to it has been read and the held
+     * reply is the sub-agent's final ({@link ActivityObserver.onPollComplete}); the first sub-agent line dated AFTER it (a
+     * `SendMessage` resume) settles it too. Either way the entry is removed, so a resumed turn holds and withdraws its text like any other.
+     * DX-5413: a nested spawner can be read AFTER its child in the same poll (discovery order), so a signal read this poll proves nothing about
+     * the child's lines; only a signal recorded in an EARLIER poll confirms (`settlesNext` on its {@link endedAwaitingPoll} entry), costing up to one poll of delay.
+     */
+    // DX-5413: `settlesNext` lives in the entry, so the one cap bounds both (a separate set outgrew it on a long-lived collector).
+    // The one-poll delay is why `SessionLogWatcher.drainFinal` drains twice: change one, change the other.
+    const endedAwaitingPoll = new Map();
+    const recordEnd = (activityId, at) => {
+        setCapped(endedAwaitingPoll, activityId, { at, settlesNext: false }, MAX_PENDING_SPAWNS);
+    };
+    /**
+     * DX-5576: the one end for a started row, whichever signal brought it (a foreground result or a task notification): confirm the held
+     * reply at the next poll's end (the sub-agent's last lines may not be read yet, DX-5333 / DX-5413), apply the end, and report only a change.
+     */
+    const endActivity = (change, end) => {
+        recordEnd(change.activityId, end.at);
+        // DX-6815: an end older than the one held (a replay of a first notification after the second) is nothing new, and so is the same end again.
+        if (change.finishedAt !== null && (end.at < change.finishedAt || (end.at === change.finishedAt && change.endStatus === end.endStatus)))
+            return;
+        applyEnd(change, { finishedAt: end.at, endStatus: end.endStatus });
+        report(change);
+    };
+    const registerForeground = (toolUseId, activityId) => {
+        const returned = earlyResults.get(toolUseId);
+        if (returned === undefined) {
+            setCapped(foregroundSpawns, toolUseId, activityId, MAX_PENDING_SPAWNS);
+            return;
+        }
+        earlyResults.delete(toolUseId);
+        const change = started.get(activityId);
+        if (change !== undefined)
+            endActivity(change, returned);
+    };
+    const confirmReport = (change) => {
+        const pending = pendingReports.get(change.activityId);
+        if (pending === undefined)
+            return;
+        pendingReports.delete(change.activityId);
+        message(pending.raw, change, "final", pending.text, pending.at);
+    };
+    const message = (raw, change, kind, text, at) => {
+        if (deps.recordMessages === undefined || typeof raw.uuid !== "string")
+            return;
+        const messageKey = withoutNul(raw.uuid);
+        if (messageKey === "")
+            return;
+        const redacted = redactSecrets(text);
+        if (redacted.trim() === "")
+            return;
+        deps.recordMessages([
+            { activityId: change.activityId, kind, messageKey, text: redacted, at, cwd: optionalLineText(raw.cwd), gitBranch: optionalLineText(raw.gitBranch) },
+        ]);
+    };
+    /**
+     * Stamp `startSha` from the first line whose `cwd` is a git checkout (a sub-agent that starts in a non-git directory tries
+     * again on each new `cwd`). The read is asynchronous, so the stamp is reported when git answers, never blocking the line feed.
+     */
+    const stampStartSha = (raw, change) => {
+        const tried = awaitingStartSha.get(change.activityId);
+        const cwd = optionalLineText(raw.cwd);
+        if (tried === undefined || cwd === null || tried.has(cwd) || deps.readHeadSha === undefined)
+            return;
+        tried.add(cwd);
+        void deps
+            .readHeadSha(cwd)
+            .catch(() => null)
+            .then((sha) => {
+            // Another line's answer may have stamped it first; the first answer stands.
+            if (sha === null || !awaitingStartSha.has(change.activityId))
+                return;
+            awaitingStartSha.delete(change.activityId);
+            change.startSha = sha;
+            report(change);
+        });
+    };
+    const applyEnd = (change, end) => {
+        // DX-6815: the LATEST finish stands (the server's own merge, `mergedFinish`), so a sub-agent resumed after its first finish ends again at its
+        // second; the LATEST status wins with it.
+        change.finishedAt = end.finishedAt;
+        change.endStatus = end.endStatus;
+    };
+    /** DX-5333 — what a line does to the held report: a tool call of the same message withdraws it, any other line confirms it. */
+    const settlePendingReport = (raw, change) => {
+        const pending = pendingReports.get(change.activityId);
+        if (pending === undefined)
+            return;
+        if (raw.type === "assistant" && assistantMessageId(raw) === pending.messageId) {
+            // The same message's next block: more text replaces the held text (set by the caller), a tool call withdraws it.
+            if (hasToolUse(raw))
+                pendingReports.delete(change.activityId);
+            return;
+        }
+        confirmReport(change);
+    };
+    const onNotification = (taskId, endStatus, at) => {
+        const source = `${SUBAGENT_SOURCE_PREFIX}${taskId}`;
+        const change = started.get(source);
+        if (change === undefined) {
+            setCapped(pendingEnds, source, { finishedAt: at, endStatus }, MAX_PENDING_ENDS);
+            return;
+        }
+        endActivity(change, { at, endStatus });
+    };
+    return {
+        onSourceDiscovered(info) {
+            // Not this dispatch's sub-agent (see `ignorePreexisting`). Never added to
+            // `started` either, so its later lines do not stamp activity on a row
+            // that does not exist.
+            if (deps.ignorePreexisting === true && info.preexisting)
+                return;
+            const existing = started.get(info.source);
+            if (existing) {
+                // 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;
+                    filled = true;
+                }
+                const description = labelOf(info.description);
+                if (existing.description === null && description !== null) {
+                    existing.description = description;
+                    filled = true;
+                    // DX-4508 — the description outranks the brief: a late sidecar naming a card replaces a brief-derived id.
+                    const named = firstIssueId(description);
+                    if (named !== null && named !== existing.briefIssueId)
+                        existing.briefIssueId = named;
+                }
+                if (info.foregroundToolUseId !== null)
+                    registerForeground(info.foregroundToolUseId, existing.activityId);
+                if (existing.parentActivityId === null && info.parentSource !== null) {
+                    existing.parentActivityId = info.parentSource;
+                    filled = true;
+                }
+                if (filled)
+                    report(existing);
+                return;
+            }
+            // DX-4498 — the label its spawning `Agent` call gave it, from the sidecar, redacted like every label.
+            const description = labelOf(info.description);
+            const change = {
+                kind: "agent",
+                activityId: info.source,
+                agentType: info.agentType,
+                description,
+                startedAt: info.discoveredAt,
+                // DX-5110: the file's own last write, not the discovery time: a restarted collector re-discovers every finished
+                // sub-agent, and the server's GREATEST merge would otherwise revive each as live for the liveness window.
+                lastActivityAt: info.lastWriteAt,
+                finishedAt: null,
+                parentActivityId: info.parentSource,
+                effort: null,
+                currentActivity: null,
+                endStatus: null,
+                // DX-4508 — the card the description names (the REDACTED label: the one way a label leaves a transcript); the
+                // brief fills it in only while this is still null.
+                briefIssueId: description === null ? null : firstIssueId(description),
+            };
+            const pending = pendingEnds.get(info.source);
+            if (pending !== undefined) {
+                pendingEnds.delete(info.source);
+                applyEnd(change, pending);
+                recordEnd(info.source, pending.finishedAt);
+            }
+            started.set(info.source, change);
+            // DX-5576: after `started.set`, so a result already read ends the row it was just registered for.
+            if (info.foregroundToolUseId !== null)
+                registerForeground(info.foregroundToolUseId, info.source);
+            if (!info.preexisting && deps.readHeadSha !== undefined) {
+                change.startSha = null;
+                awaitingStartSha.set(info.source, new Set());
+            }
+            report(change);
+        },
+        onPollComplete() {
+            // DX-5413: only an end signal recorded in an earlier poll confirms; one read this poll waits for the next.
+            for (const [activityId, ended] of [...endedAwaitingPoll]) {
+                if (!ended.settlesNext) {
+                    ended.settlesNext = true;
+                    continue;
+                }
+                const change = started.get(activityId);
+                if (change !== undefined)
+                    confirmReport(change);
+                endedAwaitingPoll.delete(activityId);
+            }
+        },
+        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;
+            }
+            // DX-5333 — the spawner's result for a foreground spawn ends that sub-agent; a nested spawner's line has no
+            // `toolUseResult`, so the match is on the call id alone. Read wherever it is found, like a notification.
+            if (raw.type === "user") {
+                for (const result of toolResults(raw)) {
+                    // A spawn moved to the background answers at once with a launch notice; that is not its completion.
+                    if (isAsyncLaunch(raw, result.text))
+                        continue;
+                    const spawned = foregroundSpawns.get(result.toolUseId);
+                    if (spawned === undefined) {
+                        if (spawnCallIds.has(result.toolUseId))
+                            setCapped(earlyResults, result.toolUseId, { at, endStatus: foregroundEndStatus(result) }, MAX_PENDING_SPAWNS);
+                        continue;
+                    }
+                    foregroundSpawns.delete(result.toolUseId);
+                    const spawnedChange = started.get(spawned);
+                    if (spawnedChange !== undefined)
+                        endActivity(spawnedChange, { at, endStatus: foregroundEndStatus(result) });
+                }
+            }
+            if (raw.type === "assistant")
+                for (const id of spawnCallIdsOf(raw))
+                    setCapped(spawnCallIds, id, true, MAX_PENDING_SPAWNS);
+            const change = started.get(meta.source);
+            if (!change)
+                return;
+            // DX-5333 — a follow-up delivered as a queued command.
+            const queued = queuedCommandText(raw);
+            if (queued !== null)
+                message(raw, change, "followup", queued, at);
+            // DX-5333: a line dated after the spawn's result is a resumed turn; what was held before it was the final of the turn that returned.
+            const ended = endedAwaitingPoll.get(change.activityId);
+            if (ended !== undefined && at > ended.at)
+                endedAwaitingPoll.delete(change.activityId);
+            settlePendingReport(raw, change);
+            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 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
+            // silent for half an hour would come out of it looking live, so
+            // `RUNNING_ACTIVITY_SILENT_AFTER_MS` could never fire for it. That is the
+            // one signal this feature has for "ended or stuck" (DX-3246 fixed the same
+            // 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.
+            //
+            // GREATEST, mirroring the server: a line read out of order, or an older
+            // 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;
+            }
+            // DX-5333 — the checkout the sub-agent started in, read from its first line that names a git checkout.
+            stampStartSha(raw, change);
+            if (raw.type === "user") {
+                // DX-5333 — the brief (the chain's root line) and every later message sent to it; a tool result is neither.
+                const text = userText(raw);
+                if (text !== null && (raw.isMeta !== true || isCoordinatorLine(raw)))
+                    message(raw, change, raw.parentUuid === null ? "brief" : "followup", text, at);
+                // DX-5333 — the answer to a problem-create call this sub-agent made.
+                for (const result of toolResults(raw)) {
+                    const source = pendingProblemCalls.get(result.toolUseId);
+                    if (source === undefined)
+                        continue;
+                    pendingProblemCalls.delete(result.toolUseId);
+                    const problemRefNum = createdProblemRefNum(result.text);
+                    if (problemRefNum !== null)
+                        deps.recordProblemLinks?.([{ activityId: source, problemRefNum }]);
+                }
+                // 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. DX-4508 — read only while no card is known: a description's id wins.
+                // DX-5898 - the profile word is read from the same root line, once.
+                if (change.briefProfile === undefined && raw.parentUuid === null && text !== null) {
+                    change.briefProfile = leadingProfileWord(text);
+                    changed = true;
+                }
+                if (change.briefIssueId === null && raw.parentUuid === null) {
+                    const id = text === null ? null : firstIssueId(text);
+                    if (id !== null) {
+                        change.briefIssueId = id;
+                        changed = true;
+                    }
+                }
+            }
+            else {
+                // DX-5333 — a reply that ended the sub-agent's turn is its report; a problem-create call is remembered until answered.
+                const text = assistantText(raw);
+                if (text !== "") {
+                    if (raw.message?.stop_reason === "end_turn") {
+                        pendingReports.delete(change.activityId);
+                        message(raw, change, "final", text, at);
+                    }
+                    else if (!hasToolUse(raw) && raw.isApiErrorMessage !== true) {
+                        // DX-5333 — never a synthetic API-error line (`isApiErrorMessage`, model `<synthetic>`): Claude Code's notice, not a reply.
+                        pendingReports.set(change.activityId, { raw, text, at, messageId: assistantMessageId(raw) });
+                    }
+                }
+                for (const id of problemCreateCallIds(raw)) {
+                    setCapped(pendingProblemCalls, id, change.activityId, MAX_PENDING_PROBLEM_CALLS);
+                }
+            }
+            if (raw.type === "assistant" && 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);
+        },
+    };
+}