@tryinget/pi-activity-strip 0.8.0 → 0.10.0

package/src/native/recovery-sources.mjs

@@ -0,0 +1,358 @@
+// ---
+// summary: "Allowlisted session metadata readers; JSONL is projected only by jq, never replayed."
+// read_when: ["changing recovery registry or transcript discovery"]
+// ---
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { sendBrokerMessage } from "../client/broker-client.mjs";
+import { makeMessage } from "../common/protocol.mjs";
+import { UUID } from "../common/recovery-identity.mjs";
+import { fileIdentity, openJsonlDescriptors, record, string, textFile } from "./recovery-proc.mjs";
+
+/** @typedef {import('../common/recovery-types.ts').SessionObservation} SessionObservation */
+/** @typedef {import('../common/recovery-types.ts').SourceCoverage} SourceCoverage */
+/** @typedef {import('../common/recovery-types.ts').TranscriptObservation} TranscriptObservation */
+
+/** @param {string} file */
+function metadataJson(file) {
+  const stat = fs.statSync(file);
+  if (!stat.isFile() || stat.size > 262144) throw new Error("metadata-bound");
+  return record(JSON.parse(textFile(file)));
+}
+
+/** @param {string} root */
+export function claudeRegistry(root) {
+  /** @type {SessionObservation[]} */
+  const sessions = [];
+  /** @type {SourceCoverage} */
+  const coverage = { source: root, state: "observed", observed: 0, rejected: 0, limitations: [] };
+  try {
+    const names = fs
+      .readdirSync(root)
+      .filter((v) => v.endsWith(".json"))
+      .sort();
+    coverage.observed = names.length;
+    if (names.length > 4096) coverage.limitations.push("registry-file-limit:4096");
+    for (const name of names.slice(0, 4096)) {
+      try {
+        const file = path.join(root, name);
+        const before = fileIdentity(file);
+        const row = metadataJson(file);
+        const after = fileIdentity(file);
+        const pid = row.pid;
+        const sessionId = string(row.sessionId);
+        if (!Number.isSafeInteger(pid) || Number(pid) <= 0 || !UUID.test(sessionId)) {
+          coverage.rejected++;
+          continue;
+        }
+        sessions.push({
+          harness: "claude",
+          sessionId,
+          pid: Number(pid),
+          source: "claude-registry",
+          sourceRef: file,
+          cwd: string(row.cwd),
+          startedAt: Number(row.startedAt),
+          pidDomain: string(row.pidDomain) || null,
+          procStart: string(row.procStart) || null,
+          bootId: string(row.bootId) || null,
+          changed: JSON.stringify(before) !== JSON.stringify(after),
+          transcripts: [],
+        });
+      } catch {
+        coverage.rejected++;
+      }
+    }
+  } catch {
+    coverage.state = "unavailable";
+  }
+  return { sessions, coverage };
+}
+
+/** Where Nodecode's client keeps shell presence: it writes only under an absolute XDG_RUNTIME_DIR,
+ * so nothing else is read. => the directory, or null.
+ * @param {NodeJS.ProcessEnv} env */
+export function nodecodeShellRoot(env) {
+  const runtime = env.XDG_RUNTIME_DIR ?? "";
+  return runtime.startsWith("/") ? path.join(runtime, "nodecode", "shells") : null;
+}
+
+/** Nodecode's own shell presence records: a terminal shell attached to its session names that
+ * session, never one it only previews, with its pid and /proc start ticks, and removes the record
+ * when it ends. Detached sessions and RPC clients write none. A record has no PID-namespace domain
+ * or boot id. Its resume command, home and profile are never read.
+ * @param {string | null} root */
+export function nodecodeShells(root) {
+  /** @type {SessionObservation[]} */
+  const sessions = [];
+  /** @type {SourceCoverage} */
+  const coverage = {
+    source: root ?? "nodecode-shell-presence",
+    state: "observed",
+    observed: 0,
+    rejected: 0,
+    limitations: [
+      "attached terminal shells only; no PID-namespace domain or boot id; ids unique per Nodecode home",
+    ],
+  };
+  if (root === null) {
+    coverage.state = "unavailable";
+    coverage.limitations.push("XDG_RUNTIME_DIR unset or relative");
+    return { sessions, coverage };
+  }
+  try {
+    const names = fs
+      .readdirSync(root)
+      .filter((v) => v.endsWith(".json"))
+      .sort();
+    coverage.observed = names.length;
+    if (names.length > 4096) coverage.limitations.push("registry-file-limit:4096");
+    for (const name of names.slice(0, 4096)) {
+      try {
+        const file = path.join(root, name);
+        // The writer replaces a regular file atomically; it never links one in.
+        if (!fs.lstatSync(file).isFile()) throw new Error("not-a-regular-file");
+        const before = fileIdentity(file);
+        const row = metadataJson(file);
+        const after = fileIdentity(file);
+        const { pid, start_ticks: ticks } = row;
+        const sessionId = string(row.session_id);
+        // Without start ticks a record could claim a later Nodecode on its pid, so it is refused.
+        if (
+          row.version !== 1 ||
+          row.kind !== "nodecode-shell" ||
+          !Number.isSafeInteger(pid) ||
+          Number(pid) <= 0 ||
+          name !== `${pid}.json` ||
+          !Number.isSafeInteger(ticks) ||
+          Number(ticks) < 0 ||
+          !/^[!-~]{1,128}$/.test(sessionId)
+        ) {
+          coverage.rejected++;
+          continue;
+        }
+        sessions.push({
+          harness: "nodecode",
+          sessionId,
+          pid: Number(pid),
+          source: "nodecode-shell-presence",
+          sourceRef: file,
+          cwd: string(row.cwd),
+          startedAt: 0,
+          pidDomain: null,
+          procStart: String(ticks),
+          bootId: null,
+          changed: JSON.stringify(before) !== JSON.stringify(after),
+          transcripts: [],
+        });
+      } catch {
+        coverage.rejected++;
+      }
+    }
+  } catch {
+    coverage.state = "unavailable";
+  }
+  return { sessions, coverage };
+}
+
+/** Mark each session whose source, read again after the capture, no longer says the same thing:
+ * same pid, session, start, cwd, birth token and domain. Ordinary heartbeats do not count.
+ * @param {SessionObservation[]} sessions @param {Map<string, SessionObservation[]>} after */
+export function markRepublished(sessions, after) {
+  for (const s of sessions) {
+    const peers = after.get(s.source);
+    if (!peers) continue;
+    s.changed ||= !peers.some(
+      (a) =>
+        a.pid === s.pid &&
+        a.sessionId === s.sessionId &&
+        a.startedAt === s.startedAt &&
+        a.cwd === s.cwd &&
+        a.procStart === s.procStart &&
+        a.pidDomain === s.pidDomain &&
+        !a.changed,
+    );
+  }
+}
+
+export async function piBroker() {
+  /** @type {SessionObservation[]} */
+  const sessions = [];
+  /** @type {SourceCoverage} */
+  const coverage = {
+    source: "pi-activity-strip-broker",
+    state: "observed",
+    observed: 0,
+    rejected: 0,
+    limitations: ["only broker publishers, not all Pi sessions; no source process-birth token"],
+  };
+  try {
+    const response = await sendBrokerMessage(makeMessage("ping"), { expectReply: true });
+    if (!response?.ok || !Array.isArray(response.snapshot?.sessions))
+      throw new Error("broker-unavailable");
+    const rows = response.snapshot.sessions;
+    coverage.observed = rows.length;
+    for (const row of rows) {
+      if (!row.sessionId || !Number.isSafeInteger(row.processId)) {
+        coverage.rejected++;
+        continue;
+      }
+      sessions.push({
+        harness: "pi",
+        sessionId: row.sessionId,
+        pid: row.processId,
+        source: "pi-broker",
+        sourceRef: "pi-activity-strip broker ping",
+        cwd: row.cwd,
+        startedAt: row.startedAt,
+        updatedAt: row.updatedAt,
+        pidDomain: null,
+        procStart: null,
+        changed: false,
+        transcripts: [],
+      });
+    }
+  } catch {
+    coverage.state = "unavailable";
+  }
+  return { sessions, coverage };
+}
+
+/** Scan exactly root plus one directory level, filenames only; no symlink directories.
+ * @param {string} root */
+export function transcriptIndex(root) {
+  /** @type {Map<string, string[]>} */
+  const files = new Map();
+  /** @type {SourceCoverage} */
+  const coverage = {
+    source: root,
+    state: "observed",
+    observed: 0,
+    rejected: 0,
+    limitations: ["filenames only; depth <= 2; limit 100000; no historical-session inventory"],
+  };
+  let examined = 0;
+  /** @param {string} dir @param {number} depth */
+  function visit(dir, depth) {
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (++examined > 100000) {
+          coverage.state = "truncated";
+          return;
+        }
+        const file = path.join(dir, entry.name);
+        if (entry.isDirectory() && depth === 0) visit(file, 1);
+        if (!entry.isFile() || !entry.name.endsWith(".jsonl")) continue;
+        coverage.observed++;
+        const match = /(?:^|_)([0-9a-f-]{36})\.jsonl$/i.exec(entry.name);
+        if (!match || !UUID.test(match[1])) continue;
+        const id = match[1].toLowerCase();
+        files.set(id, [...(files.get(id) ?? []), file]);
+      }
+    } catch {
+      coverage.rejected++;
+      coverage.state = "partial-or-unavailable";
+    }
+  }
+  visit(root, 0);
+  return { files, coverage };
+}
+
+/** First record only, projected through jq. No raw session text enters JS or diagnostic errors.
+ * @param {string} file @param {string} harness */
+export function sessionHeader(file, harness) {
+  const filter =
+    harness === "pi"
+      ? 'if .type == "session" then {id, cwd, timestamp} else {} end, halt'
+      : 'if .type == "session_meta" then .payload | {id, cwd, timestamp} else {} end, halt';
+  try {
+    const raw = execFileSync("jq", ["-c", filter, "--", file], {
+      encoding: "utf8",
+      maxBuffer: 65536,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return record(JSON.parse(raw));
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string} file @param {string} id @param {string} harness @returns {TranscriptObservation} */
+export function inspectTranscript(file, id, harness) {
+  try {
+    const before = fileIdentity(file);
+    const header = harness === "claude" ? null : sessionHeader(file, harness);
+    const after = fileIdentity(file);
+    const changed = JSON.stringify(before) !== JSON.stringify(after);
+    return {
+      path: file,
+      state:
+        header === null
+          ? "filename-candidate"
+          : string(header.id) === id
+            ? "header-id-matched"
+            : "header-unconfirmed",
+      method: header === null ? "filename-and-stat-only; content-not-read" : "jq-first-record-id",
+      ...after,
+      changed,
+    };
+  } catch {
+    return { path: file, state: "unavailable", method: "stat" };
+  }
+}
+
+/** @param {import('../common/recovery-types.ts').ProcessObservation[]} processes @param {string} codexHome */
+export function codexDescriptors(processes, codexHome) {
+  /** @type {SessionObservation[]} */
+  const sessions = [];
+  /** @type {SourceCoverage} */
+  const coverage = {
+    source: "codex-open-rollout-descriptors",
+    state: "observed",
+    observed: 0,
+    rejected: 0,
+    limitations: ["no SQLite reads or recent-cwd fallback; current display unsupported"],
+  };
+  for (const p of processes.filter((p) => p.harness === "codex")) {
+    const fds = openJsonlDescriptors(p.pid);
+    if (fds.state !== "observed") coverage.rejected++;
+    const seen = new Set();
+    for (const fd of fds.descriptors) {
+      if (!fd.target.startsWith(`${codexHome}/sessions/`) || seen.has(fd.target)) continue;
+      seen.add(fd.target);
+      coverage.observed++;
+      const header = sessionHeader(fd.target, "codex");
+      const id = string(header.id);
+      if (!UUID.test(id)) {
+        coverage.rejected++;
+        continue;
+      }
+      let changed = true;
+      try {
+        changed =
+          fs.readlinkSync(fd.descriptor) !== fd.target ||
+          fileIdentity(fd.descriptor).identity !== fd.identity ||
+          fileIdentity(fd.target).identity !== fd.identity;
+      } catch {
+        /* retain changed */
+      }
+      sessions.push({
+        harness: "codex",
+        sessionId: id,
+        pid: p.pid,
+        source: "codex-open-rollout",
+        sourceRef: fd.descriptor,
+        cwd: string(header.cwd),
+        startedAt: Date.parse(string(header.timestamp)),
+        pidDomain: p.pidDomain,
+        procStart: p.startTicks,
+        bootId: p.bootId,
+        changed,
+        transcripts: [inspectTranscript(fd.target, id, "codex")],
+      });
+    }
+  }
+  return { sessions, coverage };
+}

package/src/native/runtime-diagnostics.mjs

@@ -0,0 +1,242 @@
+// ---
+// summary: "read-only, allowlisted ribbon diagnostics; observations never grant input or AK authority"
+// read_when:
+//   - "changing ribbon build/focus/ownership explanations or their privacy boundary"
+// ---
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import { open, readlink, stat } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizeKeyboardObservation } from "../common/keyboard-observation.mjs";
+import { PANEL_PROTOCOL } from "./panel-protocol.mjs";
+import { parseProcStat } from "./recovery-proc.mjs";
+
+/** Record only the current supervised child's optional native-clock observation.
+ * This never calls projection/admission and refuses earlier requests or backwards native clocks.
+ * @param {import("../common/contracts.ts").ActivityStripRuntimeStatus} status
+ * @param {unknown} event @param {number | undefined} panelPid */
+export function recordNativeKeyboardObservation(status, event, panelPid) {
+  const observation = normalizeKeyboardObservation(event);
+  if (
+    !observation ||
+    !Number.isSafeInteger(panelPid) ||
+    Number(panelPid) <= 0 ||
+    panelPid !== status.panelPid
+  )
+    return false;
+  const previous = status.nativeKeyboardObservation;
+  if (
+    previous &&
+    previous.panelPid === panelPid &&
+    (observation.request < previous.request || observation.nativeMs < previous.nativeMs)
+  )
+    return false;
+  status.nativeKeyboardObservation = { ...observation, panelPid: Number(panelPid) };
+  return true;
+}
+
+/** @param {import("../common/contracts.ts").ActivityStripRuntimeStatus} status */
+function currentNativeObservation(status) {
+  const previous = status.nativeKeyboardObservation;
+  if (status.state !== "ready" || !previous || previous.panelPid !== status.panelPid) return null;
+  const observation = normalizeKeyboardObservation({
+    ...previous,
+    protocol: 2,
+    type: "keyboard-observation",
+  });
+  return observation ? { ...observation, panelPid: previous.panelPid } : null;
+}
+
+const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
+/** @param {import("node:crypto").BinaryLike} bytes */
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** @param {unknown} value */
+const isHash = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+
+// Startup source-tree observation, NOT proof of all in-memory bytes or AK custody.
+function startupSourceSha256() {
+  try {
+    const files = ["package.json"];
+    /** @param {string} relative */
+    const visit = (relative) => {
+      for (const entry of fs.readdirSync(path.join(packageRoot, relative), {
+        withFileTypes: true,
+      })) {
+        const next = path.join(relative, entry.name);
+        if (entry.isDirectory()) visit(next);
+        else if (entry.isFile()) files.push(next);
+      }
+    };
+    visit("src");
+    return sha256(
+      files
+        .sort()
+        .map((file) => `${file}\0${sha256(fs.readFileSync(path.join(packageRoot, file)))}\n`)
+        .join(""),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Descriptor-bound, capped, asynchronous read; FIFOs/devices cannot block the controller loop.
+ * @param {string} file @param {number} cap @param {boolean} [followSymlink] */
+async function boundedFile(file, cap, followSymlink = false) {
+  const handle = await open(
+    file,
+    fs.constants.O_RDONLY | fs.constants.O_NONBLOCK | (followSymlink ? 0 : fs.constants.O_NOFOLLOW),
+  );
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || before.size > cap) throw new Error("unavailable");
+    const bytes = Buffer.alloc(cap + 1);
+    let length = 0;
+    while (length <= cap) {
+      const { bytesRead } = await handle.read(bytes, length, cap + 1 - length, length);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    const after = await handle.stat();
+    if (length > cap || before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+      throw new Error("changed");
+    return { bytes: bytes.subarray(0, length), identity: `${after.dev}:${after.ino}` };
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Non-atomic PID observation, checked for birth/executable changes during the sample.
+ * Receipt matching means integrity, NOT approval or original-child custody.
+ * @param {number | null | undefined} pid @param {{procRoot?: string}} [options] */
+export async function inspectPanelBuild(pid, { procRoot = "/proc" } = {}) {
+  if (!Number.isSafeInteger(pid) || Number(pid) <= 0) return { state: "unavailable" };
+  const base = path.join(procRoot, String(pid));
+  let binarySha256;
+  try {
+    const birth = parseProcStat(
+      (await boundedFile(path.join(base, "stat"), 8192)).bytes.toString(),
+      Number(pid),
+    );
+    if (!birth) return { state: "unavailable" };
+    const exe = path.join(base, "exe");
+    const location = await readlink(exe);
+    const executable = await boundedFile(exe, 16 * 1024 * 1024, true);
+    binarySha256 = sha256(executable.bytes);
+    let receipt;
+    try {
+      receipt = JSON.parse(
+        (
+          await boundedFile(path.join(path.dirname(location), "artifact.json"), 64 * 1024)
+        ).bytes.toString(),
+      );
+    } catch {
+      receipt = null;
+    }
+    const afterBirth = parseProcStat(
+      (await boundedFile(path.join(base, "stat"), 8192)).bytes.toString(),
+      Number(pid),
+    );
+    const afterExe = await stat(exe);
+    if (
+      birth.startTicks !== afterBirth?.startTicks ||
+      (await readlink(exe)) !== location ||
+      executable.identity !== `${afterExe.dev}:${afterExe.ino}`
+    )
+      return { state: "changed-during-observation" };
+    if (!receipt)
+      return { state: "unavailable", binarySha256, processStartTicks: birth.startTicks };
+    const privateProtocol = Number.isSafeInteger(receipt.panelProtocol)
+      ? receipt.panelProtocol
+      : null;
+    return {
+      state:
+        privateProtocol !== PANEL_PROTOCOL
+          ? "incompatible"
+          : receipt.schema === "pi-activity-strip-native-artifact.v1" &&
+              receipt.target === "x86_64-unknown-linux-gnu" &&
+              receipt.sha256 === binarySha256
+            ? "receipt-matched"
+            : "receipt-mismatch",
+      binarySha256,
+      processStartTicks: birth.startTicks,
+      privateProtocol,
+      receiptedSourceSha256: isHash(receipt.sourceSha256) ? receipt.sourceSha256 : null,
+    };
+  } catch {
+    // A failed generation check must not retain a digest attributed to the wrong process.
+    return { state: "unavailable" };
+  }
+}
+
+/** @param {{runtimeStatus: import("../common/contracts.ts").ActivityStripRuntimeStatus;
+ * projection: ReturnType<typeof import("./panel-projection.mjs").createNativePanelProjection>}} options */
+export function createRuntimeStatusReader({ runtimeStatus, projection }) {
+  const controllerStartupSourceSha256 = startupSourceSha256();
+  /** @type {Awaited<ReturnType<typeof inspectPanelBuild>>} */
+  let panelBuild = { state: "unavailable" };
+  let observedPid = runtimeStatus.panelPid;
+  let sampledAt = 0;
+  /** @type {Promise<void> | null} */
+  let pending = null;
+  function refresh() {
+    const pid = runtimeStatus.panelPid;
+    if (pid !== observedPid) {
+      observedPid = pid;
+      sampledAt = 0;
+      panelBuild = { state: "pending" };
+    }
+    if (!pending && (sampledAt === 0 || Date.now() - sampledAt >= 1000)) {
+      pending = inspectPanelBuild(pid)
+        .then((next) => {
+          if (runtimeStatus.panelPid === pid) {
+            panelBuild = next;
+            sampledAt = Date.now();
+          }
+        })
+        .finally(() => {
+          pending = null;
+        });
+    }
+  }
+  return () => {
+    refresh(); // async sampling only; status/keyboard event handling never waits for file I/O.
+    const facts = projection.diagnostics();
+    const nativeKeyboardObservation = currentNativeObservation(runtimeStatus);
+    const visibilityReason =
+      runtimeStatus.state !== "ready"
+        ? runtimeStatus.state
+        : facts.persistentPresentation
+          ? runtimeStatus.windowVisible === true
+            ? "persistent-workspace"
+            : "awaiting-panel-visibility"
+          : !facts.contextValid
+            ? "unproven-focus"
+            : facts.focus === "non-agent"
+              ? "non-agent-focus"
+              : !facts.eligible
+                ? "no-admitted-owner"
+                : runtimeStatus.windowVisible !== true
+                  ? "awaiting-panel-visibility"
+                  : facts.focus === "neutral" || facts.source === "neutral"
+                    ? "eligible-presence-context"
+                    : "eligible-agent-context";
+    return {
+      ...runtimeStatus,
+      nativeKeyboardObservation,
+      warnings: [...(runtimeStatus.warnings ?? [])],
+      ribbonDiagnostics: {
+        controllerStartupSourceSha256,
+        expectedPrivateProtocol: PANEL_PROTOCOL,
+        panelBuild: { ...panelBuild },
+        panelBuildObservedAt: sampledAt || null,
+        visibilityReason,
+        ...facts,
+        // Last observed native-domain fact only: never infer expiry from the controller clock.
+        captureExpiry: nativeKeyboardObservation ? "native-observed" : "not-observed",
+        nativeKeyboardObservation,
+      },
+    };
+  };
+}