@alexkroman1/aai-cli 5.8.1 → 5.10.0

package/dist/scaffold/CLAUDE.md

@@ -97,8 +97,9 @@ export default agent({
   silencePrompt?: string;                    // instruction injected on silence timeout (requires silenceTimeoutMs)
   minBargeInWords?: number;                  // pipeline only — words before user speech interrupts the reply (default 2)
   interruptionMinDurationMs?: number;        // pipeline only — sustained speech (ms) before an interim barge-in interrupts (default 500; 0 disables)
-  holdPhrase?: string;                       // pipeline only — spoken before a silent tool-call turn (default "One moment."; "" disables)
-  falseInterruptionTimeoutMs?: number;       // pipeline only — resume an interrupted reply if no user turn commits (default 2000; 0 disables)
+  deadAirCoverMs?: number;                   // pipeline only — speak a short filler after this much silence in a turn (default 5000; 0 disables)
+  resumeFalseInterruption?: boolean;         // pipeline only — resume an interrupted reply if no user turn commits (default true)
+  preemptiveGeneration?: boolean;            // pipeline only — start the reply from a high-confidence interim (default true; false opts out)
   state?: () => S;                           // per-session mutable state, exposed as ctx.state
                                              // (S is inferred; see "Typing ctx.state")
   syncState?: (state: S) => unknown;         // push a projection of state to the client
@@ -250,9 +251,26 @@ land). End-of-turn detection (how long a pause ends the user's turn)
 belongs to the STT provider: `assemblyAIStt({ minTurnSilenceMs })` (default
 2000 ms) / `deepgram({ endpointing })` (default 1500 ms), so mid-utterance
 pauses don't split a request.
-`holdPhrase` is spoken when a turn opens with a tool call and no speech.
-`falseInterruptionTimeoutMs` resumes an interrupted reply when a barge-in
-turns out to be noise (no user turn commits within the window).
+`deadAirCoverMs` is how long a turn may go silent before the transport speaks
+a short filler, so a long tool chain doesn't sound like a dropped call. It is
+measured silence, not a guess about the turn's shape, so a reply that arrives
+promptly pays nothing; `0` disables it. The wording is not yours to set — the
+filler must be purely declarative and never a request for patience, or the
+caller answers it and the answer barges in.
+`resumeFalseInterruption` (default `true`) resumes an interrupted reply when
+a barge-in turns out to be noise — no user turn ever commits. The wait is not
+configurable: the resume fires once the transcript stream goes quiet with no
+final, so it can never race a real turn the STT is still endpointing.
+`preemptiveGeneration` (default `true`) starts generating the reply as soon
+as transcription is confident the caller has finished, and uses that
+already-running answer if the committed transcript matches. It can shorten the
+pause before the agent speaks, and **how much is unmeasured** — nobody has
+shown the size of the saving. What bounds the downside is that a speculation
+never speaks, calls a tool, or enters history until the real turn adopts it, so
+the worst case is a wasted request and a turn that behaves exactly as it would
+with the flag off. Set `preemptiveGeneration: false` to opt out — worth doing
+on a tool-heavy agent, where a speculation that reaches a tool call is thrown
+away, so it is cost with no upside.
 
 ## Providers
 
@@ -651,10 +669,11 @@ interpolate values into the SQL string. The rows come back as plain objects;
 A query returning more than 1000 rows throws — always bound reads with
 `LIMIT` (paginate with `LIMIT`/`OFFSET`).
 
-**Storage must be enabled** or accessing `ctx.db` throws:
+**The database must be enabled** or accessing `ctx.db` throws:
 
 - CLI: `aai storage enable`
-- Studio: the Storage toggle
+- Studio: Settings pane → Database → Enable database (covers both the
+  preview and published agents, each with its own schema)
 - `aai dev`: set `DATABASE_URL` in the project `.env`
 
 Create tables lazily from tool code and upsert with `on conflict`:
@@ -929,8 +948,10 @@ Never hardcode secrets in agent code.
   `ctx.env`.
 - **Production:** `npx @alexkroman1/aai-cli secret put NAME`
 - **Access:** `ctx.env.MY_KEY` in tool execute functions.
-- **AssemblyAI key:** CLI prompts on first use, stores globally. No `.env`
-  entry needed. For CI, set `ASSEMBLYAI_API_KEY` env var.
+- **AssemblyAI key:** `npx @alexkroman1/aai-cli login` links your account and
+  stores the key globally — the only way the CLI authenticates. No `.env`
+  entry needed. For CI, point `AAI_CONFIG_DIR` at a config dir holding a
+  logged-in key (an exported `ASSEMBLYAI_API_KEY` does not authenticate).
 
 ## Voice rules for systemPrompt
 
@@ -984,9 +1005,11 @@ Common mistakes when working in aai projects:
   platform's Modal/Deno sandbox; the self-hosted `aai dev` server has no
   sandbox, so there `run_code` refuses with an error result. Deploy to test
   it end-to-end, or use the `calculate` builtin for simple arithmetic in dev.
-- **`ctx.db` throws until storage is enabled.** Enable it with
-  `aai storage enable` (CLI), the Storage toggle (studio), or `DATABASE_URL`
-  in `.env` (`aai dev`) before shipping tools that persist data.
+- **`ctx.db` throws until the database is enabled.** Enable it with
+  `aai storage enable` (CLI), Settings → Database (studio), or
+  `DATABASE_URL` in `.env` (`aai dev`) before shipping tools that persist
+  data. In the studio it takes effect when each agent next deploys — the
+  preview redeploys itself, production on the next publish.
 - **The database is per-app.** Rows are shared by every session of one
   deployment — key them yourself if sessions must not see each other's data
   (or keep session-scoped data in `ctx.state`).
@@ -1002,7 +1025,9 @@ Common mistakes when working in aai projects:
 - Agent code runs in a sandboxed worker — use `fetch` for HTTP, `ctx.env`
   for secrets
 - Tool execution timeout: 30 seconds
-- `maxSteps` limits tool calls per turn (default 10) — increase for
-  multi-tool workflows
+- `maxSteps` limits tool calls per turn (default 10) — lower it for a
+  latency-sensitive agent. On reaching the cap the agent spends one more LLM
+  step with tools switched off, so it answers with what it has instead of
+  going silent mid-chain
 - Tool returns `undefined` if execute function has no return statement —
   always return a value

package/dist/scaffold/package.json

@@ -11,15 +11,15 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^5.8.1",
-    "@alexkroman1/aai-ui": "^5.8.1",
+    "@alexkroman1/aai": "^5.10.0",
+    "@alexkroman1/aai-ui": "^5.10.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^5.8.1",
+    "@alexkroman1/aai-cli": "^5.10.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",

package/dist/{secret-Dr0qnxeb.mjs → secret-4_dYyrpA.mjs}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { a as unwrapCancel, n as log, s as fail, u as ok } from "./_ui-8kOEB-JH.mjs";
-import { t as slugRequest } from "./_slug-api-CGJSST9B.mjs";
+import { a as ok, n as fail } from "./_output-CC300DzW.mjs";
+import { n as log, o as unwrapCancel } from "./_ui-DfwfDbT-.mjs";
+import { t as slugRequest } from "./_slug-api-fRNNR8tz.mjs";
 import * as p from "@clack/prompts";
 import { text } from "node:stream/consumers";
 //#region secret.ts

package/dist/{storage-CoQB8d-u.mjs → storage-BTfErOOW.mjs}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { n as log, s as fail, u as ok } from "./_ui-8kOEB-JH.mjs";
-import { t as slugRequest } from "./_slug-api-CGJSST9B.mjs";
+import { a as ok, n as fail } from "./_output-CC300DzW.mjs";
+import { n as log } from "./_ui-DfwfDbT-.mjs";
+import { t as slugRequest } from "./_slug-api-fRNNR8tz.mjs";
 import * as p from "@clack/prompts";
 //#region storage.ts
 async function storageRequest(cwd, init, server) {

package/dist/{studio-_UBBvh5V.mjs → studio-LNvXtWak.mjs}

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { n as log, o as CliError, t as fmtUrl, u as ok } from "./_ui-8kOEB-JH.mjs";
-import { s as updateProjectConfig } from "./_config-Y5V-5Krn.mjs";
-import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
-import { i as resolveDeployTarget } from "./_agent-2nVugrN3.mjs";
-import { layerScaffold } from "./_templates-BfyRyE7z.mjs";
+import { a as ok, t as CliError } from "./_output-CC300DzW.mjs";
+import { n as log, t as fmtUrl } from "./_ui-DfwfDbT-.mjs";
+import { s as updateProjectConfig } from "./_config-DMyolIk9.mjs";
+import { t as resolveServerEnv } from "./_server-common-DX8Bfrf5.mjs";
+import { i as resolveDeployTarget } from "./_agent-DS2PUJcl.mjs";
+import { layerScaffold } from "./_templates-BWJOiWOO.mjs";
 import { n as apiRequest } from "./_api-client-B-upMGkc.mjs";
 import path from "node:path";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
@@ -290,7 +291,7 @@ async function syncEnvSecrets(cwd, serverUrl, apiKey, slug) {
 }
 async function executePublish(opts) {
 	if (!opts.skipTypecheck) {
-		const { assertTypechecks } = await import("./_typecheck-gate-DvE8S3aQ.mjs");
+		const { assertTypechecks } = await import("./_typecheck-gate-DB-PY0A3.mjs");
 		await assertTypechecks(opts.cwd);
 	}
 	const pushed = await pushProject(opts);

package/dist/templates/dispatch-center/agent.ts

@@ -1,5 +1,4 @@
 import { agent } from "@alexkroman1/aai";
-import { assemblyAIStt } from "@alexkroman1/aai/stt";
 import { dashboardView } from "./shared.ts";
 import systemPrompt from "./system-prompt.md?raw";
 import { incidentAddNote } from "./tools/incident_add_note.ts";
@@ -20,11 +19,10 @@ export default agent({
   // One projection replaces eleven `ctx.send("incidents", ...)` calls, and
   // is the single place that decides caller PII stays server-side.
   syncState: dashboardView,
-  // Only the STT stage is declared (LLM and TTS stay on the AssemblyAI
-  // defaults): a dispatcher reads addresses and unit numbers in bursts with
-  // pauses inside one message, so end-of-turn silence has to be longer than
-  // the default or "unit twelve … respond to" splits in two.
-  stt: assemblyAIStt({ minTurnSilenceMs: 2200 }),
+  // A dispatcher reads addresses and unit numbers in bursts with pauses inside
+  // one message ("unit twelve … respond to"). The default pipeline's
+  // `max_turn_silence` already tolerates that; reach for
+  // `assemblyAIStt({ maxTurnSilenceMs })` only if your callers pause longer.
   systemPrompt,
   greeting:
     "Dispatch Command Center online. Restoring operational state. I'm ready to take incoming calls, manage active incidents, or run dispatch operations. Say 'dashboard' for a full status report. What do we have.",

package/dist/templates/retail/agent.ts

@@ -1,5 +1,4 @@
 import { agent } from "@alexkroman1/aai";
-import { assemblyAIStt } from "@alexkroman1/aai/stt";
 import type { StateSlot } from "./shared.ts";
 import { storeView } from "./shared.ts";
 import { createDefaultState } from "./store.ts";
@@ -41,11 +40,10 @@ export default agent({
   // authenticated one may reach the browser.
   syncState: storeView,
 
-  // Callers read order numbers and ten-digit item numbers in bursts with
-  // pauses inside one utterance, so end-of-turn silence has to be longer than
-  // the default or "W seven six seven … eight oh seven two" splits in two.
-  stt: assemblyAIStt({ minTurnSilenceMs: 2200 }),
-
+  // Callers read order numbers and ten-digit item numbers in bursts with pauses
+  // inside one utterance ("W seven six seven … eight oh seven two"). The default
+  // pipeline's `max_turn_silence` already tolerates that; reach for
+  // `assemblyAIStt({ maxTurnSilenceMs })` only if your callers pause longer.
   systemPrompt,
   greeting:
     "Thanks for calling. Before I can look anything up I'll need to find your account — " +

package/dist/templates/retail/registry.test.ts

@@ -105,16 +105,18 @@ describe("tool registry", () => {
     );
   });
 
+  // Both sweep the registry, so they assert softly: adding a batch of tools
+  // should list every one still missing its entry, not just the first.
   test("every registered tool has sample args, so the sweeps below cover it", () => {
     for (const [name] of registry) {
-      expect(SAMPLE_ARGS[name], `add SAMPLE_ARGS["${name}"]`).toBeDefined();
+      expect.soft(SAMPLE_ARGS[name], `add SAMPLE_ARGS["${name}"]`).toBeDefined();
     }
   });
 
   test("every tool declares a description the model can act on", () => {
     for (const [name, def] of registry) {
-      expect(def.description, name).toBeTruthy();
-      expect(def.description.length, name).toBeGreaterThan(40);
+      expect.soft(def.description, name).toBeTruthy();
+      expect.soft(def.description.length, name).toBeGreaterThan(40);
     }
   });
 });

package/dist/templates/retail/resolve.test.ts

@@ -19,7 +19,9 @@ describe("normalizeOrderId", () => {
       "5866402",
       " #w 586 6402 ",
     ]) {
-      expect(normalizeOrderId(spoken), spoken).toBe("#W5866402");
+      // Soft: a narrowed normalizer drops a whole family of spoken forms, and
+      // which ones it drops is what says where the pattern went wrong.
+      expect.soft(normalizeOrderId(spoken), spoken).toBe("#W5866402");
     }
   });
 });
@@ -37,7 +39,7 @@ describe("resolveOrder — canonical ids", () => {
     const state = stateFor("olivia_ito_3591");
     for (const spoken of ["#W5866402", "W 5866402", "5866402"]) {
       const order = resolveOrder(state, spoken);
-      expect(isError(order) ? null : order.order_id, spoken).toBe("#W5866402");
+      expect.soft(isError(order) ? null : order.order_id, spoken).toBe("#W5866402");
     }
   });
 
@@ -52,7 +54,7 @@ describe("resolveOrder — shorthand", () => {
     const state = stateFor("olivia_ito_3591");
     for (const spoken of ["the delivered one", "my delivered order", "delivered"]) {
       const order = resolveOrder(state, spoken);
-      expect(isError(order) ? null : order.order_id, spoken).toBe("#W5866402");
+      expect.soft(isError(order) ? null : order.order_id, spoken).toBe("#W5866402");
     }
   });
 
@@ -61,7 +63,7 @@ describe("resolveOrder — shorthand", () => {
     const result = resolveOrder(state, "my pending order");
     if (!isError(result)) throw new Error("expected ambiguity");
     for (const id of ["#W5442520", "#W7941031", "#W3657213"]) {
-      expect(result.error).toContain(id);
+      expect.soft(result.error, `ambiguity message omits ${id}`).toContain(id);
     }
   });
 

package/dist/templates/retail/seed.test.ts

@@ -90,18 +90,25 @@ describe("seed shape", () => {
     expect(Object.keys(seed.orders)).toHaveLength(22);
   });
 
+  // These four sweep the whole corpus, so they assert SOFTLY: one hand-edited
+  // order usually breaks several records at once, and a hard failure reports
+  // the first and hides how far the damage runs.
   test("every order belongs to a seeded user and is listed on that user", () => {
     for (const order of Object.values(seed.orders)) {
       const user = seed.users[order.user_id];
-      expect(user, `order ${order.order_id} has no seeded user`).toBeDefined();
-      expect(user?.orders).toContain(order.order_id);
+      expect.soft(user, `order ${order.order_id} has no seeded user`).toBeDefined();
+      expect
+        .soft(user?.orders ?? [], `${order.order_id} is not listed on its user`)
+        .toContain(order.order_id);
     }
   });
 
   test("every user's listed orders are all seeded", () => {
     for (const user of Object.values(seed.users)) {
       for (const orderId of user.orders) {
-        expect(seed.orders[orderId], `${user.user_id} lists unseeded ${orderId}`).toBeDefined();
+        expect
+          .soft(seed.orders[orderId], `${user.user_id} lists unseeded ${orderId}`)
+          .toBeDefined();
       }
     }
   });
@@ -110,11 +117,10 @@ describe("seed shape", () => {
     for (const order of Object.values(seed.orders)) {
       for (const item of order.items) {
         const variant = seed.products[item.product_id]?.variants[item.item_id];
-        expect(
-          variant,
-          `${order.order_id}: ${item.item_id} missing from its product`,
-        ).toBeDefined();
-        expect(variant?.price).toBe(item.price);
+        expect
+          .soft(variant, `${order.order_id}: ${item.item_id} missing from its product`)
+          .toBeDefined();
+        expect.soft(variant?.price, `${order.order_id}: ${item.item_id} price`).toBe(item.price);
       }
     }
   });
@@ -123,10 +129,12 @@ describe("seed shape", () => {
     for (const order of Object.values(seed.orders)) {
       const user = seed.users[order.user_id];
       for (const payment of order.payment_history) {
-        expect(
-          user?.payment_methods[payment.payment_method_id],
-          `${order.order_id}: unknown method ${payment.payment_method_id}`,
-        ).toBeDefined();
+        expect
+          .soft(
+            user?.payment_methods[payment.payment_method_id],
+            `${order.order_id}: unknown method ${payment.payment_method_id}`,
+          )
+          .toBeDefined();
       }
     }
   });
@@ -148,7 +156,7 @@ describe("seed coverage — each datum backs a specific test in agent.test.ts",
   test("every status the tools branch on is present", () => {
     const statuses = new Set(Object.values(seed.orders).map((o) => o.status));
     for (const s of ["pending", "processed", "delivered", "cancelled"]) {
-      expect(statuses, `no ${s} order seeded`).toContain(s);
+      expect.soft(statuses, `no ${s} order seeded`).toContain(s);
     }
   });
 

package/dist/templates/retail/shared.test.ts

@@ -57,7 +57,9 @@ describe("storeView", () => {
       "#W4316152",
       "#W1840144",
     ]) {
-      expect(json, `projection leaked ${leaked}`).not.toContain(leaked);
+      // Soft: a widened projection leaks several fields at once, and the full
+      // list is what says how much of the other customers' records got out.
+      expect.soft(json, `projection leaked ${leaked}`).not.toContain(leaked);
     }
   });
 
@@ -84,15 +86,17 @@ describe("DEMO_PERSONAS", () => {
     const users = Object.values((structuredClone(seedJson) as unknown as Store).users);
     for (const persona of DEMO_PERSONAS) {
       const user = users.find((u) => u.email === persona.email);
-      expect(user, `no seeded customer has email ${persona.email}`).toBeDefined();
-      expect(`${user?.name.first_name} ${user?.name.last_name}`).toBe(persona.name);
-      expect(user?.address.zip).toBe(persona.zip);
+      expect.soft(user, `no seeded customer has email ${persona.email}`).toBeDefined();
+      expect
+        .soft(`${user?.name.first_name} ${user?.name.last_name}`, persona.email)
+        .toBe(persona.name);
+      expect.soft(user?.address.zip, persona.email).toBe(persona.zip);
     }
   });
 
   test("every persona carries a hint, so a user can pick a path deliberately", () => {
     for (const persona of DEMO_PERSONAS) {
-      expect(persona.hint.length, persona.name).toBeGreaterThan(20);
+      expect.soft(persona.hint.length, persona.name).toBeGreaterThan(20);
     }
   });
 });

package/dist/templates/solo-rpg/agent.test.ts

@@ -167,11 +167,13 @@ describe("applyConsequences MISS matrix", () => {
     ] as const) {
       const state = playingState();
       const { deltas, clockEvents } = applyConsequences(state, miss, position, "standard", null);
-      expect(state.health).toBe(5 - dmg);
-      expect(deltas.health).toBe(-dmg);
-      expect(state.clocks[0]?.filled).toBe(ticks);
-      expect(deltas.clockTicks).toBe(ticks);
-      expect(clockEvents).toHaveLength(0); // 4-segment clock not full yet
+      // Each row starts from a fresh state, so they are independent — assert
+      // softly and a rebalanced table reports the whole matrix in one run.
+      expect.soft(state.health, position).toBe(5 - dmg);
+      expect.soft(deltas.health, position).toBe(-dmg);
+      expect.soft(state.clocks[0]?.filled, position).toBe(ticks);
+      expect.soft(deltas.clockTicks, position).toBe(ticks);
+      expect.soft(clockEvents, position).toHaveLength(0); // 4-segment clock not full yet
     }
   });
 

package/dist/templates/solo-rpg/shared.ts

@@ -341,8 +341,8 @@ export function saveGameState(ctx: ToolContext, state: GameState): void {
 
 // ── Persistent save slots (ctx.db) ───────────────────────────────────────────
 // save_game / load_game are genuine cross-session persistence, so they use
-// the app's SQL database. Requires storage: `aai storage enable` (or the
-// Storage toggle in the studio); under `aai dev`, set DATABASE_URL in .env.
+// the app's SQL database. Requires storage: `aai storage enable` (or
+// Settings → Database in the studio); under `aai dev`, set DATABASE_URL in .env.
 //
 // Slots are keyed by name alone — the whole point of a save is loading it in
 // a LATER session, whose sessionId differs, so the key can't embed one. The

package/dist/{test-3Gq4pqH_.mjs → test-C-V98oC-.mjs}

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { n as log, s as fail, u as ok } from "./_ui-8kOEB-JH.mjs";
-import { a as errorMessage, n as binFromPackageJson, r as errorCode } from "./_utils-Ch0J4s6a.mjs";
+import { a as ok, n as fail } from "./_output-CC300DzW.mjs";
+import { n as log } from "./_ui-DfwfDbT-.mjs";
+import { a as errorMessage, n as binFromPackageJson, r as errorCode } from "./_utils-8KKw-bzi.mjs";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import path from "node:path";
@@ -50,8 +51,7 @@ function runVitest(cwd) {
 		testFile
 	], {
 		cwd,
-		stdio: "inherit",
-		env: { NODE_OPTIONS: "--experimental-strip-types" }
+		stdio: "inherit"
 	});
 	return true;
 }

package/dist/typecheck.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { a as errorMessage, n as binFromPackageJson } from "./_utils-Ch0J4s6a.mjs";
-import { existsSync } from "node:fs";
+import { a as errorMessage, n as binFromPackageJson } from "./_utils-8KKw-bzi.mjs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 //#region typecheck.ts
@@ -56,13 +56,69 @@ function findTypescriptPackage(cwd) {
 		dir = parent;
 	}
 }
-/** Resolve the project's TypeScript compiler entry (its own `tsc` bin). */
-function resolveTscEntry(cwd) {
+/**
+* Resolve the project's TypeScript compiler entry (its own `tsc` bin), plus
+* its major version — see {@link tscArgs} for what the version decides.
+*/
+function resolveTsc(cwd) {
 	const dir = findTypescriptPackage(cwd);
 	if (dir === void 0) throw new Error("no typescript package in the project's node_modules");
-	const bin = binFromPackageJson(path.join(dir, "package.json"), "tsc");
+	const manifest = path.join(dir, "package.json");
+	const bin = binFromPackageJson(manifest, "tsc");
 	if (!bin) throw new Error("installed typescript package declares no tsc bin");
-	return bin;
+	return {
+		entry: bin,
+		major: readMajor(manifest)
+	};
+}
+/**
+* The resolved compiler's major version, or 0 when it can't be read.
+*
+* 0 is the safe answer: {@link tscArgs} only ADDS flags above a version
+* floor, so an unreadable manifest degrades to the flag set every TypeScript
+* accepts rather than failing a build over a cosmetic read.
+*/
+function readMajor(manifest) {
+	try {
+		const { version } = JSON.parse(readFileSync(manifest, "utf-8"));
+		return typeof version === "string" ? Number.parseInt(version, 10) || 0 : 0;
+	} catch {
+		return 0;
+	}
+}
+/**
+* The `tsc` argv for one project check.
+*
+* `--singleThreaded` is the interesting one, and it is a SPEEDUP here rather
+* than a throttle. TypeScript 7 parallelizes parse/check/emit by default,
+* which pays off on a repo-sized program and costs on a single agent project —
+* and this function only ever checks one of those. Measured on the templates
+* project (14 agents, the closest in-repo analogue of a studio workspace):
+*
+* - pinned to 1 core: 2.4–2.9s parallel vs 1.2–1.4s single — ~2x faster
+* - on 4 cores:       1.21–1.24s parallel vs 1.01–1.04s single
+*
+* The 1-core number is the one that matters: a guest sandbox RESERVES one CPU
+* (`SANDBOX_CPU`) and this same check runs after every settled write burst in
+* the studio (`aai-guest/studio-write-diagnostics.ts`), where the whole design
+* rests on it finishing in well under a second. Parallelism inside a one-core
+* reservation is oversubscription: the threads exist, contend, and the wall
+* clock doubles.
+*
+* Gated on major >= 7 because the flag is TS 7's, and an unknown compiler
+* option is a HARD error (TS5023) — a project pinning an older TypeScript
+* would fail its build on a flag it never asked for. `engines`/scaffold pin
+* `^7`, so in practice this floor is always met; it exists so a project that
+* pins otherwise degrades instead of breaking.
+*/
+function tscArgs(entry, major) {
+	return [
+		entry,
+		"--noEmit",
+		"--pretty",
+		"false",
+		...major >= 7 ? ["--singleThreaded"] : []
+	];
 }
 /**
 * Typecheck the project at `cwd` with its own tsconfig + compiler.
@@ -76,9 +132,9 @@ async function typecheckProject(cwd) {
 		ok: true,
 		skipped: true
 	};
-	let tscEntry;
+	let tsc;
 	try {
-		tscEntry = resolveTscEntry(cwd);
+		tsc = resolveTsc(cwd);
 	} catch (err) {
 		return {
 			ok: false,
@@ -86,12 +142,7 @@ async function typecheckProject(cwd) {
 		};
 	}
 	const result = await new Promise((resolve, reject) => {
-		const child = spawn(process.execPath, [
-			tscEntry,
-			"--noEmit",
-			"--pretty",
-			"false"
-		], {
+		const child = spawn(process.execPath, tscArgs(tsc.entry, tsc.major), {
 			cwd,
 			timeout: TYPECHECK_TIMEOUT_MS,
 			stdio: [

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "5.8.1",
+  "version": "5.10.0",
   "type": "module",
   "bin": {
-    "aai": "dist/cli.mjs"
+    "aai": "bin.mjs"
   },
   "exports": {
     "./client-bundler": {
@@ -23,6 +23,7 @@
     }
   },
   "files": [
+    "bin.mjs",
     "dist"
   ],
   "dependencies": {
@@ -37,8 +38,8 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.1.5",
     "zod": "^4.4.3",
-    "@alexkroman1/aai-ui": "5.8.1",
-    "@alexkroman1/aai": "5.8.1"
+    "@alexkroman1/aai": "5.10.0",
+    "@alexkroman1/aai-ui": "5.10.0"
   },
   "devDependencies": {
     "playwright": "^1.61.1",