trajectories 0.0.0 → 0.1.2

package/legacy/scripts/observe-daemon.ts

@@ -0,0 +1,570 @@
+#!/usr/bin/env bun
+// Read-only observer: never import Trajectories' DB class (it migrates and can load models).
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, writeFileSync, writeSync } from "node:fs";
+import { createConnection } from "node:net";
+import { arch, cpus, platform, release, totalmem } from "node:os";
+import { join, resolve } from "node:path";
+
+const HELP = `Usage: bun legacy/scripts/observe-daemon.ts --pid PID --db PATH --out NEW_DIRECTORY
+  --seconds 180          Observation window; never starts or stops the target
+  --interval-ms 1000     Process cadence (minimum 100; 500 also supported)
+  --db-interval-ms 5000  Read-only aggregate cadence, plus baseline/end
+  --timeout-ms 2000      Deadline for each ps/SQLite subprocess
+  --marker STRING       Optional FTS5 literal-phrase counts; never saved as text
+  --ssh HOST:PORT       Probe a loopback SSH banner; banner text is never retained
+  --expect-exit true    Treat observed target teardown as successful completion
+Output: samples.jsonl and summary.json, directory 0700/files 0600.
+Exit: 0 window completed, 2 incomplete/tree exited/collection error, 130 interrupted.
+RSS sums may double-count shared pages; sampled peaks/CPU deltas are lower bounds.
+No raw argv, environment, transcript, title, source path, or warning log capture.
+`;
+
+export function parseOptions(args: string[]) {
+  const allowed = new Set(["pid", "db", "out", "seconds", "interval-ms", "db-interval-ms", "timeout-ms", "marker", "ssh", "expect-exit"]);
+  const flags = new Map<string, string>();
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i]?.replace(/^--/, "");
+    const value = args[i + 1];
+    if (!args[i]?.startsWith("--") || !allowed.has(key) || flags.has(key) || !value || value.startsWith("--")) {
+      throw new Error("invalid_or_duplicate_option");
+    }
+    flags.set(key, value);
+  }
+  function number(key: string, fallback: number, min: number, max: number) {
+    const value = Number(flags.get(key) ?? fallback);
+    if (!Number.isFinite(value) || value < min || value > max) throw new Error(`invalid_${key}`);
+    return value;
+  }
+  if (!flags.has("pid") || !flags.has("db") || !flags.has("out")) throw new Error("pid_db_out_required");
+  const pid = number("pid", 0, 2, 2147483647);
+  if (!Number.isInteger(pid) || pid === process.pid) throw new Error("invalid_pid");
+  const intervalMs = number("interval-ms", 1000, 100, 60000);
+  const marker = flags.get("marker");
+  if (marker !== undefined && (!marker.trim() || marker.length > 1024)) throw new Error("invalid_marker");
+  const ssh = flags.get("ssh");
+  let sshTarget: { host: string; port: number } | undefined;
+  if (ssh !== undefined) {
+    const match = /^(127\.0\.0\.1|localhost|\[::1\]):(\d{1,5})$/.exec(ssh);
+    const port = Number(match?.[2]);
+    if (!match || !Number.isInteger(port) || port < 1 || port > 65535) throw new Error("invalid_ssh");
+    sshTarget = { host: match[1] === "[::1]" ? "::1" : match[1]!, port };
+  }
+  const expectExit = flags.get("expect-exit") ?? "false";
+  if (!["true", "false"].includes(expectExit)) throw new Error("invalid_expect_exit");
+  return {
+    pid, db: resolve(flags.get("db")!), out: resolve(flags.get("out")!), marker,
+    ssh: sshTarget, expectExit: expectExit === "true",
+    seconds: number("seconds", 180, 0.1, 86400), intervalMs,
+    dbIntervalMs: number("db-interval-ms", Math.max(5000, intervalMs), intervalMs, 86400000),
+    timeoutMs: number("timeout-ms", 2000, 1, 60000),
+  };
+}
+type Options = ReturnType<typeof parseOptions>;
+const unavailable = (reason: string) => ({ status: "unavailable" as const, reason });
+const sha256 = (value: string | Buffer) => createHash("sha256").update(value).digest("hex");
+
+export async function runBounded(command: string[], timeoutMs: number, input?: string) {
+  const start = performance.now();
+  try {
+    const child = Bun.spawn(command, {
+      stdin: input === undefined ? "ignore" : Buffer.from(input), stdout: "pipe", stderr: "ignore",
+      env: { PATH: "/usr/bin:/bin", LC_ALL: "C", TZ: "UTC" },
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      // Only the observer's own ps/SQLite subprocess, never the target.
+      try { child.kill("SIGKILL"); } catch { /* May already have exited. */ }
+    }, timeoutMs);
+    try {
+      const stdout = await new Response(child.stdout).text();
+      const exitCode = await child.exited;
+      return {
+        stdout,
+        report: {
+          status: timedOut ? "timed_out" : exitCode === 0 ? "ok" : "failed",
+          exit_code: exitCode, signal: child.signalCode ?? null, elapsed_ms: performance.now() - start,
+        },
+      };
+    } finally {
+      clearTimeout(timer);
+      if (child.exitCode === null) {
+        child.kill("SIGKILL");
+        await child.exited;
+      }
+    }
+  } catch {
+    return { stdout: "", report: { status: "spawn_failed", exit_code: null, signal: null, elapsed_ms: performance.now() - start } };
+  }
+}
+
+type ProcIo = { rchar: number; wchar: number; read_bytes: number; write_bytes: number };
+type ProcessRow = { pid: number; ppid: number; rss_bytes: number; cpu_seconds: number; ps_cpu_percent: number; state: string; start_time: string; proc_io?: ProcIo };
+
+function getconf(name: string): number | null {
+  if (platform() !== "linux") return null;
+  try {
+    const result = Bun.spawnSync(["/usr/bin/getconf", name], { stdout: "pipe", stderr: "ignore" });
+    const value = Number(result.stdout.toString().trim());
+    return result.exitCode === 0 && Number.isFinite(value) && value > 0 ? value : null;
+  } catch { return null; }
+}
+
+const CLOCK_TICKS = getconf("CLK_TCK");
+const PAGE_SIZE = getconf("PAGESIZE");
+
+function linuxProcessMetrics(row: ProcessRow): ProcessRow {
+  if (!CLOCK_TICKS || !PAGE_SIZE) return row;
+  try {
+    const stat = readFileSync(`/proc/${row.pid}/stat`, "utf8");
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/);
+    if (fields.length < 22) return row;
+    const cpu = (Number(fields[11]) + Number(fields[12])) / CLOCK_TICKS;
+    const rss = Number(fields[21]) * PAGE_SIZE;
+    const io = Object.fromEntries(readFileSync(`/proc/${row.pid}/io`, "utf8").trim().split("\n")
+      .map((line) => line.split(/:\s+/, 2))) as Record<string, string>;
+    const procIo: ProcIo = {
+      rchar: Number(io.rchar), wchar: Number(io.wchar),
+      read_bytes: Number(io.read_bytes), write_bytes: Number(io.write_bytes),
+    };
+    if (![cpu, rss, ...Object.values(procIo)].every(Number.isFinite)) return row;
+    return { ...row, cpu_seconds: cpu, rss_bytes: rss, proc_io: procIo };
+  } catch { return row; }
+}
+export function parsePs(text: string): ProcessRow[] {
+  return text.trim().split("\n").filter(Boolean).map((line) => {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+([\d:.\-]+)\s+([\d.]+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
+    if (!match) throw new Error("invalid_ps_row");
+    const [, pid, ppid, rss, time, cpu, state, start] = match;
+    const [days, clock] = time.includes("-") ? time.split("-") : ["0", time];
+    const parts = clock.split(":").map(Number);
+    if (parts.length < 2 || parts.length > 3 || parts.some((value) => !Number.isFinite(value))) throw new Error("invalid_ps_time");
+    const seconds = Number(days) * 86400 + parts.reduce((total, value) => total * 60 + value, 0);
+    return { pid: Number(pid), ppid: Number(ppid), rss_bytes: Number(rss) * 1024,
+      cpu_seconds: seconds, ps_cpu_percent: Number(cpu), state, start_time: start.replace(/\s+/g, " ") };
+  });
+}
+const identity = (row: ProcessRow) => `${row.pid}:${row.start_time}`;
+
+export class ProcessTree {
+  private rootIdentity?: string;
+  private seen = new Set<string>();
+  private previous = new Map<string, number>();
+  private previousAt?: number;
+  private previousIo = new Map<string, ProcIo>();
+  observedCpuSeconds = 0;
+  observedIo: ProcIo = { rchar: 0, wchar: 0, read_bytes: 0, write_bytes: 0 };
+
+  constructor(private pid: number, private observerPid = process.pid) {}
+
+  sample(rows: ProcessRow[], atMs: number) {
+    const live = rows.filter((row) => !row.state.startsWith("Z"));
+    const root = live.find((row) => row.pid === this.pid);
+    if (!this.rootIdentity && root) this.rootIdentity = identity(root);
+    const rootStatus = root
+      ? identity(root) === this.rootIdentity ? "alive" : "pid_reused"
+      : this.rootIdentity ? "exited" : "not_found";
+    const excluded = new Set([this.observerPid]);
+    const selected = new Map<number, ProcessRow>();
+    // Retain already observed descendants after reparenting; do not attach a reused root PID.
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const row of live) {
+        if (excluded.has(row.ppid) && !excluded.has(row.pid)) { excluded.add(row.pid); changed = true; }
+      }
+    }
+    for (const row of live) {
+      if (!excluded.has(row.pid) && (identity(row) === this.rootIdentity || this.seen.has(identity(row)))) selected.set(row.pid, row);
+    }
+    for (let changed = true; changed;) {
+      changed = false;
+      for (const row of live) {
+        if (!excluded.has(row.pid) && selected.has(row.ppid) && !selected.has(row.pid)) {
+          selected.set(row.pid, row); changed = true;
+        }
+      }
+    }
+    const members = [...selected.values()].sort((a, b) => a.pid - b.pid)
+      .map((row) => platform() === "linux" ? linuxProcessMetrics(row) : row);
+    let delta = 0;
+    const next = new Map<string, number>();
+    const nextIo = new Map<string, ProcIo>();
+    for (const row of members) {
+      const key = identity(row);
+      const previous = this.previous.get(key);
+      if (previous !== undefined) delta += Math.max(0, row.cpu_seconds - previous);
+      next.set(key, row.cpu_seconds);
+      if (row.proc_io) {
+        const previousIo = this.previousIo.get(key);
+        if (previousIo) {
+          for (const field of ["rchar", "wchar", "read_bytes", "write_bytes"] as const) {
+            this.observedIo[field] += Math.max(0, row.proc_io[field] - previousIo[field]);
+          }
+        }
+        nextIo.set(key, row.proc_io);
+      }
+      this.seen.add(key);
+    }
+    const sampledCores = this.previousAt === undefined || atMs <= this.previousAt ? null : delta / ((atMs - this.previousAt) / 1000);
+    this.previous = next;
+    this.previousIo = nextIo;
+    this.previousAt = atMs;
+    this.observedCpuSeconds += delta;
+    return { status: "ok" as const, root_status: rootStatus, members,
+      observed_identities: this.seen.size, rss_bytes: members.reduce((sum, row) => sum + row.rss_bytes, 0),
+      cpu_lifetime_seconds_sum: members.reduce((sum, row) => sum + row.cpu_seconds, 0),
+      ps_cpu_percent_sum: members.reduce((sum, row) => sum + row.ps_cpu_percent, 0),
+      observed_cpu_seconds_lower_bound: this.observedCpuSeconds, sampled_cpu_cores: sampledCores,
+      proc_io_members: nextIo.size,
+      proc_io_lifetime_sum: members.reduce((total, row) => {
+        if (!row.proc_io) return total;
+        for (const field of ["rchar", "wchar", "read_bytes", "write_bytes"] as const) total[field] += row.proc_io[field];
+        return total;
+      }, { rchar: 0, wchar: 0, read_bytes: 0, write_bytes: 0 } as ProcIo),
+      proc_io_observed_delta_lower_bound: { ...this.observedIo } };
+  }
+}
+
+export function readCoverage(path: string, marker?: string) {
+  const db = new Database(path, { readonly: true, strict: true });
+  try {
+    db.exec("PRAGMA query_only = ON; PRAGMA trusted_schema = OFF; PRAGMA busy_timeout = 100; PRAGMA cache_size = -2048; BEGIN");
+    const tables = new Set((db.query(`SELECT name FROM sqlite_master WHERE type = 'table'
+      AND name IN ('sessions', 'records', 'records_embeddings', 'records_fts', 'ingest_cursors', 'ingest_queue')`)
+      .all() as { name: string }[]).map((row) => row.name));
+    if (!tables.has("sessions") || !tables.has("records")) throw new Error("ledger_schema_absent");
+    const sources = "'codex','claude-code','pi','omp','hermes','letta-code','openclaw','droid','deepagents','openhands','cursor','opencode','gemini-cli','copilot-cli','grok','kimi','cline','fx','managed','atif'";
+    function count(table: string, column?: string) {
+      if (!tables.has(table)) return unavailable("table_absent");
+      const by_source = column ? db.query(`SELECT CASE WHEN ${column} IN (${sources}) THEN ${column} ELSE 'other' END AS source,
+        count(*) AS count FROM ${table} GROUP BY 1 ORDER BY 1`).all() as { source: string; count: number }[] : undefined;
+      const total = by_source ? by_source.reduce((sum, row) => sum + row.count, 0)
+        : (db.query(`SELECT count(*) AS total FROM ${table}`).get() as { total: number }).total;
+      return { status: "ok", total, ...(by_source ? { by_source } : {}) };
+    }
+    const cursors = tables.has("ingest_cursors") ? {
+      status: "ok", ...db.query(`SELECT count(*) AS total, coalesce(sum(size), 0) AS source_bytes,
+        coalesce(sum(bytes_ingested), 0) AS bytes_ingested,
+        coalesce(sum(max(size - bytes_ingested, 0)), 0) AS bytes_pending,
+        coalesce(sum(record_count), 0) AS record_count,
+        coalesce(sum(status = 'failed'), 0) AS failed,
+        coalesce(sum(status = 'pending'), 0) AS pending,
+        coalesce(sum(status = 'ok'), 0) AS ok,
+        coalesce(sum(status NOT IN ('ok', 'failed', 'pending')), 0) AS other_status,
+        max(unixepoch(updated_at)) AS latest_update_epoch_seconds FROM ingest_cursors`).get() as Record<string, number | null>,
+    } : unavailable("ingest_cursors_table_absent");
+    const queue = tables.has("ingest_queue") ? {
+      status: "ok", ...db.query(`SELECT count(*) AS total,
+        coalesce(sum(next_attempt_at IS NULL OR next_attempt_at <= datetime('now')), 0) AS eligible,
+        coalesce(sum(next_attempt_at > datetime('now')), 0) AS retrying FROM ingest_queue`).get() as Record<string, number>,
+    } : unavailable("ingest_queue_table_absent");
+    const markerCounts = marker === undefined ? { status: "not_requested" }
+      : !tables.has("records_fts") ? unavailable("records_fts_table_absent")
+      : { status: "ok", method: "fts5_literal_phrase", ...db.query(`SELECT count(*) AS records,
+          count(DISTINCT session_id) AS sessions FROM records_fts WHERE records_fts MATCH ?`)
+        .get(`"${marker.replaceAll('"', '""')}"`) as Record<string, number> };
+    return {
+      status: "ok", schema_version: (db.query("PRAGMA user_version").get() as { user_version: number }).user_version,
+      coverage: { sessions: count("sessions", "source"), records: count("records", "source_type"),
+        embeddings: count("records_embeddings"), fts: count("records_fts") },
+      cursors, queue, marker: markerCounts,
+      warnings: unavailable("Warnings are stderr events, not durable SQLite counters; logs are deliberately not read. Failed cursors and retry queue state are reported separately."),
+    };
+  } finally {
+    db.close();
+  }
+}
+
+type NumericMap = Record<string, number>;
+
+function keyValues(path: string): NumericMap {
+  return Object.fromEntries(readFileSync(path, "utf8").trim().split("\n").filter(Boolean).map((line) => {
+    const [key, value] = line.trim().split(/\s+/, 2);
+    return [key!, Number(value)];
+  }).filter((entry) => Number.isFinite(entry[1]))) as NumericMap;
+}
+
+function pressure(path: string): Record<string, NumericMap> {
+  return Object.fromEntries(readFileSync(path, "utf8").trim().split("\n").filter(Boolean).map((line) => {
+    const [kind, ...fields] = line.trim().split(/\s+/);
+    return [kind!, Object.fromEntries(fields.map((field) => {
+      const [key, value] = field.split("=", 2);
+      return [key!, Number(value)];
+    }).filter((entry) => Number.isFinite(entry[1])))];
+  }));
+}
+
+function ioStat(path: string): NumericMap {
+  const total: NumericMap = {};
+  for (const line of readFileSync(path, "utf8").trim().split("\n").filter(Boolean)) {
+    for (const field of line.trim().split(/\s+/).slice(1)) {
+      const [key, raw] = field.split("=", 2);
+      const value = Number(raw);
+      if (key && Number.isFinite(value)) total[key] = (total[key] ?? 0) + value;
+    }
+  }
+  return total;
+}
+
+function cgroupDirectory(pid: number): string | null {
+  if (platform() !== "linux") return null;
+  try {
+    const line = readFileSync(`/proc/${pid}/cgroup`, "utf8").split("\n").find((entry) => entry.startsWith("0::"));
+    if (!line) return null;
+    const root = "/sys/fs/cgroup";
+    const path = resolve(root, `.${line.slice(3)}`);
+    return path === root || path.startsWith(root + "/") ? path : null;
+  } catch { return null; }
+}
+
+function cgroupSample(directory: string | null) {
+  if (!directory) return unavailable("unified_target_cgroup_unavailable");
+  try {
+    const numberFile = (name: string) => Number(readFileSync(join(directory, name), "utf8").trim());
+    return {
+      status: "ok" as const,
+      memory_current_bytes: numberFile("memory.current"),
+      memory_peak_bytes: numberFile("memory.peak"),
+      pids_current: numberFile("pids.current"),
+      cpu: keyValues(join(directory, "cpu.stat")),
+      io: (() => {
+        try { return { status: "ok" as const, ...ioStat(join(directory, "io.stat")) }; }
+        catch { return unavailable("I/O controller is not delegated to the target cgroup."); }
+      })(),
+      memory_events: keyValues(join(directory, "memory.events")),
+      pressure: {
+        cpu: pressure(join(directory, "cpu.pressure")),
+        memory: pressure(join(directory, "memory.pressure")),
+        io: pressure(join(directory, "io.pressure")),
+      },
+    };
+  } catch { return unavailable("target_cgroup_metrics_unreadable"); }
+}
+
+function cgroupLimits(directory: string | null) {
+  if (!directory) return unavailable("unified_target_cgroup_unavailable");
+  try {
+    const value = (name: string) => readFileSync(join(directory, name), "utf8").trim();
+    return {
+      status: "ok" as const,
+      cpu_max: value("cpu.max"), cpu_weight: value("cpu.weight"),
+      memory_high: value("memory.high"), memory_max: value("memory.max"),
+      pids_max: value("pids.max"), io_weight: (() => { try { return value("io.weight"); } catch { return null; } })(),
+    };
+  } catch { return unavailable("target_cgroup_limits_unreadable"); }
+}
+
+function numericDelta(end: unknown, start: unknown): unknown {
+  if (!end || !start || typeof end !== "object" || typeof start !== "object") {
+    return unavailable("cgroup_boundary_sample_unavailable");
+  }
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(end as Record<string, unknown>)) {
+    const previous = (start as Record<string, unknown>)[key];
+    if (typeof value === "number" && typeof previous === "number") result[key] = Math.max(0, value - previous);
+    else if (value && previous && typeof value === "object" && typeof previous === "object") result[key] = numericDelta(value, previous);
+  }
+  return result;
+}
+
+export async function probeSshBanner(
+  target: { host: string; port: number },
+  timeoutMs: number,
+): Promise<{ status: "ok" | "failed"; latency_ms: number; reason?: string }> {
+  const start = performance.now();
+  return new Promise((resolveProbe) => {
+    const socket = createConnection(target);
+    let settled = false;
+    let received = "";
+    const settle = (status: "ok" | "failed", reason?: string) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolveProbe({ status, latency_ms: performance.now() - start, ...(reason ? { reason } : {}) });
+    };
+    const timer = setTimeout(() => settle("failed", "timeout"), timeoutMs);
+    socket.on("data", (chunk) => {
+      received += chunk.toString("utf8");
+      if (received.length > 255) return settle("failed", "invalid_banner");
+      const newline = received.indexOf("\n");
+      if (newline >= 0) {
+        const valid = received.slice(0, newline).replace(/\r$/, "").startsWith("SSH-");
+        settle(valid ? "ok" : "failed", valid ? undefined : "invalid_banner");
+      }
+    });
+    socket.on("error", () => settle("failed", "connection_error"));
+    socket.on("end", () => settle("failed", "connection_closed"));
+  });
+}
+
+export async function observe(options: Options) {
+  const settings = { pid: options.pid, database_path: options.db, seconds: options.seconds, interval_ms: options.intervalMs,
+    db_interval_ms: options.dbIntervalMs, command_timeout_ms: options.timeoutMs,
+    marker_sha256: options.marker === undefined ? null : sha256(options.marker),
+    ssh_probe: options.ssh ? { host: options.ssh.host, port: options.ssh.port } : { status: "not_requested" },
+    expect_exit: options.expectExit };
+  const cgroup = cgroupDirectory(options.pid);
+  const provenance = { helper_sha256: sha256(readFileSync(import.meta.path)), runtime: `Bun ${Bun.version}`,
+    os: platform(), os_release: release(), arch: arch(), logical_cpus: cpus().length, host_memory_bytes: totalmem(),
+    target_revision: unavailable("An explicit PID does not establish the target build revision."),
+    target_limits: cgroupLimits(cgroup), cache_state: "uncontrolled observation" };
+  // A new directory and exclusive files avoid overwriting or following existing evidence symlinks.
+  mkdirSync(options.out, { mode: 0o700 });
+  const samplePath = join(options.out, "samples.jsonl");
+  const fd = openSync(samplePath, "wx", 0o600);
+  const digest = createHash("sha256");
+  const tree = new ProcessTree(options.pid);
+  const start = performance.now();
+  const startedAt = new Date().toISOString();
+  const startRecord = JSON.stringify({ type: "start", schema_version: 2, started_at: startedAt, settings, provenance }) + "\n";
+  writeSync(fd, startRecord);
+  digest.update(startRecord);
+  const deadline = start + options.seconds * 1000;
+  let interrupted = false;
+  const onSignal = () => { interrupted = true; };
+  process.on("SIGINT", onSignal);
+  process.on("SIGTERM", onSignal);
+  let count = 0, errors = 0, timeouts = 0, missedIntervals = 0, nextDbAt = start;
+  let stopReason = "duration_elapsed";
+  let baseline: ReturnType<ProcessTree["sample"]> | null = null;
+  let last: ReturnType<ProcessTree["sample"]> | null = null;
+  let peakRss: number | null = null, peakCores: number | null = null;
+  let dbBaseline: unknown = null, dbEnd: unknown = null;
+  let cgroupBaseline: unknown = null, cgroupEnd: unknown = null;
+  let procIoSeen = false;
+  let sshProbes = 0, sshFailures = 0, sshMaxLatency: number | null = null;
+  try {
+    while (true) {
+      const ps = await runBounded(["/bin/ps", "-A", "-o", "pid=", "-o", "ppid=", "-o", "rss=",
+        "-o", "time=", "-o", "pcpu=", "-o", "stat=", "-o", "lstart="], options.timeoutMs);
+      const at = performance.now();
+      last = null;
+      let processError = "ps_command_failed";
+      if (ps.report.status === "ok") {
+        try { last = tree.sample(parsePs(ps.stdout), at); } catch { processError = "ps_parse_failed"; }
+      }
+      if (last && last.root_status !== "not_found") {
+        baseline ??= last;
+        peakRss = Math.max(peakRss ?? 0, last.rss_bytes);
+        if (last.sampled_cpu_cores !== null) peakCores = Math.max(peakCores ?? 0, last.sampled_cpu_cores);
+        procIoSeen ||= last.proc_io_members > 0;
+      } else if (!last) errors++;
+      if (ps.report.status === "timed_out") timeouts++;
+      const treeExited = last !== null && last.members.length === 0;
+      const finish = interrupted || at >= deadline || treeExited || (!last && count === 0);
+      let database: unknown = { status: "not_sampled" };
+      let databaseCommand: unknown = null;
+      if (at >= nextDbAt || finish) {
+        const result = await runBounded([process.execPath, import.meta.path, "--sample-db"], options.timeoutMs,
+          JSON.stringify({ path: options.db, marker: options.marker }));
+        databaseCommand = result.report;
+        database = unavailable(result.report.status === "timed_out" ? "database_timeout" : "database_query_failed");
+        if (result.report.status === "ok") {
+          try { database = JSON.parse(result.stdout); } catch { errors++; }
+        } else errors++;
+        if (result.report.status === "timed_out") timeouts++;
+        dbBaseline ??= database;
+        dbEnd = database;
+        nextDbAt = performance.now() + options.dbIntervalMs;
+      }
+      const cgroupMetrics = cgroupSample(cgroup);
+      if (cgroupMetrics.status === "ok") {
+        cgroupBaseline ??= cgroupMetrics;
+        cgroupEnd = cgroupMetrics;
+      }
+      const ssh = options.ssh
+        ? await probeSshBanner(options.ssh, Math.min(options.timeoutMs, Math.max(100, options.intervalMs)))
+        : { status: "not_requested" as const };
+      if (ssh.status !== "not_requested") {
+        sshProbes++;
+        if (ssh.status === "failed") sshFailures++;
+        sshMaxLatency = Math.max(sshMaxLatency ?? 0, ssh.latency_ms);
+      }
+      const sample = JSON.stringify({ type: "sample", index: count++, at: new Date(Date.parse(startedAt) + at - start).toISOString(),
+        elapsed_ms: at - start, sample_finished_elapsed_ms: performance.now() - start,
+        ps_command: ps.report, processes: last ?? unavailable(processError),
+        database_command: databaseCommand, database, cgroup: cgroupMetrics, ssh });
+      writeSync(fd, sample + "\n");
+      digest.update(sample + "\n");
+      if (finish) {
+        stopReason = interrupted ? "interrupted" : treeExited ? (last?.root_status === "not_found" ? "pid_not_found" : "tree_exited")
+          : !last ? "process_snapshot_failed" : "duration_elapsed";
+        break;
+      }
+      const now = performance.now();
+      const nominalNext = at + options.intervalMs;
+      if (now > nominalNext) missedIntervals += Math.floor((now - at) / options.intervalMs);
+      await Bun.sleep(Math.max(0, Math.min(nominalNext, deadline) - now));
+    }
+  } finally {
+    closeSync(fd);
+    process.off("SIGINT", onSignal);
+    process.off("SIGTERM", onSignal);
+  }
+  const normalCompletion = stopReason === "duration_elapsed" || (options.expectExit && stopReason === "tree_exited");
+  const summary = {
+    schema_version: 2, kind: "process_tree_observation", stop_reason: stopReason,
+    status: normalCompletion && errors === 0 ? "completed" : "incomplete",
+    started_at: startedAt, ended_at: new Date().toISOString(), elapsed_seconds: (performance.now() - start) / 1000,
+    sample_count: count, collection_errors: errors, command_timeouts: timeouts, missed_intervals: missedIntervals,
+    settings, provenance,
+    tree: { root_pid: options.pid, root_status_at_end: last?.root_status ?? "unavailable",
+      alive_at_end: baseline && last ? last.members.length > 0 : null, observed_identities: last?.observed_identities ?? null },
+    memory: { method: "sum of ps RSS * 1024 for sampled tree members", baseline_rss_bytes: baseline?.rss_bytes ?? null,
+      peak_rss_bytes: peakRss, end_rss_bytes: baseline && last ? last.rss_bytes : null,
+      after_teardown: baseline && last?.members.length === 0 ? { status: "measured", bytes: 0 } : unavailable("Tree teardown not observed; target is never stopped by this helper.") },
+    cpu: { method: "positive ps user+system time deltas for same PID+start-time identities, divided by actual sample intervals",
+      observed_seconds_lower_bound: baseline ? tree.observedCpuSeconds : null, peak_sampled_cores: peakCores,
+      baseline_lifetime_seconds_sum: baseline?.cpu_lifetime_seconds_sum ?? null, end_lifetime_seconds_sum: baseline && last ? last.cpu_lifetime_seconds_sum : null },
+    io: procIoSeen ? { status: "measured", method: "positive /proc/<pid>/io deltas for sampled PID+start-time identities; lower bounds",
+      logical_read_bytes: tree.observedIo.rchar, logical_write_bytes: tree.observedIo.wchar,
+      storage_read_bytes: tree.observedIo.read_bytes, storage_write_bytes: tree.observedIo.write_bytes }
+      : unavailable(platform() === "linux" ? "No readable target /proc I/O sample was captured." : "Per-process byte counters are unavailable on this platform."),
+    cgroup: { baseline: cgroupBaseline ?? unavailable("No readable target cgroup sample was captured."),
+      end: cgroupEnd ?? unavailable("No readable target cgroup sample was captured."),
+      delta: numericDelta(cgroupEnd, cgroupBaseline) },
+    ssh: options.ssh ? { status: "measured", method: "loopback TCP connect through complete SSH identification line",
+      probes: sshProbes, failures: sshFailures, max_banner_latency_ms: sshMaxLatency }
+      : { status: "not_requested" },
+    usage: { observer_models: { status: "not_applicable", reason: "Collector imports only builtins and makes no model/network calls." },
+      target_tokens: unavailable("Target token/cache accounting is not exposed by ps or these SQLite aggregates.") },
+    database: { baseline: dbBaseline, end: dbEnd },
+    artifacts: [{ path: "samples.jsonl", sha256: digest.digest("hex") }],
+    limitations: [
+      "RSS includes shared pages; sums can double-count. Baseline is attach time, not pre-start memory.",
+      "Sampled RSS peaks and CPU deltas are lower bounds. Short-lived/unseen children and CPU before first sighting or after last sighting are missed.",
+      "Linux /proc I/O deltas have the same sampling boundary; sync's application work counters are the source-read authority for short-lived workers.",
+      "PID identity uses ps lstart with second precision; same-second PID reuse cannot be distinguished. Only observed descendants survive reparenting in attribution.",
+      "ps %CPU is a platform-reported average (decaying on macOS), not interval CPU. Interval cores are computed separately from counters.",
+      "Each SQLite subprocess opens read-only with query_only and a short read transaction. Aggregates add observer load; actual timings/timeouts are recorded.",
+      "Cursor byte totals sum logical cursors; they are neither unique source-file bytes nor I/O counters.",
+      "Duration bounds observation, not an external kill of the target; in-flight/final samples may add command-timeout overhead. Actual elapsed time is reported.",
+      "A completed collection is not evidence that ingestion is correct or complete. Missing tables/counters are unavailable, not zero.",
+    ],
+  };
+  writeFileSync(join(options.out, "summary.json"), JSON.stringify(summary, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+  return summary;
+}
+
+if (import.meta.main) {
+  if (process.argv[2] === "--sample-db") {
+    try {
+      const { path, marker } = JSON.parse(await Bun.stdin.text());
+      console.log(JSON.stringify(readCoverage(path, marker)));
+    } catch { process.exitCode = 2; }
+  } else if (process.argv.slice(2).includes("--help")) {
+    console.log(HELP);
+  } else {
+    try {
+      const summary = await observe(parseOptions(process.argv.slice(2)));
+      console.log(JSON.stringify({ status: summary.status, stop_reason: summary.stop_reason, sample_count: summary.sample_count }));
+      process.exitCode = summary.stop_reason === "interrupted" ? 130 : summary.status === "completed" ? 0 : 2;
+    } catch {
+      console.error("Observation failed: check required options, a new output directory, and readable input paths. Use --help.");
+      process.exitCode = 2;
+    }
+  }
+}

package/legacy/scripts/retitle-sessions.md

@@ -0,0 +1,19 @@
+# One-shot Trajectories session retitle (historical: 2026-09-06)
+
+Sessions whose title derived from harness boilerplate (`<recommended_plugins>`
+etc.) were retitled in-place via SQL mirroring the normalizer's fixed logic
+(first non-boilerplate user record). Run only if an old DB predates the fix:
+
+```sql
+UPDATE sessions SET title = (
+  SELECT substr(r.content, 1, 120) FROM records r
+  WHERE r.session_id = sessions.id AND r.record_type = 'user'
+    AND r.content IS NOT NULL AND trim(r.content) != ''
+    AND trim(r.content) NOT LIKE '<recommended_plugins>%'
+    AND trim(r.content) NOT LIKE '<environment_context>%'
+    AND trim(r.content) NOT LIKE '<user_info>%'
+    AND trim(r.content) NOT LIKE '<system_warning>%'
+  ORDER BY r.source_order_id LIMIT 1
+)
+WHERE title LIKE '<recommended_plugins>%';
+```