@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/traces/sync.js

@@ -1,31 +1,10 @@
-/**
- * Incremental sync of derived, redacted SessionTrajectory blobs to the
- * agents-traces R2 store.
- *
- * Security invariant: only the derived signal (steps + gaps + stats +
- * errorCount + programTimeShare) is uploaded — no raw transcript text.
- * redactSecrets() is called inside buildTrajectory() before we PUT.
- *
- * Sync gate: `sessions.db` `file_mtime_ms` is the source of truth.  A ledger
- * at `getRuntimeStateDir()/traces-sync.json` records the last sync timestamp
- * per device so re-runs skip unchanged sessions.
- *
- * Retry ledger: the mtime watermark alone cannot retry failures — a later-mtime
- * success advances it past an earlier failed row, which the next run's
- * `file_mtime_ms > watermark` filter then skips forever. So the same ledger also
- * records the identity + typed evidence of each failed session (`failures`), and
- * the row query unions those retry-worthy ids back in regardless of the watermark
- * (PHNX-3267). Failures are typed so a gone transcript (`transcript-unavailable`,
- * expected history, aged out after a TTL and never re-read) is distinguished from a
- * real parse/upload failure (retried until it resolves).
- */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { getDB, readSessionInsights, readSessionPhenotypes, readSessionTopics, writeSessionInsights, writeSessionPhenotypes, writeSessionTopics, } from '../session/db.js';
-import { parseSession } from '../session/parse.js';
-import { buildTrajectory } from '../session/trajectory.js';
-import { computeInsightFacets } from '../session/insights.js';
+import { parseSession } from '@phnx-labs/sessions-cli/reader';
+import { buildTrajectory } from '@phnx-labs/sessions-cli/reader';
+import { computeInsightFacets } from '@phnx-labs/sessions-cli/reader';
 import { knownSecretValuesFromEnv, redactSecrets } from '../redact.js';
 import { getRuntimeStateDir } from '../state.js';
 import { resolveTracesBackend } from './backend.js';
@@ -33,44 +12,24 @@ import { classifyCause, classifyTopic, computeDriftSignal, } from './classify.js
 import { computeBehavioralPatterns, computeInsights } from './insights.js';
 import { classifyPhenotype, recoveredAfterErrors } from './phenotype.js';
 import { buildSessionDetailV2 } from './schema2-build.js';
-/**
- * The per-session shard body: the schema-2 rich `ToolExecution` detail. The
- * console decoder (prix/web) reads BOTH schema 1 and schema 2 and is the only
- * shard consumer, so emitting schema 2 is backward-compatible by construction —
- * no rollout flag is needed and none should exist (a producer that runs across
- * the fleet must not depend on an operator setting an env var). Both the upload
- * and dry-run paths call this one builder.
- */
 export function buildSessionShard(traj, events, knownSecrets) {
     return buildSessionDetailV2(traj, events, { redact: true, knownSecrets });
 }
-/** Push derived, redacted trajectories for this device to the traces store. */
 export async function syncTraces(opts = {}) {
     const dryRun = opts.dryRun === true;
     const outDir = opts.outDir;
     if (dryRun && !outDir) {
         throw new Error('traces sync --dry-run requires --out <dir>');
     }
-    // A dry-run computes locally and writes to disk: no Phoenix backend needed.
     const backend = dryRun ? null : resolveTracesBackend();
     const owner = backend?.userId ?? 'local';
     const ledger = readSyncLedger();
     const db = getDB();
     const device = localDevice();
-    // Scope to this machine only — the DB can contain peer rows mirrored from the
-    // fleet; uploading those under this device's prefix would corrupt the index.
-    // NULL machine rows are legacy local sessions (pre-machine-field). A dry-run
-    // ignores the incremental watermark so the export covers every session.
     const sinceMtime = dryRun ? 0 : (ledger.lastSyncMtime ?? 0);
     const watermarkRows = db
         .prepare('SELECT * FROM sessions WHERE (machine = ? OR machine IS NULL) AND file_mtime_ms > ? ORDER BY file_mtime_ms ASC')
         .all(device, sinceMtime);
-    // The watermark alone loses failures: a later-mtime success advances it past an
-    // earlier failed row, which the `file_mtime_ms > sinceMtime` filter then skips
-    // forever. So union in the sessions we explicitly recorded as retry-worthy
-    // failures (parse/upload — a `transcript-unavailable` file is gone, re-reading it
-    // wastes work) regardless of where the watermark sits. A dry-run ignores the
-    // ledger entirely and already selects every row.
     const retryIds = dryRun
         ? []
         : (ledger.failures ?? [])
@@ -96,12 +55,7 @@ export async function syncTraces(opts = {}) {
     let transcriptUnavailable = 0;
     let parseFailed = 0;
     let uploadFailed = 0;
-    // Advance the watermark only to the max mtime of successfully uploaded sessions.
-    // On its own this does NOT retry failures (a later success strands earlier ones);
-    // the failure ledger below is what actually re-selects them next run.
     let maxSuccessMtime = ledger.lastSyncMtime ?? 0;
-    // Carry prior failures forward by id so a stranded row's identity + evidence
-    // survives across syncs. A success removes the id; a repeat failure updates it.
     const now = Date.now();
     const failures = new Map((ledger.failures ?? []).map((f) => [f.id, f]));
     const recordFailure = (row, kind, err) => {
@@ -133,8 +87,6 @@ export async function syncTraces(opts = {}) {
             traj = buildTrajectory(events, session, { redact: true, knownSecrets });
         }
         catch (err) {
-            // A gone/unreadable transcript is expected history, not a retry-worthy error;
-            // a file that IS present but failed to parse is a real problem to retry.
             if (!fs.existsSync(row.file_path)) {
                 transcriptUnavailable++;
                 recordFailure(row, 'transcript-unavailable', err);
@@ -154,7 +106,7 @@ export async function syncTraces(opts = {}) {
             }
             uploaded++;
             maxSuccessMtime = Math.max(maxSuccessMtime, row.file_mtime_ms ?? 0);
-            failures.delete(row.id); // recovered — drop it from the retry set
+            failures.delete(row.id);
         }
         catch (err) {
             uploadFailed++;
@@ -167,14 +119,13 @@ export async function syncTraces(opts = {}) {
             const allRows = db
                 .prepare('SELECT * FROM sessions WHERE machine = ? OR machine IS NULL')
                 .all(device);
-            // Seed rolling bucket history from the previous shard so drift signals accumulate.
             let prevShard = null;
             if (dryRun && outDir) {
                 const prevPath = path.join(outDir, 'index.json');
                 try {
                     prevShard = JSON.parse(fs.readFileSync(prevPath, 'utf8'));
                 }
-                catch { /* first run — no prior shard */ }
+                catch { }
             }
             else if (backend) {
                 prevShard = await getIndexShard(backend, device);
@@ -188,26 +139,13 @@ export async function syncTraces(opts = {}) {
             }
         }
         catch (err) {
-            // Not fatal to the per-session upload (that loop already ran), but it DOES
-            // mean the console shard is now stale. Record it so the caller can surface a
-            // warning instead of reporting a clean, green sync — a silent swallow here is
-            // exactly what let a 59h-stale, insight-less index hide in plain sight
-            // (PHNX-3401). Do NOT re-throw: the session data is durable and worth keeping.
             indexError = err instanceof Error ? err.message : String(err);
         }
     }
-    // A dry-run never advances the incremental watermark: it is a read-only export.
     if (!dryRun) {
-        // Age out long-unavailable transcripts so a corpus of deleted files cannot grow
-        // the retry set without bound; parse/upload failures persist until they resolve.
         const persistedFailures = [...failures.values()].filter((f) => !(f.kind === 'transcript-unavailable' &&
             now - f.firstSeen > TRANSCRIPT_UNAVAILABLE_TTL_MS));
         writeSyncLedger({ lastSyncMtime: maxSuccessMtime, failures: persistedFailures });
-        // Register the Phoenix session with Prix so the console can fetch live data
-        // (PHNX-3257). Fire-and-forget — a link failure must not block sync.
-        // Managed backend only: the BYO path's token is a static write token that
-        // bypasses Phoenix auth (resolveTracesBackend's userId: 'byo' sentinel) —
-        // it is not a Phoenix identity credential and must never be sent to Prix.
         if (backend && backend.userId !== 'byo') {
             fetch('https://api.prix.dev/api/v1/traces/link', {
                 method: 'POST',
@@ -226,30 +164,13 @@ export async function syncTraces(opts = {}) {
         indexError,
     };
 }
-/**
- * Topic/label substrings that identify an internal-prompt session regardless of its
- * message/tool shape. These are the harness-spawned utility prompts the Rush app
- * fires (they run under the `claude` harness): title generation writes the 3–4 word
- * session title, the watchdog polls for stalled agents, the commit-message writer
- * drafts a conventional commit, and factory workers are dispatched sub-agents. The
- * title-generation prompt lives in the `topic` column, the rest can land in either
- * `topic` or `label`, so both are matched.
- */
 const UTILITY_PROMPT_SIGNATURES = [
-    /generate a 3-4 word title/i, // title generation
-    /generate a concise session headline/i, // session-title daemon service (PHNX-3797)
-    /you are a watchdog|watchdog monitoring/i, // watchdog tick
-    /conventional[- ]commit/i, // commit-message writer
-    /factory worker/i, // dispatched factory worker
+    /generate a 3-4 word title/i,
+    /generate a concise session headline/i,
+    /you are a watchdog|watchdog monitoring/i,
+    /conventional[- ]commit/i,
+    /factory worker/i,
 ];
-/**
- * Classify a session as internal `utility` plumbing vs real `agent` work (PHNX-3474).
- * `toolCallCount` is the AUTHORITATIVE per-session tool-call count from the loaded
- * `tool_calls` rows (the row's own `tool_call_count` column is a fallback for a row
- * whose calls weren't loaded). A session is `utility` when a known internal-prompt
- * signature matches its topic/label, OR it made no tool call AND has ≤2 messages —
- * the single-shot machine-call shape. Otherwise it is `agent`.
- */
 export function classifySessionKind(row, toolCallCount) {
     const haystack = `${row.topic ?? ''}\n${row.label ?? ''}`;
     if (UTILITY_PROMPT_SIGNATURES.some((re) => re.test(haystack)))
@@ -266,51 +187,20 @@ function percentile(values, ratio) {
     const sorted = [...values].sort((a, b) => a - b);
     return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
 }
-/**
- * A delta between consecutive events longer than this reads as an idle stall, not
- * work — the same threshold the trajectory uses for its gap detection
- * (`DEFAULT_IDLE_THRESHOLD_MS`, trajectory.ts). Kept in lockstep so active time
- * here and the gaps drawn in a session's detail view agree on what "idle" means.
- */
 const IDLE_GAP_THRESHOLD_MS = 120_000;
-/** Max example session refs carried per topic tile so a tile is drillable (PHNX-3408). */
 const TOPIC_SESSION_CAP = 30;
-/**
- * Active time for a session in the index shard: its recorded span minus every idle
- * gap > 120s (PHNX-3457). The index build already holds the ordered `tool_calls`
- * rows for the whole corpus, so idle is derived from them here — no transcript
- * re-parse. A cursor sweeps the span from `sessionStartMs`: each stretch where the
- * cursor sits idle for more than the threshold before the next call starts is
- * subtracted, and idle is measured from a call's END (its own `end_timestamp` when
- * known, else its start) so a call's own blocking duration is never mistaken for
- * idle. Crucially the sweep also books the gaps at the two BOUNDARIES — before the
- * first call and after the last call to the session end — so a session with a lone
- * tool call that was then abandoned and resumed hours later (the case a
- * between-calls-only measure missed entirely, leaving the whole 345h span counted
- * as active) has that trailing idle stripped. A session end is `sessionStartMs +
- * spanMs`, so the two agree by construction.
- *
- * Bounded to `[0, spanMs]`. A session with NO tool calls returns the full span
- * unchanged rather than a fabricated zero: there is no tool-call evidence of idle
- * either way, and treating a chat-only turn as 100% idle would be a worse error
- * than leaving its span uncorrected. Where the full event stream IS available (a
- * per-session `SessionDetail`), {@link activeMsFromTrajectory} is used instead —
- * it sees message events this call-only approximation cannot, so the two are close
- * but not identical by design (the corpus-scale index build cannot afford the
- * per-session parse the detail view does).
- */
 export function sessionActiveMs(spanMs, sessionCalls, sessionStartMs) {
     if (spanMs <= 0)
         return Math.max(0, spanMs);
     if (!Number.isFinite(sessionStartMs))
-        return spanMs; // can't place calls on the span
+        return spanMs;
     const spanEndMs = sessionStartMs + spanMs;
     const ordered = sessionCalls
         .map((c) => ({ startMs: Date.parse(c.timestamp), endMs: Date.parse(c.end_timestamp ?? c.timestamp) }))
         .filter((c) => Number.isFinite(c.startMs))
         .sort((a, b) => a.startMs - b.startMs);
     if (ordered.length === 0)
-        return spanMs; // no tool-call evidence of idle
+        return spanMs;
     let idleMs = 0;
     let cursor = sessionStartMs;
     for (const call of ordered) {
@@ -320,17 +210,14 @@ export function sessionActiveMs(spanMs, sessionCalls, sessionStartMs) {
         if (endMs > cursor)
             cursor = endMs;
     }
-    // Trailing idle: the stretch from the last call's end to the session's end.
     if (spanEndMs > cursor + IDLE_GAP_THRESHOLD_MS)
         idleMs += spanEndMs - cursor;
     return Math.max(0, spanMs - Math.min(idleMs, spanMs));
 }
-/** Active time from an already-built trajectory: span minus its idle gaps (all > threshold). */
 export function activeMsFromTrajectory(traj) {
     const idleMs = traj.gaps.reduce((sum, gap) => sum + gap.durationMs, 0);
     return Math.max(0, traj.spanMs - Math.min(idleMs, traj.spanMs));
 }
-/** Human description of a failed call, keyed by (tool, desc, cause) for grouping. Exported for computeInsights(). */
 export function failureDescription(call, cause) {
     if (cause === 'guard')
         return /main-branch-guard/i.test(`${call.error_code ?? ''} ${call.error ?? ''}`)
@@ -366,23 +253,6 @@ function attentionFlags(errorCount, facets) {
         flags.push(`${correctionCount} correction${correctionCount === 1 ? '' : 's'}`);
     return flags;
 }
-/**
- * Persist a derived-cache warm-up (topics / insights) without letting a
- * contended DB take down the whole index build.
- *
- * These write-backs only speed up the NEXT sync — the shard about to be built
- * reads from the in-memory `topics` / `insights` maps that were already
- * populated above, never from what this write persists. So the write is
- * genuinely optional to the shard's correctness.
- *
- * Yet it was the single point that broke the console: on an active machine the
- * Rush app holds `sessions.db`, this `BEGIN IMMEDIATE` waits out the 30s
- * `busy_timeout` and throws `SQLITE_BUSY`, the throw escaped `buildIndexShard`,
- * and `syncTraces` swallowed it — so the index (with wasted-time / failure
- * clusters / latency) never re-uploaded and the dashboard sat 59h stale
- * (PHNX-3401). Isolating the failure here keeps the index building; the warning
- * makes the degraded cache visible instead of silent.
- */
 function persistDerivedCache(label, write) {
     try {
         write();
@@ -392,7 +262,6 @@ function persistDerivedCache(label, write) {
         console.warn(`traces: ${label} cache warm-up skipped (${msg}) — index still built`);
     }
 }
-/** Build the redacted rich console shard from indexed metadata and derived caches. */
 export function buildIndexShard(rows, device, owner, prevShard) {
     const db = getDB();
     const knownSecrets = knownSecretValuesFromEnv();
@@ -422,18 +291,10 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         else
             callsBySession.set(call.session_id, [call]);
     }
-    // Classify every row as real `agent` work or internal `utility` plumbing, then run
-    // the ENTIRE rest of the shard build over the agent set ONLY (PHNX-3474). Utility
-    // rows — title-gen / watchdog / commit-message / factory-worker calls, ~68% of the
-    // corpus — are tagged and excluded here, never deleted from sessions.db, so the
-    // console counts and scores real agent work: `sessionsImported`, the medians,
-    // needs-attention, tool-error-rate, and the topic buckets all measure `agentRows`.
     const kindOf = new Map(rows.map((row) => [row.id, classifySessionKind(row, callsBySession.get(row.id)?.length ?? 0)]));
     const agentRows = rows.filter((row) => kindOf.get(row.id) === 'agent');
     const agentIds = agentRows.map((row) => row.id);
     const utilityCount = rows.length - agentRows.length;
-    // Tool calls belonging to utility rows never contribute to the failure/latency
-    // stats or the tool-error rate — filter them out at the source alongside the rows.
     const agentCalls = calls.filter((call) => kindOf.get(call.session_id) === 'agent');
     const topics = readSessionTopics(agentIds);
     const missingTopics = agentRows.filter((row) => !topics.has(row.id)).map((row) => {
@@ -448,15 +309,6 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         return { id: row.id, fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, topic };
     });
     persistDerivedCache('session-topics', () => writeSessionTopics(missingTopics));
-    // Insights (frictionSignals) and phenotype (false-termination / …) both need
-    // the parsed transcript, which flat tool_calls rows don't carry — so both are
-    // lazily derived per-session and cached by transcript mtime+size, then read for
-    // the WHOLE corpus (`rows` = allRows) every sync. That full-corpus read is what
-    // keeps the phenotype grouping dimension consistent: a session synced weeks ago
-    // still contributes its real phenotype from cache, so it can never fragment away
-    // from an identically-signatured session synced this run purely by *when* each
-    // was first seen (PHNX-3327). A cache-miss row is parsed at most once here even
-    // when both derivations are missing.
     const insights = readSessionInsights(agentIds);
     const phenotypes = readSessionPhenotypes(agentIds);
     const missingInsights = [];
@@ -471,7 +323,7 @@ export function buildIndexShard(rows, device, owner, prevShard) {
             events = parseSession(row.file_path, row.agent);
         }
         catch {
-            continue; // gone/unreadable transcript — leave both uncached, same as before
+            continue;
         }
         if (needInsights) {
             try {
@@ -479,7 +331,7 @@ export function buildIndexShard(rows, device, owner, prevShard) {
                 insights.set(row.id, facets);
                 missingInsights.push({ id: row.id, fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, facets });
             }
-            catch { /* leave this session's facets uncached; recompute next sync */ }
+            catch { }
         }
         if (needPhenotype) {
             try {
@@ -488,7 +340,7 @@ export function buildIndexShard(rows, device, owner, prevShard) {
                 phenotypes.set(row.id, phenotype);
                 missingPhenotypes.push({ id: row.id, fileMtimeMs: row.file_mtime_ms, fileSize: row.file_size, phenotype });
             }
-            catch { /* leave this session's phenotype uncached; recompute next sync */ }
+            catch { }
         }
     }
     persistDerivedCache('session-insights', () => writeSessionInsights(missingInsights));
@@ -530,8 +382,6 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         topicCounts.set(topic.key, bucket);
     }
     const failedCalls = agentCalls.filter((call) => call.outcome === 'error');
-    // `behavioral` is not a failed-tool-call cause (classifyCause never returns it),
-    // so it stays 0 in this tool-error split; it surfaces as its own failurePatterns.
     const byCause = { real: 0, guard: 0, hook: 0, behavioral: 0 };
     const failureCounts = new Map();
     for (const call of failedCalls) {
@@ -543,19 +393,9 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         current.count++;
         failureCounts.set(key, current);
     }
-    // Duration stats run over ACTIVE time, not raw span (PHNX-3457): span minus idle
-    // gaps > 120s, derived per session from the tool_calls already loaded above. A
-    // session resumed after hours, or left idle mid-turn, otherwise inflates the
-    // median/p90 with wall-clock the agent did no work in (real corpus max span:
-    // 345h). The raw span stays available per session on `SessionDetail.meta.spanMs`.
     const activeDurations = agentRows.flatMap((row) => row.duration_ms == null
         ? []
         : [sessionActiveMs(row.duration_ms, callsBySession.get(row.id) ?? [], Date.parse(row.timestamp))]);
-    // Segment the same active-time figure into AGENT vs INTERACTIVE runs (PHNX-3472).
-    // A session is an AGENT run when it made any tool call OR has more than 8
-    // messages; otherwise INTERACTIVE (a one-shot query). Only sessions with a
-    // non-null duration contribute to the medians; `measuredFraction` reports how
-    // much of the corpus that covers.
     const agentActive = [];
     const interactiveActive = [];
     let measured = 0;
@@ -568,7 +408,6 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         (isAgent ? agentActive : interactiveActive).push(active);
     }
     const measuredFraction = agentRows.length === 0 ? 0 : measured / agentRows.length;
-    // Build today's per-bucket stats for the rolling drift window.
     const todayDate = new Date().toISOString().slice(0, 10);
     const todayStats = [...topicCounts.values()].map(({ key }) => {
         const sessionsInBucket = [...topics.entries()]
@@ -588,16 +427,8 @@ export function buildIndexShard(rows, device, owner, prevShard) {
     const prevHistory = prevShard?.bucketHistory ?? [];
     const bucketHistory = [...prevHistory, todayStats].slice(-14);
     const driftSignals = computeDriftSignal(prevHistory, todayStats);
-    // Silent-stall friction (per-session, no failed tool call) becomes cross-session
-    // behavioral FailurePatterns, ranked into the same top-K by wasted idle time.
     const behavioralPatterns = computeBehavioralPatterns(insights, prevShard);
     const patternInsights = computeInsights(agentRows, agentCalls, prevShard, phenotypes, behavioralPatterns);
-    // Per-session roster (PHNX-3483): one flat scalar row per agent session, the raw
-    // material the Rush console filters and re-aggregates client-side. `durationMs`
-    // reuses `sessionActiveMs` (the value behind `stats.medianMs`; 0 for a null-duration
-    // row, which the segmented stats above skip entirely), and `mode` reuses the
-    // AGENT-vs-INTERACTIVE predicate from the segmentation above so a mode-split median
-    // over the MEASURED rows reproduces `stats.agentMedianMs` / `interactiveMedianMs`.
     const needsAttentionIds = new Set(needsAttention.map((s) => s.id));
     const sessions = agentRows.map((row) => {
         const isAgent = (callsBySession.get(row.id)?.length ?? 0) > 0 || (row.message_count ?? 0) > 8;
@@ -647,12 +478,6 @@ export function buildIndexShard(rows, device, owner, prevShard) {
             label: bucket.label,
             count: bucket.count,
             group: bucket.group,
-            // Up to TOPIC_SESSION_CAP most-recent example sessions, so the console can
-            // drill from a tile into its session list. Capped to keep the shard small;
-            // the tile's `count` remains the true total. These are correct on this
-            // per-device shard; the fleet-aggregate `/all` view (worker-template.ts,
-            // a must-not-touch R2 worker here) carries only the first device's refs
-            // per topic until PHNX-3464 merges them across devices.
             sessions: bucket.refs
                 .sort((a, b) => b.recencyMs - a.recencyMs)
                 .slice(0, TOPIC_SESSION_CAP)
@@ -670,7 +495,6 @@ export function buildIndexShard(rows, device, owner, prevShard) {
         sessions,
     };
 }
-/** Plain-language summary of the friction in a run, or null when it ran clean. */
 export function buildWhereItWentWrong(traj) {
     const errorSteps = traj.steps.filter((s) => s.outcome === 'error');
     const biggestGap = traj.gaps.reduce((max, g) => (!max || g.durationMs > max.durationMs ? g : max), null);
@@ -687,41 +511,11 @@ export function buildWhereItWentWrong(traj) {
         return null;
     return `This run hit ${parts.join('; ')}.`;
 }
-/**
- * Truthful run-level outcome (PHNX-3387).
- *
- * A run with zero tool errors `completed`. A run that hit tool errors is
- * `completed` ONLY when it *causally recovered* — a substantive, non-human-facing
- * tool step succeeded strictly after the last error AND resolved the failed work
- * (its work signature matches an errored step's), the exact predicate the
- * false-termination phenotype uses ({@link recoveredAfterErrors}). A run whose
- * last substantive step is the error, whose only post-error steps are human-facing
- * (a punt to `AskUserQuestion` — the case the broken "last tool call ok" heuristic
- * mislabeled `completed`), or whose only post-error success is unrelated work (a
- * failed `bun test` followed by an incidental `ls`) stays `errored`.
- *
- * This is what makes `surfacedToolFailures` on a `completed` run honest: those
- * are failures the run recovered from, not a green status hiding an unresolved
- * failure. It never flips a run that ended unresolved to `completed` (no
- * regression vs the old `errorCount > 0 ? errored : completed`), and it does not
- * flip a run whose failed work was never resolved just because some later,
- * unrelated call happened to succeed.
- */
 export function deriveRunOutcome(traj) {
     if (traj.errorCount === 0)
         return 'completed';
     return recoveredAfterErrors({ steps: traj.steps }) ? 'completed' : 'errored';
 }
-/**
- * Map the derived trajectory to the console's SessionDetail shape, stripping
- * local-machine PII (full cwd, account) that would expose filesystem paths if
- * written to R2. `repo` is the cwd basename only.
- */
-/**
- * The `meta` block shared by the schema-1 {@link SessionDetail} and the schema-2
- * `SessionDetailV2`. Strips local-machine PII (full cwd, account): `repo` is the
- * cwd basename only. Factored so both producers stamp identical meta.
- */
 export function buildDetailMeta(traj) {
     const s = traj.session;
     const stats = traj.stats;
@@ -798,12 +592,6 @@ async function putIndexShard(backend, device, owner, shard) {
         throw new Error(`PUT ${url} → ${res.status}`);
     }
 }
-/**
- * A `transcript-unavailable` failure is kept (so its count stays reportable) but
- * not retried, because re-reading a file that is gone wastes work. Age it out of
- * the ledger after this window so a corpus of long-deleted transcripts cannot grow
- * the failure set without bound.
- */
 const TRANSCRIPT_UNAVAILABLE_TTL_MS = 14 * 24 * 60 * 60 * 1000;
 function ledgerPath() {
     return path.join(getRuntimeStateDir(), 'traces-sync.json');
@@ -822,22 +610,12 @@ function writeSyncLedger(ledger) {
     fs.mkdirSync(path.dirname(p), { recursive: true });
     fs.writeFileSync(p, JSON.stringify(ledger, null, 2) + '\n', 'utf8');
 }
-/**
- * True once the user has run `agents traces sync` at least once (the ledger
- * file exists). This is the opt-in signal the run-exit auto-sync gates on
- * (PHNX-3628): a user who has never synced has not opted into the traces store,
- * so an `agents run` never uploads on their behalf.
- */
 export function hasSyncedBefore() {
     return fs.existsSync(ledgerPath());
 }
-// ---------------------------------------------------------------------------
-// Local device name
-// ---------------------------------------------------------------------------
 function localDevice() {
     return (process.env['AGENTS_SYNC_MACHINE_ID'] ?? os.hostname()).toLowerCase().replace(/\.local$/, '');
 }
-/** Minimal subset of rowToMeta needed to satisfy buildTrajectory's SessionMeta param. */
 function rowToMeta(row) {
     const SESSION_RUN_MODES = ['plan', 'edit', 'auto', 'skip'];
     return {

package/dist/lib/traces/worker-template.d.ts

@@ -1,4 +1 @@
-/**
- * Render the traces Worker source. Pure — bindings are wired at deploy time.
- */
 export declare function renderTracesWorkerScript(): string;

package/dist/lib/traces/worker-template.js

@@ -1,32 +1,3 @@
-// The Cloudflare Worker that fronts the R2 traces bucket.
-//
-// SECURITY: unlike agents-share, there is NO public GET path here. Every route
-// — PUT and GET — requires a Phoenix bearer. The caller must be the record's
-// owner (path prefix == verified userId). A missing bearer → 401; a wrong
-// owner → 403; public cache headers are NEVER emitted.
-//
-// Routes (all require Phoenix bearer + userId owner match):
-//   PUT  /<userId>/<device>/index.json            — per-device stats shard
-//   PUT  /<userId>/<device>/sessions/<id>.json    — per-session SessionDetail
-//   GET  /<userId>/<device>/...                   — returns the stored object
-//   GET  /<userId>/all/index.json                 — cross-device merge (read-side)
-//   GET  /<userId>/all/sessions/<id>.json         — first device that holds <id>
-//   GET  /                                        — 200 description (no data)
-//
-// The CLI writes per-device (`localDevice()` == hostname); the console asks for
-// the "all agents" view (`/all/`). `all` is not a real device — the worker
-// synthesizes it on read by listing this owner's device prefixes and merging.
-// A single device is an exact passthrough; cross-device stats that need the raw
-// sample (median, latency percentiles) are session-weighted approximations,
-// documented at the merge site. This keeps the CLI unchanged and uploads nothing
-// extra — the per-device shards already in R2 are the source (PHNX-3397).
-//
-// Emitted as a string so it compiles into dist/** and ships with no
-// package.json#files change. `provisionTraces.ts` uploads this verbatim as an
-// ES-module Worker with a BUCKET (R2) binding + a PHOENIX_ID_BASE secret.
-/**
- * Render the traces Worker source. Pure — bindings are wired at deploy time.
- */
 export function renderTracesWorkerScript() {
     return `// GENERATED by agents-cli agents traces — do not edit; edit
 // src/lib/traces/worker-template.ts and re-provision.