@fitchmultz/pi-subagents 0.52.16 → 0.52.18

package/docs/code-quality.md

@@ -1,85 +1,113 @@
 # Code quality
 
-Oxlint checks maintained TypeScript and JavaScript. Oxfmt owns formatting.
-Both tools use the committed npm versions and repository configuration.
+The [Strict Oxlint/Oxfmt Engineering Standard v5.2](strict-oxlint-oxfmt-standard.md)
+owns the policy. [Quality exceptions](quality-exceptions.md) records the few
+operations that require different treatment. No finding budget or suppression
+baseline is accepted.
+
+## Commands
+
+Use the committed npm lockfile. Local checks are:
 
 ```sh
 npm ci --ignore-scripts
 npm run lint
-npm run lint:fix
-npm run format
 npm run format:check
 npm run typecheck
-npm run ci
+npm run typecheck:declarations
+npm run check:quality
+npm run build
 ```
 
-Lint rejects unsafe types, unchecked assertions, floating promises, accidental
-mutation, import cycles and ambiguous control flow. Application readonly types
-remain checked by TypeScript. `typescript/prefer-readonly-parameter-types` is
-disabled: the published backend cannot express the existing native SDK aliases
-with package-scoped allowances. The project does not patch the checker or add
-production wrappers to satisfy that rule.
+`npm run lint:fix` and `npm run format` are writing conveniences.
+`npm run lint:agent` is another output format for the same lint gate.
 
-Production limits are complexity 10, depth 3, parameters 4, statements 40,
-function lines 80 and file lines 500, excluding blank lines and comments.
-Tests retain complexity 15, depth 4 and parameters 6. Cohesive test suites have
-no size or statement limits.
+Full `npm run ci` remains hosted-only. It runs each independent gate even when
+another fails: native lint, format, implementation types, handwritten declaration
+types, policy and coverage, package size, package/install smokes, unit tests, and
+integration tests. Package smokes build the actual artifacts before testing them.
+The aggregate fails if any gate fails.
+
+CI qualifies official Pi on Linux and the maintained fork on Linux and macOS.
+Those are distinct runtime graphs, not interchangeable version labels. Android
+has no published oxlint-tsgolint backend; native semantic qualification runs on
+a supported host. A skipped local native probe is not hosted acceptance.
+
+## Coverage and enforcement
+
+`quality/check.ts` compares the effective policy with the normative JSON in the
+standard and the explicit repository mappings. It checks native lint membership,
+resolved compiler membership, formatter ownership, and required command scope.
+The inventory includes ignored files outside generated, dependency, and private
+runtime trees, so hiding maintained code with a Git ignore does not exempt it.
+
+The compiler's own resolution checks production dependencies on test support,
+including aliases, re-exports, and literal dynamic imports. Oxc's parser identifies
+actual comments and operation-bound directives. Strings containing example
+directives are data. Copied, moved, duplicate, stale, and wrong-operation
+directives fail; unused directives also fail native lint.
+
+The source profiles are:
 
-Formatting uses width 100, two spaces, LF and double quotes. npm owns lockfile
-formatting. Build outputs keep their own bytes.
-The VS Code Oxc extension uses these same lint and formatting configurations.
+- `src/**`, `scripts/**`, `quality/**`, and `.github/scripts/**` are production
+  implementation. Mixed-use helpers retain that profile.
+- `test/**` contains tests, fixtures, and exclusively test-used support.
+- `*.test-d.{ts,mts,cts}` are compiler-checked negative consumer contracts with
+  explained expected failures and passing counterparts.
+- Handwritten `*.d.{ts,mts,cts}` files receive the declaration profile and an
+  actual `skipLibCheck:false` check through `quality/declarations.ts`.
 
-`npm run ci` runs lint, formatting, TypeScript, package/install smokes and all
-tests. CI separately qualifies the latest official Pi on GitHub-hosted Linux and
-the maintained fork on Linux and macOS. There is no custom checker build, probe
-suite or self-hosted runner requirement.
+The root `tsconfig.json` checks all maintained TS and JS with the full required
+strict options. The application retains `skipLibCheck:true` because the installed
+SDK dependency closure includes incompatible third-party declaration imports.
+The declaration gate checks any handwritten declarations and their real dependency
+closure without that option or permissive stubs. There are currently no handwritten
+declaration files.
 
-CI's lint job also enforces the production byte ceiling before qualification
-substitutes the selected host graph. The retired workflow schema generator and
-its patching dependency are not part of the new runtime. `npm run check:size`
-still reports source and production line counts for visibility; no line count
-is mandated. The 1 MiB byte ceiling and all lint limits stay unchanged.
+`tsconfig.build.json` and `tsconfig.client.json` are emission configurations, not
+substitutes for the checked root project. Build-swap tests, packed-consumer type
+tests, and actual package/native-install smokes verify their outputs.
+
+Production limits are complexity 10, depth 3, parameters 4, statements 40,
+function lines 80, and file lines 500. Tests retain complexity 15, depth 4, and
+parameters 6 without statement or line limits. These are the standard's profiles,
+not local exceptions. There is no React, DOM JSX, Jest, or Vitest implementation;
+Node's test runner owns execution. A real failing assertion is qualified through
+the repository test command.
+
+Oxfmt owns supported maintained files, with width 100, two spaces, LF, double
+quotes, and no import/package/Tailwind/JSDoc transformations. npm owns
+`package-lock.json`; the build owns `dist/**` and temporary publication trees.
+Captured `docs/evidence/*.log` files retain original command bytes. Git, Pi state,
+dependency trees, npm cache, and OS metadata are not maintained source.
+No committed generated output requires a separate freshness generator.
+
+The existing viewer import restriction remains: lazy viewer values must come
+from the selected host through `observe-layout.ts`. It strengthens the base
+policy and protects runtime identity. The existing 1 MiB production-byte ceiling
+also remains. Neither is a new requirement of this standard.
 
 ## Adoption record
 
-Repository: `fitchmultz/pi-subagents`. Adopted standard: strict Oxlint/Oxfmt
-engineering standard v5.1.2, kept as the repository copy at
-`docs/strict-oxlint-oxfmt-standard.md`. Exception records live in
-[Quality exceptions](quality-exceptions.md) and follow the standard's Appendix B.
-
-Supported runtime and package manager: Node `>=24.21.0` with npm and the
-committed lockfile. Installed tool versions (devDependencies): oxlint 1.90.0,
-oxlint-tsgolint 7.0.2005, oxfmt 0.75.0, `@types/node` 24.19.2, typebox 1.4.3.
-
-Configuration and acceptance paths: lint `.oxlintrc.json`, formatting
-`.oxfmtrc.json`, compiler `tsconfig.json`. Local acceptance commands are
-`npm run lint`, `npm run format:check` and `npm run typecheck`; the aggregate
-acceptance command is hosted `npm run ci` (lint, formatting, TypeScript, byte
-ceiling, package/install smokes and the complete test suites, plus separate
-official-Pi and fork qualification jobs).
-
-Compiler projects and source profiles: one `tsc --noEmit` project covers all
-maintained TypeScript and checked-JavaScript (`src`, `scripts`, `test`,
-`.github`) with `strict`, `checkJs`, `noUncheckedIndexedAccess`,
-`exactOptionalPropertyTypes` and the full strict flag set. Lint profiles:
-production limits (complexity 10, depth 3, parameters 4, statements 40,
-function lines 80, file lines 500), test/fixture limits (complexity 15, depth
-4, parameters 6, no size limits) and declaration files with size limits off.
-
-Formatter and generator ownership: oxfmt formats all maintained source at
-width 100; npm owns lockfile formatting; build outputs keep their own bytes.
-
-Migration status: complete. The toolchain, baseline configuration, strict
-TypeScript compiler options, checked-JavaScript coverage and this records
-policy landed as PRs #319, #320, #321, #325 and the records PR; the policy
-integrity keeper `test/unit/strict-oxlint-policy.test.ts` pins the effective
-configuration, the four-entry overrides inventory and the directive rule-name
-inventory against drift.
-
-Integrated verification: hosted `npm run ci` on the merge of each part, with
-the single-agent-runtime, agent-receipts, pi-intercom-native-replay and
-retired-history-archive keepers exercising the native contracts. Locally
-verified state for the checked-JavaScript part is recorded in PR #325; the
-retired-history-archive suite requires passwordless `sudo` and
-`scripts/package-smoke.mjs` requires a short Unix socket directory, so hosted
-CI is the authoritative gate for both.
+Repository: `fitchmultz/pi-subagents`. Standard: v5.2, 3 November 2026.
+Runtime: Node `>=24.21.0`, npm, committed lockfile.
+Qualified tools: Oxlint 1.91.0, oxlint-tsgolint 7.0.2006, Oxfmt 0.76.0,
+TypeScript 7.0.2, oxc-parser 0.157.0, and `@types/node` 24.19.2.
+
+The adoption starts at `7f449e2dcc8e7e82432bea79a2709f0b49256239`.
+The adoption PR records the exact integrated head and hosted results; CI verifies
+the source SHA before qualification. Local M1 evidence uses Node 24.22.1 and
+official Pi 1.5.0; separate native fork coverage runs against its selected graph.
+
+Qualification lives in `strict-oxlint-qualification.test.ts`,
+`lint-node-test-allowance.test.ts`, `quality-coverage.test.ts`,
+`strict-oxlint-policy.test.ts`, and `quality-acceptance.test.ts`.
+These cover semantic and category rules, all six structural boundaries, Node
+registration origins, operation attachment, strict JS/TS/declaration checking,
+formatting idempotence, coverage omissions, and acceptance exit propagation.
+The adoption also exercised each aggregate gate's failure independently; ordinary
+regression coverage retains one representative failure plus the all-green case.
+
+The policy and source repairs are integrated. Completion requires the adoption
+PR's exact-head hosted checks and release verification; local passes alone do not
+establish complete adoption.

package/docs/intercom.md

@@ -330,8 +330,12 @@ not an end-to-end exactly-once guarantee for arbitrary tool side effects.
 
 Idle recovery preserves admission order within the non-passive backlog and wakes
 once on its last item; passive breadcrumbs are appended before that waking work.
-The first eligible ask remains the implicit reply target, independently of which
-message triggers the turn. A busy recipient's steer is handed to Pi's native
+The first unresolved eligible ask remains the implicit reply target, independently
+of which message triggers the turn. Reply attribution refers to the unresolved
+ask by ID. Placing delayed input does not revive an already replied, expired, or
+retired reply obligation. A failed turn can retire only an ask whose input Pi has
+consumed; queued input remains answerable after abort recovery.
+A busy recipient's steer is handed to Pi's native
 queue and consumed at its next tool boundary; no extension probe asks another
 tool to give up the turn.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitchmultz/pi-subagents",
-  "version": "0.52.16",
+  "version": "0.52.18",
   "description": "Pi extension for subagent orchestration and local session coordination",
   "license": "MIT",
   "type": "module",
@@ -68,8 +68,10 @@
     "lint:agent": "oxlint --type-aware --deny-warnings --format=agent .",
     "format": "oxfmt --write .",
     "format:check": "oxfmt --check .",
-    "ci": "npm run lint && npm run format:check && npm run typecheck && npm run check:size && npm run smoke:package && npm run smoke:install && npm run test:all",
-    "smoke:real-pi": "node scripts/real-pi-smoke.mjs"
+    "ci": "node quality/acceptance.ts",
+    "smoke:real-pi": "node scripts/real-pi-smoke.mjs",
+    "check:quality": "node quality/check.ts",
+    "typecheck:declarations": "node quality/declarations.ts"
   },
   "pi": {
     "extensions": [
@@ -110,9 +112,10 @@
     "@earendil-works/pi-tui": "1.5.0",
     "@types/node": "24.19.2",
     "@types/sinon": "22.0.2",
-    "oxfmt": "0.75.0",
-    "oxlint": "1.90.0",
-    "oxlint-tsgolint": "7.0.2005",
+    "oxc-parser": "0.157.0",
+    "oxfmt": "0.76.0",
+    "oxlint": "1.91.0",
+    "oxlint-tsgolint": "7.0.2006",
     "sinon": "22.1.0",
     "type-fest": "5.10.0",
     "typebox": "1.4.3",

package/scripts/build.mjs

@@ -11,6 +11,7 @@
  */
 
 import { execFile as execFileCallback } from "node:child_process";
+import assert from "node:assert/strict";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
@@ -21,7 +22,6 @@ import { promisify } from "node:util";
 import { compilerInvocation } from "./typescript.mjs";
 
 /** @type {(file: string, args: readonly string[], options: import("node:child_process").ExecFileOptions) => Promise<{ stdout: string, stderr: string }>} */
-// oxlint-disable-next-line typescript/strict-void-return
 const execFile = promisify(execFileCallback);
 const RM_OPTIONS = { force: true, maxRetries: 5, recursive: true, retryDelay: 100 };
 
@@ -80,7 +80,6 @@ async function reapStrandedStaging(/** @type {string} */ cwd) {
       continue;
     }
     // Reap abandoned trees sequentially to bound filesystem removal pressure.
-    // oxlint-disable-next-line no-await-in-loop
     await discardStaging(join(cwd, entry.name));
   }
 }
@@ -114,13 +113,13 @@ async function compileToStaging(
     await compileProject(cwd, stagingDir, compiler, "tsconfig.client.json");
     await stampBuild(cwd, stagingDir);
   } catch (error) {
-    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- exec rejections carry partial output
-    const output = /** @type {{ stdout?: string, stderr?: string }} */ (error);
-    if (output.stdout !== undefined && output.stdout !== "") {
-      process.stdout.write(output.stdout);
-    }
-    if (output.stderr !== undefined && output.stderr !== "") {
-      process.stderr.write(output.stderr);
+    if (typeof error === "object" && error !== null) {
+      if ("stdout" in error && typeof error.stdout === "string") {
+        process.stdout.write(error.stdout);
+      }
+      if ("stderr" in error && typeof error.stderr === "string") {
+        process.stderr.write(error.stderr);
+      }
     }
     await discardStaging(stagingDir);
     throw error;
@@ -135,13 +134,13 @@ async function stampBuild(/** @type {string} */ cwd, /** @type {string} */ stagi
     .sort();
   for (const file of files) {
     // Hash sorted path/content pairs in order without buffering the whole emitted tree.
-    // oxlint-disable-next-line no-await-in-loop
     const content = await readFile(join(stagingDir, file));
     hash.update(file).update("\0").update(content).update("\0");
   }
-  /** @type {{ version: string }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  /** @type {unknown} */
   const pkg = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+  assert.ok(typeof pkg === "object" && pkg !== null && "version" in pkg);
+  assert.ok(typeof pkg.version === "string");
   const { version } = pkg;
   await writeFile(
     join(stagingDir, stamp),
@@ -184,7 +183,6 @@ async function publishStaging(/** @type {string} */ stagingDir, /** @type {strin
     });
     for (let retry = 0; ; retry++) {
       // Each retry must observe publication before another rename can race it.
-      // oxlint-disable-next-line no-await-in-loop
       if (await tryPublish(stagingDir, distDir, retry)) {
         break;
       }

package/scripts/check-compat.mjs

@@ -19,6 +19,8 @@ const run = (
   /** @type {import("node:child_process").SpawnSyncOptions} */ options = {},
 ) => {
   // Outlasts the 1_200_000 ms integration watchdog in scripts/run-tests.mjs.
+  // Inherited stdio produces null at runtime despite SpawnSyncReturns<T>'s declaration.
+  /** @type {import("node:child_process").SpawnSyncReturns<string | Buffer | null>} */
   const result = spawnSync(command, args, { stdio: "inherit", timeout: 1_500_000, ...options });
   if (result.error) {
     throw result.error;
@@ -28,8 +30,7 @@ const run = (
     0,
     `${command} ${args.join(" ")} failed (${result.status ?? result.signal ?? "unknown"})`,
   );
-  // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- spawnSync stdout shape depends on caller options
-  return /** @type {string | undefined} */ (/** @type {unknown} */ (result.stdout))?.trim();
+  return result.stdout === null ? undefined : result.stdout.toString().trim();
 };
 const git = (/** @type {string} */ cwd, /** @type {string[]} */ args) =>
   run("git", args, { cwd, stdio: ["ignore", "pipe", "inherit"], encoding: "utf8" });

package/scripts/compat-host.mjs

@@ -12,9 +12,12 @@ if (hostPackageJson === undefined) {
 }
 export const hostRoot = realpathSync(dirname(hostPackageJson));
 export const hostIndex = join(hostRoot, "dist/index.js");
-/** @type {{ version: string, bin: { pi: string } }} */
-// oxlint-disable-next-line typescript/no-unsafe-assignment
+/** @type {unknown} */
 const manifest = JSON.parse(readFileSync(join(hostRoot, "package.json"), "utf8"));
+assert.ok(typeof manifest === "object" && manifest !== null);
+assert.ok("version" in manifest && typeof manifest.version === "string");
+assert.ok("bin" in manifest && typeof manifest.bin === "object" && manifest.bin !== null);
+assert.ok("pi" in manifest.bin && typeof manifest.bin.pi === "string");
 export const hostCli = realpathSync(join(hostRoot, manifest.bin.pi));
 /** @type {[string, string][]} */
 const expectedHostPaths = [
@@ -26,7 +29,6 @@ for (const [name, actual] of expectedHostPaths) {
   const expected = process.env[name];
   if (expected !== undefined) {
     assert.equal(
-      // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
       realpathSync(expected),
       realpathSync(actual),
       `${name} must select the installed graph`,
@@ -35,11 +37,9 @@ for (const [name, actual] of expectedHostPaths) {
 }
 const expectedVersion = process.env.PI_COMPAT_EXPECTED_VERSION;
 if (expectedVersion !== undefined) {
-  // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
   assert.equal(manifest.version, expectedVersion);
 }
 assert.equal(
-  // oxlint-disable-next-line typescript/no-unnecessary-condition -- assert generic inference already matches
   realpathSync(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))),
   realpathSync(hostIndex),
 );

package/scripts/intercom-bridge-credentials.mjs

@@ -161,8 +161,7 @@ function issueCertificate(
 }
 
 function readConfig(/** @type {string} */ path) {
-  /** @type {{ ca?: string, clients?: unknown[], cert?: string, key?: string }} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
+  /** @type {unknown} */
   const config = JSON.parse(readFileSync(path, "utf8"));
   if (!isRecord(config) || !Array.isArray(config.clients) || typeof config.ca !== "string") {
     throw new Error("Invalid clients allowlist.");
@@ -178,7 +177,9 @@ function readConfig(/** @type {string} */ path) {
     }
     return { ...client, name: client.name, cwd: client.cwd, fingerprint256: client.fingerprint256 };
   });
-  return { ...config, ca: config.ca, clients };
+  /** @type {Record<string, unknown> & { ca: string, clients: typeof clients }} */
+  const validated = { ...config, ca: config.ca, clients };
+  return validated;
 }
 
 let args;

package/scripts/intercom-remote.mjs

@@ -32,7 +32,6 @@ const actions = {
   send: ["to", "message", "id", "passive", "expects-reply", "reply-to"],
 };
 function messageId(/** @type {string | undefined} */ id) {
-  // oxlint-disable-next-line no-control-regex
   const controls = /[\u0000-\u001f\u007f-\u009f]/;
   if (id !== undefined && (id.trim() === "" || id.length > 512 || controls.test(id))) {
     throw new Error("Invalid message ID.");

package/scripts/native-package-smoke-assertions.mjs

@@ -1,6 +1,22 @@
 // Journal and observation assertions shared with the packed-native smoke script.
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
+import { isRecord, isUnknownArray } from "../src/shared/unknown.ts";
+
+function jsonRecords(/** @type {string} */ file) {
+  return readFileSync(file, "utf8")
+    .trimEnd()
+    .split("\n")
+    .map((line) => {
+      /** @type {unknown} */ const entry = JSON.parse(line);
+      assert.ok(isRecord(entry));
+      return entry;
+    });
+}
+
+function containsText(/** @type {unknown} */ content, /** @type {string} */ text) {
+  return isUnknownArray(content) && content.some((part) => isRecord(part) && part.text === text);
+}
 
 /**
  * Assert the child journal records its native tool result and completion entry.
@@ -9,23 +25,15 @@ import { readFileSync } from "node:fs";
  * @param {string} completionText
  */
 export function assertChildJournal(sessionFile, terminalEntryId, completionText) {
-  const childEntries = readFileSync(sessionFile, "utf8")
-    .trimEnd()
-    .split("\n")
-    .map((line) =>
-      /** @type {{ id?: string, type?: string, message?: { role?: string, toolName?: string, content?: { text?: string }[] } }} */ (
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- journal line shape, guarded below
-        JSON.parse(line)
-      ),
-    );
-  // oxlint-disable typescript/no-unnecessary-condition -- journal fields are optional under tsc
+  const childEntries = jsonRecords(sessionFile);
   assert.ok(
     childEntries.some(
       (entry) =>
         entry.type === "message" &&
-        entry.message?.role === "toolResult" &&
-        entry.message?.toolName === "packed_probe" &&
-        entry.message?.content?.some((part) => part.text === "PACKED_TOOL_RESULT") === true,
+        isRecord(entry.message) &&
+        entry.message.role === "toolResult" &&
+        entry.message.toolName === "packed_probe" &&
+        containsText(entry.message.content, "PACKED_TOOL_RESULT"),
     ),
     "actual child journal contains its native tool result",
   );
@@ -34,12 +42,12 @@ export function assertChildJournal(sessionFile, terminalEntryId, completionText)
       (entry) =>
         entry.id === terminalEntryId &&
         entry.type === "message" &&
-        entry.message?.role === "assistant" &&
-        entry.message?.content?.some((part) => part.text === completionText) === true,
+        isRecord(entry.message) &&
+        entry.message.role === "assistant" &&
+        containsText(entry.message.content, completionText),
     ),
     "completion references an actually published child assistant entry",
   );
-  // oxlint-enable typescript/no-unnecessary-condition
 }
 
 /**
@@ -47,13 +55,7 @@ export function assertChildJournal(sessionFile, terminalEntryId, completionText)
  * @param {string} observations
  */
 export function assertObservations(observations) {
-  /** @type {Record<string, unknown>[]} */
-  // oxlint-disable-next-line typescript/no-unsafe-assignment
-  const observed = readFileSync(observations, "utf8")
-    .trimEnd()
-    .split("\n")
-    // oxlint-disable-next-line typescript/no-unsafe-return
-    .map((line) => JSON.parse(line));
+  const observed = jsonRecords(observations);
   const matches = (/** @type {(item: Record<string, unknown>) => boolean} */ predicate) =>
     observed.filter(predicate).length;
   assert.equal(