@tryinget/pi-activity-strip 0.8.0 → 0.10.0

package/src/common/keyboard-observation.mjs

@@ -0,0 +1,35 @@
+/** Optional private-v2 observation. Never authorization, query text or a wall-clock countdown.
+ * @param {unknown} input */
+export function normalizeKeyboardObservation(input) {
+  if (!input || typeof input !== "object") return null;
+  const event = /** @type {Record<string, unknown>} */ (input);
+  const { protocol, type, request, origin, reason, nativeMs, deadlineMs, captured } = event;
+  const safe = (/** @type {unknown} */ value) => Number.isSafeInteger(value) && Number(value) >= 0;
+  if (
+    protocol !== 2 ||
+    type !== "keyboard-observation" ||
+    !safe(request) ||
+    Number(request) === 0 ||
+    !safe(nativeMs) ||
+    captured !== true ||
+    typeof reason !== "string" ||
+    !["acquired", "activity", "idle-expired", "source-revoked"].includes(reason)
+  )
+    return null;
+  if (origin === "hover") {
+    if (
+      !safe(deadlineMs) ||
+      (reason === "idle-expired" && Number(nativeMs) < Number(deadlineMs)) ||
+      (["acquired", "activity"].includes(reason) && Number(nativeMs) >= Number(deadlineMs))
+    )
+      return null;
+  } else if (origin !== "explicit" || deadlineMs !== null || reason === "idle-expired") return null;
+  return {
+    request: Number(request),
+    origin: /** @type {"hover" | "explicit"} */ (origin),
+    reason: /** @type {"acquired" | "activity" | "idle-expired" | "source-revoked"} */ (reason),
+    nativeMs: Number(nativeMs),
+    deadlineMs: deadlineMs === null ? null : Number(deadlineMs),
+    captured: true,
+  };
+}

package/src/common/overlay-readiness.mjs

@@ -0,0 +1,11 @@
+// ---
+// summary: "distinguishes broker liveness from an explicitly ready native overlay"
+// read_when:
+//   - "changing startup reuse, waiter success, or CLI status exit semantics"
+// ---
+
+/** A pong alone is not overlay readiness or artifact approval.
+ * @param {import("./contracts.ts").BrokerResponse | null | undefined} result */
+export function isOverlayReady(result) {
+  return result?.ok === true && result.runtimeStatus?.state === "ready";
+}

package/src/common/presence-apps.mjs

@@ -0,0 +1,57 @@
+// ---
+// summary: "decides which focused non-agent applications keep the activity strip present"
+// read_when:
+//   - "changing which applications keep the strip visible, or the presence env override"
+// ---
+
+/**
+ * Applications the operator works in beside the agents: the terminal family that hosts agent tabs
+ * (and plain shells, nodecode, angelx, Cursor's `agent`), and the password manager reached for in
+ * the middle of agent work. Focusing one of them keeps the strip on screen. Presence is a
+ * visibility policy only; it never claims that the window owns a card.
+ */
+export const DEFAULT_PRESENCE_APP_IDS = Object.freeze([
+  "com.mitchellh.ghostty",
+  "com.tryinget.ghosttysidequest",
+  "com.onepassword.OnePassword",
+  "1Password",
+]);
+
+/** @type {Map<string, {all: boolean; ids: Set<string>}>} */
+const parsed = new Map();
+
+/**
+ * `PI_ACTIVITY_STRIP_PRESENCE_APP_IDS` is a comma list applied to the defaults: `id` adds an app,
+ * `-id` removes one, `none` drops every default, `*` keeps the strip present over every app.
+ * App ids compare case-insensitively.
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function presenceAppsFor(env = process.env) {
+  const raw = String(env?.PI_ACTIVITY_STRIP_PRESENCE_APP_IDS ?? "");
+  const cached = parsed.get(raw);
+  if (cached) return cached;
+  const ids = new Set(DEFAULT_PRESENCE_APP_IDS.map((id) => id.toLowerCase()));
+  let all = false;
+  for (const entry of raw.split(",").map((value) => value.trim().toLowerCase())) {
+    if (!entry) continue;
+    if (entry === "*") all = true;
+    else if (entry === "none") {
+      ids.clear();
+      all = false;
+    } else if (entry.startsWith("-")) ids.delete(entry.slice(1).trim());
+    else ids.add(entry);
+  }
+  const result = { all, ids };
+  parsed.set(raw, result);
+  return result;
+}
+
+/** @param {unknown} appId @param {NodeJS.ProcessEnv} [env] */
+export function isPresenceApp(appId, env = process.env) {
+  const id = String(appId ?? "")
+    .trim()
+    .toLowerCase();
+  if (!id) return false;
+  const apps = presenceAppsFor(env);
+  return apps.all || apps.ids.has(id);
+}

package/src/common/recovery-identity.mjs

@@ -0,0 +1,85 @@
+// ---
+// summary: "Exact harness-qualified claimant identities for read-only recovery projections."
+// read_when: ["changing recovery claimant joins"]
+// ---
+
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** One base-36 field of a Nodecode id: uppercase with no leading zero, so one spelling each.
+ * @param {string} field @param {number} least @param {number} most */
+function base36Field(field, least, most) {
+  return field.length >= least && field.length <= most && /^(?:0|[1-9A-Z][0-9A-Z]*)$/.test(field);
+}
+
+/** A decimal field of a Nodecode id, of at least `least`, in at most six digits.
+ * @param {string} field @param {number} least */
+function decimalField(field, least) {
+  return /^[1-9][0-9]{0,5}$/.test(field) && Number(field) >= least;
+}
+
+/** @param {string} time @param {string} random */
+function stamp(time, random) {
+  return base36Field(time, 7, 8) && base36Field(random, 1, 10);
+}
+
+/** AK owns this grammar: valid_nodecode_session_id in agent-kernel crates/ak-core/src/tasks.rs.
+ * A shell is `s-<random>`, a durable session `session-<time>-<random>`, a fork
+ * `fork-turn-<time>-<random>-<n>` and one more number when that name is taken. `s-GATEWAY` is the
+ * gateway's shared pseudo-session: it names no one session. Every other Nodecode id stays refused.
+ * @param {unknown} id */
+function validNodecodeId(id) {
+  if (typeof id !== "string" || id === "s-GATEWAY") return false;
+  const parts = id.split("-");
+  if (parts[0] === "s" && parts.length === 2) return base36Field(parts[1], 1, 8);
+  if (parts[0] === "session" && parts.length === 3) return stamp(parts[1], parts[2]);
+  if (parts[0] !== "fork" || parts[1] !== "turn") return false;
+  if (parts.length < 5 || parts.length > 6) return false;
+  const [, , time, random, n, taken] = parts;
+  return (
+    stamp(time, random) && decimalField(n, 1) && (taken === undefined || decimalField(taken, 2))
+  );
+}
+
+/** @param {string} id */
+const lowercaseUuid = (id) => (UUID.test(id) ? id.toLowerCase() : null);
+/** @param {string} id */
+const exactNodecodeId = (id) => (validNodecodeId(id) ? id : null);
+
+/** Each harness's AK prefix, and how its ids are spelled in a claimant (null: no such claimant).
+ * A UUID folds to lowercase; a Nodecode id is case-exact, so it is kept or refused, never folded. */
+const HARNESSES =
+  /** @type {Record<string, {prefix: string; spell: (id: string) => string | null}>} */ ({
+    pi: { prefix: "session-", spell: lowercaseUuid },
+    claude: { prefix: "claude-session-", spell: lowercaseUuid },
+    codex: { prefix: "codex-session-", spell: lowercaseUuid },
+    nodecode: { prefix: "nodecode-session-", spell: exactNodecodeId },
+  });
+
+/** Unknown harnesses and ids outside a harness's form have no published AK claimant mapping.
+ * @param {string} harness @param {string} id */
+export function claimantFor(harness, id) {
+  if (!Object.hasOwn(HARNESSES, harness)) return null;
+  const { prefix, spell } = HARNESSES[harness];
+  const spelled = spell(id);
+  return spelled === null ? null : `${prefix}${spelled}`;
+}
+
+/** @param {unknown} value */
+export function parseClaimant(value) {
+  if (typeof value !== "string") return null;
+  for (const [harness, { prefix, spell }] of Object.entries(HARNESSES)) {
+    if (!value.startsWith(prefix)) continue;
+    const id = spell(value.slice(prefix.length));
+    if (id !== null) return { harness, id, claimant: `${prefix}${id}` };
+  }
+  return null;
+}
+
+/** Strip publisher ids are explicitly namespaced; a bare UUID is Pi only.
+ * @param {unknown} value */
+export function publisherClaimant(value) {
+  if (typeof value !== "string") return null;
+  if (UUID.test(value)) return claimantFor("pi", value);
+  const match = /^agent:([^:]+):(.+)$/.exec(value);
+  return match ? claimantFor(match[1], match[2]) : null;
+}

package/src/common/recovery-manifest.mjs

@@ -0,0 +1,417 @@
+// ---
+// summary: "Pure, conservative recovery links with observation coverage, never custody transfer."
+// read_when: ["changing recovery manifest proof semantics"]
+// ---
+import { createHash } from "node:crypto";
+import { claimantFor, parseClaimant } from "./recovery-identity.mjs";
+
+/** @typedef {import('./recovery-types.ts').ProcessObservation} ProcessObservation */
+/** @typedef {import('./recovery-types.ts').SessionObservation} SessionObservation */
+/** @typedef {import('./recovery-types.ts').RecoveryInputs} RecoveryInputs */
+
+export const MANIFEST_SCHEMA = "pi-activity-strip.recovery-manifest.v1";
+// /proc/stat btime has one-second precision. This is a comparison allowance, not identity proof.
+export const BIRTH_CLOCK_ALLOWANCE_MS = 2000;
+
+/** Preserve unmatched/reused live processes independently of stale registry assertions.
+ * @param {RecoveryInputs} input @returns {SessionObservation[]} */
+export function withProcessOnlyObservations(input) {
+  const result = [...input.sessions];
+  const linked = new Set(
+    input.sessions.map((s) => processLink(s, input).process?.pid).filter(Boolean),
+  );
+  for (const p of input.before.filter((p) => p.harness)) {
+    if (linked.has(p.pid)) continue;
+    result.push({
+      harness: p.harness,
+      sessionId: null,
+      pid: p.pid,
+      source: "process-scan",
+      sourceRef: `/proc/${p.pid}/stat`,
+      cwd: p.cwd,
+      startedAt: p.birthMs,
+      pidDomain: p.pidDomain,
+      procStart: p.startTicks,
+      bootId: p.bootId,
+      changed: false,
+      transcripts: [],
+    });
+  }
+  return result;
+}
+
+export const RECOVERY_CAPABILITIES = [
+  {
+    harness: "pi",
+    session: "broker-self-report",
+    transcript: "header-id",
+    currentDisplay: "unproved",
+    claimantPrefix: "session-",
+    limitation: "broker has no process-birth token; custom session roots need --pi-session-root",
+  },
+  {
+    harness: "claude",
+    session: "registry-pid-domain-procStart",
+    transcript: "filename-candidate",
+    currentDisplay: "unproved",
+    claimantPrefix: "claude-session-",
+    limitation: "registry lacks boot id; start-time mismatch retained; transcript content not read",
+  },
+  {
+    harness: "codex",
+    session: "open-rollout-header",
+    transcript: "open-descriptor",
+    currentDisplay: "unsupported",
+    claimantPrefix: "codex-session-",
+    limitation:
+      "open descriptor proves neither writer nor currently displayed thread; no cwd/recency fallback",
+  },
+  {
+    harness: "nodecode",
+    session: "shell-presence-pid-startTicks",
+    transcript: "unsupported",
+    currentDisplay: "unproved",
+    claimantPrefix: "nodecode-session-",
+    limitation:
+      "presence record lacks pid domain and boot id, so links stay unconfirmed; ids unique per home",
+  },
+  {
+    harness: "angelx",
+    session: "unsupported",
+    transcript: "unsupported",
+    currentDisplay: "unsupported",
+    claimantPrefix: null,
+    limitation:
+      "installed saved-session metadata has no verified live presence; filename PID may be historical",
+  },
+  {
+    harness: "agnt",
+    session: "unsupported",
+    transcript: "unsupported",
+    currentDisplay: "unsupported",
+    claimantPrefix: null,
+    limitation:
+      "Electron application; frontend activeConversationId has no verified process-birth publisher",
+  },
+  {
+    harness: "omp",
+    session: "unsupported",
+    transcript: "unsupported",
+    currentDisplay: "unsupported",
+    claimantPrefix: null,
+    limitation:
+      "no qualified current-session adapter; breadcrumbs and daemon client IDs are not live conversation identity",
+  },
+  {
+    harness: "unknown",
+    session: "unsupported",
+    transcript: "unsupported",
+    currentDisplay: "unsupported",
+    claimantPrefix: null,
+    limitation: "no guessed UUID, command replay, or canonical AK prefix",
+  },
+];
+
+/** @param {ProcessObservation | undefined} a @param {ProcessObservation | undefined} b */
+export function sameProcess(a, b) {
+  return Boolean(
+    a &&
+      b &&
+      a.pid === b.pid &&
+      a.startTicks === b.startTicks &&
+      a.bootId === b.bootId &&
+      a.pidDomain === b.pidDomain &&
+      a.executableIdentity === b.executableIdentity &&
+      a.ppid === b.ppid &&
+      a.harness === b.harness &&
+      a.selectorDigest === b.selectorDigest,
+  );
+}
+
+/** Namespace is checked BEFORE looking up a host PID, including coincident start ticks.
+ * @param {SessionObservation} session @param {RecoveryInputs} input */
+export function processLink(session, input) {
+  const provenance = [session.sourceRef];
+  /** @type {string[]} */
+  const uncertainties = [];
+  const result = (
+    state = "unresolved",
+    process = /** @type {ProcessObservation | null} */ (null),
+  ) => ({ state, process, provenance, uncertainties });
+  if (session.pidDomain && session.pidDomain !== input.pidDomain) {
+    uncertainties.push("foreign-pid-domain-no-mapping");
+    return result("foreign-namespace");
+  }
+  if (session.bootId && session.bootId !== input.bootId) return result("boot-mismatch");
+  if (session.changed) return result("source-changed");
+  const before = input.before.find((p) => p.pid === session.pid);
+  const after = input.after.find((p) => p.pid === session.pid);
+  if (!before) return result("not-observed");
+  provenance.push(
+    `/proc/${session.pid}/stat`,
+    `/proc/${session.pid}/exe`,
+    `/proc/${session.pid}/ns/pid`,
+  );
+  if (!sameProcess(before, after)) return result("process-changed");
+  if (before.harness !== session.harness) return result("harness-mismatch");
+  if (session.procStart && session.procStart !== before.startTicks) return result("birth-mismatch");
+  if (session.source === "process-scan") return result("process-only", before);
+  if (session.source === "codex-open-rollout") {
+    uncertainties.push("open-descriptor-is-not-writer-or-current-display");
+    return result("open-descriptor-associated", before);
+  }
+  if (session.source === "pi-broker") {
+    uncertainties.push(
+      "publisher-has-no-process-birth-token",
+      "self-report-not-current-display-proof",
+    );
+    if (
+      !session.updatedAt ||
+      session.updatedAt < input.startedAt - 12000 ||
+      session.updatedAt > input.endedAt + BIRTH_CLOCK_ALLOWANCE_MS
+    )
+      return result("stale-publisher", before);
+    if (session.startedAt < before.birthMs - BIRTH_CLOCK_ALLOWANCE_MS)
+      return result("birth-mismatch");
+    return result("reported", before);
+  }
+  if (!session.pidDomain || !session.procStart) {
+    uncertainties.push("registry-missing-pid-domain-or-birth-token");
+    return result("unconfirmed", before);
+  }
+  uncertainties.push("registry-has-no-boot-id");
+  const delta = session.startedAt - before.birthMs;
+  if (!Number.isFinite(delta) || Math.abs(delta) > BIRTH_CLOCK_ALLOWANCE_MS) {
+    uncertainties.push("registry-startedAt-differs-from-process-birth");
+    return result("uncertain-start-time", before);
+  }
+  return result("birth-correlated", before);
+}
+
+/** @param {ProcessObservation | null} process @param {RecoveryInputs} input */
+function windowLinks(process, input) {
+  if (!process)
+    return {
+      state: "unresolved",
+      windows: [],
+      provenance: [],
+      uncertainties: ["no-stable-process-link"],
+    };
+  /** @type {ProcessObservation[]} */
+  const chain = [];
+  const seen = new Set();
+  let current = process;
+  while (current && !seen.has(current.pid) && chain.length < 64) {
+    seen.add(current.pid);
+    if (
+      !sameProcess(
+        current,
+        input.after.find((p) => p.pid === current.pid),
+      )
+    ) {
+      return { state: "changed", windows: [], provenance: [], uncertainties: ["ancestor-changed"] };
+    }
+    chain.push(current);
+    const parent = input.before.find((p) => p.pid === current.ppid);
+    if (!parent) break;
+    current = parent;
+  }
+  const candidates = input.windows.filter((w) => chain.some((p) => p.pid === w.pid));
+  const stable = candidates.filter((w) =>
+    input.windowsAfter.some(
+      (a) => a.id === w.id && a.pid === w.pid && a.workspace_id === w.workspace_id,
+    ),
+  );
+  const changed =
+    stable.length !== candidates.length ||
+    input.windowsAfter.some(
+      (w) => chain.some((p) => p.pid === w.pid) && !candidates.some((b) => b.id === w.id),
+    );
+  const windows = stable.map((w) => {
+    const ws = input.workspaces.find((s) => s.id === w.workspace_id);
+    const wsStable = ws && input.workspacesAfter.some((a) => a.id === ws.id && a.idx === ws.idx);
+    return {
+      id: w.id,
+      hostPid: w.pid,
+      workspaceId: w.workspace_id,
+      workspaceIndex: wsStable ? ws.idx : null,
+      relation: "process-ancestry-containment",
+      provenance: [
+        "niri msg -j windows",
+        ...chain.map((p) => `/proc/${p.pid}/stat`),
+        "niri msg -j workspaces",
+      ],
+    };
+  });
+  return {
+    state: changed
+      ? "changed"
+      : windows.length > 1
+        ? "ambiguous"
+        : windows.length === 1
+          ? "containment-only"
+          : "not-observed",
+    windows,
+    provenance: ["niri msg -j windows (before/after)"],
+    uncertainties: [
+      "containment-is-not-exact-tab-identity",
+      ...(changed ? ["window-observation-changed"] : []),
+    ],
+  };
+}
+
+/** @param {RecoveryInputs} input @param {{includePaths?: boolean}} [options] */
+
+export function buildRecoveryManifest(input, { includePaths = false } = {}) {
+  const observations = withProcessOnlyObservations(input);
+  const sessions = observations.map((s, index) => {
+    const process = processLink(s, input);
+    const claimant = s.sessionId ? claimantFor(s.harness, s.sessionId) : null;
+    return {
+      observationId: `observation-${index + 1}`,
+      harness: s.harness,
+      session: {
+        id: s.sessionId,
+        source: s.source,
+        provenance: [s.sourceRef],
+        cwd: s.cwd,
+        reportedStartedAt: s.startedAt || null,
+      },
+      process,
+      placement: windowLinks(process.process, input),
+      transcripts: s.transcripts,
+      ak: {
+        claimant,
+        authority: "AK-only; observation does not transfer custody",
+        links:
+          /** @type {Array<{taskId: number; state: string; claimant: string; leaseExpiresAt: string; provenance: string[]}>} */ ([]),
+      },
+    };
+  });
+  const claims = input.claims.map((c) => {
+    const claimant = parseClaimant(c.claimed_by);
+    const lease = Date.parse(c.lease_expires_at);
+    const matched = claimant ? sessions.filter((s) => s.ak.claimant === claimant.claimant) : [];
+    const state = !claimant
+      ? "unsupported-claimant"
+      : !Number.isFinite(lease)
+        ? "invalid-lease"
+        : lease <= input.endedAt
+          ? "expired"
+          : c.status !== "claimed"
+            ? "not-claimed"
+            : matched.length > 1
+              ? "ambiguous-session"
+              : matched.length === 1
+                ? "exact-claimant"
+                : "session-not-observed";
+    if (state === "exact-claimant")
+      matched[0].ak.links.push({
+        taskId: c.id,
+        state,
+        claimant: c.claimed_by,
+        leaseExpiresAt: c.lease_expires_at,
+        provenance: ["ak task list --status claimed --format json --all --verbose"],
+      });
+    return {
+      taskId: c.id,
+      claimant: c.claimed_by,
+      harness: claimant?.harness ?? null,
+      leaseExpiresAt: c.lease_expires_at,
+      state,
+      observationIds: matched.map((s) => s.observationId),
+      provenance: ["ak task list --status claimed --format json --all --verbose"],
+    };
+  });
+  const manifest = {
+    schema: MANIFEST_SCHEMA,
+    readOnly: true,
+    complete: false,
+    observation: {
+      startedAt: new Date(input.startedAt).toISOString(),
+      endedAt: new Date(input.endedAt).toISOString(),
+      bootId: input.bootId,
+      pidDomain: input.pidDomain,
+      atomic: false,
+    },
+    privacy: {
+      paths: includePaths ? "included-private-output-only" : "sha256-redacted",
+      transcriptContent: "never-emitted",
+      titles: "never-emitted",
+      commandLines: "never-emitted",
+    },
+    capabilities: RECOVERY_CAPABILITIES,
+    sources: input.sources,
+    coverage: {
+      observationRows: sessions.length,
+      identifiedSessionObservations: sessions.filter((s) => s.session.id).length,
+      distinctSessionIdentities: new Set(
+        sessions.filter((s) => s.session.id).map((s) => `${s.harness}:${s.session.id}`),
+      ).size,
+      processOnlyObservations: sessions.filter((s) => !s.session.id).length,
+      processCandidates: input.before.filter((p) => p.harness).length,
+      processLinks: sessions.filter((s) => s.process.process).length,
+      processLinkStates: counts(sessions.map((s) => s.process.state)),
+      harnesses: Object.fromEntries(
+        [...new Set(sessions.map((s) => s.harness))].map((h) => [
+          h,
+          {
+            observationRows: sessions.filter((s) => s.harness === h).length,
+            distinctSessionIdentities: new Set(
+              sessions.filter((s) => s.harness === h && s.session.id).map((s) => s.session.id),
+            ).size,
+            processOnlyObservations: sessions.filter((s) => s.harness === h && !s.session.id)
+              .length,
+          },
+        ]),
+      ),
+      placementStates: counts(sessions.map((s) => s.placement.state)),
+      transcripts: counts(sessions.flatMap((s) => s.transcripts.map((t) => t.state))),
+      claimRows: claims.length,
+      claimStates: counts(claims.map((c) => c.state)),
+    },
+    limitations: [
+      "Non-atomic bounded observation; processes can start or exit after capture.",
+      "No full historical session census or transcript/context completeness claim.",
+      "No exact terminal tab/current display proof; no reopen, focus or replay command.",
+      "AK6737 owns custody; AK6481 owns native reopen; this is observation only.",
+    ],
+    sessions,
+    claims,
+    windowContainmentGroups: [
+      ...new Set(sessions.flatMap((s) => s.placement.windows.map((w) => w.id))),
+    ].map((windowId) => {
+      const contained = sessions.filter((s) => s.placement.windows.some((w) => w.id === windowId));
+      return {
+        windowId,
+        relation: "candidate-containment-not-session-count",
+        processObservations: new Set(contained.map((s) => s.process.process?.pid).filter(Boolean))
+          .size,
+        distinctSessionIdentities: new Set(
+          contained.filter((s) => s.session.id).map((s) => `${s.harness}:${s.session.id}`),
+        ).size,
+        observationIds: contained.map((s) => s.observationId),
+      };
+    }),
+  };
+  return includePaths ? manifest : redactPaths(manifest);
+}
+
+/** @param {string[]} values */
+
+function counts(values) {
+  return Object.fromEntries(
+    [...new Set(values)].sort().map((key) => [key, values.filter((v) => v === key).length]),
+  );
+}
+
+/** @template T @param {T} value @returns {T} */
+function redactPaths(value) {
+  return JSON.parse(
+    JSON.stringify(value, (_key, item) =>
+      typeof item === "string" && item.startsWith("/")
+        ? `path-sha256:${createHash("sha256").update(item).digest("hex")}`
+        : item,
+    ),
+  );
+}

package/src/common/recovery-types.ts

@@ -0,0 +1,75 @@
+// summary: Read-only recovery observation types; not AK custody or reopen authority.
+export interface ProcessObservation {
+  pid: number;
+  ppid: number;
+  startTicks: string;
+  birthMs: number;
+  bootId: string;
+  pidDomain: string;
+  executable: string;
+  executableIdentity: string;
+  selectorDigest?: string;
+  cwd: string;
+  harness: string;
+}
+export interface SessionObservation {
+  harness: string;
+  sessionId: string | null;
+  pid: number;
+  source: string;
+  sourceRef: string;
+  cwd: string;
+  startedAt: number;
+  pidDomain: string | null;
+  procStart: string | null;
+  bootId?: string | null;
+  changed: boolean;
+  updatedAt?: number;
+  transcripts: TranscriptObservation[];
+}
+export interface TranscriptObservation {
+  path: string;
+  state: string;
+  method: string;
+  identity?: string;
+  size?: number;
+  changed?: boolean;
+  sessionId?: string | null;
+}
+export interface WindowObservation {
+  id: number;
+  pid: number | null;
+  workspace_id: number | null;
+}
+export interface WorkspaceObservation {
+  id: number;
+  idx: number;
+}
+export interface SourceCoverage {
+  source: string;
+  state: string;
+  observed: number;
+  rejected: number;
+  limitations: string[];
+}
+export interface ClaimObservation {
+  id: number;
+  claimed_by: string;
+  status: string;
+  lease_expires_at: string;
+}
+export interface RecoveryInputs {
+  startedAt: number;
+  endedAt: number;
+  bootId: string;
+  pidDomain: string;
+  before: ProcessObservation[];
+  after: ProcessObservation[];
+  sessions: SessionObservation[];
+  windows: WindowObservation[];
+  windowsAfter: WindowObservation[];
+  workspaces: WorkspaceObservation[];
+  workspacesAfter: WorkspaceObservation[];
+  claims: ClaimObservation[];
+  sources: SourceCoverage[];
+}