@fitchmultz/pi-subagents 0.52.16 → 0.52.18

package/scripts/real-pi-live.mjs

@@ -6,48 +6,14 @@ import process from "node:process";
 import { setTimeout as delay } from "node:timers/promises";
 import { isChildTreeAlive } from "../src/shared/post-exit-stdio-guard.ts";
 import { filesIn, processRef } from "./real-pi-processes.mjs";
+import assert from "node:assert/strict";
+import { isRecord } from "../src/shared/unknown.ts";
+import { sessionView } from "./real-pi-events.mjs";
 
-/**
- * One JSON record decoded from the RPC main's stdout stream.
- * @typedef {Record<string, unknown> & { type?: string }} RpcEvent
- */
-/**
- * A message record projected from a message_end event.
- * @typedef {object} StreamedMessage
- * @property {string | undefined} customType
- * @property {string | undefined} role
- * @property {{ type?: string, text?: string }[] | undefined} content
- * @property {string | undefined} stopReason
- * @property {SessionNotice | undefined} details
- */
-/**
- * A completion notification saved from a custom agent-completion message.
- * @typedef {object} SessionNotice
- * @property {string | undefined} id
- * @property {number | undefined} index
- * @property {{ status?: string } | undefined} result
- * @property {{ text?: string } | undefined} page
- */
-/**
- * A launch/continuation receipt projected from a tool_execution_end event.
- * @typedef {object} SessionReceipt
- * @property {string | undefined} tool
- * @property {string | undefined} receipt
- * @property {string | undefined} name
- * @property {string | undefined} id
- * @property {string | undefined} sessionFile
- * @property {string | undefined} context
- * @property {number | undefined} index
- * @property {string | undefined} predecessor
- */
-/**
- * The verified view of one live RPC session.
- * @typedef {object} SessionView
- * @property {RpcEvent[]} events
- * @property {SessionReceipt[]} receipts
- * @property {Map<string | undefined, SessionNotice>} notices
- * @property {{ index: number, text: string, stopReason: string | undefined }[]} replies
- */
+/** @typedef {import("./real-pi-events.mjs").RpcEvent} RpcEvent */
+/** @typedef {import("./real-pi-events.mjs").SessionReceipt} SessionReceipt */
+/** @typedef {import("./real-pi-events.mjs").SessionNotice} SessionNotice */
+/** @typedef {import("./real-pi-events.mjs").SessionView} SessionView */
 /**
  * The shared smoke runner options (built by scripts/real-pi-smoke.mjs).
  * @typedef {object} LiveSmokeOptions
@@ -96,47 +62,6 @@ function modelArgs() {
   return args;
 }
 
-function addMessage(
-  /** @type {SessionView} */ view,
-  /** @type {StreamedMessage | undefined} */ message,
-  /** @type {number} */ index,
-) {
-  if (message?.customType === "agent-completion" && message.details !== undefined) {
-    view.notices.set(message.details.id, { ...message.details, index });
-  } else if (message?.role === "assistant") {
-    const text = (message.content ?? []).filter((part) => part.type === "text");
-    view.replies.push({
-      index,
-      text: text.map((part) => part.text).join("\n"),
-      stopReason: message.stopReason,
-    });
-  }
-}
-
-function sessionView(/** @type {RpcEvent[]} */ events) {
-  /** @type {SessionView} */
-  const view = { events, receipts: [], notices: new Map(), replies: [] };
-  for (const [index, event] of events.entries()) {
-    // oxlint-disable typescript/no-unsafe-type-assertion, typescript/no-unnecessary-type-assertion -- RpcEvent carries unknown payloads
-    const details = /** @type {SessionReceipt | undefined} */ (
-      /** @type {{ details?: SessionReceipt } | undefined} */ (event.result)?.details
-    );
-    // oxlint-enable typescript/no-unsafe-type-assertion, typescript/no-unnecessary-type-assertion
-    if (event.type === "message_end") {
-      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- RpcEvent carries unknown payloads
-      addMessage(view, /** @type {StreamedMessage} */ (event.message), index);
-    } else if (
-      event.type === "tool_execution_end" &&
-      details !== undefined &&
-      (details.receipt === "launch" || details.receipt === "continuation")
-    ) {
-      // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- RpcEvent carries unknown payloads
-      view.receipts.push({ ...details, index, tool: /** @type {string} */ (event.toolName) });
-    }
-  }
-  return view;
-}
-
 // Persistent RPC main: launch/continuation receipts are not completion, so the main stays
 // alive until every receipt's native completion notification has resumed and settled it.
 function rpcSession(
@@ -158,13 +83,15 @@ function rpcSession(
     for (let end = buffer.indexOf("\n"); end >= 0; end = buffer.indexOf("\n")) {
       const line = buffer.slice(0, end).replace(/\r$/, "");
       buffer = buffer.slice(end + 1);
-      /** @type {RpcEvent} */ let record;
+      /** @type {unknown} */ let record;
       try {
-        // oxlint-disable-next-line typescript/no-unsafe-assignment
         record = JSON.parse(line);
       } catch {
         continue;
       }
+      if (!isRecord(record)) {
+        continue;
+      }
       events.push(record);
       if (record.type === "response" && record.id === "smoke" && record.success !== true) {
         settle.reject(new Error(`RPC prompt was rejected: ${JSON.stringify(record.error)}`));
@@ -229,19 +156,13 @@ async function runLiveSession(
     // Verify while the main is alive; only then request its orderly shutdown.
     await verify(view);
   } finally {
-    // oxlint-disable-next-line typescript/no-unnecessary-condition -- the finally also runs when startup failed
-    session?.close();
+    session.close();
     writeFileSync(
       join(options.root, `${label.replace(/ /g, "-")}.jsonl`),
-      // oxlint-disable-next-line typescript/no-unnecessary-condition, typescript/strict-boolean-expressions -- the finally also runs when startup failed
-      session ? session.events.map((event) => JSON.stringify(event)).join("\n") : "",
+      session.events.map((event) => JSON.stringify(event)).join("\n"),
     );
   }
   await exited;
-  // oxlint-disable-next-line typescript/no-unnecessary-condition -- flow analysis misses the race failure path
-  if (view === undefined) {
-    throw new Error(`${label} settled without a session view`);
-  }
   return view;
 }
 
@@ -250,11 +171,12 @@ function* savedAssistantModels(/** @type {string} */ file) {
     if (line.trim() === "") {
       continue;
     }
-    /** @type {{ type?: string, message?: { role?: string, provider?: string, model?: string } }} */
-    // oxlint-disable-next-line typescript/no-unsafe-assignment
-    const entry = JSON.parse(line);
-    if (entry.type === "message" && entry.message?.role === "assistant") {
-      yield `${entry.message.provider ?? ""}/${entry.message.model ?? ""}`;
+    /** @type {unknown} */ const entry = JSON.parse(line);
+    assert.ok(isRecord(entry));
+    if (entry.type === "message" && isRecord(entry.message) && entry.message.role === "assistant") {
+      const { provider = "", model = "" } = entry.message;
+      assert.ok(typeof provider === "string" && typeof model === "string");
+      yield `${provider}/${model}`;
     }
   }
 }
@@ -307,9 +229,10 @@ function asyncCompletion(/** @type {string} */ dir, /** @type {string} */ runId)
   if (!existsSync(resultPath)) {
     return { status: "missing" };
   }
-  /** @type {{ id: string, status: string, error?: string }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
-  const result = JSON.parse(readFileSync(resultPath, "utf8"));
+  /** @type {unknown} */ const result = JSON.parse(readFileSync(resultPath, "utf8"));
+  assert.ok(isRecord(result));
+  assert.ok(typeof result.status === "string");
+  assert.ok(result.error === undefined || typeof result.error === "string");
   if (result.id !== runId) {
     throw new Error("Async completion belongs to another saved run");
   }
@@ -320,9 +243,8 @@ function asyncCompletion(/** @type {string} */ dir, /** @type {string} */ runId)
   if (!existsSync(processPath)) {
     return { status: "completed; actor exit unconfirmed" };
   }
-  /** @type {{ pid: number }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
-  const actor = JSON.parse(readFileSync(processPath, "utf8"));
+  /** @type {unknown} */ const actor = JSON.parse(readFileSync(processPath, "utf8"));
+  assert.ok(isRecord(actor) && typeof actor.pid === "number");
   return {
     status: result.status,
     output: isChildTreeAlive(processRef(actor.pid))
@@ -356,7 +278,6 @@ async function waitForAsyncCompletion(
       return;
     }
     // Result publication is not process exit; retain resources until final actor writes finish.
-    // oxlint-disable-next-line no-await-in-loop
     await delay(100, undefined, { signal });
   }
   throw new Error(
@@ -395,7 +316,7 @@ function requireFinalReply(
   /** @type {RegExp} */ pattern,
 ) {
   const last = view.replies.at(-1);
-  const notified = Math.max(-1, ...[...view.notices.values()].map(({ index }) => index ?? -1));
+  const notified = Math.max(-1, ...[...view.notices.values()].map(({ index }) => index));
   if (last === undefined || last.stopReason !== "stop" || last.index < notified) {
     throw new Error(
       `${label} did not finish a successful reply after its final completion notification.`,
@@ -410,7 +331,7 @@ function requireCompletion(
   /** @type {string} */ expected,
 ) {
   const notice = view.notices.get(receipt.id);
-  if (notice?.result?.status !== "completed" || notice.page?.text?.trim() !== expected) {
+  if (notice?.result.status !== "completed" || notice.page.text?.trim() !== expected) {
     throw new Error(`Run ${receipt.id ?? ""} completion notification did not report: ${expected}`);
   }
 }
@@ -435,7 +356,6 @@ async function runBasicLiveSmoke(
   for (const [kind, prompt, tool] of prompts) {
     const label = `real Pi ${kind} prompt`;
     // Keep separate native parent sessions so each smoke owns its saved runs.
-    // oxlint-disable-next-line no-await-in-loop
     await runLiveSession(runOptions, {
       label,
       prompt,
@@ -524,7 +444,7 @@ function topologyLinksPreserved(first, continued, forked, firstNotice) {
 
 function requireForkTopology(/** @type {SessionView} */ view) {
   const kinds = view.receipts.map(
-    ({ tool, receipt, context }) => `${tool ?? ""}:${receipt ?? ""}:${context ?? ""}`,
+    ({ tool, receipt, context }) => `${tool}:${receipt}:${context ?? ""}`,
   );
   const expected = [
     "agent_runs:continuation:fresh",

package/scripts/real-pi-processes.mjs

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import assert from "node:assert/strict";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -9,7 +10,6 @@ import {
   trySignalChildTree,
 } from "../src/shared/post-exit-stdio-guard.ts";
 
-// oxlint-disable-next-line typescript/strict-void-return
 const execFileAsync = promisify(execFile);
 
 /**
@@ -69,10 +69,8 @@ export function processRef(/** @type {number} */ pid) {
 // This attempt owns only PIDs discovered from private run files or known direct children.
 // Credentials and artifacts must remain available until all owned workers and the broker exit.
 export class SmokeProcesses {
-  // oxlint-disable-next-line typescript/prefer-readonly -- JSDoc class fields cannot express readonly
-  /** @type {Map<number, ProcessEntry>} */ #processes = new Map();
-  // oxlint-disable-next-line typescript/prefer-readonly -- JSDoc class fields cannot express readonly
-  /** @type {SmokeProcessOptions} */ #options;
+  /** @readonly @type {Map<number, ProcessEntry>} */ #processes = new Map();
+  /** @readonly @type {SmokeProcessOptions} */ #options;
 
   constructor(/** @type {SmokeProcessOptions} */ { cwd, env, timeoutMs, signal, root }) {
     this.#options = { cwd, env, timeoutMs, signal, root };
@@ -103,83 +101,84 @@ export class SmokeProcesses {
   run(label, command, args, input) {
     const { cwd, env, timeoutMs, signal } = this.#options;
     signal.throwIfAborted();
-    return new Promise((resolve, reject) => {
-      /** @type {Promise<void> | undefined} */ let discovery;
-      /** @type {string | undefined} */ let discoveryError;
-      const finish = async (
-        /** @type {Error | undefined} */ error,
-        /** @type {string} */ output = "",
-      ) => {
-        clearTimeout(timer);
-        clearInterval(watcher);
-        signal.removeEventListener("abort", cancel);
-        await discovery;
-        if (error) {
-          reject(error);
+    /** @type {PromiseWithResolvers<string>} */
+    const completion = Promise.withResolvers();
+    /** @type {Promise<void> | undefined} */ let discovery;
+    /** @type {string | undefined} */ let discoveryError;
+    let child;
+    try {
+      child = execFile(command, args, spawnOptions(cwd, env), (error, stdout, stderr) => {
+        const output = `${stdout}${stderr}`;
+        if (error === null) {
+          completion.resolve(output);
         } else {
-          resolve(output);
-        }
-      };
-      const failure = (
-        /** @type {import("node:child_process").ExecFileException | null} */ error,
-        /** @type {string} */ output,
-      ) =>
-        error === null
-          ? undefined
-          : new Error(
+          completion.reject(
+            new Error(
               `${label} failed with ${error.code ?? "spawn error"}\nCommand: ${command} ${args.join(" ")}\n${output}`,
-            );
-      const child = execFile(command, args, spawnOptions(cwd, env), (error, stdout, stderr) => {
-        const output = `${stdout}${stderr}`;
-        // oxlint-disable-next-line typescript/no-floating-promises -- finish settles the outer promise by design
-        void finish(failure(error, output), output);
+            ),
+          );
+        }
       });
-      attachChildProcessLifecycle(child);
-      if (child.pid !== undefined) {
-        /** @type {ProcessEntry} */ const entry = { child };
-        this.#processes.set(child.pid, entry);
-        child.once("close", () => {
-          entry.exited = !isChildTreeAlive(child);
-        });
-      }
-      // Discover detached startup children even if their parent's startup fails.
-      const watcher = setInterval(() => {
-        discovery ??= this.#collect()
-          .catch((/** @type {unknown} */ error) => {
-            const message = error instanceof Error ? error.message : JSON.stringify(error);
-            if (message !== discoveryError) {
-              console.error(`[real-pi-smoke] process discovery: ${message}`);
-            }
-            discoveryError = message;
-          })
-          .finally(() => {
-            discovery = undefined;
-          });
-      }, 100);
-      // The outer finally stops parents AND detached workers; rejecting must not kill parents first.
-      const timer = setTimeout(() => {
-        // oxlint-disable-next-line typescript/no-floating-promises -- finish settles the outer promise by design
-        void finish(
-          new Error(
-            `${label} timed out after ${timeoutMs}ms\nCommand: ${command} ${args.join(" ")}`,
-          ),
-        );
-      }, timeoutMs);
-      const cancel = () => {
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion, typescript/no-floating-promises -- signal.reason is any; finish settles the outer promise
-        void finish(/** @type {Error | undefined} */ (signal.reason));
-      };
-      signal.addEventListener("abort", cancel, { once: true });
-      child.stdin?.on("error", () => {
-        // A command may exit without reading RPC input; execFile reports its exit failure.
+    } catch (error) {
+      return Promise.reject(error);
+    }
+    attachChildProcessLifecycle(child);
+    if (child.pid !== undefined) {
+      /** @type {ProcessEntry} */ const entry = { child };
+      this.#processes.set(child.pid, entry);
+      child.once("close", () => {
+        entry.exited = !isChildTreeAlive(child);
       });
-      // A function input owns a persistent RPC stdin and closes it to request orderly shutdown.
+    }
+    // Discover detached startup children even if their parent's startup fails.
+    const watcher = setInterval(() => {
+      discovery ??= this.#collect()
+        .catch((/** @type {unknown} */ error) => {
+          const message = error instanceof Error ? error.message : JSON.stringify(error);
+          if (message !== discoveryError) {
+            console.error(`[real-pi-smoke] process discovery: ${message}`);
+          }
+          discoveryError = message;
+        })
+        .finally(() => {
+          discovery = undefined;
+        });
+    }, 100);
+    // The outer finally stops parents AND detached workers; rejecting must not kill parents first.
+    const timer = setTimeout(() => {
+      completion.reject(
+        new Error(`${label} timed out after ${timeoutMs}ms\nCommand: ${command} ${args.join(" ")}`),
+      );
+    }, timeoutMs);
+    const cancel = () => {
+      /** @type {unknown} */ const reason = signal.reason;
+      completion.reject(reason);
+    };
+    signal.addEventListener("abort", cancel, { once: true });
+    child.stdin?.on("error", () => {
+      // A command may exit without reading RPC input; execFile reports its exit failure.
+    });
+    // A function input owns a persistent RPC stdin and closes it to request orderly shutdown.
+    try {
       if (typeof input === "function") {
         input(child);
       } else {
         child.stdin?.end(input);
       }
-    });
+    } catch (error) {
+      completion.reject(error);
+    }
+    async function waitForCompletion() {
+      try {
+        return await completion.promise;
+      } finally {
+        clearTimeout(timer);
+        clearInterval(watcher);
+        signal.removeEventListener("abort", cancel);
+        await discovery;
+      }
+    }
+    return waitForCompletion();
   }
 
   #readRunPids() {
@@ -194,9 +193,10 @@ export class SmokeProcesses {
     const runs = join(agentDir, "sessions", "agent-runs");
     for (const file of filesIn(runs)) {
       if (basename(file) === "process.json" && basename(dirname(file)) === "actor.lock") {
-        /** @type {{ pid: number }} */
-        // oxlint-disable-next-line typescript/no-unsafe-assignment
+        /** @type {unknown} */
         const record = JSON.parse(readFileSync(file, "utf8"));
+        assert.ok(typeof record === "object" && record !== null && "pid" in record);
+        assert.ok(typeof record.pid === "number");
         this.#remember(record.pid);
       }
     }
@@ -231,10 +231,8 @@ export class SmokeProcesses {
       if (entry.exited !== true) {
         entry.exited = !isChildTreeAlive(entry.child);
       }
-      // oxlint-disable-next-line typescript/no-unnecessary-boolean-literal-compare -- exited stays optional under tsc
-      if (entry.exited !== true) {
+      if (!entry.exited) {
         // The Map expands during discovery; sequential traversal covers newly found grandchildren.
-        // oxlint-disable-next-line no-await-in-loop
         await this.#discoverChildren(entry.child);
       }
     }
@@ -246,8 +244,7 @@ export class SmokeProcesses {
       if (entry.exited !== true) {
         entry.exited = !isChildTreeAlive(entry.child);
       }
-      // oxlint-disable-next-line typescript/no-unnecessary-boolean-literal-compare -- exited stays optional under tsc
-      if (entry.exited !== true) {
+      if (!entry.exited) {
         alive.push(entry);
       }
     }
@@ -273,7 +270,6 @@ export class SmokeProcesses {
       let collected = false;
       try {
         // Ownership discovery must finish before this iteration signals processes.
-        // oxlint-disable-next-line no-await-in-loop
         await this.#collect();
         collected = true;
       } catch (error) {
@@ -290,7 +286,6 @@ export class SmokeProcesses {
       }
       this.#signal(alive);
       // Recheck liveness after signals; concurrent polling would race tree cleanup.
-      // oxlint-disable-next-line no-await-in-loop
       await delay(50);
     }
   }

package/scripts/real-pi-smoke.mjs

@@ -4,6 +4,8 @@ import { join, resolve } from "node:path";
 import process from "node:process";
 import { runLiveSmoke } from "./real-pi-live.mjs";
 import { SmokeProcesses } from "./real-pi-processes.mjs";
+import assert from "node:assert/strict";
+import { isRecord, isUnknownArray } from "../src/shared/unknown.ts";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 
@@ -123,9 +125,8 @@ async function verifyBundledResources(
       throw new Error(`bundled Pi resources did not register ${name}:\n${output}`);
     }
   }
-  /** @type {string[]} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
-  const tools = JSON.parse(readFileSync(marker, "utf8"));
+  /** @type {unknown} */ const tools = JSON.parse(readFileSync(marker, "utf8"));
+  assert.ok(isUnknownArray(tools));
   for (const name of ["delegate", "agent_runs", "intercom"]) {
     if (!tools.includes(name)) {
       throw new Error(`${name} must be eager on the single package entry`);
@@ -146,17 +147,15 @@ async function verifyBundledResources(
 
 /**
  * @param {string} output
- * @returns {{ type?: string, id?: string, success?: boolean, data?: { commands?: { name?: string }[] } } | undefined}
+ * @returns {Record<string, unknown> | undefined}
  */
 function commandResponse(output) {
-  /** @type {{ type?: string, id?: string, success?: boolean, data?: { commands?: { name?: string }[] } } | undefined} */
+  /** @type {Record<string, unknown> | undefined} */
   let response;
   for (const line of output.split(/\r?\n/)) {
     try {
-      /** @type {{ type?: string, id?: string, success?: boolean, data?: { commands?: { name?: string }[] } }} */
-      // oxlint-disable-next-line typescript/no-unsafe-assignment
-      const parsed = JSON.parse(line);
-      if (parsed.type === "response" && parsed.id === "commands") {
+      /** @type {unknown} */ const parsed = JSON.parse(line);
+      if (isRecord(parsed) && parsed.type === "response" && parsed.id === "commands") {
         response = parsed;
       }
     } catch {
@@ -166,15 +165,18 @@ function commandResponse(output) {
   return response;
 }
 
-function registeredCommands(
-  /** @type {{ success?: boolean, data?: { commands?: { name?: string }[] } } | undefined} */ response,
-) {
-  return response !== undefined &&
-    response.success === true &&
-    response.data !== undefined &&
-    Array.isArray(response.data.commands)
-    ? response.data.commands.map((command) => command.name)
-    : [];
+function registeredCommands(/** @type {Record<string, unknown> | undefined} */ response) {
+  if (
+    response?.success !== true ||
+    !isRecord(response.data) ||
+    !isUnknownArray(response.data.commands)
+  ) {
+    return [];
+  }
+  return response.data.commands.map((command) => {
+    assert.ok(isRecord(command));
+    return command.name;
+  });
 }
 
 function createProject(/** @type {string} */ root) {

package/src/agent/host.ts

@@ -108,7 +108,7 @@ export async function loadSDK(root: string): Promise<HostSDK> {
     return resolvedSDK;
   }
   // Selected host SDK, not a second package-local runtime hidden behind Jiti aliases.
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  // oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: selected host module must retain its runtime identity.
   const sdk: HostSDK = await import(pathToFileURL(path.join(root, "dist/index.js")).href);
   return sdk;
 }

package/src/agent/notifications.ts

@@ -8,17 +8,20 @@ import type { Launch, Result } from "./contracts.ts";
 import { launchAt, list, runDirectory } from "./storage.ts";
 import { readCanonicalResult, readResult } from "./usage.ts";
 
+function isStringSet(value: unknown): value is Set<string> {
+  if (!(value instanceof Set)) {
+    return false;
+  }
+  const entries: Set<unknown> = value;
+  return [...entries].every((entry) => typeof entry === "string");
+}
+
 function queuedAdmissions(): Set<string> {
   const store = globalThis as Record<string, unknown>;
   const existing = store.__pi_single_agent_admissions__;
-  if (existing instanceof Set) {
-    const values: Set<unknown> = existing;
-    const strings = [...values].filter((value): value is string => typeof value === "string");
-    if (strings.length === values.size) {
-      // Keep one live queue identity across native extension reloads.
-      // oxlint-disable-next-line typescript/no-unsafe-return
-      return existing;
-    }
+  if (isStringSet(existing)) {
+    // Keep one live queue identity across native extension reloads.
+    return existing;
   }
   const queued = new Set<string>();
   store.__pi_single_agent_admissions__ = queued;

package/src/agent/observe-layout.ts

@@ -15,11 +15,11 @@ if (manifest === undefined) {
   throw new Error("Cannot locate the native Pi TUI package.");
 }
 const root = pathToFileURL(path.join(path.dirname(manifest), "dist/index.js"));
-// oxlint-disable-next-line typescript/no-unsafe-assignment
+// oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: resolve the selected host TUI, not a second package instance.
 const tuiPromise: Promise<typeof Tui> = import(root.href);
-// oxlint-disable-next-line typescript/no-unsafe-assignment
+// oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: layout must share the selected host TUI instance.
 const layoutPromise: Promise<typeof Layout> = import(new URL("./layout.js", root).href);
-// oxlint-disable-next-line typescript/no-unsafe-assignment
+// oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: dispatch must share the selected host TUI instance.
 const dispatchPromise: Promise<typeof Dispatch> = import(new URL("./tui.js", root).href);
 const [tui, layout, dispatch, sdk] = await Promise.all([
   tuiPromise,

package/src/agent/parking.ts

@@ -400,7 +400,6 @@ async function awaitWake(
         throw new Error(failure);
       }
       // DirectoryWatch reconciles dropped hints without imposing a deadline on native startup.
-      // oxlint-disable-next-line no-await-in-loop
       await wake.sleep(200);
     }
   } finally {

package/src/agent/process.ts

@@ -63,9 +63,7 @@ export async function observeAlive(identities: readonly ClaimedProcess[]): Promi
     // One `ps` at a time: each spawn briefly holds the event loop, so concurrent spawns add up.
     const { pid, identity, clock } = claim;
     verdicts.push(
-      probe(claim) ??
-        // oxlint-disable-next-line no-await-in-loop
-        !(await observeChildProcessReplaced(pid, identity, claim.published, clock)),
+      probe(claim) ?? !(await observeChildProcessReplaced(pid, identity, claim.published, clock)),
     );
   }
   return verdicts;
@@ -243,7 +241,6 @@ async function awaitStopping(
         throw new Error("Previous actor is still stopping; no replacement was launched.");
       }
       // The old actor must actually exit before replacing its generation.
-      // oxlint-disable-next-line no-await-in-loop
       await delay(25);
     }
   }

package/src/agent/runner.ts

@@ -344,13 +344,11 @@ class Actor {
           this.retry = false;
           this.pending().forEach((command) => this.accept(command));
         }
-        // oxlint-disable-next-line no-await-in-loop
         if (await this.park(runtime, parked)) {
           return;
         }
         const polling = this.retry || this.stopping || watch === "unwatched";
         const tick = Math.max(1, this.nextParentCheck - performance.now());
-        // oxlint-disable-next-line no-await-in-loop
         await this.wake.sleep(polling ? 100 : tick);
       }
     } finally {

package/src/agent/shutdown.ts

@@ -44,7 +44,6 @@ async function waitForExit(targets: readonly ProcessIdentity[], timeout: number)
   const deadline = Date.now() + timeout;
   while (Date.now() < deadline && targets.some(alive)) {
     // Join actual process exit while native abort persists the interrupted turn.
-    // oxlint-disable-next-line no-await-in-loop
     await delay(25);
   }
 }

package/src/agent/typebox.ts

@@ -8,12 +8,12 @@ import { isChild, packageRoot } from "./host.ts";
 // Pi aliases these imports to its own instance (including bundled virtual modules).
 // Only the detached runner needs absolute imports from the selected host package.
 const require = isChild() ? createRequire(path.join(packageRoot(), "dist/index.js")) : undefined;
-// oxlint-disable-next-line typescript/no-unsafe-assignment
+// oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: detached runners resolve the selected host schema instance.
 const typeboxPromise: Promise<typeof NativeTypebox> =
   require === undefined
     ? import("typebox")
     : import(pathToFileURL(require.resolve("typebox")).href);
-// oxlint-disable-next-line typescript/no-unsafe-assignment
+// oxlint-disable-next-line typescript/no-unsafe-assignment -- QX-004: validation must use the selected host schema instance.
 const valuePromise: Promise<typeof NativeValue> =
   require === undefined
     ? import("typebox/value")