@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/traces/schema2-build.js

@@ -1,47 +1,15 @@
-/**
- * schema2-build — the PRODUCER's per-tool mappers + `buildSessionDetailV2`
- * (PHNX-3442 step 2, increments 2-4).
- *
- * Populates the `SessionStepV2` discriminated union (schema2.ts) from the parsed
- * session events, reusing the SAME infrastructure the schema-1 path already uses:
- *
- *   - the callId pairing loop (`pairSteps` in session/trajectory.ts) — so a step's
- *     (use event, result event) triple is recovered without a duplicate loop;
- *   - bash unwrap/tokenize/classify (`session/bash-command.ts`) + the effective
- *     program resolver (`effectiveProgram`);
- *   - the meta / whereItWentWrong / surfacedToolFailures / active-time helpers
- *     factored out of sync.ts (`buildDetailMeta`, `buildWhereItWentWrong`, …).
- *
- * The command/patch/output PARSING lives here; the worker stores the shard
- * opaquely and the console reads the union directly and never reparses (spec §5).
- *
- * category / risk / categoryMetrics are DELIBERATELY omitted from the schema-2
- * detail: the shipped consumer (`decodeSessionDetail` → coerceCategory/Risk/Metrics)
- * backfills them to the same neutral defaults it uses for schema-1, so computing
- * them here would be inventing session-level signal this step does not own.
- */
 import { createHash } from 'node:crypto';
 import { redactSecrets } from '../redact.js';
-import { classifyBashCommand, tokenizeBash, unwrapCommand, } from '../session/bash-command.js';
-import { computeSummaryStats } from '../session/render.js';
-import { extractShellPrograms } from '../session/shell-programs.js';
-import { effectiveProgram, eventTimestampsMs, pairSteps, } from '../session/trajectory.js';
+import { classifyBashCommand, tokenizeBash, unwrapCommand, } from '@phnx-labs/sessions-cli/reader';
+import { computeSummaryStats } from '@phnx-labs/sessions-cli/reader';
+import { extractShellPrograms } from '@phnx-labs/sessions-cli/reader';
+import { effectiveProgram, eventTimestampsMs, pairSteps, } from '@phnx-labs/sessions-cli/reader';
 import { classifyActionDanger } from './schema2-danger.js';
 import { activeMsFromTrajectory, buildDetailMeta, buildWhereItWentWrong, } from './sync.js';
-// ---------------------------------------------------------------------------
-// Small value helpers
-// ---------------------------------------------------------------------------
-/** Cap on a single preview's characters — the same 500-ish bound parse.ts uses. */
 const PREVIEW_MAX = 2000;
 function shortHash(text) {
     return createHash('sha256').update(text).digest('hex').slice(0, 16);
 }
-/**
- * A bounded, redacted preview of text. `truncated` and `originalBytes` are honest —
- * the console needs to know whether it is seeing the whole thing (spec: the UI must
- * distinguish complete from truncated output). `originalBytes` is the UTF-8 byte
- * length of the FULL text, before clipping.
- */
 function textPreview(raw, redact, knownSecrets) {
     if (raw === undefined || raw === null || raw.length === 0)
         return undefined;
@@ -70,7 +38,6 @@ function numberArg(args, ...keys) {
     }
     return undefined;
 }
-/** The result event's ExecutionResult (exit/status/error codes + a combined output preview). */
 function resultOf(resultEvent, redact, knownSecrets) {
     const result = {};
     if (!resultEvent)
@@ -92,11 +59,6 @@ function stepOutcome(step) {
         return o;
     return 'unknown';
 }
-/**
- * `at-least` when the output was truncated by the parser's per-event cap, else
- * `exact`. The parser caps `output` centrally (parse.ts `maxToolOutputChars`), so a
- * result whose text hit the cap under-counts — the count is a floor, not the truth.
- */
 function countLines(resultEvent) {
     if (!resultEvent)
         return undefined;
@@ -104,40 +66,17 @@ function countLines(resultEvent) {
     if (typeof text !== 'string' || text.length === 0)
         return undefined;
     const lines = text.split('\n');
-    // A trailing newline yields a final empty element — don't count it as a line.
     const value = lines.length > 0 && lines[lines.length - 1] === '' ? lines.length - 1 : lines.length;
-    // The parser truncates long tool output; we can't see the original length here,
-    // so a preview that fills the cap is treated as a floor. PREVIEW-independent:
-    // parse.ts already clipped, so the safest signal is whether the text looks cut.
     const truncated = text.length >= PREVIEW_MAX;
     return { value, relation: truncated ? 'at-least' : 'exact' };
 }
-// ---------------------------------------------------------------------------
-// Bash unwrapping — extend unwrapCommand for the shell-exec wrappers it misses
-// ---------------------------------------------------------------------------
-/**
- * `unwrapCommand` (bash-command.ts) strips VAR=/sudo/cd&&/npx/loops/subshells but
- * NOT an interpreter wrapper like `/bin/zsh -lc "…"`, `bash -lc '…'`, or `sh -c …`
- * — the exact shape the managed runner wraps every command in. Peel that first,
- * then hand the inner payload to the existing unwrapper so all the wrappers it DOES
- * know still apply. One extra rule, at the source, not a fork of unwrapCommand.
- */
 export function unwrapShellExec(command) {
     const s = command.trim();
-    // <interpreter> [flags] -c|-lc "PAYLOAD"  — interpreter is bash/zsh/sh/dash/ksh,
-    // possibly a full path; the -c flag may be clustered with login/interactive
-    // flags (`-lc`, `-ic`). The payload is the last quoted argument.
     const m = s.match(/^(?:\S*\/)?(?:bash|zsh|sh|dash|ksh)\s+(?:-[a-zA-Z]*c[a-zA-Z]*)\s+(['"])([\s\S]*)\1\s*$/);
     if (m)
         return unwrapShellExec(m[2]);
     return unwrapCommand(s);
 }
-/**
- * Map a classifier `BashCategory` (the rich vcs|build-test|install|… taxonomy) to
- * the coarse schema-2 `BashCategory` (build|test|git|network|other). `build-test`
- * needs the argv/subcommand to decide build vs test — `bun test` is test, `bun
- * build` is build — so this takes the tokenized argv too.
- */
 export function mapBashCategory(cat, argv) {
     switch (cat) {
         case 'vcs':
@@ -155,34 +94,18 @@ export function mapBashCategory(cat, argv) {
             return 'other';
     }
 }
-/**
- * Whether a segment's argv is COMPLETE — i.e. no dynamic node (command
- * substitution, process substitution, arithmetic/param expansion, glob) could
- * change what actually ran. Reuses the shell parser's occurrence walk indirectly:
- * a segment whose reconstructed programs from `extractShellPrograms` are all static
- * is complete. We approximate with the parser's diagnostics + a substitution scan,
- * because the schema-2 argv is the tokenizeBash split (shlex), which cannot itself
- * report expansion.
- */
 function argvComplete(source) {
-    // A command/process substitution or an unexpanded var/glob means the literal
-    // argv we tokenized is not the whole story.
     if (/\$\(|\$\{|`|<\(|\)\s*$/.test(source) && /\$\(|\$\{|`|<\(/.test(source))
         return false;
     if (/\$[A-Za-z_]/.test(source))
-        return false; // a bare $VAR expansion
+        return false;
     if (/[*?]/.test(source) && !/['"][^'"]*[*?]/.test(source))
-        return false; // an unquoted glob
+        return false;
     return true;
 }
-/** Build the per-segment BashAction list for a bash command. */
 export function buildBashActions(unwrapped) {
     const segments = tokenizeBash(unwrapped);
     const actions = [];
-    // Recover each segment's raw source text for `source`/argvComplete: tokenizeBash
-    // drops the operators, so re-derive display source from the argv join (redaction
-    // is applied by the caller on the whole command; the per-action source is the
-    // already-tokenized argv, which carries no secrets the command didn't).
     segments.forEach((argv, i) => {
         if (argv.length === 0)
             return;
@@ -214,9 +137,6 @@ function bashExecution(step, useEvent, resultEvent, ctx) {
     const unwrappedCommand = ctx.redact ? redactSecrets(unwrapped, ctx.knownSecrets) : unwrapped;
     const { diagnostics } = extractShellPrograms(unwrapped);
     const actions = buildBashActions(unwrapped);
-    // parseStatus: `parsed` when we tokenized ≥1 segment and the parser had no
-    // diagnostics; `partial` when we got segments but the parser flagged something;
-    // `unparseable` when we recovered no segments at all from a non-empty command.
     let parseStatus;
     if (actions.length === 0)
         parseStatus = rawCommand.trim().length === 0 ? 'parsed' : 'unparseable';
@@ -284,12 +204,6 @@ function grepExecution(step, useEvent, resultEvent, ctx) {
         exec.hits = hits;
     return exec;
 }
-/**
- * Build a FileMutation from an Edit (`old_string`/`new_string`) or Write
- * (`content`). The single hunk's added/removed line counts come from the string
- * diff; beforeHash/afterHash are content fingerprints so the cross-step revert
- * ledger can match a later edit that restores an earlier one.
- */
 function fileMutationFromEdit(useEvent) {
     const path = stringArg(useEvent.args, 'file_path', 'path', 'filePath') ?? useEvent.path;
     if (!path)
@@ -297,8 +211,6 @@ function fileMutationFromEdit(useEvent) {
     const oldStr = stringArg(useEvent.args, 'old_string', 'old_str');
     const newStr = stringArg(useEvent.args, 'new_string', 'new_str');
     if (oldStr === undefined && newStr === undefined) {
-        // No diff strings — record the mutation with an empty hunk list rather than
-        // fabricate line counts.
         return { path, operation: 'update', hunks: [] };
     }
     const before = oldStr ?? '';
@@ -329,9 +241,6 @@ function fileMutationFromWrite(useEvent) {
         removedLines: 0,
         afterHash: shortHash(content),
     };
-    // A Write with no prior-content evidence: `overwrite` when the file may have
-    // existed. We cannot tell create vs overwrite from the event, so `overwrite`
-    // (the conservative "may have clobbered") — never invent `create`.
     return { path, operation: 'overwrite', hunks: [hunk] };
 }
 function countStringLines(text) {
@@ -349,7 +258,6 @@ function editExecution(step, useEvent, resultEvent, ctx) {
         tool: step.tool ?? 'Edit',
         result: resultOf(resultEvent, ctx.redact, ctx.knownSecrets),
         files,
-        // reverts[] is populated in a cross-step pass over all mutations (see below).
         reverts: [],
     };
 }
@@ -366,6 +274,7 @@ function writeExecution(step, useEvent, resultEvent, ctx) {
     };
 }
 function redactMutationPath(m, ctx) {
+    // Mutation paths cross the device boundary and must be scrubbed with other projected data.
     if (!ctx.redact)
         return m;
     return { ...m, path: redactSecrets(m.path, ctx.knownSecrets) };
@@ -431,7 +340,6 @@ function hookExecution(event, ordinal, startMs) {
         exec.hookEvent = hookEvent;
     return exec;
 }
-/** Shared base fields for any execution step, mapped from the drawn trajectory step. */
 function executionBase(step, kind) {
     const base = {
         kind,
@@ -459,25 +367,7 @@ function thinkingStep(step) {
         label: step.label,
     };
 }
-// ---------------------------------------------------------------------------
-// Cross-step revert ledger
-// ---------------------------------------------------------------------------
-/**
- * Detect when a later edit/write REVERTS an earlier one on the same path+hunk, by
- * content fingerprint: a hunk B reverts hunk A when they touch the same path and
- * B's afterHash equals A's beforeHash AND B's beforeHash equals A's afterHash — i.e.
- * B put the content back exactly the way A found it. Stamps `revertedByStep` on the
- * reverted hunk + mutation, and appends a RevertLink to the reverting step's
- * `reverts[]`.
- *
- * Conservative: only an EXACT hash round-trip counts. A partial/overlapping change
- * is left un-linked (empty reverts[]) rather than guessed — the spec's "do not fake
- * reverts" bar. This walks the already-built mutation steps in order; a mutation
- * with an empty hunk list (no diff strings were available) never participates.
- */
 function applyRevertLedger(steps) {
-    // Earlier hunks, most-recent-first per (path), so a revert matches the latest
-    // un-reverted change to that path.
     const earlier = [];
     for (const step of steps) {
         if (step.kind !== 'execution')
@@ -487,7 +377,6 @@ function applyRevertLedger(steps) {
         const mut = step;
         for (const file of mut.files) {
             for (const hunk of file.hunks) {
-                // Does this hunk revert any earlier un-reverted hunk on the same path?
                 if (hunk.beforeHash && hunk.afterHash) {
                     const match = earlier.find((e) => e.path === file.path &&
                         e.hunk.revertedByStep === undefined &&
@@ -497,7 +386,6 @@ function applyRevertLedger(steps) {
                         e.hunk.beforeHash === hunk.afterHash);
                     if (match) {
                         match.hunk.revertedByStep = mut.ordinal;
-                        // Stamp the mutation too when all its hunks are now reverted.
                         const parentFile = match.step.files.find((f) => f.path === match.path);
                         if (parentFile && parentFile.hunks.every((h) => h.revertedByStep !== undefined)) {
                             parentFile.revertedByStep = mut.ordinal;
@@ -514,9 +402,6 @@ function applyRevertLedger(steps) {
         }
     }
 }
-// ---------------------------------------------------------------------------
-// buildSessionDetailV2
-// ---------------------------------------------------------------------------
 const TOOL_KINDS = {
     bash: new Set(['bash', 'exec', 'execute', 'exec_command', 'run_command', 'run_shell_command', 'shell']),
     read: new Set(['read', 'view', 'cat_file']),
@@ -532,16 +417,8 @@ function toolExecutionKind(tool) {
     }
     return 'generic';
 }
-/**
- * Build the schema-2 per-session detail from a pre-built trajectory and its raw
- * events. The trajectory supplies meta/gaps/whereItWentWrong/surfacedToolFailures
- * (via the shared sync.ts helpers) and the truncation count; the raw events supply
- * the per-tool detail the schema-1 flat step could not carry.
- *
- * Re-pairs the events with `pairSteps` (the SAME loop buildTrajectory ran) to
- * recover each step's (use event, result event) triple, then dispatches per tool.
- */
 export function buildSessionDetailV2(traj, events, options = {}) {
+    // Projection defaults to secret redaction; previews are bounded while structured inputs remain.
     const redact = options.redact !== false;
     const knownSecrets = options.knownSecrets;
     const ctx = { redact, knownSecrets };
@@ -549,24 +426,11 @@ export function buildSessionDetailV2(traj, events, options = {}) {
     const firstTs = stats.firstTs;
     const eventMs = eventTimestampsMs(events);
     const drafts = pairSteps(events, eventMs, firstTs, redact, knownSecrets);
-    // Apply the SAME cap the trajectory used, so the two step lists line up and the
-    // truncation count is honest. `traj.steps` is already capped + ordinal-numbered.
     const cappedDrafts = drafts.slice(0, traj.steps.length);
     const steps = [];
     for (let i = 0; i < cappedDrafts.length; i++) {
         const draft = cappedDrafts[i];
-        // The trajectory step is the AUTHORITATIVE one: buildTrajectory resolved its
-        // outcome, duration, durationEstimated, and exitCode after pairing. The fresh
-        // draft from this re-pair only supplies the event indices (use/result); its
-        // own `step` still carries the pre-resolution placeholders. So read base fields
-        // from `traj.steps[i]` and use the draft solely for the event triple.
         const step = traj.steps[i];
-        // Guard the positional pairing. buildTrajectory and this builder both derive
-        // their drafts from the SAME events via the SAME deterministic `pairSteps`, so
-        // draft[i] must describe the same step as traj.steps[i]. If a future change
-        // makes the two call sites diverge (e.g. one filters events, the other does
-        // not), fail loud here rather than silently emit a shard whose danger flags,
-        // timestamps, and paths belong to the wrong step.
         if (draft.step.kind !== step.kind || draft.step.callId !== step.callId) {
             throw new Error(`schema-2 step/draft misalignment at ordinal ${step.ordinal}: ` +
                 `draft(kind=${draft.step.kind},callId=${draft.step.callId ?? '∅'}) vs ` +
@@ -601,10 +465,6 @@ export function buildSessionDetailV2(traj, events, options = {}) {
                 break;
         }
     }
-    // Draw hook firings (parse.ts `type:'hook'`) as first-class HookExecution steps.
-    // They are not tool_use events, so pairSteps never drew them; merge them into the
-    // step stream by startMs and re-number ordinals so the ordering stays truthful.
-    // A session with no hook events leaves `steps` and its ordinals untouched.
     const hookSteps = [];
     for (let i = 0; i < events.length; i++) {
         const e = events[i];
@@ -633,5 +493,4 @@ export function buildSessionDetailV2(traj, events, options = {}) {
             .map((step) => ({ tool: step.tool, label: step.label, detail: step.detail })),
     };
 }
-// re-export for callers/tests
 export { activeMsFromTrajectory };

package/dist/lib/traces/schema2-danger.d.ts

@@ -1,37 +1,7 @@
-/**
- * Danger classifier for a single shell action's argv (PHNX-3442, producer side).
- *
- * Safety-sensitive: the schema-2 `BashAction.danger` drives the console's
- * destructive-operation surfacing and risk scoring. So this is CONSERVATIVE by
- * construction — it defaults to `normal` and only escalates on CLEAR structural
- * evidence in the tokenized argv, never on a substring of raw command text. The
- * argv it reads is one tokenizeBash segment (see `tokenizeBash` in
- * `session/bash-command.ts`): the executable at argv[0] and its already-split
- * arguments, so a flag like `-rf` is a whole token, not a substring hunt.
- *
- * The three levels mirror the shipped consumer union (`BashDanger`):
- *   - DESTRUCTIVE            — irrecoverable data loss / history rewrite / force
- *                              overwrite of an important path. Requires a WHERE-less
- *                              DELETE, a recursive/force delete, a hard reset, etc.
- *   - potentially-destructive — plain `rm`, soft/mixed `git reset`, `mv` over a
- *                              path, plain `kill` — recoverable-ish but worth a flag.
- *   - normal                 — everything else.
- *
- * `destructiveOperation` is a short stable label (never raw text) naming WHY the
- * action was flagged, so the console can group by operation without re-parsing.
- */
 import type { BashDanger } from './schema2.js';
 interface DangerVerdict {
     danger: BashDanger;
-    /** Short stable label naming the operation, e.g. `recursive-delete`. Omitted for `normal`. */
     destructiveOperation?: string;
 }
-/**
- * Classify one tokenized shell action. `argvComplete` is false when a dynamic node
- * (command substitution / glob / var expansion) kept the argv incomplete; when a
- * DESTRUCTIVE signal depends on a token that could have been mangled by expansion
- * we DO still flag it (a `rm -rf $DIR` is destructive regardless of what `$DIR`
- * expands to), because the operation itself is the danger, not its target.
- */
 export declare function classifyActionDanger(argv: string[], _argvComplete?: boolean): DangerVerdict;
 export {};

package/dist/lib/traces/schema2-danger.js

@@ -1,78 +1,34 @@
-/**
- * Danger classifier for a single shell action's argv (PHNX-3442, producer side).
- *
- * Safety-sensitive: the schema-2 `BashAction.danger` drives the console's
- * destructive-operation surfacing and risk scoring. So this is CONSERVATIVE by
- * construction — it defaults to `normal` and only escalates on CLEAR structural
- * evidence in the tokenized argv, never on a substring of raw command text. The
- * argv it reads is one tokenizeBash segment (see `tokenizeBash` in
- * `session/bash-command.ts`): the executable at argv[0] and its already-split
- * arguments, so a flag like `-rf` is a whole token, not a substring hunt.
- *
- * The three levels mirror the shipped consumer union (`BashDanger`):
- *   - DESTRUCTIVE            — irrecoverable data loss / history rewrite / force
- *                              overwrite of an important path. Requires a WHERE-less
- *                              DELETE, a recursive/force delete, a hard reset, etc.
- *   - potentially-destructive — plain `rm`, soft/mixed `git reset`, `mv` over a
- *                              path, plain `kill` — recoverable-ish but worth a flag.
- *   - normal                 — everything else.
- *
- * `destructiveOperation` is a short stable label (never raw text) naming WHY the
- * action was flagged, so the console can group by operation without re-parsing.
- */
 const NORMAL = { danger: 'normal' };
-/** basename of an executable token so `/bin/rm` and `rm` classify alike. */
 function baseName(token) {
     const noArgs = token.replace(/^.*\//, '');
     return noArgs.toLowerCase();
 }
-/** True when any argv token is exactly one of `names`. */
 function hasToken(argv, names) {
     return argv.some((t) => names.has(t));
 }
-/** A single-dash cluster flag that CONTAINS every letter in `letters` (e.g. `-rf` ⊇ r,f). */
 function hasClusterFlag(argv, letters) {
     return argv.some((t) => {
         if (!/^-[a-zA-Z]+$/.test(t))
-            return false; // single-dash short cluster only
+            return false;
         const body = t.slice(1);
         return letters.every((l) => body.includes(l));
     });
 }
-/** A GNU long flag present as its own token (e.g. `--force`, `--hard`). */
 function hasLongFlag(argv, flag) {
     return argv.includes(flag);
 }
 const RM_TOKEN = new Set(['rm']);
 const KILL_TOKEN = new Set(['kill', 'pkill', 'killall']);
-/** Paths that are catastrophic to force-overwrite via a redirect target. */
 const IMPORTANT_REDIRECT_TARGET = /^\/dev\/(?:sd|nvme|disk|hd|mmcblk|vd)/i;
-/**
- * SQL-ish argv reconstruction: for a `psql -c "DROP TABLE x"` the SQL lives in a
- * single quoted token, so danger scanning of SQL joins the argv back into one
- * lower-cased string and matches structural SQL, not shell tokens. Bounded to the
- * argv we already hold — no new parse.
- */
 function joinedSql(argv) {
     return argv.join(' ').toLowerCase();
 }
-/**
- * Classify one tokenized shell action. `argvComplete` is false when a dynamic node
- * (command substitution / glob / var expansion) kept the argv incomplete; when a
- * DESTRUCTIVE signal depends on a token that could have been mangled by expansion
- * we DO still flag it (a `rm -rf $DIR` is destructive regardless of what `$DIR`
- * expands to), because the operation itself is the danger, not its target.
- */
 export function classifyActionDanger(argv, _argvComplete = true) {
     if (argv.length === 0)
         return NORMAL;
     const exe = baseName(argv[0]);
-    // Everything after the executable — the flags/args the danger tests read.
     const rest = argv.slice(1);
-    // ── rm ──────────────────────────────────────────────────────────────────
     if (exe === 'rm' || hasToken(argv, RM_TOKEN)) {
-        // Only treat a real `rm` invocation (argv[0]) — a stray `rm` argument to some
-        // other tool is not an rm call.
         if (exe === 'rm') {
             const recursive = hasClusterFlag(rest, ['r']) || hasLongFlag(rest, '--recursive');
             const force = hasClusterFlag(rest, ['f']) || hasLongFlag(rest, '--force');
@@ -82,31 +38,24 @@ export function classifyActionDanger(argv, _argvComplete = true) {
             if (recursive) {
                 return { danger: 'DESTRUCTIVE', destructiveOperation: 'recursive-delete' };
             }
-            // Plain `rm file` (or `rm -f file` without recursion) — recoverable-ish.
             return { danger: 'potentially-destructive', destructiveOperation: 'delete' };
         }
     }
-    // ── git ─────────────────────────────────────────────────────────────────
     if (exe === 'git') {
         const sub = rest.find((t) => !t.startsWith('-'));
         if (sub === 'reset') {
             if (hasLongFlag(rest, '--hard')) {
                 return { danger: 'DESTRUCTIVE', destructiveOperation: 'git-reset-hard' };
             }
-            // soft / mixed reset — moves HEAD but keeps the working tree.
             return { danger: 'potentially-destructive', destructiveOperation: 'git-reset' };
         }
         if (sub === 'clean') {
-            // `git clean -fd` / `-fdx` — deletes untracked files irrecoverably.
             if (hasClusterFlag(rest, ['f'])) {
                 return { danger: 'DESTRUCTIVE', destructiveOperation: 'git-clean-force' };
             }
             return { danger: 'potentially-destructive', destructiveOperation: 'git-clean' };
         }
         if (sub === 'push') {
-            // A leading-`+` refspec (`git push origin +main`, `+refs/heads/main:main`,
-            // `+HEAD:main`) forces the push just like `--force`, with no flag to catch.
-            // Match a `+` followed by a ref char — not a lone `+` or a `+-`-style flag.
             const forceRefspec = rest.some((t) => /^\+[^-\s]/.test(t));
             if (hasLongFlag(rest, '--force') ||
                 hasClusterFlag(rest, ['f']) ||
@@ -116,7 +65,6 @@ export function classifyActionDanger(argv, _argvComplete = true) {
             }
         }
         if (sub === 'checkout') {
-            // `git checkout -- .` / `git checkout -- <path>` throws away working changes.
             if (rest.includes('--')) {
                 return { danger: 'DESTRUCTIVE', destructiveOperation: 'git-checkout-discard' };
             }
@@ -129,7 +77,6 @@ export function classifyActionDanger(argv, _argvComplete = true) {
         }
         return NORMAL;
     }
-    // ── kill ────────────────────────────────────────────────────────────────
     if (exe === 'kill' || exe === 'pkill' || exe === 'killall') {
         if (hasToken(rest, new Set(['-9', '-SIGKILL', '-KILL']))) {
             return { danger: 'DESTRUCTIVE', destructiveOperation: 'kill-9' };
@@ -138,12 +85,9 @@ export function classifyActionDanger(argv, _argvComplete = true) {
             return { danger: 'potentially-destructive', destructiveOperation: 'kill' };
         }
     }
-    // ── mv (over an existing path — we cannot know if the target exists, so this is
-    // the recoverable-ish tier, never DESTRUCTIVE) ────────────────────────────
     if (exe === 'mv') {
         return { danger: 'potentially-destructive', destructiveOperation: 'move-overwrite' };
     }
-    // ── dd / mkfs (disk writers) ──────────────────────────────────────────────
     if (exe === 'dd') {
         if (rest.some((t) => /^of=/.test(t))) {
             return { danger: 'DESTRUCTIVE', destructiveOperation: 'dd-write' };
@@ -152,9 +96,6 @@ export function classifyActionDanger(argv, _argvComplete = true) {
     if (/^mkfs(\.|$)/.test(exe)) {
         return { danger: 'DESTRUCTIVE', destructiveOperation: 'mkfs' };
     }
-    // ── redirect to a raw device / important path ─────────────────────────────
-    // A `> /dev/sda`-style redirect target appears as a token in the argv (the
-    // tokenizer keeps `>` and its target). Flag only clearly catastrophic targets.
     for (let i = 0; i < argv.length; i++) {
         const t = argv[i];
         if (t === '>' || t === '>>') {
@@ -163,13 +104,11 @@ export function classifyActionDanger(argv, _argvComplete = true) {
                 return { danger: 'DESTRUCTIVE', destructiveOperation: 'overwrite-device' };
             }
         }
-        // Fused form `>/dev/sda`.
         const fused = t.match(/^>>?(\/\S+)$/);
         if (fused && IMPORTANT_REDIRECT_TARGET.test(fused[1])) {
             return { danger: 'DESTRUCTIVE', destructiveOperation: 'overwrite-device' };
         }
     }
-    // ── SQL (psql/mysql/sqlite3 -c "…", or a bare SQL statement) ───────────────
     const sql = joinedSql(argv);
     if (/\bdrop\s+table\b/.test(sql)) {
         return { danger: 'DESTRUCTIVE', destructiveOperation: 'sql-drop-table' };
@@ -177,7 +116,6 @@ export function classifyActionDanger(argv, _argvComplete = true) {
     if (/\btruncate\b/.test(sql)) {
         return { danger: 'DESTRUCTIVE', destructiveOperation: 'sql-truncate' };
     }
-    // DELETE FROM without a WHERE clause. A DELETE with WHERE is scoped → normal.
     if (/\bdelete\s+from\b/.test(sql) && !/\bwhere\b/.test(sql)) {
         return { danger: 'DESTRUCTIVE', destructiveOperation: 'sql-delete-no-where' };
     }

package/dist/lib/traces/schema2.d.ts

@@ -3,11 +3,6 @@ interface SessionStepBase {
     ordinal: number;
     startMs: number;
     durationMs: number;
-    /**
-     * Whether `durationMs` was measured from a paired result (`false`) or inferred
-     * from the next event (`true`). Mandatory — the console must visually
-     * distinguish measured from inferred duration.
-     */
     durationEstimated: boolean;
     outcome: StepOutcome;
     label: string;
@@ -21,7 +16,6 @@ interface ExecutionBase extends SessionStepBase {
     kind: 'execution';
     lane: string;
     callId?: string;
-    /** The tool call this execution targets (hook/permission → the guarded call). */
     targetCallId?: string;
 }
 type ToolExecutionType = 'bash' | 'edit' | 'write' | 'read' | 'grep' | 'generic';
@@ -49,7 +43,6 @@ export interface BashAction {
     ordinal: number;
     source: string;
     argv: string[];
-    /** false when a dynamic node (substitution/expansion) kept argv incomplete. */
     argvComplete: boolean;
     program?: string;
     categories: BashCategory[];
@@ -58,9 +51,7 @@ export interface BashAction {
 }
 export interface BashExecution extends ToolExecutionBase {
     executionType: 'bash';
-    /** Redacted outer command. */
     command: string;
-    /** Redacted shell payload after unwrapping `/bin/zsh -lc "…"`. */
     unwrappedCommand: string;
     parseStatus: 'parsed' | 'partial' | 'unparseable';
     parseDiagnostics: string[];
@@ -126,7 +117,6 @@ export interface GenericToolExecution extends ToolExecutionBase {
     executionType: 'generic';
     input?: TextPreview;
 }
-/** A permission request/decision — a first-class sibling, NOT a fake tool. */
 export interface PermissionExecution extends ExecutionBase {
     executionType: 'permission';
     lane: 'permission';
@@ -136,7 +126,6 @@ export interface PermissionExecution extends ExecutionBase {
     scope?: string;
     reason?: TextPreview;
 }
-/** A hook firing — a first-class sibling, NOT a fake tool. */
 export interface HookExecution extends ExecutionBase {
     executionType: 'hook';
     lane: 'hook';

package/dist/lib/traces/segments.d.ts

@@ -1,28 +1,13 @@
-/**
- * Group-by dimensions + time-to-first-tool latency for the traces insight
- * engine (the console's Issue bar).
- *
- * Pure functions, no I/O. Classifiers are DATA-DRIVEN TABLES — a new task type
- * or timing bucket is a row, not a new if/else-by-name arm. The integrator
- * (`insights.ts` / `sync.ts`) tags each session; this file does not write the
- * shard.
- *
- * Input is the redacted `SessionDetail` from `agents traces sync` plus the
- * SyncRow fields the detail strips (prompt, gitBranch, files). Structural —
- * `SessionDetail` is a valid `SegmentSession`.
- */
 export declare const TASK_TYPES: readonly ["bugfix", "feature", "refactor", "test", "chore", "other"];
 export type TaskType = (typeof TASK_TYPES)[number];
 declare const FAILURE_TIMINGS: readonly ["early", "mid", "late"];
 type FailureTiming = (typeof FAILURE_TIMINGS)[number];
-/** The #1 group-by axis: compare the pair, never the model alone. */
 interface SegmentAgent {
     model: string;
     harness: string;
 }
 export interface SegmentFile {
     path: string;
-    /** Write/create vs Edit/patch. */
     action: 'new' | 'edit';
 }
 export interface SegmentStep {
@@ -33,11 +18,6 @@ export interface SegmentStep {
     kind?: 'tool' | 'thinking' | string;
     label?: string;
 }
-/**
- * Session shape the classifiers read. `SessionDetail` (sessions/<id>.json)
- * satisfies this; callers may also pass SyncRow fields (`prompt`, `gitBranch`,
- * `agent`, `model`, `files`) alongside steps.
- */
 export interface SegmentSession {
     id?: string;
     prompt?: string | null;
@@ -66,7 +46,6 @@ export interface Percentiles {
     p99: number;
     max: number;
 }
-/** Time-to-first-tool latency — `steps[0].startMs` over tool-using sessions. */
 export interface LatencyInsight {
     firstToolMs: Percentiles;
 }
@@ -81,37 +60,14 @@ type DiffShape = {
     newOnly: boolean;
     choreOnly: boolean;
 };
-/**
- * Task-type rules, first match wins. Prompt/branch keywords outrank diff shape
- * except where `shape` is set (test-only files, chore-only files, all-new files).
- *
- * Order is the product priority: test-only work is not a "feature"; a `fix/`
- * branch is a bugfix even if files are new; chore lockfile edits are not features.
- */
 export declare const TASK_TYPE_RULES: ReadonlyArray<{
     type: Exclude<TaskType, 'other'>;
     patterns: readonly RegExp[];
     shape?: keyof Pick<DiffShape, 'testOnly' | 'newOnly' | 'choreOnly'>;
 }>;
-/** Model × harness unit — the #1 group-by axis. */
 export declare function deriveAgent(session: SegmentSession): SegmentAgent;
-/**
- * Classify the session's work from the opening prompt + diff shape (files
- * touched, new vs edit, test-only). First matching table row wins.
- */
 export declare function classifyTaskType(session: SegmentSession): TaskType;
-/**
- * Bucket the FIRST failing step by its normalized position in the session
- * span (`firstFailure.startMs / spanMs`). Sessions with no failing step
- * return null — they do not belong on the failure-timing axis.
- */
 export declare function failureTiming(session: SegmentSession): FailureTiming | null;
-/**
- * Time-to-first-tool latency from `steps[0].startMs` across sessions that
- * recorded at least one step. Nearest-rank percentiles (same formula as the
- * traces index stats) so p99 on `/tmp/traces-real` lands at ~128s.
- */
 export declare function computeLatency(sessions: readonly SegmentSession[]): LatencyInsight;
-/** All three group-by dimensions for one session. */
 export declare function deriveDimensions(session: SegmentSession): SegmentDimensions;
 export {};