agentel 0.2.0

package/docs/code-reference.md

@@ -0,0 +1,1108 @@
+# Code Reference
+
+This is a practical map of the current agentlog codebase. It lists every
+top-level function in `src/` and describes what each one is responsible for.
+Functions exported by a module are called out first; private helpers are still
+listed because many of the importers and CLI flows are intentionally small,
+plain functions rather than classes.
+
+## Entry Points
+
+### `bin/agentlog.js`
+
+Runs `src/cli.main()` with process arguments. This is the installed `agentlog`
+binary.
+
+### `bin/agentlog-recall.js`
+
+Runs the recall command surface used by installed skills and slash commands.
+
+## `src/archive.js`
+
+Archive storage, transcript normalization, canonical event persistence,
+markdown rendering, session listing, and reveal-cache reads.
+
+Exports:
+
+- `archiveRoot(env)`: resolves the root archive object directory from config.
+- `countSessions(env)`: returns total archived sessions and counts by provider.
+- `decodeSegment(value)`: decodes an archive path segment.
+- `encodeSegment(value)`: URL-encodes an archive path segment.
+- `ensureConversationMarkdown(session, env)`: materializes a missing
+  `conversation.md` from an existing transcript JSONL.
+- `listSessions(env)`: reads all archived metadata files and returns session
+  records sorted newest first, including derived raw source archive paths when
+  present.
+- `normalizeMessages(messages)`: normalizes raw messages into indexed,
+  timestamped transcript records.
+- `objectPathForSession(session, env)`: computes the archive directory for one
+  session using repo/scope, provider, and date.
+- `readTranscript(file)`: reads transcript JSONL into message objects.
+- `readEvents(sessionOrPath)`: reads canonical `events.jsonl` records from a
+  session metadata object or event path.
+- `renderConversationMarkdown(session, messages, events)`: renders readable
+  Markdown, including redaction marker styling and canonical tool event
+  sections.
+- `revealSession(sessionId, env)`: reads the optional unredacted reveal-cache
+  JSONL for a session.
+- `stableSessionId(provider, sourcePath, startedAt, messages)`: generates a
+  deterministic fallback session id.
+- `toIso(value)`: converts date-ish values to ISO strings.
+- `walk(dir, visit)`: recursively walks a directory tree.
+- `writeSession(input, env)`: redacts, normalizes, writes, indexes, computes
+  stats metadata (`messageCount`, `userMessageCount`, `usage`, `models`), and
+  copies declared raw source files for one archived session.
+
+Internal helpers:
+
+- `removeStaleSessionCopies(session, metadataPath, env)`: removes older archive
+  copies for the same provider/session id or same source path.
+- `copyRawFiles(input, rawPath)`: copies source files into
+  `session=<id>.raw/` and writes the raw manifest. When `sharedRawFiles` is set,
+  it stores large source files once under `raw-sources/` and writes manifest
+  references from each session.
+- `rawSourceFiles(input)`: collects deduped raw files from `rawFiles`,
+  `sourceFiles`, `sourcePath`, and SQLite sidecars.
+- `rawSourceCandidate(value)`: resolves a raw source path, including paths with
+  fragment suffixes.
+- `sqliteSidecarFiles(file)`: returns existing SQLite WAL/SHM sidecar
+  candidates for database-backed sources.
+- `safeRawFilename(value)`: sanitizes original basenames for raw archive copies.
+- `fileSha256(file)`: hashes a copied raw file for the manifest.
+- `safeRm(file)`: removes files or directories while ignoring missing paths.
+- `safeStat(file)`: stats a path while ignoring missing paths.
+- `safeUnlink(file)`: deletes a file while ignoring missing files.
+- `dedupeAdjacentMessages(messages)`: collapses adjacent duplicate transcript
+  messages.
+- `normalizedContent(value)`: whitespace-normalizes message content for
+  dedupe.
+- `timestampsNear(left, right)`: treats near-identical timestamps as duplicate
+  candidates.
+- `normalizeRole(role)`: maps provider roles into agentlog transcript roles.
+- `yamlString(value)`: serializes frontmatter string values.
+- `markdownLine(value)`: makes a single-line Markdown heading string.
+- `roleLabel(role)`: renders a display label for a transcript role.
+- `normalizePrecomputedEvents(events, session)`: fills session/source fields on
+  caller-provided canonical events before archive write.
+- `redactCanonicalEvents(events, options)`: redacts all string values inside
+  canonical events.
+- `redactStructuredStrings(value, options)`: recursively redacts strings in
+  metadata/event objects.
+- `touchManifest(session, pathsForSession, env)`: updates the archive manifest.
+
+## `src/canonical-events.js`
+
+Provider-independent event normalization, tool-call text rendering, and
+low-signal filtering.
+
+Exports:
+
+- `CANONICAL_EVENT_SCHEMA_VERSION`: current event schema id,
+  `agentlog.events.v1`.
+- `EVENT_KINDS`: constants for `session.started`, `prompt.submitted`,
+  `response.generated`, `tool.called`, and `tool.completed`.
+- `normalizeSessionEvents(session, messages, options)`: maps transcript
+  messages into canonical events.
+- `messageToCanonicalEvents(message, session, options)`: maps one message into
+  zero or more canonical events.
+- `stableEventId(sessionId, messageIndex, kind, ordinal, content)`: creates a
+  deterministic event id.
+- `renderEventText(event)`: returns keyword-searchable text for one event.
+- `renderToolCallText(toolCall)`: renders a normalized tool call into readable
+  prose.
+- `isLowSignalToolCall(toolCall)`: filters path-only, numeric-only, and
+  oversized tool-call content from search text.
+- `normalizeToolCall(raw, provider)`: normalizes provider tool-call metadata.
+- `normalizeToolResult(raw, provider)`: normalizes provider tool-result
+  metadata.
+
+## `src/parser-versions.js`
+
+Central semantic parser-version table used by import fingerprints, archive
+metadata, and canonical events.
+
+Exports:
+
+- `PARSER_VERSIONS`: source-type to parser-version string map.
+- `SOURCE_TYPE_ALIASES`: compatibility aliases for older source labels.
+- `canonicalSourceType(sourceType)`: resolves an alias to the canonical source
+  type.
+- `parserVersionForSource(sourceType)`: returns the current parser version or
+  `null`.
+- `fingerprintPrefix(sourceType)`: returns `<source-type>-v<version>` and
+  throws for unknown source types.
+- `assertKnownSourceType(sourceType)`: validates a source type.
+
+## `src/version.js`
+
+Single package-version source for CLI and MCP surfaces.
+
+Exports:
+
+- `version`: the value from `package.json`.
+
+## `src/autostart.js`
+
+Platform-specific background startup integration.
+
+Exports:
+
+- `autostartStatus()`: reports platform support, enabled state, and target file.
+- `disableAutostart()`: removes the platform autostart entry.
+- `enableAutostart(options)`: writes and optionally loads the platform autostart
+  entry.
+- `recallInvocation()`: returns the preferred command/args for invoking
+  `agentlog-recall`.
+
+Internal helpers:
+
+- `autostartTarget()`: chooses the platform-specific autostart target.
+- `macLaunchAgent()`: builds the macOS LaunchAgent definition.
+- `linuxUserUnit()`: builds the systemd user service definition.
+- `windowsTaskFile()`: builds the Windows helper command and task actions.
+- `cliPath()`: resolves the repo-local CLI file.
+- `commandOnPath(command)`: finds an installed command on `PATH`.
+- `shellQuote(value)`: single-quotes a shell value.
+- `unsupportedNote(platform)`: formats unsupported-platform text.
+- `quoteSystemd(value)`: escapes spaces for systemd command lines.
+- `escapeXml(value)`: XML-escapes plist values.
+
+## `src/cli.js`
+
+The command-line application, init wizard, history web server, recall installers,
+and terminal presentation helpers. Small command handlers that can stand alone
+live under `src/commands/`.
+
+Exports:
+
+- `main(argv, env)`: dispatches CLI commands.
+- `parseArgs(argv)`: splits positional arguments and `--flags`.
+- `recallSurfaceTemplates()`: returns generated recall command/skill templates.
+
+Command handlers:
+
+- `initCommand(flags, env)`: runs interactive setup, config writes, source
+  discovery, optional imports, and next-step output.
+- `startCommand(env)`: starts the supervisor, detached unless `--foreground`
+  already routed to the foreground runner.
+- `stopCommand(env)`: stops the supervisor process.
+- `statusCommand(flags, env)`: prints or returns home, storage, supervisor,
+  session, index, collector, sync, and recent archive state.
+- `recentArchivedSessions(env, limit)`: returns recently written session
+  metadata for status output.
+- `configCommand(args, env)`: handles `config get` and `config set`.
+- `migrateCommand(flags, env)`: updates storage backend configuration.
+- `syncCommand(flags, env)`: runs archive sync with configured or flag-provided
+  remote settings.
+- `autostartCommand(action)`: enables, disables, or reports autostart.
+- `resetCommand(flags, env)`: removes agentlog local state and archive objects.
+- `uninstallCommand(flags, env)`: stops services, removes autostart, and
+  optionally removes data.
+- `revealCommand(sessionId, env)`: prints unredacted reveal-cache JSONL.
+- `redactCommand(action, env)`: reapplies redaction to archived sessions.
+- `indexCommand(action, env)`: pauses, resumes, rebuilds, or reports the search
+  index.
+- `doctorCommand(flags, env)`: runs diagnostics.
+- `importCommand(args, flags, env)`: imports local sources or web export files.
+- `recallCommand(args, env)`: handles recall server/install/show/reindex flows.
+- `showRecallSession(sessionId, env)`: prints a session through the recall path.
+- `showCommand(sessionId, flags, env)`: prints, opens, or JSON-serializes a
+  session.
+- `historyCommand(args, flags, env)`: searches/lists history or launches the web
+  viewer.
+- `historyWebCommand(flags, env)`: serves the local history browser/API and
+  opens it in the default browser unless `--no-open` is set.
+- `serverCommand(flags, env)`: delegates the compatibility `server` alias to
+  the MCP stdio server.
+- `help(topic)`: prints top-level help or topic-specific help.
+- `normalizeHelpTopic(topic)`: resolves help aliases such as `clear` to `reset`.
+- `unknownHelp(topic)`: renders the fallback message for unknown help topics.
+- `formatHelpText(text)`: applies terminal styling to help text.
+- `formatHelpItem(line)`: bolds command/flag columns inside help output.
+
+Reset and process helpers:
+
+- `waitForSupervisorExit(pid, timeoutMs)`: waits briefly for a supervisor to
+  exit.
+- `pidAlive(pid)`: checks whether a process id is alive.
+- `sleep(ms)`: promise-based timeout.
+- `resetTargets(env)`: lists filesystem targets removed by reset.
+- `coalesceTargets(targets)`: removes duplicate/nested reset targets.
+- `isSameOrInside(value, parent)`: checks path containment.
+- `assertSafeResetTarget(targetPath)`: prevents reset from deleting unsafe
+  filesystem roots.
+
+Session display and API helpers:
+
+- `readSessionMarkdown(sessionId, env)`: finds a session and returns its
+  Markdown, metadata, and transcript.
+- `sessionViewPayload(view)`: builds the web/API payload for one session.
+- `dedupeTranscriptMessages(messages)`: removes duplicate messages for readable
+  view payloads.
+- `normalizedTranscriptContent(value)`: whitespace-normalizes transcript content.
+- `transcriptTimestampsNear(left, right)`: compares transcript timestamps for
+  dedupe.
+- `openTarget(target)`: opens a file path or URL with the platform default app.
+- `openFile(file)`: opens a file with the platform default app.
+- `openUrl(url)`: opens a URL with the platform default browser.
+- `historyFilters(flags, defaultLimit)`: builds history filters from CLI flags.
+- `historyFiltersFromSearchParams(params, defaultLimit)`: builds filters from
+  web query params.
+- `sessionTreePayload(filters, env)`: groups sessions by repo/scope for the web
+  file tree.
+- `repoSessionsPayload(repoKey, filters, offset, env)`: returns paginated
+  sessions for one repo/scope group.
+- `sessionRepoKey(session)`: returns the tree key for a session group.
+- `sessionRepoLabel(session)`: returns the tree label for a session group.
+- `displaySessionRepoLabel(session)`: chooses repo, scope, or local path display
+  text.
+- `displayScopeLabel(scope)`: turns known scope keys into readable labels.
+- `parseFilterExpression(filter)`: parses combined filter expressions.
+- `clampLimit(value, fallback)`: bounds list/search limits.
+- `historyTitle(base, filters)`: formats terminal history subtitles.
+- `writeJsonResponse(res, payload, status)`: writes a JSON HTTP response.
+
+Recall integration helpers:
+
+- `addRecallToAgent(target, env)`: installs MCP config or recall command files
+  for one agent.
+- `installRecallSurface(target, env, options)`: installs slash-command/skill
+  recall surfaces.
+- `normalizeRecallTarget(target)`: maps common source/client aliases to recall
+  installer targets.
+- `writeTextFile(file, text)`: writes a text file after ensuring its directory.
+- `genericRecallInstructions()`: common recall workflow text for agents.
+- `claudeRecallCommand()`: generated Claude `/recall` command body.
+- `geminiRecallCommand()`: generated Gemini recall command config.
+- `antigravityRecallSkill()`: generated Antigravity recall skill body.
+- `cursorRecallCommand()`: generated Cursor project `/recall` command body.
+- `cursorRecallRule()`: generated Cursor rule that advertises agentlog recall.
+- `devinRecallSkill()`: generated Devin `/recall` skill body.
+- `opencodeRecallCommand()`: generated OpenCode `/recall` command body.
+- `clineRecallWorkflow()`: generated Cline `/recall.md` workflow body.
+- `aiderRecallInstructions()`: generated Aider loadable recall instructions.
+- `codexRecallSkill()`: generated Codex skill body.
+- `recallArchiveHints()`: shared archive path and filter hints.
+- `commandOnPath(command)`: finds an executable on `PATH`.
+- `shellQuote(value)`: quotes a shell argument.
+- `writeJsonMcpConfig(file, invocation)`: writes an MCP JSON config file.
+- `opencodeConfigFile(env)`: resolves the OpenCode global config path.
+- `writeOpenCodeMcpConfig(file, invocation)`: writes OpenCode's `mcp.agentlog`
+  config shape.
+- `readJsonConfigFile(file, fallback)`: reads strict JSON or simple JSONC
+  config files.
+- `stripJsonCommentsAndTrailingCommas(text)`: converts common JSONC syntax to
+  JSON before parsing.
+- `printRecallAdded(target, file, invocation)`: prints recall install output.
+- `configureClaudeTelemetry()`: merges Claude telemetry settings.
+- `configureGeminiTelemetry()`: merges Gemini CLI telemetry settings.
+- `configureClineTelemetry(env)`: writes Cline OTel environment and launcher
+  helper files.
+
+Argument, output, and formatting helpers:
+
+- `parseRepoFilter(filter)`: parses comma-separated repo filters.
+- `printDiscovery(label, result)`: prints discovery summary rows.
+- `printImportResults(results)`: prints import summary rows.
+- `printPageTitle(title, subtitle)`: prints styled page headers.
+- `printState(label, value, tone)`: prints a labeled status row.
+- `printProviderCounts(counts, emptyText)`: prints counts grouped by provider.
+- `printRecentArchives(sessions)`: prints recent archived sessions.
+- `printSessionList(sessions)`: prints terminal history session rows.
+- `printSearchResults(results)`: prints terminal search results.
+- `providerLabel(provider)`: maps provider keys to display names.
+- `formatWhen(value)`: formats timestamps for display.
+- `truncate(value, max)`: shortens long strings.
+- `wrapText(value, width)`: wraps terminal text.
+- `formatDetails(details)`: formats key/value details.
+- `printInitBanner(env)`: prints the large init banner.
+- `printSection(title)`: prints a boxed section title.
+- `printCheck(label, value)`: prints a success row.
+- `printCommand(label, command)`: prints a suggested command row.
+- `printMuted(text)`: prints muted explanatory text.
+- `box(lines, options)`: draws a terminal box.
+- `center(text, width)`: centers text within a fixed width.
+- `visibleLength(text)`: measures terminal-visible length after ANSI stripping.
+- `color(text, style)`: wraps text in ANSI color/style codes.
+- `compactPath(value)`: shortens paths with `~`.
+- `fullPath(value)`: expands `~` and resolves paths for display.
+- `describeStorage(cfg)`: formats storage backend text.
+
+Init wizard helpers:
+
+- `chooseStorageSetup(flags, env)`: selects local and remote archive
+  destinations.
+- `chooseArchiveDestinations()`: interactive toggle UI for archive destinations.
+- `remoteBackendLabel(backend)`: display label for remote backend keys.
+- `remoteUrlPrompt(backend)`: prompt text for remote endpoint setup.
+- `chooseDataRoot(flags, env)`: asks for the archive data directory.
+- `resolveUserPath(value)`: resolves home-relative, `~/`, and absolute paths.
+- `chooseSetupSettings(flags)`: asks for autostart/recall toggles.
+- `chooseTelemetrySettings(flags)`: asks for post-import OTel bridge toggles.
+- `setupOptionGroups(flags)`: builds setup toggle groups.
+- `chooseImportSince(flags)`: asks which history window to import.
+- `chooseImportSources(flags, discovered)`: asks which discovered sources to
+  import.
+- `chooseWatcherSources(flags, discovered, importSources)`: asks which sources
+  the supervisor should poll after backfill.
+- `importSourceOptions(discovered)`: builds the source toggle list from
+  discovery results.
+- `sourceSummary(result)`: formats discovered source counts.
+- `confirm(question, defaultYes)`: yes/no prompt.
+- `ask(question)`: readline prompt wrapper.
+- `createProgressReporter(options)`: renders updating progress bars for
+  discovery/import.
+
+Embedded history web app functions:
+
+- `historyHtml(token)`: returns the full local web history app HTML.
+- `params(extra)`: builds API query parameters from filter controls.
+- `esc(value)`: HTML-escapes strings.
+- `getJson(path, query)`: fetches a JSON API route.
+- `providerLabel(provider)`: browser-side provider display mapping.
+- `formatWhen(value)`: browser-side timestamp formatting.
+- `renderTree(payload)`: renders the session tree.
+- `renderSearchResults(items)`: renders search result rows.
+- `sessionNode(item, includeExcerpt)`: creates one session button.
+- `loadMoreNode(group)`: creates a repo/group pagination button.
+- `loadMoreRepo(repoKey, marker)`: loads more sessions for one group.
+- `loadSession(id)`: fetches and renders one session.
+- `setLoadingSession(id)`: shows loading state in the detail pane.
+- `setEmptySession(message)`: shows empty/error state in the detail pane.
+- `renderSession(payload)`: renders session header, Markdown, messages, and
+  copy controls.
+- `renderMessages(messages)`: renders readable transcript messages.
+- `messageElement(message)`: creates one readable message row.
+- `copyIconSvg()`: returns the copy icon SVG.
+- `messageCopyButton(content)`: creates per-message copy controls.
+- `copyMessageContent(button, content)`: copies one message and updates tooltip
+  state.
+- `roleLabel(role)`: browser-side role display mapping.
+- `detectToolName(text)`: returns a detected tool label.
+- `detectToolInvocation(text)`: parses tool/skill invocation text.
+- `toolHeader(tool)`: renders a tool callout header.
+- `renderToolCallout(tool)`: renders a readable tool/skill card.
+- `stripToolInvocationLine(text)`: removes the invocation line from content.
+- `renderRichText(value)`: renders Markdown-ish message content.
+- `renderCode(value)`: renders fenced code blocks.
+- `renderText(value)`: renders paragraph blocks.
+- `renderTextBlock(block)`: renders a block with inline tool callouts.
+- `renderMarkdownBlock(block)`: renders headings, lists, quotes, tables, or
+  paragraphs.
+- `isMarkdownTable(lines)`: detects Markdown tables.
+- `splitMarkdownTableRow(line)`: splits table rows.
+- `renderMarkdownTable(lines)`: renders a Markdown table.
+- `renderInline(value)`: renders links, code spans, skill links, and plain
+  inline Markdown.
+- `renderInlinePlain(value)`: renders emphasis and redaction chips.
+- `renderMarkdownLink(label, href)`: renders safe links.
+- `renderSkillLink(name, skillPath)`: renders `$skill` links.
+- `compactSkillPath(value)`: shortens skill paths for display.
+- `setView(mode)`: toggles readable and raw Markdown views.
+- `sessionDetailsText(payload)`: builds copyable session details.
+- `copyText(value)`: writes text to the clipboard.
+- `copySessionDetails()`: copies session metadata for pasting into agents.
+- `loadTree()`: fetches and renders the tree.
+- `search()`: runs a search and renders results.
+- `setupCustomSelects()`: wires custom select dropdown behavior.
+- `setSidebarCollapsed(collapsed)`: collapses or expands the tree pane.
+
+## `src/commands/logs.js`
+
+Supervisor log display.
+
+Exports:
+
+- `logsCommand(flags, env)`: prints logs or follows appended bytes without
+  reprinting the whole file on every change.
+
+## `src/commands/server.js`
+
+Compatibility command for MCP startup.
+
+Exports:
+
+- `serverCommand(flags, env, deps)`: runs the same MCP stdio server used by
+  `agentlog recall start`.
+
+## `src/collector.js`
+
+OTLP HTTP collector for local telemetry.
+
+Exports:
+
+- `startCollector(env, options)`: starts the collector if enabled or forced.
+- `writeTelemetryPayload(req, body, env)`: stores one telemetry payload under
+  the archive telemetry directory.
+
+Internal helpers:
+
+- `isOtlpPath(url)`: recognizes `/v1/logs`, `/v1/traces`, and `/v1/metrics`.
+- `collectBody(req)`: buffers an HTTP request body.
+- `writeJsonResponse(res, payload, status)`: writes JSON HTTP responses.
+- `safeJson(body)`: parses JSON or wraps raw text.
+- `looksLikeJson(body)`: cheaply detects JSON-looking request bodies.
+
+## `src/config.js`
+
+Config defaults, persistence, and key access.
+
+Exports:
+
+- `defaultConfig(env)`: returns the default config object.
+- `getConfigKey(key, env)`: reads a dotted config key.
+- `initConfig(options, env)`: creates a config with setup options.
+- `loadConfig(env)`: reads config from disk and merges defaults.
+- `saveConfig(config, env)`: writes config JSON.
+- `setConfigKey(key, value, env)`: updates a dotted config key.
+
+Internal helper:
+
+- `parseConfigValue(value)`: parses booleans, numbers, JSON, and strings from
+  CLI input.
+
+## `src/doctor.js`
+
+Diagnostic checks for installation, dependencies, config, and source coverage.
+
+Export:
+
+- `runDoctor(env)`: returns checks, warnings, and source coverage details.
+
+Internal helpers:
+
+- `sourceCoverage(discovery, cfg)`: compares discovered source counts with
+  configured import sources.
+- `coverageRow(source, label, result, configured)`: builds one source coverage
+  row.
+- `add(checks, name, ok, detail, remediation)`: appends one diagnostic check.
+- `commandExists(command)`: tests whether a command is on `PATH`.
+- `remoteTargetLabel(cfg)`: formats configured remote archive targets.
+
+## `src/importers.js`
+
+All local and export importers. More source-specific behavior is documented in
+`docs/history-source-handling.md`.
+
+Exports:
+
+- `discoverCliHistory(env, options)`: scans all known local sources and reports
+  counts.
+- `extractGenericMessagesFromJson(data, source, fallbackTime)`: recursively
+  extracts role/content message nodes from arbitrary JSON.
+- `extractText(value, depth)`: converts nested provider content shapes into
+  text.
+- `expandImportSources(source, explicitSources)`: resolves `all` or explicit
+  source selections.
+- `extractCursorConversations(data, sourceKey, fallbackTime)`: extracts Cursor
+  bubble conversations from SQLite JSON blobs.
+- `importCliHistory(options, env)`: dispatches local source imports.
+- `importWebChat(provider, file, options, env)`: imports ChatGPT or Claude.ai
+  export files.
+- `normalizeEventRole(role)`: maps provider roles into agentlog roles.
+- `parseClaudeDesktopSessionFile(file, kind)`: parses one Claude Desktop local
+  session metadata/audit file.
+- `parseAgentJsonl(file, provider)`: parses generic JSONL agent transcripts.
+- `parseJsonlHistoryFile(file, source, fallbackTime)`: parses generic JSONL
+  history records with fallback timestamps.
+- `parseSince(value)`: parses import windows such as `30d` or `all`.
+- `readCursorProjectTranscriptSessions(options)`: reads newer Cursor
+  `agent-transcripts` sessions.
+- `readDevinSessionsFromDb(dbPath)`: reads Devin for Terminal sessions from one
+  SQLite `sessions.db` file.
+- `readExportJson(file)`: reads a JSON export directly or from ZIP.
+
+Import dispatch and generic providers:
+
+- `importJsonlProvider(provider, roots, since, options, env)`: imports JSONL
+  providers such as Claude Code and Claude SDK jobs.
+- `importClaudeDesktopProvider(provider, since, options, env)`: imports Claude
+  Desktop/Workspace metadata and audit sessions.
+- `matchesImportedSessionRepo(session, repo, wantedRepos)`: checks repo filters
+  for sessions with repo or scope attribution.
+- `importCodexProvider(provider, since, options, env)`: imports Codex CLI or
+  Desktop threads from state DB, rollout files, and Codex supplementary
+  summaries when available.
+- `importCursorProvider(provider, since, options, env)`: imports Cursor SQLite
+  and Cursor project transcript sessions; supervisor calls set
+  `cursorRecovery=false` to skip raw SQLite salvage/backfill.
+- `importStructuredProvider(provider, sessions, since, options, env)`: imports
+  pre-normalized structured sources such as Gemini, Antigravity, Cline,
+  OpenCode, and Aider.
+- `structuredSessionReplaceSourcePathCopies(provider, sourceType)`: sourcePath
+  replacement policy for structured imports; Devin disables replacement because
+  many sessions share one SQLite DB.
+- `jsonlProviderSourceType(provider)`: chooses the source type for generic JSONL
+  imports such as Claude CLI, Claude SDK, and Codex fallback sessions.
+
+Generic parsing helpers:
+
+- `stampMessages(messages, sourceType)`: stamps parser version/source metadata
+  onto parsed messages.
+- `dedupeAdjacentMessages(messages)`: collapses adjacent duplicate messages.
+- `normalizedContent(value)`: whitespace-normalizes content for dedupe.
+- `timestampsNear(left, right)`: compares timestamps for dedupe.
+- `extractMessage(event, provider)`: extracts one message from common event
+  shapes.
+- `extractClaudeMessagesFromEvent(event, provider, context)`: Claude Code/SDK
+  JSONL parser for text, thinking, tool calls/results, model, request id, and
+  usage metadata, including `apply_patch` shell calls promoted to edit diffs.
+- `updateClaudeParseContext(event, provider, context)`: keeps Claude model,
+  session, and cwd context while parsing JSONL records.
+- `extractCodexSummaryMessage(event, provider)`: extracts readable Codex
+  reasoning-summary events from rollout JSONL.
+- `codexSummaryText(summary)`: normalizes Codex summary strings or
+  `summary_text` parts.
+- `codexSupplementContent(title, content)`: wraps a supplementary Codex document
+  with a readable heading.
+- `extractToolCallFromEvent(event, provider)`: normalizes Codex-style function
+  call response items into `metadata.toolCalls[]`, including `apply_patch`
+  heredocs embedded in shell commands.
+- `toolDisplayName(value)`: turns underscore-separated tool names into display
+  labels.
+- `summarizeToolArguments(value)`: builds a short redaction-aware argument
+  summary for tool-call metadata.
+- `normalizeWebConversations(provider, data)`: normalizes web export
+  conversations.
+- `chatgptMessages(conversation)`: parses ChatGPT export conversation nodes.
+- `claudeMessages(conversation)`: parses Claude.ai export messages.
+- `genericConversationMessages(conversation, source)`: fallback web-export
+  parser.
+
+Discovery and summary helpers:
+
+- `summarizeFiles(files)`: counts files, projects, and oldest mtime.
+- `summarizeCodex(env, source)`: summary wrapper for Codex threads.
+- `summarizeCodexThreads(allThreads, source)`: summarizes Codex CLI/Desktop
+  counts.
+- `summarizeClaude()`: summarizes Claude Code CLI files.
+- `summarizeClaudeScan(scan)`: formats Claude scan results.
+- `summarizeClaudeSdk()`: summarizes Claude SDK job files.
+- `summarizeClaudeSdkScan(scan)`: formats SDK job results.
+- `summarizeClaudeDesktop(env, options)`: summarizes Claude app local sessions.
+- `summarizeClaudeDesktopSessions(sessions, kind)`: filters/summarizes Claude
+  app session kinds.
+- `summarizeDevin(env, options)`: summarizes Devin CLI SQLite sessions.
+- `summarizeCursor(env, options)`: summarizes Cursor SQLite and transcript
+  sessions.
+- `readClineSessions(env, options)`: scans Cline task folders and returns
+  normalized sessions.
+- `readOpenCodeSessions(env, options)`: scans OpenCode JSON storage and returns
+  normalized sessions.
+- `readAiderSessions(env, options)`: scans Aider markdown history files and
+  returns normalized sessions.
+- `summarizeStructuredSessions(sessions, note)`: summarizes structured
+  providers.
+- `summarizeStructuredSessionDetails(sessions)`: counts detail keys, artifacts,
+  and binary-only stores.
+
+Source location and file helpers:
+
+- `codexRoots(env)`: returns fallback Codex sessions roots.
+- `claudeRoots()`: returns Claude project root.
+- `jsonlFiles(roots)`: scans roots for JSONL and JSONL zstd files.
+- `claudeFiles()`: returns interactive Claude Code JSONL files.
+- `claudeSdkFiles()`: returns Claude SDK job JSONL files.
+- `scanClaudeProjectFiles(options)`: scans and classifies Claude project JSONL.
+- `isClaudeConversationFile(file)`: tests whether a Claude file is interactive.
+- `classifyClaudeFile(file)`: classifies Claude JSONL as conversation, SDK job,
+  or other.
+- `readInitialLines(file, maxLines, maxBytes)`: reads a bounded prefix of a
+  large JSONL file.
+- `readCodexThreads(env)`: queries Codex state DB for top-level threads and
+  optional `stage1_outputs` summary documents.
+- `sqliteTableExists(dbPath, tableName)`: checks optional SQLite tables before
+  querying version-dependent Codex state.
+- `codexStateDb(env)`: resolves Codex state DB path.
+- `codexSupplementaryMessages(thread, fallbackTimestamp)`: converts Codex
+  `rollout_summary` and `raw_memory` rows into archived transcript messages.
+- `codexSupplementaryMessage(kind, title, content, timestamp)`: builds one
+  supplementary Codex message.
+- `codexSupplementFingerprint(thread)`: hashes Codex supplementary documents
+  into the import fingerprint.
+- `summarizeCodexSources(threads)`: counts CLI and Desktop Codex threads.
+
+Claude Desktop helpers:
+
+- `readClaudeDesktopSessions(options)`: scans Claude app local session roots.
+- `claudeDesktopMetadataMessages(data, kind, startedAt)`: builds fallback
+  messages from metadata.
+- `claudeDesktopAuditPath(file)`: resolves sibling audit JSONL path.
+- `readClaudeDesktopAuditMessages(file, kind)`: parses audit events into
+  messages.
+- `extractClaudeAssistantText(content)`: keeps assistant text parts.
+- `extractClaudeDesktopUserText(event)`: keeps direct user prompts and selected
+  question answers.
+- `normalizeClaudeDesktopCwd(data)`: finds an existing cwd/folder from metadata.
+- `claudeDesktopUncategorizedScope(kind)`: returns uncategorized scope for
+  missing cwd.
+- `summarizeClaudeDesktopKinds(sessions)`: counts workspace versus code desktop
+  sessions.
+
+Cursor helpers:
+
+- `cursorWorkspaceDbs(env)`: finds older Cursor `state.vscdb` stores.
+- `cursorGlobalStorageDbs(env)`: finds Cursor's global `state.vscdb` for raw
+  salvage.
+- `cursorWorkspaceStorageRoot(env)`: resolves the Cursor workspace storage root.
+- `cursorGlobalStorageRoot(env)`: resolves the Cursor global storage root.
+- `cursorProjectsRoot(env)`: resolves the newer Cursor project transcript root.
+- `cursorProjectTranscriptFiles(env)`: finds Cursor transcript JSON/JSONL files.
+- `groupCursorTranscriptFiles(files, env)`: groups transcript files by session.
+- `parseCursorTranscriptGroup(group)`: normalizes one transcript session group.
+- `parseCursorTranscriptFile(file)`: parses one Cursor transcript file.
+- `parseCursorJsonHistoryFile(file, source, fallbackTime)`: parses Cursor JSON
+  transcripts with Cursor-specific tool metadata before generic fallback.
+- `cursorMessagesFromRecord(record, source, fallbackTime)`: converts one Cursor
+  record/bubble/event into message and tool-result rows.
+- `cursorToolCallsFromRecord(record)`: extracts Cursor tool, command, edit, and
+  diff call metadata.
+- `cursorToolResultsFromRecord(record)`: extracts Cursor tool/command output
+  metadata.
+- `cursorUsage(record)`: normalizes Cursor token usage fields when present.
+- `eventTimestamp(event)`: extracts timestamps from common event paths.
+- `offsetTimestamp(fallbackTime, offset)`: creates stable fallback timestamps.
+- `cursorSlugToPath(slug, env)`: decodes Cursor project slugs to existing paths.
+- `addCursorSlugCandidates(candidates, root, tokens)`: generates candidate
+  decoded paths.
+- `startsWithTokens(tokens, prefix)`: checks token prefixes.
+- `readCursorSessionsFromDb(dbPath, options)`: reads conversations from one
+  Cursor DB; supervisor imports pass `includeRawSalvage=false` so raw SQLite
+  backfill stays explicit.
+- `readCursorRows(dbPath)`: queries Cursor `ItemTable`.
+- `readCursorGlobalDiskKvSessionsFromDb(dbPath, options)`: reconstructs Cursor
+  global `cursorDiskKV` Composer/Agent sessions from `composerData:<id>` headers
+  or inline `conversation` arrays and matching `bubbleId:<id>:<bubble>` rows.
+- `readCursorRawSqliteSalvageSessionsFromDb(dbPath, options)`: streams Cursor
+  DB, backup, and WAL bytes for deleted or migrated JSON fragments.
+- `cursorRawSqliteFilesForDb(dbPath)`: returns the Cursor raw-salvage files for
+  a SQLite DB.
+- `extractCursorRawSqliteFragmentsFromFile(file)`: streams one raw Cursor DB
+  file and extracts parseable `composerData` and `bubbleId` fragments.
+- `extractCursorRawSqliteFragmentsFromText(text, sourcePath)`: test helper for
+  the raw Cursor fragment scanner.
+- `extractCursorRawSqliteConversationsFromText(text, sourcePath, fallbackTime)`:
+  test helper that converts raw Cursor fragments into conversations.
+- `scanCursorRawSqliteText(text, sourcePath)`: chunk scanner used by raw Cursor
+  salvage.
+- `parseCursorRawJsonObjectAt(text, start, maxEnd)`: parses one balanced raw
+  JSON object with a fragment-size cap.
+- `cursorRawSqliteSalvageSessionsFromFragments(fragments, options)`: wraps raw
+  Cursor conversations into importable sessions.
+- `extractCursorRawSqliteConversationsFromFragments(fragments, fallbackTime)`:
+  groups raw Cursor fragments into conversations.
+- `cursorRawComposerDataConversations(fragment, fallbackTime)`: parses recovered
+  `composerData:<id>` records.
+- `cursorRawBubbleGroupConversation(composerId, fragments, fallbackTime)`:
+  groups recovered `bubbleId:<composerId>:<bubbleId>` records.
+- `cursorCwdFromObject(data)`: infers a Cursor cwd from workspace metadata or
+  selected file paths in recovered records.
+- `readSqliteJson(dbPath, query, label)`: runs `sqlite3 -json` for SQLite-backed
+  importers.
+- `runSqliteJson(dbPath, query)`: low-level SQLite JSON command runner.
+- `parseSqliteJson(stdout)`: parses `sqlite3 -json` output.
+- `sqliteResultError(result, label)`: formats SQLite errors.
+- `shouldRetrySqliteFromSnapshot(result, dbPath)`: detects live-DB errors that
+  can be retried from a snapshot.
+- `readSqliteJsonFromSnapshot(dbPath, query, label)`: copies a live SQLite
+  database plus WAL/SHM files to a temp directory when direct reads are locked
+  or refused.
+- `copySqliteSnapshotFile(source, target, optional)`: copies SQLite DB/WAL/SHM
+  files for snapshot reads.
+- `sqlQuote(value)`: quotes strings for SQLite SQL.
+- `readCursorWorkspaceFolder(workspaceDir)`: reads Cursor workspace folder
+  metadata.
+- `cursorBubbleToMessage(bubble, fallbackTime, index)`: converts one Cursor
+  bubble into a message.
+- `cursorRole(value)`: maps Cursor bubble roles.
+- `cursorBubbleContext(bubble)`: extracts terminal/file selection context,
+  including nested Cursor context fields whose object keys contain file URIs.
+- `dedupeCursorSessions(sessions)`: removes duplicate Cursor sessions, ranking
+  project agent transcripts above global `cursorDiskKV` composer records, global
+  composer records above workspace SQLite, and `aiService` prompt/apply history
+  as a breadcrumb fallback.
+- `mergeCursorRawAssistantOnlySessions(sessions)`: attaches recovered raw
+  assistant/tool-only Cursor fragments to matching same-project Cursor sessions
+  when the evidence is strong enough.
+- `mergeCursorRawCompanionSessions(sessions)`: attaches raw Cursor companion
+  fragments with recovered assistant/tool responses to the best matching
+  workspace or agent transcript, then drops contained raw duplicates.
+- `cursorSessionSourcePath(session)`: returns the Cursor archive/source path
+  used when scoping incremental duplicate pruning.
+- `pruneCursorArchivedDuplicates(env, state, options)`: removes duplicate
+  archived Cursor sessions; supervisor imports pass a touched-source-path scope
+  so old unrelated Cursor history is not repaired opportunistically.
+
+Cline helpers:
+
+- `clineRoots(env)`: resolves VS Code and JetBrains Cline globalStorage roots,
+  plus `AGENTLOG_CLINE_ROOT(S)` overrides.
+- `clineTaskDirs(roots)`: finds `tasks/<task-id>` directories under Cline roots.
+- `parseClineTaskDir(dir, root)`: normalizes one Cline task folder.
+- `clineApiMessages(data, fallbackTime, metadata)`: parses
+  `api_conversation_history.json` into messages and tool metadata.
+- `clineUiMessages(data, fallbackTime)`: fallback parser for `ui_messages.json`.
+- `clineToolCall(part, metadata)`: normalizes Anthropic-style Cline tool-use
+  parts.
+- `clineToolResult(part)`: normalizes Cline tool-result parts.
+- `readClineCheckpointDiffs(taskDir)`: reads checkpoint metadata, diff/patch
+  files, search/replace edits, and checkpoint shadow git repos into
+  supplementary edit tool calls.
+- `mergeClineCheckpointMessages(messages, checkpointMessages)`: attaches
+  checkpoint edit calls to the nearest assistant turn when timestamps allow.
+
+OpenCode helpers:
+
+- `openCodeStorageRoots(env)`: resolves global and project-scoped OpenCode
+  `storage` directories, plus override env vars.
+- `openCodeSessionFiles(root)`: finds session JSON files.
+- `parseOpenCodeSessionFile(file, storageRoot)`: normalizes one OpenCode
+  session plus its messages, parts, project metadata, and session diff.
+- `openCodeMessageFiles(storageRoot, sessionId)`: finds message JSON files for
+  a session.
+- `openCodePartFiles(storageRoot, messageId)`: finds part JSON files for a
+  message.
+- `openCodeToolCall(part)`: normalizes OpenCode tool parts into tool-call
+  metadata.
+- `openCodeToolResult(part)`: normalizes OpenCode tool outputs.
+- `openCodeDiffMessage(file, fallbackTime)`: converts `session_diff` JSON into
+  a supplementary edit tool call for inline diff rendering.
+
+Aider helpers:
+
+- `aiderChatHistoryFiles(env)`: finds `.aider.chat.history.md` files or an
+  explicit `AIDER_CHAT_HISTORY_FILE` override.
+- `aiderRoots(env)`: returns repo roots to scan for Aider histories, excluding
+  unsafe implicit cwd values such as the filesystem root or home directory.
+- `parseAiderChatHistoryFile(file, env)`: normalizes one Aider markdown
+  transcript and enriches it with LLM sidecar metadata and conservative git
+  diff correlation.
+- `parseAiderHistoryFile(file, options)`: provider-specific Aider parser used
+  by the central importer.
+- `parseAiderLlmHistoryText(text)`: extracts model, request id, response, and
+  token usage metadata from `.aider.llm.history`.
+- `correlateAiderMessagesWithGit(messages, cwd, options)`: attaches nearby
+  Aider auto-commit diffs as assistant edit tool calls, including multiple
+  matching commits for a single turn.
+- `aiderMarkdownMessages(text, fallbackTime)`: splits Aider `#### <prompt>`
+  headings into user/assistant turns.
+- `aiderSourceFiles(file, env)`: adds optional raw `.aider.llm.history` and
+  `.aider.input.history` sidecars.
+
+Devin helpers:
+
+- `readDevinSessions(env, options)`: resolves the Devin CLI database and reads
+  importable sessions.
+- `devinSessionsDb(env)`: returns `AGENTLOG_DEVIN_SESSIONS_DB` or
+  the platform default Devin CLI `sessions.db` path.
+- `readDevinSessionRows(dbPath)`: selects visible rows from Devin `sessions`.
+- `readDevinMessageRows(dbPath)`: selects Devin `message_nodes`.
+- `devinPromptMessages(dbPath, sessionId)`: fallback import from
+  `prompt_history`.
+- `devinMainChain(rows, mainNodeId)`: follows the selected node chain and drops
+  alternate branches.
+- `devinMessagesFromNode(row)`: parses `chat_message` JSON into agentlog
+  messages.
+- `devinVisibleContent(content, toolCalls)`: keeps visible prose while dropping
+  Devin's `none` placeholders for tool-only assistant nodes.
+- `devinIsContextUserMessage(role, content)`: skips injected Devin context.
+- `devinNormalizeToolCall(call, message)`: converts Devin tool calls into
+  normalized metadata.
+- `devinToolCallExtension(message, id)`: reads Devin's richer tool-call display
+  metadata extension.
+- `devinPublicToolCall(call)`: returns the redaction-safe tool metadata stored
+  in transcripts.
+- `devinNormalizeToolResult(content, message)`: converts Devin tool results
+  into normalized metadata.
+- `devinToolCallLine(call)`: legacy readable formatter retained for fallback
+  parsing.
+- `devinToolDisplayName(value)`: maps Devin tool names to concise labels.
+- `devinToolArgument(value)`: extracts a useful tool-call argument preview.
+- `devinTitle(messages)`: derives a fallback title from the first user prompt.
+- `devinSessionFingerprint(dbPath, row)`: fingerprints the session row plus DB
+  files.
+
+Gemini and Antigravity helpers:
+
+- `readGeminiCliSessions(options, env)`: reads Gemini CLI session/checkpoint/export
+  files and coalesces prompt-log sidecars with richer chat JSONL records when
+  they share a session id.
+- `geminiCliHistoryFiles()`: finds candidate Gemini files.
+- `isStructuredHistoryFile(file)`: tests file extensions accepted by structured
+  importers.
+- `isGeminiCliHistoryFile(root, file)`: filters Gemini tmp history files.
+- `parseGeminiCliHistoryFile(file)`: parses one Gemini file.
+- `parseGeminiCliJsonl(text, options)` and `parseGeminiCliJson(data, options)`:
+  normalize Gemini role/parts history, function calls/results, shell/code
+  execution parts, native `toolCalls[].result` entries, usage metadata, and
+  checkpoint events.
+- `parseGenericJsonHistory(file, source, fallbackTime)`: generic JSON parser.
+- `parseMarkdownChatFile(file, source, fallbackTime)`: Markdown chat parser.
+- `readWindsurfSessions(options)`: disabled experimental helper retained for
+  future Windsurf decoder work.
+- `readAntigravitySessions(options, env)`: reads Antigravity Markdown artifacts and
+  counts binary stores.
+- `readMarkdownArtifactSessions({ ... })`: common Markdown artifact reader.
+- `markdownArtifactSession(provider, dir, artifactNames, sourceType, detailKey)`:
+  converts one artifact directory into a session.
+- `markdownMessages(text, source, fallbackTime)`: splits Markdown role sections
+  into messages.
+- `markdownTitle(text)`: extracts the first Markdown H1.
+- `artifactTitleFromDir(dir)`: turns an artifact directory name into a title.
+- `artifactLabel(file)`: turns an artifact filename into a display label.
+- `inferCwdFromMarkdownFiles(files)`: finds `file://` links and resolves their
+  nearest existing directory.
+- `nearestExistingParent(value)`: walks up to the nearest existing path.
+- `geminiProjectCwd(file)`: resolves Gemini temp project roots from
+  `.project_root` sidecar files.
+
+Low-level import helpers:
+
+- `structuredSessionFingerprint(session)`: fingerprints source files by path,
+  size, and mtime.
+- `uncategorizedScope(provider)`: returns provider-scoped storage for sessions
+  that do not have a reliable cwd.
+- `countFiles(root, predicate)`: counts matching files under a root.
+- `hashId(value)`: returns a short SHA-256 id.
+- `collectFiles(root, visit)`: recursively walks files.
+- `safeStat(file)`: returns `fs.statSync` or null.
+- `fileFingerprint(file, stat)`: creates a file fingerprint string.
+- `reportProgress(options, summary, current, pathValue)`: emits import progress.
+- `recordImportSkip(summary, options, reason, session, details)`: records a
+  skip reason and, when requested, a per-session skip explanation.
+- `reportDiscoveryProgress(options, event)`: emits discovery progress.
+- `archivedSessionKeys(env)`: returns archived provider/session keys.
+- `archiveSessionKey(provider, sessionId)`: formats provider/session key.
+- `alreadyImportedFile(state, fingerprint, archived, provider)`: checks file
+  import state.
+- `alreadyImported(state, sessionId, fingerprint, archived, provider)`: checks
+  session import state.
+- `readTextMaybeZstd(file)`: reads plain or zstd-compressed JSONL.
+- `loadImportState(env)`: reads import state JSON.
+- `saveImportState(state, env)`: writes import state JSON.
+- `firstString(...values)`: returns the first non-empty string.
+- `firstLine(value)`: returns the first non-empty line.
+
+## `src/importers/shared.js`
+
+Shared importer helpers.
+
+Exports:
+
+- `parseSince(value)`: parses import windows such as `30d`, `12h`, `60m`, or
+  `all`.
+
+## `src/mcp.js`
+
+MCP stdio server for recall/search tools.
+
+Exports:
+
+- `runMcpServer(input, output, env)`: reads JSON-RPC messages and writes MCP
+  responses over stdio.
+- `handleRequest(message, env)`: handles initialize, tool listing, and tool
+  calls.
+- `McpStdioTransport`: exported transport class used by tests or callers.
+
+## `src/paths.js`
+
+Filesystem path resolution and JSON helpers.
+
+Exports:
+
+- `ensureBaseDirs(p)`: creates the core agentlog directories.
+- `ensureDir(dir)`: creates one directory recursively.
+- `homeDir(env)`: resolves `AGENTLOG_HOME` or `~/.agentlog`.
+- `paths(env)`: returns all important agentlog paths.
+- `readJson(file, fallback)`: reads JSON with fallback for missing files.
+- `writeJson(file, value)`: writes pretty JSON with private file mode.
+
+## `src/redaction.js`
+
+Redaction config, env-secret discovery, text redaction, and marker rendering.
+
+Exports:
+
+- `loadEnvValues(cwd, names, env)`: loads configured env values from process env
+  and `.env` files.
+- `loadRedactionConfig(env)`: reads `~/.agentlog/redaction.yaml`.
+- `mergeSummaries(target, source)`: merges redaction count summaries.
+- `parseRedactionYaml(text)`: parses the small supported YAML subset.
+- `redactText(input, options)`: applies built-in, env, high-entropy, and custom
+  redactions.
+- `styleRedactionMarkersForMarkdown(input)`: turns `[REDACTED:...]` markers into
+  styled Markdown HTML.
+
+Internal helpers:
+
+- `parseInlineList(value)`: parses YAML inline lists.
+- `stripYamlString(value)`: removes simple YAML quotes.
+- `envFilesFor(cwd)`: walks upward collecting `.env` file candidates.
+- `safeRedactionKind(value)`: normalizes marker kind labels.
+- `escapeHtml(value)`: HTML-escapes marker labels.
+- `replaceMatches(text, regex, replacement, summary, name)`: replaces and counts
+  matches.
+- `looksHighEntropy(value)`: detects likely high-entropy env assignments.
+- `increment(summary, key, amount)`: increments a summary count.
+- `escapeRegExp(value)`: escapes a literal for regex construction.
+
+## `src/repo.js`
+
+Repo identity and path-scope fallback logic.
+
+Exports:
+
+- `canonicalRepo(cwd)`: returns a repo key from git remote, override file, or
+  stable local path hash.
+- `canonicalizeRemote(remote)`: normalizes common git remote URL forms.
+- `normalizePathForHash(cwd)`: resolves and home-normalizes a path before
+  hashing.
+- `readRepoOverride(cwd)`: reads `.agentlog-repo` from the current tree.
+
+Internal helpers:
+
+- `normalizeHostPath(host, repoPath)`: normalizes host/repo strings.
+- `stripGit(value)`: removes trailing `.git`.
+- `runGit(cwd, args)`: executes git commands quietly.
+- `findUp(start, filename)`: searches upward for a file.
+
+## `src/search.js`
+
+Recall search, history listing, filters, and the event-first keyword index.
+
+Exports:
+
+- `buildIndex(env)`: reads canonical events when present, falls back to
+  transcripts, chunks searchable text, and writes the search index.
+- `chunkText(text, maxTokens, overlap)`: chunks long content for indexing.
+- `listHistorySessions(options, env)`: returns filtered archived session rows.
+- `listRecentSessions(limit, options, env)`: returns recent session rows.
+- `loadIndex(env)`: loads or rebuilds the index.
+- `reindexIfNeeded(env)`: rebuilds the index when stale and not paused.
+- `sessionHistoryTime(session)`: returns display-safe session times, including
+  hiding Cursor raw-salvage timestamps that were synthesized from SQLite mtimes.
+- `searchPastSessions(query, options, env)`: searches the event index first,
+  then legacy markdown/transcript fallback.
+- `tokenize(text)`: lowercases and tokenizes searchable text.
+
+Internal helpers:
+
+- `docsForEvents(session, events)`: converts canonical events into index
+  documents with event ids, event kinds, message indexes, and rendered text.
+- `docsForTranscript(session, messages)`: builds legacy transcript index
+  documents when no event file exists.
+- `searchMarkdownSessions(query, options, env)`: legacy conversation Markdown
+  search with `rg`/JS fallback.
+- `searchIndexedSessions(query, options, env)`: searches the event/transcript
+  JSON index and aggregates hits by session.
+- `ripgrepMatches(queryTokens, files)`: runs `rg --json`.
+- `jsLineMatches(queryTokens, files)`: slow in-process line search fallback.
+- `readLineWindow(file, lineNumber, radius)`: reads context around a match.
+- `inferRoleFromMarkdown(file, lineNumber)`: finds nearest message heading.
+- `escapeRegex(value)`: escapes query tokens for regex.
+- `bm25Score(doc, queryTokens, index)`: scores one indexed chunk.
+- `excerpt(text, queryTokens)`: builds a compact result excerpt.
+- `inferCallingRepo(cwd)`: infers repo key from caller cwd.
+- `displayRepoLabel(session)`: chooses repo/scope/path display text.
+- `displayScopeLabel(scope)`: formats known scope labels.
+- `compactHomePath(value)`: shortens home-relative paths.
+- `normalizeSessionFilter(options)`: normalizes provider/source/repo filters.
+- `normalizeProviderFilter(value)`: maps provider aliases.
+- `matchesSessionFilter(session, filter)`: applies provider/source/repo/date
+  filters.
+- `matchesRepoFilter(session, repoFilter)`: matches repo, scope, cwd, or label.
+- `indexIsStale(indexPath, env)`: detects whether index rebuild is needed.
+- `parseSinceFilter(value)`: parses search history windows.
+
+## `src/sources.js`
+
+Shared source ordering and labels.
+
+Exports:
+
+- `SOURCE_GROUPS`: grouped provider/source metadata for UI ordering.
+- `IMPORT_SOURCE_ORDER`: default source order for `--source all`.
+- `HISTORY_PROVIDER_OPTIONS`: flattened source option list.
+- `sourceLabel(source)`: returns display label for a source key.
+
+## `src/supervisor.js`
+
+Background process that imports, indexes, collects telemetry, and syncs.
+
+Exports:
+
+- `runSupervisorForeground(env)`: runs the supervisor loop in the current
+  process.
+- `startSupervisorDetached()`: starts the foreground supervisor detached.
+- `supervisorImportOptionsForSource(source, config)`: builds supervisor import
+  options with the configured rolling window and Cursor raw recovery disabled.
+- `supervisorImportResultLog(result, source)`: formats supervisor import/prune
+  log lines.
+- `stopSupervisor(env)`: sends SIGTERM to the recorded supervisor process.
+- `supervisorStatus(env)`: reports supervisor PID and running state.
+- `tick(env)`: runs one import, reindex, and sync cycle.
+
+Internal helpers:
+
+- `readPid(env)`: reads the supervisor PID file.
+- `isAlive(pid)`: checks whether a PID is alive.
+- `log(message, env)`: appends to supervisor log.
+
+## `src/sync.js`
+
+Remote archive sync to file targets or S3-compatible object storage. Sync is
+currently upload-only and writes under a device namespace such as
+`agentlog/devices/<device>/...`; snapshots write under
+`agentlog/snapshots/<timestamp>/<device>/...`. Bucket-scoped R2 S3 API URLs such
+as `https://<account-id>.r2.cloudflarestorage.com/<bucket>` are normalized into
+endpoint plus bucket during config/target resolution.
+
+Exports:
+
+- `configureRemoteFromFlags(flags, env)`: persists remote sync settings from CLI
+  flags.
+- `hasRemoteTarget(cfg, env)`: reports whether a remote target is configured.
+- `listLocalArchiveObjects(env, prefix)`: lists local archive objects as remote
+  keys with hashes.
+- `parseListBucketResult(xml)`: parses S3 ListObjectsV2 XML.
+- `remoteTargetFromFlags(flags, cfg, env, options)`: resolves a remote target
+  from flags, config, and env.
+- `remoteObjectPrefix(target, cfg, options)`: returns the device-scoped or
+  snapshot-scoped remote key prefix.
+- `snapshotArchive(options, env)`: uploads a point-in-time copy to the configured
+  remote target.
+- `syncArchive(options, env)`: syncs archive objects to configured/flag target.
+- `syncArchiveIfConfigured(env, options)`: no-ops unless a remote target exists.
+
+Internal helpers:
+
+- `syncArchiveToS3(target, options, env)`: uploads changed objects to S3/R2.
+- `syncArchiveToDirectory(target, options, env)`: copies changed objects to a
+  local/file URL target.
+- `listS3Objects(target, prefix)`: lists existing remote S3 objects.
+- `putS3Object(target, key, body)`: uploads one S3 object.
+- `s3Request(target, request)`: signs and sends one S3-compatible HTTP request.
+- `authorizationHeader({ target, method, pathName, query, headers, now })`:
+  builds AWS Signature V4 authorization.
+- `signingKey(secret, date, region)`: derives the SigV4 signing key.
+- `s3Path(bucket, key)`: builds path-style S3 request paths.
+- `canonicalQueryString(query, includePrefix)`: canonicalizes query params.
+- `awsEncode(value)`: AWS URI-encodes a path/query component.
+- `xmlValue(xml, name)`: extracts one XML tag value.
+- `decodeXml(value)`: decodes minimal XML entities.
+- `reportSyncProgress(options, summary, current, total, key)`: emits sync
+  progress.
+- `loadSyncState(env)`: reads sync state JSON.
+- `saveSyncState(state, env)`: writes sync state JSON.
+- `contentTypeForKey(key)`: chooses upload content type.
+- `walk(dir, visit)`: recursively walks archive files.
+- `safeStat(file)`: returns stat or null.
+- `stripPrefix(key, prefix)`: removes configured remote prefix.
+- `normalizePrefix(prefix)`: normalizes remote prefix.
+- `fileUrlPath(endpoint)`: converts file URL/string endpoint to path.
+- `value(input)`: returns the first non-empty config/env value.
+- `inferRemoteType(endpoint)`: infers remote backend from endpoint.
+- `sha256Hex(value)`: SHA-256 hex hash.
+- `hmac(key, value)`: HMAC-SHA256 buffer.
+- `hmacHex(key, value)`: HMAC-SHA256 hex.
+- `amzDate(date)`: formats SigV4 date strings.