@kinetica/admin-agent 0.2.1 → 0.2.2

package/README.md

@@ -48,7 +48,7 @@ Built with the [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-
 
 - Autonomous multi-round investigation with parallel tool calls
 - 16 read-only diagnostic tools + 4 mutation tools with interactive approval + 2 self-managing tools (reporting, batch-column alter) = **22 live tools**, plus 6 offline bundle-analysis tools = **28 total**
-- **Offline support-bundle analysis** — diagnose from an extracted `gpudb_sysinfo` bundle (per-rank logs, `gpudb.conf`, host diagnostics) with no live connection, or attach a bundle alongside a live session to cross-check captured history against current state
+- **Offline support-bundle analysis** — diagnose from an extracted `gpudb_sysinfo` bundle (per-rank logs, `gpudb.conf`, host diagnostics) with no live connection, or attach a bundle alongside a live session to cross-check captured history against current state — even bundles that don't match the standard layout, via file-name and content inference
 - Expert knowledge via pluggable playbooks (no code required to add new ones)
 - Schema-aware SQL — discovers actual column names at startup, never guesses
 - HTTPS-first URL resolution with explicit consent required before any HTTP fallback
@@ -243,6 +243,8 @@ A bundle and a live connection are **composable capabilities, not exclusive mode
 
 **Every rank, however its logs were captured.** A bundle can carry per-rank logs in two forms: full rolling logs for the ranks on the collector's own host (`logs-local/`, including rotated history like `….log.1`), and centralized Loki/promtail exports for the entire cluster (`logs/rank0.log` … `rankN.log`, plus `hostmanager.log` and per-component tails). The agent reads both transparently — it identifies each rank from either source, prefers the richer rolling log when a rank has both, and falls back to the centralized export for ranks that live on other hosts. So on a multi-node cluster you can investigate **all** ranks (and the host manager), not just the ones local to where the bundle was collected. The centralized exports are JSON-wrapped on disk; the tools unwrap them automatically, so severity filters and timelines behave identically across both formats. `kinetica_bundle_list_files` reports the true rank count under `ranks_present` — trust it rather than guessing from `logs-local/`.
 
+**Bundles that don't match the expected shape.** Not every bundle is a clean `gpudb_sysinfo` capture — a customer may hand over a flat logs-only dump, a differently-named collector's output, or a partial directory. The agent infers each file's type from its name, and for files whose names give nothing away it sniffs a bounded slice of their content against the same log/config/sysinfo parsers. So a rolling log shipped without the canonical `core-` prefix, or a host-manager `.out` capture, is still recognized, searchable, and rank-attributed rather than silently dropped. `kinetica_bundle_list_files` reports a `layout_match` verdict (`canonical` / `partial` / `unfamiliar`), a per-file confidence (`exact` / `inferred` / `weak`), and any files it couldn't place — and the operator gets a startup warning when a bundle is off-shape — so an inference is never passed off as certainty. Classification depends only on file names and contents, never on what the bundle directory itself is named.
+
 Anthropic authentication still runs in bundle mode; only the interactive Kinetica credential collection is skipped (there may be no live DB to connect to). See [Offline Bundle Analysis](#offline-bundle-analysis-read-only) for the tools, and [CLAUDE.md](CLAUDE.md) for the parser/architecture details.
 
 ## CLI Flags
@@ -330,14 +332,14 @@ The `--bundle` flag points the agent at an **extracted** support-bundle director
 
 Available against an extracted `gpudb_sysinfo` support bundle (see [Offline Bundle Mode](#offline-bundle-mode)). All read-only; the search/timeline tools stream and bound their output so a large rank log (tens of MB, hundreds of thousands of lines) never blows up the context.
 
-| Tool                           | Description                                                                                                                           |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `kinetica_load_bundle`         | Attach an extracted bundle directory; without a path it opens a directory picker (a model-supplied path needs operator confirmation)  |
-| `kinetica_bundle_list_files`   | Inventory: detected version, ranks + services present, file counts/sizes by kind — call this first                                    |
-| `kinetica_bundle_log_timeline` | Per-time-bucket severity counts across ranks (the incident shape) — call before searching                                             |
-| `kinetica_bundle_search_logs`  | Bounded log search by regex, min-severity, time window, and rank / host-manager / component (reads both rolling and Loki-export logs) |
-| `kinetica_bundle_read_config`  | Read the bundle's real on-disk `gpudb.conf`, with optional section/key filter                                                         |
-| `kinetica_bundle_read_sysinfo` | OS/process/version diagnostic files (memory, CPU, disk, GPU, network, process args)                                                   |
+| Tool                           | Description                                                                                                                                                                 |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kinetica_load_bundle`         | Attach an extracted bundle directory; without a path it opens a directory picker (a model-supplied path needs operator confirmation)                                        |
+| `kinetica_bundle_list_files`   | Inventory: detected version, ranks + services present, file counts/sizes by kind, plus a layout-match verdict + per-file confidence for off-shape bundles — call this first |
+| `kinetica_bundle_log_timeline` | Per-time-bucket severity counts across ranks (the incident shape) — call before searching                                                                                   |
+| `kinetica_bundle_search_logs`  | Bounded log search by regex, min-severity, time window, and rank / host-manager / component (reads both rolling and Loki-export logs)                                       |
+| `kinetica_bundle_read_config`  | Read the bundle's real on-disk `gpudb.conf`, with optional section/key filter                                                                                               |
+| `kinetica_bundle_read_sysinfo` | OS/process/version diagnostic files (memory, CPU, disk, GPU, network, process args)                                                                                         |
 
 ### Reporting
 
@@ -427,7 +429,7 @@ References provide domain knowledge (not diagnostic runbooks). Create a `.md` fi
 - `sql-create-index` — column index syntax, chunk skip index, when to use which
 - `version-quirks-7.2` — endpoint/property differences between 7.2.x and earlier releases
 
-Plus a **bundle-scoped reference** (`support-bundle` — bundle layout, the two per-rank log families, raw + Loki-JSONL log-line formats, severity ordering, file parsing, crash-SQL forensics) that lives in `knowledge/references/bundle/`. It loads in **every** session — even a pure live one — so that a bundle attached mid-session via `kinetica_load_bundle` has its parsing knowledge ready in the (build-once) prompt; the corpus is cached, so the cost to a session that never attaches a bundle is negligible.
+Plus a **bundle-scoped reference** (`support-bundle` — bundle layout, the two per-rank log families, raw + Loki-JSONL log-line formats, severity ordering, file parsing, crash-SQL forensics, and how to work an off-shape bundle via the `layout_match`/confidence signals) that lives in `knowledge/references/bundle/`. It loads in **every** session — even a pure live one — so that a bundle attached mid-session via `kinetica_load_bundle` has its parsing knowledge ready in the (build-once) prompt; the corpus is cached, so the cost to a session that never attaches a bundle is negligible.
 
 > **Heads up — prompt budget:** all playbooks and references are front-loaded into a single system prompt at startup, so its token cost grows with the knowledge corpus. A startup tripwire (`agent/prompt-budget.ts`) prints the assembled prompt size under `DEBUG` and warns on stderr once it exceeds ~20,000 estimated tokens. Current baseline is ~13.4k tokens (6 playbooks + 9 references). If you add substantial knowledge and trip that warning, treat it as the cue to switch from "load everything" to keyword-based playbook selection.
 

package/dist/admin-agent.js

@@ -3875,248 +3875,8 @@ var import_claude_agent_sdk4 = require("@anthropic-ai/claude-agent-sdk");
 // src/tools/bundle/list-files.ts
 var import_zod18 = require("zod");
 
-// src/bundle/known-files.ts
-var KNOWN_BUNDLE_FILES = {
-  // Host resources
-  "cpu.txt": "CPU topology, NUMA, and interrupts (lscpu, numactl, /proc/cpuinfo, /proc/interrupts)",
-  "mem.txt": "Memory usage, /proc/meminfo, and transparent-hugepage setting (free -m -t)",
-  "disk.txt": "Filesystems, mounts, block devices, and disk stats (df, mount, lsblk, fdisk, /etc/fstab, /proc/diskstats)",
-  "gpu.txt": "NVIDIA GPU inventory and state (nvidia-smi -L/-q, modinfo nvidia)",
-  "net.txt": "Network interfaces, sockets, and DNS (hostname, ifconfig, netstat, /etc/resolv.conf)",
-  // Processes
-  "ps.txt": "Full process list (ps -auxww, ps -ejHlfww)",
-  "gpudb-exe.txt": "Running gpudb processes (ps auxfwww | grep gpudb)",
-  // Hardware / firmware
-  "dmidecode.txt": "BIOS / DMI hardware inventory (dmidecode)",
-  "lshw.txt": "Hardware listing (lshw -short -numeric)",
-  "pci.txt": "PCI devices and I/O resources (lspci, /proc/ioports, /proc/iomem)",
-  // Kernel / OS
-  "dmesg.txt": "Kernel ring buffer \u2014 boot and runtime kernel messages (dmesg -T)",
-  "dmesg-timestamp.txt": "Kernel ring buffer with human-readable timestamps",
-  "sysctl.txt": "Kernel tunables (sysctl -a)",
-  "sys.txt": "OS identity, uptime, ulimits, kernel cmdline, clocksource, and loaded modules (uname, ulimit, /proc/cmdline, lsmod)",
-  "lsof.txt": "Open files and network sockets (lsof -n -P)",
-  "lslocks.txt": "Held file locks (lslocks)",
-  // Packages / linker / accounts
-  "deb.txt": "Installed Debian packages and verification (dpkg -l, dpkg -V)",
-  "rpm.txt": "Installed RPM packages (rpm -qa)",
-  "ld.so.conf.txt": "Dynamic-linker library search paths (/etc/ld.so.conf)",
-  "user.txt": "Users, groups, and the gpudb service account (whoami, id, /etc/passwd, /etc/group)",
-  "sudoers.txt": "Sudo configuration (/etc/sudoers)",
-  "etc_profile.txt": "Login shell profile (/etc/profile)",
-  "etc_bashrc.txt": "System bashrc (/etc/bashrc)",
-  "etc_host.txt": "Static hostname resolution (/etc/hosts)",
-  // Kinetica-specific
-  "gpudb.txt": "GPUdb version/build, binary md5 + ldd, and the captured gpudb.conf / gpudb_logger.conf ($GPUDB_EXE -v)",
-  "gpudb_core_etc_gpudb.conf": "The live gpudb.conf at capture time (the database's main config)",
-  "gpudb_core_etc_gpudb_logger.conf": "The logging configuration (gpudb_logger.conf)",
-  "loki-info.txt": "Loki log-index stats: labels, series, and per-class volume (logcli)",
-  "sql-queries.txt": "SQL query log extracted from Loki (logcli)",
-  "tables.txt": "Table schemas and column types (gadmin --schema), when collected",
-  "logfiles.txt": "Manifest: the log directories/files the collector enumerated",
-  "errors.txt": "Collection commands that FAILED during capture (Evidence Gaps)",
-  "proc-logs-erros.txt": "Per-process log-collection failures during capture (Evidence Gaps)"
-};
-var KIND_DESCRIPTIONS = {
-  "core-log": "Per-rank rolling Kinetica core log (the primary incident narrative)",
-  "component-log": "Component service log (sql-engine, httpd, reveal, tomcat, stats, \u2026)",
-  "loki-tail": "Last-2h Loki tail for a service (small; searched only when no core logs exist)",
-  "process-info": "Per-rank process snapshot: command line, PID, and environment (/proc/<pid>/environ)",
-  config: "Kinetica configuration file",
-  "version-info": "GPUdb version/build information",
-  "collection-errors": "Collection commands that FAILED during capture (Evidence Gaps)",
-  manifest: "Manifest of log directories/files the collector enumerated"
-};
-function basename(relPath) {
-  const parts = relPath.split("/");
-  return parts[parts.length - 1] ?? relPath;
-}
-function describeBundleFile(entry) {
-  return KNOWN_BUNDLE_FILES[basename(entry.relPath)] ?? KIND_DESCRIPTIONS[entry.kind] ?? "";
-}
-
-// src/tools/bundle/list-files.ts
-var BundleListFilesSchema = import_zod18.z.object({
-  kind: import_zod18.z.string().optional()
-});
-async function bundleListFiles(source, args = {}) {
-  const all = source.listFiles();
-  const filtered = args.kind ? all.filter((e) => e.kind === args.kind) : all;
-  const { totalFiles, totalBytes, byKind, ranks, services } = source.inventory();
-  const version = await source.detectVersion();
-  const errors = await source.collectionErrors();
-  const files = filtered.map((e) => ({
-    file: e.relPath,
-    kind: e.kind,
-    rank: e.rank ?? "",
-    size_kb: Math.round(e.sizeBytes / 1024),
-    // What the file contains — so the agent can pick the right one without reading it.
-    description: describeBundleFile(e)
-  }));
-  return {
-    ok: true,
-    data: {
-      detected_version: version ?? "unknown",
-      ranks_present: ranks.join(", ") || "none",
-      services_present: services.join(", ") || "none",
-      total_files: totalFiles,
-      total_size_mb: Number((totalBytes / 1e6).toFixed(1)),
-      counts_by_kind: byKind,
-      failed_collections: errors.length,
-      files
-    }
-  };
-}
-
-// src/tools/bundle/log-timeline.ts
-var import_zod19 = require("zod");
-var BundleLogTimelineSchema = import_zod19.z.object({
-  min_severity: import_zod19.z.enum(["INFO", "WARN", "UERR", "ERROR", "FATAL"]).optional(),
-  granularity: import_zod19.z.enum(["day", "hour", "minute"]).optional(),
-  rank: import_zod19.z.string().describe('Numeric rank only, e.g. "r0"/"r1". For the host manager use host_manager.').optional(),
-  host_manager: import_zod19.z.boolean().describe("Bucket the host-manager (hm) log \u2014 a singleton service, not a rank.").optional(),
-  component: import_zod19.z.string().optional(),
-  include_components: import_zod19.z.boolean().optional()
-});
-async function bundleLogTimeline(source, args = {}) {
-  const query3 = {
-    ...args.min_severity !== void 0 ? { minSeverity: args.min_severity } : {},
-    ...args.granularity !== void 0 ? { granularity: args.granularity } : {},
-    ...args.rank !== void 0 ? { rank: args.rank } : {},
-    ...args.host_manager !== void 0 ? { hostManager: args.host_manager } : {},
-    ...args.component !== void 0 ? { component: args.component } : {},
-    ...args.include_components !== void 0 ? { includeComponents: args.include_components } : {}
-  };
-  const result = await source.logTimeline(query3);
-  const severities = [...new Set(result.buckets.flatMap((b) => Object.keys(b.counts)))];
-  const order = ["FATAL", "ERROR", "UERR", "WARN", "INFO"];
-  severities.sort((a, b) => order.indexOf(a) - order.indexOf(b));
-  const rows = result.buckets.map((b) => {
-    const row = { time_bucket: b.bucket };
-    for (const sev of severities) row[sev] = b.counts[sev] ?? 0;
-    row.total = b.total;
-    return row;
-  });
-  return {
-    ok: true,
-    note: result.totalCounted === 0 ? "No lines at or above the severity threshold \u2014 try a lower min_severity." : `${result.totalCounted} event(s) across ${result.buckets.length} bucket(s), ${result.filesScanned.length} file(s).`,
-    data: {
-      lines_scanned: result.linesScanned,
-      files_scanned: result.filesScanned.join(", ") || "none",
-      buckets: rows
-    }
-  };
-}
-
-// src/tools/bundle/search-logs.ts
-var import_zod20 = require("zod");
-var BundleSearchLogsSchema = import_zod20.z.object({
-  regex: import_zod20.z.string().optional(),
-  min_severity: import_zod20.z.enum(["INFO", "WARN", "UERR", "ERROR", "FATAL"]).optional(),
-  from_ts: import_zod20.z.string().optional(),
-  to_ts: import_zod20.z.string().optional(),
-  rank: import_zod20.z.string().describe('Numeric rank only, e.g. "r0"/"r1". For the host manager use host_manager.').optional(),
-  host_manager: import_zod20.z.boolean().describe("Search the host-manager (hm) log \u2014 a singleton service, not a rank.").optional(),
-  component: import_zod20.z.string().optional(),
-  include_components: import_zod20.z.boolean().optional(),
-  max_matches: import_zod20.z.number().int().min(1).max(1e3).optional()
-});
-async function bundleSearchLogs(source, args = {}) {
-  const query3 = {
-    ...args.regex !== void 0 ? { regex: args.regex } : {},
-    ...args.min_severity !== void 0 ? { minSeverity: args.min_severity } : {},
-    ...args.from_ts !== void 0 ? { fromTs: args.from_ts } : {},
-    ...args.to_ts !== void 0 ? { toTs: args.to_ts } : {},
-    ...args.rank !== void 0 ? { rank: args.rank } : {},
-    ...args.host_manager !== void 0 ? { hostManager: args.host_manager } : {},
-    ...args.component !== void 0 ? { component: args.component } : {},
-    ...args.include_components !== void 0 ? { includeComponents: args.include_components } : {},
-    ...args.max_matches !== void 0 ? { maxMatches: args.max_matches } : {}
-  };
-  const result = await source.searchLogs(query3);
-  const note = result.capped ? `Showing ${result.matches.length} of ${result.totalMatched} matches across ${result.filesScanned.length} file(s) (display capped). Narrow with a tighter regex, severity, or time window to surface the specific lines.` : `${result.totalMatched} match(es) across ${result.filesScanned.length} file(s).`;
-  return {
-    ok: true,
-    note,
-    data: {
-      total_matched: result.totalMatched,
-      lines_scanned: result.linesScanned,
-      files_scanned: result.filesScanned.join(", ") || "none",
-      capped: result.capped,
-      matches: result.matches.map((m) => ({
-        file: m.file,
-        line: m.lineNumber,
-        timestamp: m.timestamp ?? "",
-        severity: m.severity ?? "",
-        rank: m.rank ?? "",
-        message: m.message
-      }))
-    }
-  };
-}
-
-// src/tools/bundle/read-config.ts
-var import_zod21 = require("zod");
-var BundleReadConfigSchema = import_zod21.z.object({
-  section: import_zod21.z.string().optional(),
-  key: import_zod21.z.string().optional()
-});
-async function bundleReadConfig(source, args = {}) {
-  const result = await source.readConfig({
-    ...args.section !== void 0 ? { section: args.section } : {},
-    ...args.key !== void 0 ? { key: args.key } : {}
-  });
-  if ("error" in result) {
-    return { ok: false, status: 0, error: result.error, raw: "" };
-  }
-  if (result.entries.length === 0 && args.section !== void 0) {
-    const all = await source.readConfig(args.key !== void 0 ? { key: args.key } : {});
-    const sections = "error" in all ? [] : [...new Set(all.entries.map((e) => e.section))].sort();
-    const sectionList = sections.map((s) => s === "" ? "(flat/top-level)" : s).join(", ");
-    return {
-      ok: true,
-      note: `No entries in section "${args.section}" of ${result.file}. gpudb.conf is largely flat \u2014 retry filtering by key only. Sections present: ${sectionList || "(none)"}.`,
-      data: { section_not_found: args.section, available_sections: sections }
-    };
-  }
-  return {
-    ok: true,
-    note: `${result.entries.length} entr(y/ies) from ${result.file}.`,
-    data: result.entries.map((e) => ({ section: e.section, key: e.key, value: e.value }))
-  };
-}
-
-// src/tools/bundle/read-sysinfo.ts
-var import_zod22 = require("zod");
-var BundleReadSysinfoSchema = import_zod22.z.object({
-  name: import_zod22.z.string().min(1)
-});
-async function bundleReadSysinfo(source, args) {
-  const result = await source.readSysinfo(args.name);
-  if ("error" in result) {
-    return { ok: false, status: 0, error: result.error, raw: "" };
-  }
-  return {
-    ok: true,
-    data: {
-      ...result.header !== void 0 ? { source_file: result.header } : {},
-      blocks: result.blocks.map((b) => ({
-        command: b.command,
-        ...b.exitCode !== void 0 ? { exit_code: b.exitCode } : {},
-        output: b.output
-      }))
-    }
-  };
-}
-
-// src/tools/bundle/load-bundle.ts
-var import_zod23 = require("zod");
-
-// src/bundle/verify-bundle.ts
-var import_promises6 = require("fs/promises");
-
 // src/bundle/BundleSource.ts
-var import_promises5 = require("fs/promises");
+var import_promises6 = require("fs/promises");
 var import_node_path6 = require("path");
 
 // src/bundle/sysinfo-block.ts
@@ -4409,20 +4169,26 @@ async function aggregateTimeline(filePath, query3 = {}) {
 }
 
 // src/bundle/bundle-index.ts
-var import_promises4 = require("fs/promises");
+var import_promises5 = require("fs/promises");
 var import_node_path5 = require("path");
 
 // src/bundle/classify-file.ts
-var ROLLING_ID_RE = /core-gpudb-rolling-(r\d+|hm)\.log(?:\.\d+)?$/;
+var ROLLING_ID_RE = /(?:core-)?gpudb-rolling-(r\d+|hm)\.log(?:\.\d+)?$/;
 var EXE_ID_RE = /gpudb-exe-(r\d+|hm)-/;
 var HOST_RE = /\b(node\w+)\b/;
+var CONF_RE = /\.conf$/i;
+var CONF_ALT_RE = /\.(cfg|ini)$/i;
 var LOG_RE = /\.log(?:\.\d+)?$/;
+var LOGISH_RE = /\.(?:log|out|err)(?:\.\d+)?$/i;
 var LOKI_RANK_RE = /^rank(\d+)\.log$/;
 var LOKI_HM_BASE = "hostmanager.log";
+var HM_TOKEN_RE = /host-?manager/i;
+var RANK_TOKEN_RE = /(?:\brank[-_]?|\br)(\d{1,2})\b/i;
+var LOG_DIR_RE = /(?:^|\/)(?:logs|logs-local|log)(?:\/|$)/;
 function rankOrService(id) {
   return id === "hm" ? { service: "host-manager" } : { rank: id };
 }
-function basename2(relPath) {
+function basename(relPath) {
   const parts = relPath.split("/");
   return parts[parts.length - 1] ?? relPath;
 }
@@ -4434,70 +4200,247 @@ function inferHost(relPath) {
   return HOST_RE.exec(relPath)?.[1] ?? void 0;
 }
 function componentName(base) {
-  return base.replace(/\.\d+$/, "").replace(/(\.log)+$/, "").replace(/^core-gpudb-/, "").replace(/^gpudb-/, "").replace(/-node\w+$/, "");
+  return base.replace(/\.\d+$/, "").replace(/(?:\.(?:log|out|err))+$/i, "").replace(/^core-gpudb-/, "").replace(/^gpudb-/, "").replace(/-node\w+$/, "");
 }
+function cls(kind, confidence, reason, parts = {}) {
+  return {
+    kind,
+    confidence,
+    reason,
+    ...parts.rank !== void 0 ? { rank: parts.rank } : {},
+    ...parts.inferredRank !== void 0 ? { inferredRank: parts.inferredRank } : {},
+    ...parts.service !== void 0 ? { service: parts.service } : {},
+    ...parts.component !== void 0 ? { component: parts.component } : {},
+    ...parts.host !== void 0 ? { host: parts.host } : {}
+  };
+}
+var MATCHERS = [
+  // ── Tier A: canonical filenames / locations (exact) ──────────────────────────
+  (c) => CONF_RE.test(c.base) ? cls("config", "exact", "config (.conf)", { host: c.host }) : null,
+  (c) => CONF_ALT_RE.test(c.base) ? cls("config", "inferred", "config-like extension (.cfg/.ini)", { host: c.host }) : null,
+  (c) => c.base === "logfiles.txt" ? cls("manifest", "exact", "collector manifest", { host: c.host }) : null,
+  (c) => c.base === "errors.txt" || c.base.endsWith("erros.txt") ? cls("collection-errors", "exact", "collection-errors summary", { host: c.host }) : null,
+  (c) => c.base === "gpudb.txt" ? cls("version-info", "exact", "gpudb.txt", { host: c.host }) : null,
+  (c) => {
+    const m = EXE_ID_RE.exec(c.base);
+    return m ? cls("process-info", "exact", "gpudb-exe process capture", {
+      ...rankOrService(m[1]),
+      host: c.host
+    }) : null;
+  },
+  (c) => {
+    const m = ROLLING_ID_RE.exec(c.base);
+    if (!m) return null;
+    const reason = c.base.startsWith("core-") ? "core rolling-log pattern" : "rolling-log pattern (no core- prefix)";
+    return cls("core-log", "exact", reason, { ...rankOrService(m[1]), host: c.host });
+  },
+  (c) => {
+    if (c.dir !== "logs" || !LOG_RE.test(c.base)) return null;
+    const lr = LOKI_RANK_RE.exec(c.base);
+    const lokiId = lr ? `r${lr[1]}` : c.base === LOKI_HM_BASE ? "hm" : void 0;
+    return lokiId !== void 0 ? cls("loki-tail", "exact", "Loki per-rank/host-manager export under logs/", {
+      ...rankOrService(lokiId),
+      host: c.host
+    }) : cls("loki-tail", "exact", "Loki component tail under logs/", {
+      component: componentName(c.base),
+      host: c.host
+    });
+  },
+  (c) => c.dir === "logs-local" && LOG_RE.test(c.base) ? cls("component-log", "exact", "component log under logs-local/", {
+    component: componentName(c.base),
+    host: c.host
+  }) : null,
+  // ── Tier B: off-shape name/extension heuristics (inferred) ───────────────────
+  // Host-manager service logs in a flat layout: the rolling-hm log is already caught
+  // above; this catches the service log and the process stdout (.out). This MUST come
+  // before the generic gpudb-prefixed matcher below — both would classify a
+  // `gpudb-host-manager-*.log` as a component-log, but only this one adds the
+  // `service: "host-manager"` tag. Kept separate (not folded into the gpudb matcher) so
+  // a host-manager log WITHOUT a gpudb prefix (e.g. a renamed `hostmanager-*.out`) still
+  // gets the service tag rather than falling through to a plain component-log.
+  (c) => HM_TOKEN_RE.test(c.base) && LOGISH_RE.test(c.base) ? cls("component-log", "inferred", "host-manager service log (name match)", {
+    service: "host-manager",
+    component: componentName(c.base),
+    host: c.host
+  }) : null,
+  // Any other gpudb-prefixed log-ish file in a non-canonical location.
+  (c) => (c.base.startsWith("gpudb") || c.base.startsWith("core-gpudb")) && LOGISH_RE.test(c.base) ? cls("component-log", "inferred", "gpudb log (name match, non-canonical location)", {
+    component: componentName(c.base),
+    host: c.host
+  }) : null,
+  // A log-ish file sitting in a log-named directory, or carrying a rank token.
+  (c) => {
+    if (!LOGISH_RE.test(c.base)) return null;
+    const inLogDir = LOG_DIR_RE.test(c.relPath);
+    const rm = RANK_TOKEN_RE.exec(c.base);
+    if (!inLogDir && !rm) return null;
+    const rank = rm ? `r${rm[1]}` : void 0;
+    const reason = rank ? "log-like file with a rank token" : "log-like file in a log directory";
+    return cls(c.dir === "logs" ? "loki-tail" : "component-log", "inferred", reason, {
+      ...rank !== void 0 ? { rank, inferredRank: true } : { component: componentName(c.base) },
+      host: c.host
+    });
+  },
+  // ── Tier C: extension-only fallbacks (weak) ──────────────────────────────────
+  (c) => c.base.endsWith(".txt") ? cls("os-diag", "weak", "fallback: .txt extension", { host: c.host }) : null,
+  (c) => LOGISH_RE.test(c.base) ? cls("component-log", "weak", "fallback: log-like extension", {
+    component: componentName(c.base),
+    host: c.host
+  }) : null
+];
 function classifyFile(relPath) {
-  const base = basename2(relPath);
+  const base = basename(relPath);
   const dir = dirOf(relPath);
   const host = inferHost(relPath);
-  if (base.endsWith(".conf")) {
-    return { kind: "config", ...host ? { host } : {} };
+  const ctx = { relPath, base, dir, ...host !== void 0 ? { host } : {} };
+  for (const matcher of MATCHERS) {
+    const result = matcher(ctx);
+    if (result) return result;
+  }
+  return cls("unknown", "weak", "unrecognized file", { host });
+}
+
+// src/bundle/sniff-file.ts
+var import_promises4 = require("fs/promises");
+var SNIFF_HEAD_BYTES = 8192;
+var SNIFF_MAX_LINES = 20;
+async function readHead(absPath, headBytes) {
+  let fh;
+  try {
+    fh = await (0, import_promises4.open)(absPath, "r");
+    const buf = Buffer.alloc(headBytes);
+    const { bytesRead } = await fh.read(buf, 0, headBytes, 0);
+    return buf.subarray(0, bytesRead).toString("utf-8");
+  } catch {
+    return "";
+  } finally {
+    await fh?.close().catch(() => void 0);
+  }
+}
+function refineSysinfoKind(command) {
+  const cmd = command.toLowerCase();
+  if (/-v\b|--version|\bgpudb_logger\b/.test(cmd) && cmd.includes("gpudb")) {
+    return { kind: "version-info", detail: "version command" };
+  }
+  if (/\bps\b|\/proc\/|environ|grep .*gpudb/.test(cmd)) {
+    return { kind: "process-info", detail: "process snapshot command" };
   }
-  if (base === "logfiles.txt") {
-    return { kind: "manifest", ...host ? { host } : {} };
+  return { kind: "os-diag", detail: "host-diagnostic command" };
+}
+function logLineResult(rank, severity, isHm) {
+  if (rank !== void 0) {
+    return { kind: "core-log", reason: `log line parsed (${severity}, rank ${rank})`, rank };
   }
-  if (base === "errors.txt" || base.endsWith("erros.txt")) {
-    return { kind: "collection-errors", ...host ? { host } : {} };
+  if (isHm) {
+    return {
+      kind: "component-log",
+      reason: `log line parsed (${severity}, host-manager)`,
+      service: "host-manager"
+    };
   }
-  if (base === "gpudb.txt") {
-    return { kind: "version-info", ...host ? { host } : {} };
+  return { kind: "component-log", reason: `log line parsed (${severity})` };
+}
+async function sniffFile(absPath, opts = {}) {
+  const headBytes = opts.headBytes ?? SNIFF_HEAD_BYTES;
+  const maxLines = opts.maxLines ?? SNIFF_MAX_LINES;
+  const text2 = await readHead(absPath, headBytes);
+  if (text2 === "") return void 0;
+  const lines = [];
+  for (const raw of text2.split("\n")) {
+    const trimmed = raw.trim();
+    if (trimmed === "") continue;
+    lines.push(raw);
+    if (lines.length >= maxLines) break;
+  }
+  if (lines.length === 0) return void 0;
+  for (const line of lines) {
+    const m = EXEC_CMD_RE.exec(line.trim());
+    if (m) {
+      const { kind, detail } = refineSysinfoKind(m[1]);
+      return { kind, reason: `EXEC_CMD header (${detail})` };
+    }
   }
-  const exeId = EXE_ID_RE.exec(base);
-  if (exeId) {
-    return { kind: "process-info", ...rankOrService(exeId[1]), ...host ? { host } : {} };
+  const unwrapped = unwrapLokiJsonl(lines[0]);
+  if (unwrapped !== void 0) {
+    const p = parseLogLine(unwrapped);
+    const rank = p.rank;
+    return {
+      kind: "loki-tail",
+      reason: `Loki JSONL record${rank ? ` (rank ${rank})` : ""}`,
+      ...rank !== void 0 ? { rank } : {}
+    };
   }
-  if (LOG_RE.test(base)) {
-    const rolling = ROLLING_ID_RE.exec(base);
-    if (rolling) {
-      return { kind: "core-log", ...rankOrService(rolling[1]), ...host ? { host } : {} };
-    }
-    if (dir === "logs") {
-      const lokiRank = LOKI_RANK_RE.exec(base);
-      const lokiId = lokiRank ? `r${lokiRank[1]}` : base === LOKI_HM_BASE ? "hm" : void 0;
-      if (lokiId !== void 0) {
-        return { kind: "loki-tail", ...rankOrService(lokiId), ...host ? { host } : {} };
-      }
-      return { kind: "loki-tail", component: componentName(base), ...host ? { host } : {} };
+  for (const line of lines) {
+    const p = parseLogLine(line);
+    if (p.severity !== void 0 && severityRank(p.severity) >= 0) {
+      const isHm = p.context?.startsWith("hm/") ?? false;
+      return logLineResult(p.rank, p.severity, isHm);
     }
-    return { kind: "component-log", component: componentName(base), ...host ? { host } : {} };
   }
-  if (base.endsWith(".txt")) {
-    return { kind: "os-diag", ...host ? { host } : {} };
+  const hasSection = lines.some((l) => SECTION_RE.test(l.trim()));
+  if (hasSection && parseIni(text2).length >= 2) {
+    return { kind: "config", reason: "INI section + key/value entries" };
   }
-  return { kind: "unknown", ...host ? { host } : {} };
+  return void 0;
 }
 
 // src/bundle/bundle-index.ts
+async function refineWithContent(c, absPath) {
+  if (c.confidence !== "weak" || c.kind === "os-diag") return c;
+  const sniff = await sniffFile(absPath);
+  if (!sniff) return c;
+  const addsKind = sniff.kind !== c.kind;
+  const addsRank = sniff.rank !== void 0 && c.rank === void 0;
+  const addsService = sniff.service !== void 0 && c.service === void 0;
+  if (!addsKind && !addsRank && !addsService) return c;
+  return {
+    ...c,
+    kind: sniff.kind,
+    confidence: "inferred",
+    reason: `content: ${sniff.reason}`,
+    ...sniff.rank !== void 0 ? { rank: sniff.rank } : {},
+    ...sniff.service !== void 0 ? { service: sniff.service } : {}
+  };
+}
 async function buildIndex(rootDir) {
   let relPaths;
+  let realRoot;
   try {
-    relPaths = await (0, import_promises4.readdir)(rootDir, { recursive: true });
+    relPaths = await (0, import_promises5.readdir)(rootDir, { recursive: true });
+    realRoot = await (0, import_promises5.realpath)(rootDir);
   } catch {
     return [];
   }
+  const dirConfined = /* @__PURE__ */ new Map();
+  const isDirConfined = (dir) => {
+    let verdict = dirConfined.get(dir);
+    if (verdict === void 0) {
+      verdict = (0, import_promises5.realpath)(dir).then(
+        (realDir) => realDir === realRoot || realDir.startsWith(realRoot + import_node_path5.sep),
+        () => false
+        // an unresolvable directory (broken/cyclic symlink) → drop its entries
+      );
+      dirConfined.set(dir, verdict);
+    }
+    return verdict;
+  };
   const settled = await Promise.all(
     relPaths.map(async (rel) => {
       const relPath = rel.split("\\").join("/");
       const absPath = (0, import_node_path5.join)(rootDir, rel);
       try {
-        const s = await (0, import_promises4.lstat)(absPath);
+        const s = await (0, import_promises5.lstat)(absPath);
         if (s.isSymbolicLink() || !s.isFile()) return null;
-        const c = classifyFile(relPath);
+        if (!await isDirConfined((0, import_node_path5.dirname)(absPath))) return null;
+        const c = await refineWithContent(classifyFile(relPath), absPath);
         return {
           relPath,
           absPath,
           kind: c.kind,
+          confidence: c.confidence,
+          ...c.reason !== void 0 ? { reason: c.reason } : {},
           ...c.rank !== void 0 ? { rank: c.rank } : {},
+          ...c.inferredRank !== void 0 ? { inferredRank: c.inferredRank } : {},
           ...c.service !== void 0 ? { service: c.service } : {},
           ...c.host !== void 0 ? { host: c.host } : {},
           ...c.component !== void 0 ? { component: c.component } : {},
@@ -4513,6 +4456,25 @@ async function buildIndex(rootDir) {
 
 // src/bundle/BundleSource.ts
 var GPUDB_VERSION_RE = /GPUdb version\s*:\s*(\S+)/;
+var ANCHOR_KINDS = ["config", "version-info"];
+var MIN_ANCHORS_FOR_CANONICAL = 2;
+var PARTIAL_INFERRED_FRACTION = 0.25;
+function assessLayout(inventory) {
+  const anchorsPresent = ANCHOR_KINDS.filter((k) => (inventory.byKind[k] ?? 0) > 0).length;
+  const inferredFraction = inventory.totalFiles > 0 ? inventory.inferredFiles / inventory.totalFiles : 0;
+  let layout;
+  if (anchorsPresent === 0) layout = "unfamiliar";
+  else if (anchorsPresent >= MIN_ANCHORS_FOR_CANONICAL && inferredFraction < PARTIAL_INFERRED_FRACTION)
+    layout = "canonical";
+  else layout = "partial";
+  if (layout === "canonical") return { layout };
+  const bits = [`${inventory.inferredFiles}/${inventory.totalFiles} files classified by inference`];
+  if (inventory.unknownFiles > 0) bits.push(`${inventory.unknownFiles} unclassified`);
+  if (inventory.inferredRanks.length > 0)
+    bits.push(`inferred ranks ${inventory.inferredRanks.join(", ")} (unconfirmed)`);
+  const layoutWarning = layout === "unfamiliar" ? `This bundle does not match the canonical gpudb_sysinfo layout \u2014 no config/version/host-diagnostic files were found. Working from inference: ${bits.join("; ")}.` : `This bundle only partially matches the canonical layout: ${bits.join("; ")}.`;
+  return { layout, layoutWarning };
+}
 function selectLogFiles(index, opts) {
   if (opts.component !== void 0) {
     return index.filter(
@@ -4567,12 +4529,17 @@ async function createBundleSource(rootDir) {
   const inventoryValue = (() => {
     const byKind = {};
     const rankSet = /* @__PURE__ */ new Set();
+    const inferredRankSet = /* @__PURE__ */ new Set();
     const serviceSet = /* @__PURE__ */ new Set();
     let totalBytes = 0;
+    let inferredFiles = 0;
+    let unknownFiles = 0;
     for (const e of index) {
       byKind[e.kind] = (byKind[e.kind] ?? 0) + 1;
       totalBytes += e.sizeBytes;
-      if (e.rank) rankSet.add(e.rank);
+      if (e.confidence === "inferred") inferredFiles++;
+      if (e.kind === "unknown") unknownFiles++;
+      if (e.rank) (e.inferredRank ? inferredRankSet : rankSet).add(e.rank);
       if (e.service) serviceSet.add(e.service);
     }
     return {
@@ -4580,14 +4547,17 @@ async function createBundleSource(rootDir) {
       totalBytes,
       byKind,
       ranks: [...rankSet].sort(),
-      services: [...serviceSet].sort()
+      inferredRanks: [...inferredRankSet].filter((r) => !rankSet.has(r)).sort(),
+      services: [...serviceSet].sort(),
+      inferredFiles,
+      unknownFiles
     };
   })();
   const detectVersion = async () => {
     const versionFile = findByKind("version-info");
     if (versionFile) {
       try {
-        const parsed = parseSysinfo(await (0, import_promises5.readFile)(versionFile.absPath, "utf-8"));
+        const parsed = parseSysinfo(await (0, import_promises6.readFile)(versionFile.absPath, "utf-8"));
         for (const block of parsed.blocks) {
           const m = GPUDB_VERSION_RE.exec(block.output);
           if (m) return m[1];
@@ -4598,7 +4568,7 @@ async function createBundleSource(rootDir) {
     const configFile = findByKind("config");
     if (configFile) {
       try {
-        const entries = parseIni(await (0, import_promises5.readFile)(configFile.absPath, "utf-8"));
+        const entries = parseIni(await (0, import_promises6.readFile)(configFile.absPath, "utf-8"));
         return entries.find((e) => e.key === "file_version")?.value;
       } catch {
         return void 0;
@@ -4610,7 +4580,7 @@ async function createBundleSource(rootDir) {
     const configFile = index.find((e) => e.kind === "config" && e.relPath.endsWith("gpudb.conf")) ?? findByKind("config");
     if (!configFile) return { error: "no gpudb.conf found in bundle" };
     try {
-      const entries = parseIni(await (0, import_promises5.readFile)(configFile.absPath, "utf-8"));
+      const entries = parseIni(await (0, import_promises6.readFile)(configFile.absPath, "utf-8"));
       return { entries: filterIni(entries, opts), file: configFile.relPath };
     } catch (err) {
       return { error: err instanceof Error ? err.message : String(err) };
@@ -4624,7 +4594,7 @@ async function createBundleSource(rootDir) {
     const abs = resolve3(entry.relPath);
     if (!abs) return { error: `path "${name}" escapes the bundle root` };
     try {
-      return parseSysinfo(await (0, import_promises5.readFile)(abs, "utf-8"));
+      return parseSysinfo(await (0, import_promises6.readFile)(abs, "utf-8"));
     } catch (err) {
       return { error: err instanceof Error ? err.message : String(err) };
     }
@@ -4683,7 +4653,7 @@ async function createBundleSource(rootDir) {
     const lines = [];
     for (const file of files) {
       try {
-        const content = await (0, import_promises5.readFile)(file.absPath, "utf-8");
+        const content = await (0, import_promises6.readFile)(file.absPath, "utf-8");
         for (const line of content.split("\n")) {
           const trimmed = line.trim();
           if (trimmed !== "" && !/^-{3,}$/.test(trimmed)) lines.push(trimmed);
@@ -4707,13 +4677,277 @@ async function createBundleSource(rootDir) {
   };
 }
 
+// src/bundle/known-files.ts
+var KNOWN_BUNDLE_FILES = {
+  // Host resources
+  "cpu.txt": "CPU topology, NUMA, and interrupts (lscpu, numactl, /proc/cpuinfo, /proc/interrupts)",
+  "mem.txt": "Memory usage, /proc/meminfo, and transparent-hugepage setting (free -m -t)",
+  "disk.txt": "Filesystems, mounts, block devices, and disk stats (df, mount, lsblk, fdisk, /etc/fstab, /proc/diskstats)",
+  "gpu.txt": "NVIDIA GPU inventory and state (nvidia-smi -L/-q, modinfo nvidia)",
+  "net.txt": "Network interfaces, sockets, and DNS (hostname, ifconfig, netstat, /etc/resolv.conf)",
+  // Processes
+  "ps.txt": "Full process list (ps -auxww, ps -ejHlfww)",
+  "gpudb-exe.txt": "Running gpudb processes (ps auxfwww | grep gpudb)",
+  // Hardware / firmware
+  "dmidecode.txt": "BIOS / DMI hardware inventory (dmidecode)",
+  "lshw.txt": "Hardware listing (lshw -short -numeric)",
+  "pci.txt": "PCI devices and I/O resources (lspci, /proc/ioports, /proc/iomem)",
+  // Kernel / OS
+  "dmesg.txt": "Kernel ring buffer \u2014 boot and runtime kernel messages (dmesg -T)",
+  "dmesg-timestamp.txt": "Kernel ring buffer with human-readable timestamps",
+  "sysctl.txt": "Kernel tunables (sysctl -a)",
+  "sys.txt": "OS identity, uptime, ulimits, kernel cmdline, clocksource, and loaded modules (uname, ulimit, /proc/cmdline, lsmod)",
+  "lsof.txt": "Open files and network sockets (lsof -n -P)",
+  "lslocks.txt": "Held file locks (lslocks)",
+  // Packages / linker / accounts
+  "deb.txt": "Installed Debian packages and verification (dpkg -l, dpkg -V)",
+  "rpm.txt": "Installed RPM packages (rpm -qa)",
+  "ld.so.conf.txt": "Dynamic-linker library search paths (/etc/ld.so.conf)",
+  "user.txt": "Users, groups, and the gpudb service account (whoami, id, /etc/passwd, /etc/group)",
+  "sudoers.txt": "Sudo configuration (/etc/sudoers)",
+  "etc_profile.txt": "Login shell profile (/etc/profile)",
+  "etc_bashrc.txt": "System bashrc (/etc/bashrc)",
+  "etc_host.txt": "Static hostname resolution (/etc/hosts)",
+  // Kinetica-specific
+  "gpudb.txt": "GPUdb version/build, binary md5 + ldd, and the captured gpudb.conf / gpudb_logger.conf ($GPUDB_EXE -v)",
+  "gpudb_core_etc_gpudb.conf": "The live gpudb.conf at capture time (the database's main config)",
+  "gpudb_core_etc_gpudb_logger.conf": "The logging configuration (gpudb_logger.conf)",
+  "loki-info.txt": "Loki log-index stats: labels, series, and per-class volume (logcli)",
+  "sql-queries.txt": "SQL query log extracted from Loki (logcli)",
+  "tables.txt": "Table schemas and column types (gadmin --schema), when collected",
+  "logfiles.txt": "Manifest: the log directories/files the collector enumerated",
+  "errors.txt": "Collection commands that FAILED during capture (Evidence Gaps)",
+  "proc-logs-erros.txt": "Per-process log-collection failures during capture (Evidence Gaps)"
+};
+var KIND_DESCRIPTIONS = {
+  "core-log": "Per-rank rolling Kinetica core log (the primary incident narrative)",
+  "component-log": "Component service log (sql-engine, httpd, reveal, tomcat, stats, \u2026)",
+  "loki-tail": "Last-2h Loki tail for a service (small; searched only when no core logs exist)",
+  "process-info": "Per-rank process snapshot: command line, PID, and environment (/proc/<pid>/environ)",
+  config: "Kinetica configuration file",
+  "version-info": "GPUdb version/build information",
+  "collection-errors": "Collection commands that FAILED during capture (Evidence Gaps)",
+  manifest: "Manifest of log directories/files the collector enumerated"
+};
+function basename2(relPath) {
+  const parts = relPath.split("/");
+  return parts[parts.length - 1] ?? relPath;
+}
+function describeBundleFile(entry) {
+  return KNOWN_BUNDLE_FILES[basename2(entry.relPath)] ?? KIND_DESCRIPTIONS[entry.kind] ?? "";
+}
+
+// src/tools/bundle/list-files.ts
+var BundleListFilesSchema = import_zod18.z.object({
+  kind: import_zod18.z.string().optional()
+});
+var MAX_UNKNOWN_LISTED = 40;
+async function bundleListFiles(source, args = {}) {
+  const all = source.listFiles();
+  const filtered = args.kind ? all.filter((e) => e.kind === args.kind) : all;
+  const inventory = source.inventory();
+  const {
+    totalFiles,
+    totalBytes,
+    byKind,
+    ranks,
+    inferredRanks,
+    services,
+    inferredFiles,
+    unknownFiles
+  } = inventory;
+  const { layout, layoutWarning } = assessLayout(inventory);
+  const version = await source.detectVersion();
+  const errors = await source.collectionErrors();
+  const files = filtered.map((e) => ({
+    file: e.relPath,
+    kind: e.kind,
+    // How sure the classification is: exact (canonical name) | inferred (heuristic) | weak.
+    confidence: e.confidence,
+    ...e.reason !== void 0 ? { why: e.reason } : {},
+    rank: e.rank ?? "",
+    size_kb: Math.round(e.sizeBytes / 1024),
+    // What the file contains — so the agent can pick the right one without reading it.
+    description: describeBundleFile(e)
+  }));
+  const unknownPaths = all.filter((e) => e.kind === "unknown").map((e) => e.relPath);
+  return {
+    ok: true,
+    data: {
+      detected_version: version ?? "unknown",
+      // How well the bundle matches the canonical gpudb_sysinfo layout.
+      layout_match: layout,
+      ...layoutWarning !== void 0 ? { layout_note: layoutWarning } : {},
+      ranks_present: ranks.join(", ") || "none",
+      ...inferredRanks.length > 0 ? { inferred_ranks_unconfirmed: inferredRanks.join(", ") } : {},
+      services_present: services.join(", ") || "none",
+      total_files: totalFiles,
+      total_size_mb: Number((totalBytes / 1e6).toFixed(1)),
+      counts_by_kind: byKind,
+      inferred_files: inferredFiles,
+      unknown_files: unknownFiles,
+      ...unknownPaths.length > 0 ? {
+        unknown_file_paths: unknownPaths.slice(0, MAX_UNKNOWN_LISTED),
+        ...unknownPaths.length > MAX_UNKNOWN_LISTED ? { unknown_file_paths_truncated: unknownPaths.length - MAX_UNKNOWN_LISTED } : {}
+      } : {},
+      failed_collections: errors.length,
+      files
+    }
+  };
+}
+
+// src/tools/bundle/log-timeline.ts
+var import_zod19 = require("zod");
+var BundleLogTimelineSchema = import_zod19.z.object({
+  min_severity: import_zod19.z.enum(["INFO", "WARN", "UERR", "ERROR", "FATAL"]).optional(),
+  granularity: import_zod19.z.enum(["day", "hour", "minute"]).optional(),
+  rank: import_zod19.z.string().describe('Numeric rank only, e.g. "r0"/"r1". For the host manager use host_manager.').optional(),
+  host_manager: import_zod19.z.boolean().describe("Bucket the host-manager (hm) log \u2014 a singleton service, not a rank.").optional(),
+  component: import_zod19.z.string().optional(),
+  include_components: import_zod19.z.boolean().optional()
+});
+async function bundleLogTimeline(source, args = {}) {
+  const query3 = {
+    ...args.min_severity !== void 0 ? { minSeverity: args.min_severity } : {},
+    ...args.granularity !== void 0 ? { granularity: args.granularity } : {},
+    ...args.rank !== void 0 ? { rank: args.rank } : {},
+    ...args.host_manager !== void 0 ? { hostManager: args.host_manager } : {},
+    ...args.component !== void 0 ? { component: args.component } : {},
+    ...args.include_components !== void 0 ? { includeComponents: args.include_components } : {}
+  };
+  const result = await source.logTimeline(query3);
+  const severities = [...new Set(result.buckets.flatMap((b) => Object.keys(b.counts)))];
+  const order = ["FATAL", "ERROR", "UERR", "WARN", "INFO"];
+  severities.sort((a, b) => order.indexOf(a) - order.indexOf(b));
+  const rows = result.buckets.map((b) => {
+    const row = { time_bucket: b.bucket };
+    for (const sev of severities) row[sev] = b.counts[sev] ?? 0;
+    row.total = b.total;
+    return row;
+  });
+  return {
+    ok: true,
+    note: result.totalCounted === 0 ? "No lines at or above the severity threshold \u2014 try a lower min_severity." : `${result.totalCounted} event(s) across ${result.buckets.length} bucket(s), ${result.filesScanned.length} file(s).`,
+    data: {
+      lines_scanned: result.linesScanned,
+      files_scanned: result.filesScanned.join(", ") || "none",
+      buckets: rows
+    }
+  };
+}
+
+// src/tools/bundle/search-logs.ts
+var import_zod20 = require("zod");
+var BundleSearchLogsSchema = import_zod20.z.object({
+  regex: import_zod20.z.string().optional(),
+  min_severity: import_zod20.z.enum(["INFO", "WARN", "UERR", "ERROR", "FATAL"]).optional(),
+  from_ts: import_zod20.z.string().optional(),
+  to_ts: import_zod20.z.string().optional(),
+  rank: import_zod20.z.string().describe('Numeric rank only, e.g. "r0"/"r1". For the host manager use host_manager.').optional(),
+  host_manager: import_zod20.z.boolean().describe("Search the host-manager (hm) log \u2014 a singleton service, not a rank.").optional(),
+  component: import_zod20.z.string().optional(),
+  include_components: import_zod20.z.boolean().optional(),
+  max_matches: import_zod20.z.number().int().min(1).max(1e3).optional()
+});
+async function bundleSearchLogs(source, args = {}) {
+  const query3 = {
+    ...args.regex !== void 0 ? { regex: args.regex } : {},
+    ...args.min_severity !== void 0 ? { minSeverity: args.min_severity } : {},
+    ...args.from_ts !== void 0 ? { fromTs: args.from_ts } : {},
+    ...args.to_ts !== void 0 ? { toTs: args.to_ts } : {},
+    ...args.rank !== void 0 ? { rank: args.rank } : {},
+    ...args.host_manager !== void 0 ? { hostManager: args.host_manager } : {},
+    ...args.component !== void 0 ? { component: args.component } : {},
+    ...args.include_components !== void 0 ? { includeComponents: args.include_components } : {},
+    ...args.max_matches !== void 0 ? { maxMatches: args.max_matches } : {}
+  };
+  const result = await source.searchLogs(query3);
+  const note = result.capped ? `Showing ${result.matches.length} of ${result.totalMatched} matches across ${result.filesScanned.length} file(s) (display capped). Narrow with a tighter regex, severity, or time window to surface the specific lines.` : `${result.totalMatched} match(es) across ${result.filesScanned.length} file(s).`;
+  return {
+    ok: true,
+    note,
+    data: {
+      total_matched: result.totalMatched,
+      lines_scanned: result.linesScanned,
+      files_scanned: result.filesScanned.join(", ") || "none",
+      capped: result.capped,
+      matches: result.matches.map((m) => ({
+        file: m.file,
+        line: m.lineNumber,
+        timestamp: m.timestamp ?? "",
+        severity: m.severity ?? "",
+        rank: m.rank ?? "",
+        message: m.message
+      }))
+    }
+  };
+}
+
+// src/tools/bundle/read-config.ts
+var import_zod21 = require("zod");
+var BundleReadConfigSchema = import_zod21.z.object({
+  section: import_zod21.z.string().optional(),
+  key: import_zod21.z.string().optional()
+});
+async function bundleReadConfig(source, args = {}) {
+  const result = await source.readConfig({
+    ...args.section !== void 0 ? { section: args.section } : {},
+    ...args.key !== void 0 ? { key: args.key } : {}
+  });
+  if ("error" in result) {
+    return { ok: false, status: 0, error: result.error, raw: "" };
+  }
+  if (result.entries.length === 0 && args.section !== void 0) {
+    const all = await source.readConfig(args.key !== void 0 ? { key: args.key } : {});
+    const sections = "error" in all ? [] : [...new Set(all.entries.map((e) => e.section))].sort();
+    const sectionList = sections.map((s) => s === "" ? "(flat/top-level)" : s).join(", ");
+    return {
+      ok: true,
+      note: `No entries in section "${args.section}" of ${result.file}. gpudb.conf is largely flat \u2014 retry filtering by key only. Sections present: ${sectionList || "(none)"}.`,
+      data: { section_not_found: args.section, available_sections: sections }
+    };
+  }
+  return {
+    ok: true,
+    note: `${result.entries.length} entr(y/ies) from ${result.file}.`,
+    data: result.entries.map((e) => ({ section: e.section, key: e.key, value: e.value }))
+  };
+}
+
+// src/tools/bundle/read-sysinfo.ts
+var import_zod22 = require("zod");
+var BundleReadSysinfoSchema = import_zod22.z.object({
+  name: import_zod22.z.string().min(1)
+});
+async function bundleReadSysinfo(source, args) {
+  const result = await source.readSysinfo(args.name);
+  if ("error" in result) {
+    return { ok: false, status: 0, error: result.error, raw: "" };
+  }
+  return {
+    ok: true,
+    data: {
+      ...result.header !== void 0 ? { source_file: result.header } : {},
+      blocks: result.blocks.map((b) => ({
+        command: b.command,
+        ...b.exitCode !== void 0 ? { exit_code: b.exitCode } : {},
+        output: b.output
+      }))
+    }
+  };
+}
+
+// src/tools/bundle/load-bundle.ts
+var import_zod23 = require("zod");
+
 // src/bundle/verify-bundle.ts
+var import_promises7 = require("fs/promises");
 var ARCHIVE_RE = /\.(tgz|tar\.gz|tar|gz|zip)$/i;
 var EXPECTED_KINDS = ["config", "core-log"];
 async function verifyBundle(bundlePath) {
   let info;
   try {
-    info = await (0, import_promises6.stat)(bundlePath);
+    info = await (0, import_promises7.stat)(bundlePath);
   } catch {
     return { ok: false, error: `bundle path does not exist: ${bundlePath}` };
   }
@@ -4733,12 +4967,15 @@ async function verifyBundle(bundlePath) {
   }
   const missingExpected = EXPECTED_KINDS.filter((k) => (inventory.byKind[k] ?? 0) === 0);
   const kineticaVersion = await bundleSource.detectVersion();
+  const { layout, layoutWarning } = assessLayout(inventory);
   return {
     ok: true,
     bundleSource,
     ...kineticaVersion !== void 0 ? { kineticaVersion } : {},
     inventory,
-    missingExpected
+    missingExpected,
+    layout,
+    ...layoutWarning !== void 0 ? { layoutWarning } : {}
   };
 }
 
@@ -4957,7 +5194,7 @@ Before gathering evidence, announce a brief 2-3 line plan: restate the issue, li
 
 ### Round 1 \u2014 Orient
 
-- ${t}kinetica_bundle_list_files${t} \u2014 **ALWAYS FIRST.** Learn the detected version, which ranks are present, what file kinds exist, and how many collections failed.
+- ${t}kinetica_bundle_list_files${t} \u2014 **ALWAYS FIRST.** Learn the detected version, which ranks are present, what file kinds exist, and how many collections failed. Check ${t}layout_match${t}: if it is not ${t}canonical${t}, this bundle is off-shape (e.g. a logs-only dump) \u2014 read the ${t}layout_note${t}, treat any ${t}unknown_file_paths${t} as evidence to inspect by hand (open one with ${t}kinetica_bundle_read_sysinfo${t}), and trust ${t}ranks_present${t} over ${t}inferred_ranks_unconfirmed${t}. See the support-bundle reference ("When the bundle doesn't match the expected layout").
 - ${t}kinetica_bundle_log_timeline${t} (min_severity: WARN) \u2014 get the incident shape: when did WARN/ERROR/FATAL spike, and on which rank?
 
 ### Round 2 \u2014 Drill Down
@@ -5077,7 +5314,7 @@ function createBundleHolder(initial) {
 }
 
 // src/cli/pick-bundle-path.ts
-var import_promises7 = require("fs/promises");
+var import_promises8 = require("fs/promises");
 var import_node_path7 = require("path");
 function isPermissionError(err) {
   if (typeof err !== "object" || err === null || !("code" in err)) return false;
@@ -5092,7 +5329,7 @@ async function listDirectoryCandidates(term) {
   const resolved = (0, import_node_path7.resolve)(baseDir);
   let entries;
   try {
-    entries = await (0, import_promises7.readdir)(resolved, { withFileTypes: true });
+    entries = await (0, import_promises8.readdir)(resolved, { withFileTypes: true });
   } catch (err) {
     if (isPermissionError(err)) return { kind: "denied", dir: resolved };
     return { kind: "ok", candidates: [] };
@@ -6087,7 +6324,7 @@ async function logout() {
 
 // src/session/env-file.ts
 var import_fs2 = require("fs");
-var import_promises8 = require("fs/promises");
+var import_promises9 = require("fs/promises");
 var import_path2 = require("path");
 var import_picocolors11 = __toESM(require("picocolors"));
 function parseEnvContent(content) {
@@ -6179,11 +6416,11 @@ async function offerSaveCredentials(url, user, dir) {
     const filePath = (0, import_path2.join)(dir ?? process.cwd(), ".env");
     let existing;
     try {
-      existing = await (0, import_promises8.readFile)(filePath, "utf8");
+      existing = await (0, import_promises9.readFile)(filePath, "utf8");
     } catch {
     }
     const content = buildEnvContent(url, user, existing);
-    await (0, import_promises8.writeFile)(filePath, content, "utf8");
+    await (0, import_promises9.writeFile)(filePath, content, "utf8");
     console.error(import_picocolors11.default.dim("Saved to .env"));
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -6624,7 +6861,12 @@ async function main() {
       process.exitCode = 1;
       return;
     }
-    if (result.missingExpected.length > 0) {
+    if (result.layoutWarning !== void 0) {
+      process.stderr.write(
+        import_picocolors15.default.yellow(`Warning: ${result.layoutWarning} Diagnosing with what is present.
+`)
+      );
+    } else if (result.missingExpected.length > 0) {
       process.stderr.write(
         import_picocolors15.default.yellow(
           `Warning: bundle is missing expected artifact(s): ${result.missingExpected.join(", ")}. Diagnosing with what is present.

package/knowledge/references/bundle/support-bundle.md

@@ -49,6 +49,17 @@ See `rank-architecture.md` (Where queries are logged) for why this locality hold
 - **Packages / accounts:** `deb.txt` / `rpm.txt` (installed packages), `user.txt` (users/groups, gpudb account), `ld.so.conf.txt`, `etc_*.txt` (system shell/host config).
 - **Evidence Gaps:** `errors.txt` / `proc-logs-erros.txt` — collection commands that FAILED. `logfiles.txt` — manifest of log dirs the collector enumerated.
 
+### When the bundle doesn't match the expected layout
+
+Not every bundle is a full `gpudb_sysinfo` capture. A customer may hand over a bare logs-only dump, a differently-named collector's output, or a flat directory. `kinetica_bundle_list_files` tells you how well it matched, so you never reason blindly over an unfamiliar shape:
+
+- **`layout_match`** — `canonical` (a normal gpudb_sysinfo bundle), `partial`, or `unfamiliar` (none of the expected config/version/host-diagnostic anchors were found, e.g. a logs-only dump). When it is not `canonical`, a `layout_note` summarizes what was inferred.
+- **Per-file `confidence`** — `exact` (matched a canonical name/location), `inferred` (recognized by a name or content heuristic — e.g. a rolling log shipped WITHOUT the `core-` prefix, or a `.out` whose first lines parsed as log lines), or `weak`. The `why` field states how each file was classified.
+- **`inferred_ranks_unconfirmed`** — ranks seen only via a loose name guess, never confirmed by a canonical pattern or by log content. Treat these as "possible — verify," distinct from `ranks_present`, which stays trustworthy.
+- **`unknown_file_paths`** — files that could not be classified at all. Do NOT ignore them: they may be evidence under an unfamiliar name. Read one with `kinetica_bundle_read_sysinfo` (it returns the raw content / EXEC_CMD blocks) to decide what it holds.
+
+Inference does not make a file second-class: a rolling log recognized without its `core-` prefix is treated exactly like a canonical core log — it appears in `ranks_present` and `kinetica_bundle_search_logs`/`log_timeline` search it normally. The parsers have already been applied for you. Your job: trust `ranks_present` / `services_present`, sanity-check anything marked `inferred` or `unknown`, and state plainly in the report when the evidence came from an off-shape bundle (note the `layout_match`).
+
 ### Two log families — and why every rank is reachable
 
 A bundle carries per-rank logs in up to two places, and the collector host usually holds only a couple of the cluster's ranks:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinetica/admin-agent",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Autonomous diagnostic agent for Kinetica databases",
   "license": "Apache-2.0",
   "author": "Kinetica",