@tryinget/pi-activity-strip 0.9.0 → 0.10.0

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[];
+}

package/src/common/ribbon-status.mjs

@@ -0,0 +1,41 @@
+// ---
+// summary: "renders only allowlisted ribbon observation fields, never arbitrary diagnostic text"
+// read_when:
+//   - "changing diagnostic output or its redaction boundary"
+// ---
+
+import { normalizeKeyboardObservation } from "./keyboard-observation.mjs";
+
+/** @param {unknown} value @param {string[]} allowed */
+const enumValue = (value, allowed) =>
+  typeof value === "string" && allowed.includes(value) ? value : "unknown";
+/** @param {unknown} value */
+const hashValue = (value) =>
+  typeof value === "string" && /^[a-f0-9]{64}$/.test(value) ? value : "unknown";
+
+/** @param {import("./contracts.ts").ActivityStripRuntimeStatus["ribbonDiagnostics"]} diagnostics */
+export function formatRibbonDiagnostics(diagnostics) {
+  if (!diagnostics) return ["ribbon diagnostics: not reported by this controller"];
+  const build = diagnostics.panelBuild;
+  const native = normalizeKeyboardObservation({
+    ...diagnostics.nativeKeyboardObservation,
+    protocol: 2,
+    type: "keyboard-observation",
+  });
+  return [
+    `visibility reason: ${enumValue(diagnostics.visibilityReason, ["starting", "error", "unproven-focus", "non-agent-focus", "no-admitted-owner", "awaiting-panel-visibility", "eligible-agent-context", "eligible-presence-context", "persistent-workspace"])}`,
+    `keyboard authorization: ${enumValue(diagnostics.keyboardAuthorization, ["none", "hover", "explicit"])} (not proof of capture)`,
+    ...(native
+      ? [
+          `capture expiry: last native observation (${native.origin}; ${native.reason}), not current authority`,
+          `native monotonic ms: ${native.nativeMs}; idle deadline ms: ${native.deadlineMs ?? "not applicable (explicit)"}; request: ${native.request} (same native process clock only; not a countdown)`,
+        ]
+      : ["capture expiry: not observed (native monotonic clock)"]),
+    `private protocol: expected ${Number.isSafeInteger(diagnostics.expectedPrivateProtocol) ? diagnostics.expectedPrivateProtocol : "unknown"}, receipt ${Number.isSafeInteger(build?.privateProtocol) ? build.privateProtocol : "unknown"}`,
+    `panel receipt: ${enumValue(build?.state, ["pending", "unavailable", "changed-during-observation", "incompatible", "receipt-matched", "receipt-mismatch"])}`,
+    `panel PID executable sha256: ${hashValue(build?.binarySha256)} (sampled; not custody proof)`,
+    `panel build sampled at: ${Number.isSafeInteger(diagnostics.panelBuildObservedAt) ? diagnostics.panelBuildObservedAt : "unknown"} (stale after process changes)`,
+    `receipted native source sha256: ${hashValue(build?.receiptedSourceSha256)}`,
+    `controller startup source sha256: ${hashValue(diagnostics.controllerStartupSourceSha256)} (observation, not loaded-byte proof)`,
+  ];
+}

package/src/common/status-report.mjs

@@ -6,6 +6,24 @@
 
 /** @typedef {import("./contracts.ts").BrokerResponse} BrokerResponse */
 
+import { formatRibbonDiagnostics } from "./ribbon-status.mjs";
+
+/**
+ * When the AK deferral list was read and how long it may be reused; empty for unusable values.
+ * @param {{akTaskDeferredReadAt?: number | null; akTaskDeferredMaxAgeMs?: number}} runtime
+ */
+function deferralListAge(runtime) {
+  const readAt = runtime.akTaskDeferredReadAt;
+  if (typeof readAt !== "number" || !Number.isFinite(readAt) || Math.abs(readAt) > 8.64e15)
+    return "";
+  const maxAge = runtime.akTaskDeferredMaxAgeMs;
+  const reuse =
+    typeof maxAge === "number" && Number.isFinite(maxAge) && maxAge > 0
+      ? `, reused up to ${Math.round(maxAge / 1000)} s`
+      : "";
+  return `; deferral list read ${new Date(readAt).toISOString()}${reuse}`;
+}
+
 /** @param {BrokerResponse | null | undefined} result */
 export function formatBrokerRuntimeStatus(result) {
   if (!result?.ok) return "stopped";
@@ -26,6 +44,14 @@ export function formatBrokerRuntimeStatus(result) {
   if (typeof runtime.windowVisible === "boolean") {
     lines.push(`surface visible: ${runtime.windowVisible ? "yes" : "no"}`);
   }
+  if (typeof runtime.panelExpanded === "boolean") {
+    lines.push(
+      runtime.panelExpanded && runtime.windowVisible === false
+        ? "expansion: stale (hidden surface)"
+        : `expansion: ${runtime.panelExpanded ? "expanded" : "compact"} (reported; cause not observed)`,
+    );
+  }
+  lines.push(...formatRibbonDiagnostics(runtime.ribbonDiagnostics));
   if (typeof runtime.rendererCardCount === "number") {
     const hidden =
       typeof runtime.rendererHiddenTabCardCount === "number"
@@ -64,7 +90,7 @@ export function formatBrokerRuntimeStatus(result) {
     if (runtime.akTaskState === "ok") {
       const orphaned = Number(runtime.akTaskOrphanCount ?? 0);
       lines.push(
-        `AK task refs: ok (${runtime.akTaskClaimCount ?? 0} live claims, ${runtime.akTaskDeferredCount ?? 0} deferred${orphaned > 0 ? `, ${orphaned} orphaned claims` : ""})`,
+        `AK task refs: ok (${runtime.akTaskClaimCount ?? 0} live claims, ${runtime.akTaskDeferredCount ?? 0} deferred${orphaned > 0 ? `, ${orphaned} orphaned claims` : ""}${deferralListAge(runtime)})`,
       );
     } else if (runtime.akTaskState !== "disabled") {
       lines.push(
@@ -101,10 +127,19 @@ export function summarizeBrokerRuntimeStatus(result) {
 
   const runtime = result.runtimeStatus;
   if (!runtime) {
-    return { headline: "Activity strip is running", level: "info" };
+    return {
+      headline: "Activity strip broker is running; overlay readiness is unknown",
+      level: "warning",
+    };
   }
 
   if (runtime.state === "ready") {
+    if (runtime.tabInventoryState === "failed" || runtime.tabInventoryState === "unavailable") {
+      return {
+        headline: `Activity strip overlay is ready; tab inventory ${runtime.tabInventoryState}`,
+        level: "warning",
+      };
+    }
     return { headline: "Activity strip is running and ready", level: "info" };
   }
 

package/src/common/workspace-view.mjs

@@ -5,6 +5,7 @@
 // ---
 
 import { canVerifyTabVisibility, placeSessionWindow } from "./niri-focus.mjs";
+import { isPresenceApp } from "./presence-apps.mjs";
 import { projectSessionCards, sessionCardId } from "./session-cards.mjs";
 import { parseTerminalTitleBinding } from "./surface-bindings.mjs";
 import { canonicalGhosttyTerminalKey } from "./terminal-identity.mjs";
@@ -40,6 +41,50 @@ export function resolveSurfaceVisibility(window, session, placement, options = {
   return "unknown";
 }
 
+/** @typedef {"agent" | "neutral" | "non-agent" | "unknown" | "none"} FocusKind */
+/**
+ * Classify exact admitted Niri ownership, never app-id/title heuristics. Card ownership alone
+ * makes a window "agent"; a focused presence application that owns no exact card is "neutral":
+ * the strip stays on screen over it and the window itself, not a card, is the interaction source.
+ * @param {Array<Record<string, unknown>>} windows
+ * @param {Record<string, unknown>} workspace
+ * @param {Array<Record<string, unknown>>} cards
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {FocusKind}
+ */
+export function classifyWorkspaceFocus(windows, workspace, cards, env = process.env) {
+  if (
+    windows.some(
+      (window) => !Number.isInteger(window?.id) || typeof window?.is_focused !== "boolean",
+    )
+  )
+    return "unknown";
+  const focused = windows.filter((window) => window.is_focused === true);
+  // Niri retains an active window while an exclusive layer surface owns the keyboard. NULL
+  // alone is not ownership: only the controller's pending explicit request can admit it.
+  if (focused.length === 0) return windows.length > 0 ? "none" : "unknown";
+  if (focused.length !== 1) return "unknown";
+  const window = focused[0];
+  if (!Number.isInteger(window.id) || window.workspace_id !== workspace.id) return "unknown";
+  return classifyAdmittedWindowFocus(Number(window.id), cards, window, env);
+}
+
+/** Exact Niri focus events may update eligibility before a slower full projection finishes.
+ * Without the window's own facts presence cannot be proven, so the strict result stands.
+ * @param {number} windowId @param {Array<Record<string, unknown>>} cards
+ * @param {Record<string, unknown> | null} [window] @param {NodeJS.ProcessEnv} [env]
+ * @returns {FocusKind}
+ */
+export function classifyAdmittedWindowFocus(windowId, cards, window = null, env = process.env) {
+  if (!Number.isInteger(windowId)) return "unknown";
+  const visible = cards.filter(
+    (card) => card.windowId === windowId && card.surfaceVisible !== false,
+  ).length;
+  if (visible === 1) return "agent";
+  if (window?.id === windowId && isPresenceApp(window.app_id, env)) return "neutral";
+  return visible === 0 ? "non-agent" : "unknown";
+}
+
 /**
  * Project the global broker snapshot onto one exact Niri workspace. Membership requires an exact
  * window placement: a visible title, or a hidden tab attributed through its Ghostty host process.
@@ -129,8 +174,17 @@ export function resolveWorkspaceView(windows, workspace, sessions, options = {})
       windows.some((window) => window?.id === session.windowId && window?.is_focused === true),
   );
   const focusedCard = focusedCandidates.length === 1 ? focusedCandidates[0] : null;
+  const focusedWindows = windows.filter((window) => window?.is_focused === true);
+  const focusWindow =
+    focusedWindows.length === 1 &&
+    Number.isInteger(focusedWindows[0]?.id) &&
+    focusedWindows[0].workspace_id === workspace.id
+      ? Number(focusedWindows[0].id)
+      : null;
   return {
     workspace,
+    focusKind: classifyWorkspaceFocus(windows, workspace, projectedSessions, options.env),
+    focusWindowId: focusWindow,
     sessions: projectedSessions,
     focusedSessionId: focusedCard ? String(focusedCard.sessionId ?? "") || null : null,
     focusedCardId: focusedCard ? String(focusedCard.cardId ?? "") || null : null,