0.6.10 - deterministic waiting, safe self-healing, token controls, domain understanding

[divshekhar]

What this is

The 0.6.10 feature release — live-verified, not 1.0.0 (see plan/V1-ROADMAP.md for the 1.0 gate). Bumps all 10
publishable @syrin/iris-* packages 0.5.0 → 0.6.10.

Highlights (full list in CHANGELOG [0.6.10])

Deterministic waiting (M3) — kills the #1 flake cause (sleeps)

• New { kind: "settled", quietMs } predicate: passes once network + structural-DOM activity is quiet for quietMs. Ambient
  dom.text/animation churn (count-ups, spinners) is ignored so an animated page still settles.
• iris_act_and_wait with no until now auto-settles — "act, then wait for quiet" in one call, the documented replacement
  for a fixed sleep.

Self-healing (M5) — heal the locator, never the intent

• iris_flow_heal apply:true re-replays the healed flow and re-asserts its success consequence; if a rebound locator resolves
  but the consequence no longer fires, the write is refused (status:consequence_broken, file untouched).

Token efficiency (M2) — every read tool self-budgets

• iris_query gains limit + count_only; iris_network/iris_console gain limit + a cost:{bytes,tokens} hint
  (most-recent-N, non-silent truncation).

Domain understanding (M4)

• iris_domain now reports mustHold per flow — the success consequence that must hold — so an agent can answer "what are the
  critical flows and what must hold for each?" from the model alone.

Rigor
success-oracle thesis, now enforced at the live-assert layer too).

Reliability

• Browser observers (network/route/console) now restore the true original global on teardown instead of a bound copy.

Verification

• Unit: build 10/10, lint 9/9, typecheck 18/18, unit tests 16/16 packages (~978 tests).
• Live e2e on this build: full Playwright battery 14/14 (Vite/React demo + Next.js 15 + api) → no regression; a new
  new-features-test.mjs spec 7/7 positively exercises the new surfaces in a real browser — including settled resolving
  against the demo's count-up animations (the exact ambient-churn condition the fix targets).

Summary by CodeRabbit

• New Features

  • Deterministic settling predicates for reliable page waits
  • iris_act_and_wait auto-settles when until is omitted
  • iris_query now supports limit and count_only pagination controls
  • Network and console tools now support limit parameter
  • New iris_domain tool for inspecting app's testable surface
  • New iris init command for guided project setup with Vite/Next/Claude/Cursor integration

• Bug Fixes

  • Browser teardown now fully restores patched globals to original identities
  • iris_flow_heal re-verifies success consequences; refuses to persist if broken

• Documentation

  • Updated getting-started guides for new setup command and Vite plugin integration
  • Added token-efficiency guidance for diffed snapshots

[coderabbitai]

Warning

Review limit reached

@divshekhar, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 45 minutes and 26 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 08274d45-919f-4fb3-a8e8-888c7bcc4f0e

📥 Commits

Reviewing files that changed from the base of the PR and between 3b0e8e0 and 777a60b.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (2)

• packages/vite-plugin/package.json
• pre-commit.sh

📝 Walkthrough

Walkthrough

This PR adds new Iris tool behaviors, flow and domain analysis, iris init, a Vite plugin package and export path, browser observer teardown fixes, end-to-end and unit coverage, documentation updates, and release/version metadata for v0.6.10.

Changes

Core release changes

Layer / File(s)	Summary
Tool runtime controls and predicates packages/server/src/tools/*, packages/server/src/events/predicate.ts, packages/server/src/session/output-budget.ts, apps/e2e/specs/new-features-test.mjs, docs/agent-cheatsheet.md, docs/token-efficiency.md, docs/usage.md	Adds settled predicate support, snapshot diff responses, query pagination, cost metadata, observe recommendations, passing presence-only assert advice, and network or console limit handling, with tests and docs.
Flow grading and domain summaries packages/server/src/flows/flow-classify.ts, packages/server/src/flows/flow-success.ts, packages/server/src/domain/*, packages/server/src/index.ts, packages/test/src/*	Adds flow assertion grading, success assertion helpers, domain-model and risk-ranking builders, the iris_domain tool, richer flow save/list outputs, public re-exports, and shared test-side usage.
Replay success verification and heal safeguards packages/protocol/src/*, packages/server/src/flows/flow-replay.ts, packages/server/src/flows/heal.ts, packages/server/src/flows/flow-tools.ts, packages/server/src/flows/flows.ts, packages/server/src/flows/*test.ts	Adds replay time-floor support, ambiguous drift reporting, reusable heal application, replay success verification, and refusal to persist healed flows when the declared consequence no longer passes.
Vite plugin package and SDK export packages/vite-plugin/*, packages/iris/src/vite.ts, packages/iris/package.json, packages/iris/tsup.config.ts, docs/getting-started.md	Introduces the Vite plugin package, exposes @syrin/iris/vite, adds tests and README coverage, updates build references, and documents plugin-based Vite and React wiring.
Init command and project wiring packages/server/src/cli.ts, packages/server/src/init/*, docs/getting-started.md, docs/integrate-with-claude-code.md	Adds the iris init CLI flow, project detection, MCP registration planning for Claude and Cursor, install and framework-specific wiring steps, Node-backed execution, and updated setup guidance.
Browser observer restoration and release metadata packages/browser/src/observers/*, CHANGELOG.md, packages/*/package.json	Restores original browser global identities after console, fetch, and route observer teardown, adds regression tests, updates the changelog, and bumps package versions to 0.6.10.

Sequence Diagram(s)

sequenceDiagram
  participant CLI as iris init
  participant Runner as runInit
  participant Planner as buildPlan
  participant Claude as claude mcp add
  participant Cursor as ~/.cursor/mcp.json
  participant Project as vite.config.ts

  CLI->>Runner: init options
  Runner->>Planner: gather inputs and build plan
  Planner-->>Runner: MCP, install, framework steps
  Runner->>Claude: register iris MCP when planned
  Runner->>Cursor: merge iris server config when planned
  Runner->>Project: patch Vite config when planned

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~105 minutes

Poem

🐇 I sniffed through tools and trails anew,
Found quieter waits and snapshots too.
A Vite burrow bloomed beside the lane,
While heals now test their hops again.
With tidy paws, the globals came back home.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 46.75% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main features of this release: deterministic waiting, self-healing, token controls, and domain understanding are all core changes reflected in the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/iris-init-vite-plugin

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 15

Note

Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/getting-started.md (1)

443-443: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Align the troubleshooting package name with Step 3.

This line points to @syrin/iris-babel-plugin, while Step 3 instructs @syrin/iris/babel. Keeping both names in one guide is confusing and can misdirect setup.

Suggested doc fix

-- Wire up `@syrin/iris-babel-plugin` (Step 3). Without it, only component identity is available.
+- Wire up `@syrin/iris/babel` (Step 3). Without it, only component identity is available.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/getting-started.md` at line 443, The troubleshooting section mentions
`@syrin/iris-babel-plugin` but Step 3 of the guide references
`@syrin/iris/babel`. Update the package name reference at line 443 to use
`@syrin/iris/babel` instead to match the package name specified in Step 3,
ensuring consistency throughout the documentation and preventing setup
confusion.

🟡 Minor comments (8)

packages/browser/src/observers/console.test.ts-27-36 (1)

27-36: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Assert forwarding explicitly in the first test.

The test name says forwarding is verified, but only event emission is asserted. Add an assertion that the original console.error path is invoked so this regression is actually covered.

Suggested patch

 it('emits CONSOLE_ERROR and still forwards to the original console', () => {
+  const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
   const { emit, events } = collect();
   teardown = installConsole(emit);

   console.error('boom', 42);

   expect(events).toHaveLength(1);
   expect(events[0]?.type).toBe(EventType.CONSOLE_ERROR);
   expect(events[0]?.data.message).toBe('boom 42');
+  expect(errorSpy).toHaveBeenCalledWith('boom', 42);
+  errorSpy.mockRestore();
 });

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/browser/src/observers/console.test.ts` around lines 27 - 36, The
test verifies event emission but does not assert that the original console.error
method is actually being forwarded. Add a spy or mock of the original
console.error method before calling installConsole, then after the console.error
call, add an assertion to verify that the original console.error was invoked
with the correct arguments ('boom' and 42) to ensure the forwarding behavior is
actually covered by the test.

CHANGELOG.md-7-7 (1)

7-7: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add the missing link definition for 0.6.10.

The heading uses [0.6.10] reference-link syntax, but there is no matching link definition at the bottom, so this version entry won’t hyperlink.

📝 Proposed fix

+[0.6.10]: https://github.com/syrin-labs/iris/releases/tag/v0.6.10
 [0.5.0]: https://github.com/syrin-labs/iris/releases/tag/v0.5.0
 [0.4.0]: https://github.com/syrin-labs/iris/releases/tag/v0.4.0

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CHANGELOG.md` at line 7, The heading for version 0.6.10 uses markdown
reference-link syntax with [0.6.10], but there is no corresponding link
definition at the bottom of the CHANGELOG.md file to complete the reference. Add
a link definition at the end of the file following the pattern of other version
links in the document to match the [0.6.10] reference in the heading and enable
proper hyperlinking for this version entry.

docs/usage.md-267-267 (1)

267-267: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add mustHold? to the documented iris_domain flow shape.

Line 267 omits mustHold?, but buildDomainModel sets it when a flow has success (see packages/server/src/domain/domain-model.ts Line 117). The docs currently under-specify the returned payload.

Doc fix

-- `iris_domain({})` → `{ flowCount, flows: [{ name, steps, grade, asserts, signals, testids, warning?, risk? }], declared: { testids, signals, stores }, coverage: { asserted, presenceOnly, assertionFree }, gaps: { unassertedFlows, declaredUntestedSignals, declaredUntestedTestids }, riskRanked, summary }`
+- `iris_domain({})` → `{ flowCount, flows: [{ name, steps, grade, asserts, signals, testids, mustHold?, warning?, risk? }], declared: { testids, signals, stores }, coverage: { asserted, presenceOnly, assertionFree }, gaps: { unassertedFlows, declaredUntestedSignals, declaredUntestedTestids }, riskRanked, summary }`

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/usage.md` at line 267, The `iris_domain({})` return type documentation
at line 267 of docs/usage.md is missing the `mustHold?` optional property from
the flow object shape. Add `mustHold?` to the documented flow properties in the
return type definition to match what `buildDomainModel` actually sets in the
packages/server/src/domain/domain-model.ts file when a flow has a success
condition.

packages/server/src/flows/flows.heal.test.ts-85-93 (1)

85-93: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Make the heal test session cursor-aware so stale-signal protection is actually exercised.

heal(..., apply: true) verifies success using a since floor from session.elapsed(). Here, eventsSince() ignores the cursor and elapsed() is always 0, so buffered signals can satisfy verification even when they should be considered stale.

Suggested test-harness fix

-  eventsSince(): IrisEvent[] {
-    return this.events;
+  eventsSince(cursor: number): IrisEvent[] {
+    return this.events.filter((event) => event.t >= cursor);
   }
@@
   elapsed(): number {
-    return 0;
+    return 1;
   }
@@
 function signalEvent(name: string): IrisEvent {
-  return { t: 0, type: EventType.SIGNAL, sessionId: 's', data: { name, data: {} } };
+  return { t: 1, type: EventType.SIGNAL, sessionId: 's', data: { name, data: {} } };
 }

Also applies to: 96-99

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/flows/flows.heal.test.ts` around lines 85 - 93, The test
mock session needs to be made cursor-aware to properly exercise stale-signal
protection. Modify the mock session to track a cursor position and elapsed time:
make eventsSince() accept and use a cursor parameter to filter events rather
than returning all events, and make elapsed() return an actual tracked value
(either incrementing or controllable) instead of always returning 0. This will
ensure that heal(..., apply: true) verification with the since floor from
session.elapsed() properly validates that buffered signals outside the time
window are considered stale.

packages/server/src/tools/snapshot-cost.test.ts-6-11 (1)

6-11: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove design-doc identifiers from comments, test title, and log labels.

M0/M2 markers are internal design-doc style identifiers and should not appear in comments/test strings.

✏️ Suggested edit

- * M0 — a reproducible measurement of the M2 token wins, run over the REAL shipped functions
+ * Reproducible measurement of token savings, run over the real shipped functions
@@
-describe('M0 — snapshot token cost (M2 wins, measured on real functions)', () => {
+describe('Snapshot token cost regression (measured on real functions)', () => {
@@
-      `[M0] full re-snapshot=${String(fullTokens)} tok  diff=${String(deltaTokens)} tok  saved=${String(savedPct)}%`,
+      `[snapshot-cost] full re-snapshot=${String(fullTokens)} tok  diff=${String(deltaTokens)} tok  saved=${String(savedPct)}%`,
@@
-    console.log(`[M0] unchanged re-snapshot=${String(unchangedTokens)} tok`);
+    console.log(`[snapshot-cost] unchanged re-snapshot=${String(unchangedTokens)} tok`);
@@
-      `[M0] cost preview: ${String(preview.tokens)} tok / ${String(preview.bytes)} bytes`,
+      `[snapshot-cost] cost preview: ${String(preview.tokens)} tok / ${String(preview.bytes)} bytes`,

As per coding guidelines, "Never include internal tracking tags in comments, file names, directory names, or test descriptions. Do not use design-doc reference codes (letter + digit patterns like N5, G4, M8, P2, F1, R1) or internal version strings."

Also applies to: 39-40, 59-60, 78-78, 87-88

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/tools/snapshot-cost.test.ts` around lines 6 - 11, Remove
the internal design-doc identifiers M0 and M2 from the comment block in the
snapshot-cost.test.ts file. Specifically, remove "M0 — a reproducible
measurement of the" and replace it with a direct description, and remove "M2"
references so the comment describes the measurement approach without internal
tracking codes. Apply the same fix to all other locations in the file where
these design-doc reference patterns appear (at lines 39-40, 59-60, 78, and
87-88), ensuring all letter-digit patterns like N5, G4, M8, etc. are removed
from comments, test titles, and log labels throughout the file.

Source: Coding guidelines

apps/e2e/specs/new-features-test.mjs-1-1 (1)

1-1: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove the internal changelog tag from the file comment.

[Unreleased] in an inline comment violates the internal-tag prohibition.

✏️ Suggested edit

-// Live verification of the features added in the [Unreleased] CHANGELOG section, against the real
+// Live verification of the features added in the CHANGELOG section, against the real

As per coding guidelines, "Never include internal tracking tags in comments, file names, directory names, or test descriptions."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/e2e/specs/new-features-test.mjs` at line 1, The file comment at the
start of new-features-test.mjs contains the internal changelog tag [Unreleased]
which violates the coding guideline prohibiting internal tracking tags in
comments. Remove the reference to [Unreleased] and the CHANGELOG section from
the comment, keeping only the core description of what the file does for live
feature verification.

Source: Coding guidelines

packages/server/src/tools/assert-grade.ts-40-46 (1)

40-46: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Mixed predicates are incorrectly flagged as presence-only.

At Line 44-46 and Line 60, allOf/anyOf with { kind: 'element' } plus a non-presence predicate like { kind: 'settled' } still returns presence-only advice. That contradicts the contract in this file and causes false advice emission.

Proposed fix

 interface PredicateKinds {
   /** A signal/net leaf is present — proves the app did something a wrong element cannot fake. */
   consequence: boolean;
   /** An element/text leaf is present — a weak presence check. */
   presence: boolean;
+  /** Any non-presence, non-consequence leaf (route/console/animation/settled). */
+  other: boolean;
 }

 function walk(predicate: Predicate): PredicateKinds {
   switch (predicate.kind) {
     case 'signal':
     case 'net':
-      return { consequence: true, presence: false };
+      return { consequence: true, presence: false, other: false };
     case 'element':
     case 'text':
-      return { consequence: false, presence: true };
+      return { consequence: false, presence: true, other: false };
     case 'route':
     case 'console':
     case 'animation':
     case 'settled':
-      // Observable but not the weak presence pattern we nudge — neither flags the advice.
-      return { consequence: false, presence: false };
+      return { consequence: false, presence: false, other: true };
     case 'allOf':
     case 'anyOf': {
       const subs = predicate.predicates.map(walk);
       return {
         consequence: subs.some((s) => s.consequence),
         presence: subs.some((s) => s.presence),
+        other: subs.some((s) => s.other),
       };
     }
     case 'not':
       return walk(predicate.predicate);
   }
 }

 export function isPresenceOnlyAssertion(predicate: Predicate): boolean {
   const kinds = walk(predicate);
-  return kinds.presence && !kinds.consequence;
+  return kinds.presence && !kinds.consequence && !kinds.other;
 }

Also applies to: 58-60

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/tools/assert-grade.ts` around lines 40 - 46, The walk
function's handling of allOf and anyOf predicates incorrectly marks mixed
predicates (containing both presence-only and non-presence predicates) as
presence-only. In the return statement for these cases, the presence property is
computed using subs.some() which returns true if ANY sub-predicate is
presence-only; this should instead use subs.every() to return true only when ALL
sub-predicates are presence-only. This ensures that a combined predicate is only
flagged as presence-only when all of its constituent predicates are
presence-only, fixing the false advice emission issue that contradicts the
file's contract. Apply the same fix to both the allOf/anyOf case block starting
around line 42 and the similar logic at line 58-60.

packages/server/src/init/mcp.ts-42-45 (1)

42-45: ⚠️ Potential issue | 🟡 Minor

Extract CLI command strings as named constants.

The function uses inline strings ('get', 'add', 'user', '-s', '--', '--version') for CLI arguments. Per the coding guidelines, all domain/wire/UI strings must be named constants. Define constants for these command tokens (e.g., const MCP_GET_SUBCOMMAND = 'get', const MCP_ADD_SUBCOMMAND = 'add', const SCOPE_USER = 'user', etc.) and reference them instead.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/init/mcp.ts` around lines 42 - 45, The
claudeExistsProbe() function and other functions in this file use inline string
literals for CLI command arguments (such as 'get', 'add', 'user', '-s', '--',
'--version') instead of named constants. Define named constants at the top of
the file for each of these CLI command tokens (e.g., MCP_GET_SUBCOMMAND,
MCP_ADD_SUBCOMMAND, SCOPE_USER, etc.) following the same naming pattern as the
existing CLAUDE_CLI, MCP_SUBCOMMAND, and MCP_SERVER_NAME constants, then replace
all inline string occurrences throughout the file with references to these new
constants.

🧹 Nitpick comments (10)

packages/server/src/flows/flow-success.ts (1)

30-75: ⚡ Quick win

Extract domain/wire string literals into named constants.

This segment introduces multiple free domain/wire literals ('signal', 'net', 'element', 'allOf', 'testid', 'role', 'name', 'net', 'success'). Please promote them to named constants to match repository rules.

Proposed refactor

+const PredicateKind = {
+  signal: 'signal',
+  net: 'net',
+  element: 'element',
+  allOf: 'allOf',
+} as const;
+
+const ElementQueryKey = {
+  testid: 'testid',
+  role: 'role',
+  name: 'name',
+} as const;
+
+const SuccessLabelFallback = {
+  net: 'net',
+  success: 'success',
+} as const;
+
 export function successLabel(success: FlowExpect): string {
   if (success.signal !== undefined) return success.signal;
-  if (success.net !== undefined) return success.net.urlContains ?? success.net.method ?? 'net';
-  return success.element?.testid ?? success.element?.name ?? success.element?.role ?? 'success';
+  if (success.net !== undefined)
+    return success.net.urlContains ?? success.net.method ?? SuccessLabelFallback.net;
+  return (
+    success.element?.testid ??
+    success.element?.name ??
+    success.element?.role ??
+    SuccessLabelFallback.success
+  );
 }
 ...
-      const query: Record<string, string> = {};
-      if (testid !== undefined) query['testid'] = testid;
-      if (element.role !== undefined) query['role'] = element.role;
-      if (element.name !== undefined) query['name'] = element.name;
-      if (Object.keys(query).length > 0) parts.push({ kind: 'element', query });
+      const query: Record<string, string> = {};
+      if (testid !== undefined) query[ElementQueryKey.testid] = testid;
+      if (element.role !== undefined) query[ElementQueryKey.role] = element.role;
+      if (element.name !== undefined) query[ElementQueryKey.name] = element.name;
+      if (Object.keys(query).length > 0) parts.push({ kind: PredicateKind.element, query });

As per coding guidelines, “All domain/wire/UI strings must be named constants, never free strings in code.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/flows/flow-success.ts` around lines 30 - 75, Extract all
hardcoded string literals from the successLabel and successToPredicate functions
into named constants at the module level. Replace all occurrences of 'signal',
'net', 'element', 'allOf', 'testid', 'role', 'name', and 'success' string
literals with these named constants throughout both functions to comply with the
domain/wire string literal guidelines.

Source: Coding guidelines

packages/server/src/domain/domain-model.test.ts (1)

59-67: ⚡ Quick win

Add a regression test for “anchor signal only” coverage.

Please add a case where a flow references a signal anchor but does not assert expect.signal/success.signal, and verify declaredUntestedSignals still flags it. That protects the stated “asserted signal” contract.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/domain/domain-model.test.ts` around lines 59 - 67, Add a
new test case in the test file after the existing test that verifies when a flow
defines a signal anchor (via the signal property in flow()) but does not assert
it with expect.signal or success.signal, the signal is still properly flagged in
declaredUntestedSignals. Use buildDomainModel, flow, and contract functions
similar to the existing test pattern to construct a scenario where a flow
references a signal without asserting it, then verify that signal appears in the
gaps.declaredUntestedSignals array to protect the stated asserted signal
contract.

packages/server/src/domain/flow-risk.test.ts (1)

29-52: ⚡ Quick win

Add a PRESENCE_ONLY risk test case.

Current coverage skips the FlowAssertionGrade.PRESENCE_ONLY branch, so risk-priority regressions there won’t be caught.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/domain/flow-risk.test.ts` around lines 29 - 52, The test
suite for flowRisk is missing coverage for the FlowAssertionGrade.PRESENCE_ONLY
case, which could allow regressions to go undetected. Add a new test case in the
describe block that exercises the PRESENCE_ONLY grade by calling flowRisk with
FlowAssertionGrade.PRESENCE_ONLY as the first argument and a run result as the
second argument (similar to the existing test cases like the assertion-free flow
test), then assert the expected RiskLevel that should be returned for this grade
to ensure the branch is properly tested and documented.

packages/server/src/events/predicate.ts (1)

363-373: ⚡ Quick win

Extract newly introduced wire strings to named constants.

Line 363 and Line 372 introduce new inline domain/wire strings (note and failureReason). Please hoist these to named constants to match the repository rule and keep message contracts centralized.

As per coding guidelines, "All domain/wire/UI strings must be named constants, never free strings in code."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/events/predicate.ts` around lines 363 - 373, The inline
strings `'no activity to settle'` (used as the note value) and the failureReason
string template (used in the failureReason property) need to be extracted to
named constants following the repository's coding guidelines. Define these
strings as named constants at the module level or in a centralized constants
location, then replace the inline string literals with references to those
constants. Ensure the failureReason constant properly handles the dynamic values
by using a template string with the placeholders for lastType, quietForMs, and
quietMs.

Source: Coding guidelines

packages/server/src/events/predicate.test.ts (1)

228-311: ⚡ Quick win

Consolidate repeated predicate/event literals into named test constants.

The new settled suite adds many inline domain/wire strings (e.g., predicate kinds, signal names, URLs, messages). Please move these to file-level constants for compliance and easier fixture reuse.

As per coding guidelines, "All domain/wire/UI strings must be named constants, never free strings in code."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/events/predicate.test.ts` around lines 228 - 311, Extract
all inline domain/wire/UI strings from the settled predicate test suite (the
describe block starting at line 228) into file-level named constants. This
includes predicate kinds like 'settled', 'signal', and 'allOf', signal names
like 'deploy:shipped' and 'x', URLs like '/api/x' and '/api/deploy', event
property names and values, and failure reason strings like 'not settled'.
Replace all occurrences of these inline literals throughout the test cases with
references to the corresponding named constants to ensure compliance with the
coding guideline that all domain/wire/UI strings must be named constants.

Source: Coding guidelines

packages/server/src/tools/tools.near-miss.test.ts (1)

79-127: ⚡ Quick win

Extract newly added event/tool literals to shared constants.

The new token-budget tests add inline domain/wire strings (URLs, messages, tool-facing literals). Please promote them to named constants for compliance and consistency with other fixtures.

As per coding guidelines, "All domain/wire/UI strings must be named constants, never free strings in code."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/tools/tools.near-miss.test.ts` around lines 79 - 127, The
token budget tests in the describe block contain hardcoded string literals for
URLs, console messages, and log levels that should be extracted to named
constants. Identify all inline strings in the test cases including the URLs
'/1', '/2', '/3' used in iris_network tests, the messages 'a', 'b', 'c' used in
iris_console tests, and the level string 'error' used in the iris_console test.
Create named constants for each of these values and replace the inline strings
throughout the test methods (in the ev() calls, handler calls, and expect
assertions) with references to these constants to ensure compliance with the
coding guideline that all domain/wire strings must be named constants.

Source: Coding guidelines

packages/server/src/tools/assert-grade.test.ts (1)

5-60: ⚡ Quick win

Apply the string-constant rule in this new test suite.

This file introduces many inline domain/wire strings in predicates and assertions. Please define named constants and reuse them across cases.

As per coding guidelines, "All domain/wire/UI strings must be named constants, never free strings in code."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/tools/assert-grade.test.ts` around lines 5 - 60, The test
suite in isPresenceOnlyAssertion contains many inline string literals for
predicate kinds (element, text, signal, net, allOf, not, route, settled,
console) and test data values (button, Saved, order:placed, /api/order, Done,
Welcome, /success, error, etc.). Define named constants at the top of the test
file for all these domain/wire/UI strings and replace each inline string literal
throughout all test cases in the describe block with references to the
corresponding constant. This ensures consistency and makes the strings reusable
across the test suite.

Source: Coding guidelines

packages/server/src/session/output-budget.ts (1)

46-46: ⚡ Quick win

Extract the recommendation message into a named constant.

This introduces a free domain/wire string inline in a .ts file; move it to a named constant and format it from parameters.

♻️ Suggested change

+const LARGE_TIMELINE_RECOMMENDATION_TEMPLATE =
+  'large timeline ({events} events, ~{tokens} tokens) — pass filters:[...] (e.g. ["signal","net"]) or max_events to scope your next call and cut tokens';
+
 export function costHint(payload: unknown, events: number, droppedOldest = 0): CostHint {
   const json = JSON.stringify(payload) ?? '';
   const bytes = json.length;
   const base: CostHint = droppedOldest > 0 ? { events, bytes, droppedOldest } : { events, bytes };
   if (events >= LARGE_TIMELINE_EVENTS || bytes >= LARGE_TIMELINE_BYTES) {
-    base.recommendation = `large timeline (${String(events)} events, ~${String(estimateTokens(json))} tokens) — pass filters:[...] (e.g. ["signal","net"]) or max_events to scope your next call and cut tokens`;
+    base.recommendation = LARGE_TIMELINE_RECOMMENDATION_TEMPLATE
+      .replace('{events}', String(events))
+      .replace('{tokens}', String(estimateTokens(json)));
   }
   return base;
 }

As per coding guidelines, "All domain/wire/UI strings must be named constants, never free strings in code."

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/session/output-budget.ts` at line 46, Extract the
hardcoded recommendation message string currently assigned to
base.recommendation into a named constant at the module level. The constant
should contain the template with placeholders for the dynamic values (events
count and estimated tokens), and then reference this constant in the assignment
while still providing the formatted parameters. This ensures the domain/wire
string is not a free string in the code but follows the guideline of being a
named constant.

Source: Coding guidelines

packages/server/src/init/run.test.ts (1)

61-67: ⚡ Quick win

Add a regression test for malformed package.json.

The suite checks the missing-file case but not invalid JSON content. A targeted test here will prevent reintroducing the crash path.

🧪 Suggested test case

 describe('runInit', () => {
   it('errors cleanly without a package.json', () => {
     const io = memoryIo({});
     const r = runInit(OPTS, io);
     expect(r.ok).toBe(false);
     expect(io.lines.join('\n')).toContain('No package.json');
   });

+  it('errors cleanly with an invalid package.json', () => {
+    const io = memoryIo({ 'package.json': '{ "name": "bad-json",' });
+    const r = runInit(OPTS, io);
+    expect(r.ok).toBe(false);
+    expect(io.lines.join('\n')).toContain('Invalid package.json');
+  });
+
   it('registers iris globally via the claude CLI (not a project .mcp.json) and patches vite', () => {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/init/run.test.ts` around lines 61 - 67, Add a new
regression test case in the same test suite after the existing "errors cleanly
without a package.json" test. Create a test that verifies the runInit function
handles malformed JSON content gracefully. Use memoryIo to provide a
package.json file with invalid JSON syntax (such as incomplete or syntactically
broken JSON), call runInit with OPTS and the io object, and verify that the
result has ok set to false and that io.lines contains an appropriate error
message indicating the JSON parsing failure. This test will prevent crashes when
package.json exists but contains invalid JSON.

packages/server/src/init/vite-config.test.ts (1)

30-34: ⚡ Quick win

Add a regression case for “import exists, plugin missing”.

Current idempotency coverage only verifies fully patched input. Add a test where the config already imports @syrin/iris/vite but plugins lacks iris(); expected result should still be APPLY.

Suggested test

+  it('does not treat import-only configs as already patched', () => {
+    const src = `import { defineConfig } from 'vite';
+import { iris } from '`@syrin/iris/vite`';
+import react from '`@vitejs/plugin-react`';
+
+export default defineConfig({
+  plugins: [react()],
+});
+`;
+    const r = patchViteConfig(src);
+    expect(r.kind).toBe(VitePatchKind.APPLY);
+  });

Also applies to: 56-61

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/init/vite-config.test.ts` around lines 30 - 34, Add a new
test case after the existing idempotency test in the test file to cover the
regression scenario where a Vite config already has the import statement for
`@syrin/iris/vite` but is missing the iris() plugin in the plugins array. Create a
test config string that includes the import line but lacks the iris() function
call in the plugins configuration, then call patchViteConfig on this config and
assert that the returned kind is VitePatchKind.APPLY, confirming that the
function correctly identifies and applies the patch for this incomplete state.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/e2e/specs/new-features-test.mjs`:
- Around line 54-91: The test code lacks proper error handling and resource
cleanup. If any await statement throws an error before reaching b.close() and
server.close(), resources will leak and hang the CI. Wrap all the test logic
(from chromium.launch through the final chk call) in a try block, and move the
b.close() and server.close() calls into a finally block that runs regardless of
success or failure. Keep the process.exit call after the finally block to ensure
it only executes after cleanup is complete.

In `@packages/server/src/domain/domain-model.ts`:
- Around line 174-190: Extract all hardcoded strings in the coverage status
message building code into named constants at the module or class level. This
includes the "No saved flows yet" message, the template strings used for
constructing the parts array such as "flow"/"flows", "test first: ", "declared
signal(s) no flow asserts (", and "flow(s) assert no consequence". Replace each
free string in the code with a reference to its corresponding named constant to
ensure consistency and maintainability of domain strings throughout the
codebase.
- Around line 77-85: The flowSignals function incorrectly includes anchor
signals in addition to asserted signals, which causes flows that only reference
a signal anchor to be treated as tested even when they don't actually assert or
expect that signal. Remove the line that adds anchor signals to the set (the
condition checking if step.anchor.kind === AnchorKind.SIGNAL) so that only
signals that are explicitly asserted through expect.signal or success.signal are
counted as covered by the flow.

In `@packages/server/src/domain/domain-tools.ts`:
- Around line 23-37: The outputSchema.flows object definition is missing the
optional risk field that is actually returned by the handler's buildDomainModel
function call, causing a schema contract mismatch for consumers. Add an optional
risk field to the Zod schema object within the flows definition (around the
z.object block), using the same pattern as the other optional fields like
mustHold and warning, declaring it as z.string().optional() or with an
appropriate type based on what buildDomainModel returns.
- Around line 17-19: Extract all free string literals from the tool definition
(including the long description string in the description field, and any strings
at the locations mentioned in lines 31-33 and 57-58) into named constants at the
top of the file, then replace each free string with a reference to its
corresponding constant. This ensures all domain/wire/UI strings follow the
repository policy of being named constants rather than inline literals.

In `@packages/server/src/domain/flow-risk.ts`:
- Around line 64-75: The gradeRisk function currently maps
FlowAssertionGrade.PRESENCE_ONLY to RiskLevel.LOW, which incorrectly ranks it as
equivalent to consequence-asserting flows. Instead, change the return value for
the PRESENCE_ONLY condition to return a higher risk level (such as
RiskLevel.MEDIUM) to properly reflect that presence-only assertions represent a
weaker oracle and should be prioritized higher in triage according to the
module's risk prioritization strategy.

In `@packages/server/src/flows/flow-tools.ts`:
- Around line 109-117: The assertions schema object in the outputSchema (which
contains fields like grade, hasConsequenceAssertion, totalSteps,
consequenceSteps, weakSteps, and warning) is missing the successIsConsequence
field that is actually returned by the classifyFlowAssertions function on line
143. Add the successIsConsequence field to the z.object() schema definition with
an appropriate zod type (likely z.boolean()) to match the payload being returned
and prevent strict schema consumers from rejecting the response.
- Around line 246-247: The condition for `stepsClean` includes `steps.length >
0`, which prevents success verification when a flow has zero replayed steps.
This allows flows with declared `success` values but no steps to bypass the
`assertSuccess` check. Remove the `steps.length > 0` requirement from the
`stepsClean` variable definition so that success verification occurs regardless
of whether there are any steps, ensuring that any declared success consequence
is properly validated. Apply this same fix to the similar pattern at lines
483-484.

In `@packages/server/src/init/cursor.ts`:
- Around line 39-44: The parseConfig function currently returns a success result
with an empty config object when encountering non-object JSON roots or null
values, which incorrectly allows automatic rewrites that could overwrite
existing configuration. Modify the parseConfig function to return a result
indicating MANUAL handling mode instead of ok: true when the parsed JSON root is
not an object or is null. Additionally, apply the same MANUAL handling approach
for invalid mcpServers shapes in the configuration validation logic (in the
range around lines 54-67) to prevent unintended rewrites of existing
configuration content.

In `@packages/server/src/init/mcp.ts`:
- Around line 38-50: Extract the inline CLI command tokens ('add', 'user',
'get', '--version') into named constants at the module level, following the
no-free-strings rule. Define constants for each token (e.g., similar to how
CLAUDE_CLI, MCP_SUBCOMMAND, and MCP_SERVER_NAME are defined), then replace all
occurrences of these hardcoded strings in the command builder function and the
claudeExistsProbe and claudeAvailableProbe functions with references to the
newly created constants. This ensures all domain/wire strings are captured as
named constants throughout the module.

In `@packages/server/src/init/plan.ts`:
- Around line 68-255: Extract the inline string literals for step titles and
details throughout the file into named constants at the top, following the
pattern of CLAUDE_MCP_TITLE and CURSOR_MCP_TITLE. This applies to strings in the
installStep, viteSteps, nextSteps, and buildPlan functions including titles like
"Install dependency", "Vite plugin", "IrisDev component", "Next config
(withIris)", "Mount IrisDev", "Connect snippet", and their corresponding detail
messages. Replace each inline string literal with the appropriate constant
reference to ensure all domain/UI strings are centralized and follow the
repository's coding guidelines.

In `@packages/server/src/init/run.ts`:
- Around line 70-71: The JSON.parse call in the gatherPlanInput function at line
71 can throw an exception if the pkgRaw string contains malformed JSON, causing
the CLI to crash. Wrap the JSON.parse(pkgRaw) call in a try-catch block to
handle the parse error gracefully, and either throw a custom error with a
user-friendly message or return an error state that the caller can handle.
Similarly, check the related code around lines 157-166 where similar JSON
parsing may occur and apply the same error handling pattern to ensure all JSON
parsing in the runInit path handles malformed input without crashing.

In `@packages/server/src/init/vite-config.ts`:
- Around line 49-57: The ALREADY detection in patchViteConfig function is too
broad because checking only if the source includes IRIS_MARKER can match
occurrences in comments or imports without verifying the iris plugin is actually
in the plugins array. Replace the simple source.includes(IRIS_MARKER) check with
a more robust validation that confirms the iris() plugin call is present in the
plugins array, similar to how PLUGINS_ARRAY.test(source) validates the plugins
array structure. This ensures ALREADY is only returned when the plugin injection
is truly complete.

In `@packages/server/src/tools/tools.ts`:
- Line 1299: The tools.ts file exceeds the repository's 500-line file limit at
1299 lines. Refactor by extracting related tool definition groups (such as
snapshot tools, query tools, assert tools, and network-console tools) into
separate dedicated modules. Then import these extracted tool groups back into
tools.ts and compose them together in the DOMAIN_TOOLS spread operator to
maintain the same public API while keeping each file within the 500-line limit.
- Around line 339-356: The snapshot cache key generation in the handler function
uses a fallback value of 'default' when sessionId is not provided, causing
different sessions without an explicit sessionId to share the same cache entry
in the process-wide SNAPSHOT_CACHE. This creates privacy and correctness issues
as unrelated sessions can get deltas computed from another session's prior
snapshot. Remove the fallback to 'default' in the sessionId field passed to
applySnapshotDelta and ensure each session has a uniquely identifiable sessionId
rather than silently defaulting multiple sessions to the same cache key value.

---

Outside diff comments:
In `@docs/getting-started.md`:
- Line 443: The troubleshooting section mentions `@syrin/iris-babel-plugin` but
Step 3 of the guide references `@syrin/iris/babel`. Update the package name
reference at line 443 to use `@syrin/iris/babel` instead to match the package
name specified in Step 3, ensuring consistency throughout the documentation and
preventing setup confusion.

---

Minor comments:
In `@apps/e2e/specs/new-features-test.mjs`:
- Line 1: The file comment at the start of new-features-test.mjs contains the
internal changelog tag [Unreleased] which violates the coding guideline
prohibiting internal tracking tags in comments. Remove the reference to
[Unreleased] and the CHANGELOG section from the comment, keeping only the core
description of what the file does for live feature verification.

In `@CHANGELOG.md`:
- Line 7: The heading for version 0.6.10 uses markdown reference-link syntax
with [0.6.10], but there is no corresponding link definition at the bottom of
the CHANGELOG.md file to complete the reference. Add a link definition at the
end of the file following the pattern of other version links in the document to
match the [0.6.10] reference in the heading and enable proper hyperlinking for
this version entry.

In `@docs/usage.md`:
- Line 267: The `iris_domain({})` return type documentation at line 267 of
docs/usage.md is missing the `mustHold?` optional property from the flow object
shape. Add `mustHold?` to the documented flow properties in the return type
definition to match what `buildDomainModel` actually sets in the
packages/server/src/domain/domain-model.ts file when a flow has a success
condition.

In `@packages/browser/src/observers/console.test.ts`:
- Around line 27-36: The test verifies event emission but does not assert that
the original console.error method is actually being forwarded. Add a spy or mock
of the original console.error method before calling installConsole, then after
the console.error call, add an assertion to verify that the original
console.error was invoked with the correct arguments ('boom' and 42) to ensure
the forwarding behavior is actually covered by the test.

In `@packages/server/src/flows/flows.heal.test.ts`:
- Around line 85-93: The test mock session needs to be made cursor-aware to
properly exercise stale-signal protection. Modify the mock session to track a
cursor position and elapsed time: make eventsSince() accept and use a cursor
parameter to filter events rather than returning all events, and make elapsed()
return an actual tracked value (either incrementing or controllable) instead of
always returning 0. This will ensure that heal(..., apply: true) verification
with the since floor from session.elapsed() properly validates that buffered
signals outside the time window are considered stale.

In `@packages/server/src/init/mcp.ts`:
- Around line 42-45: The claudeExistsProbe() function and other functions in
this file use inline string literals for CLI command arguments (such as 'get',
'add', 'user', '-s', '--', '--version') instead of named constants. Define named
constants at the top of the file for each of these CLI command tokens (e.g.,
MCP_GET_SUBCOMMAND, MCP_ADD_SUBCOMMAND, SCOPE_USER, etc.) following the same
naming pattern as the existing CLAUDE_CLI, MCP_SUBCOMMAND, and MCP_SERVER_NAME
constants, then replace all inline string occurrences throughout the file with
references to these new constants.

In `@packages/server/src/tools/assert-grade.ts`:
- Around line 40-46: The walk function's handling of allOf and anyOf predicates
incorrectly marks mixed predicates (containing both presence-only and
non-presence predicates) as presence-only. In the return statement for these
cases, the presence property is computed using subs.some() which returns true if
ANY sub-predicate is presence-only; this should instead use subs.every() to
return true only when ALL sub-predicates are presence-only. This ensures that a
combined predicate is only flagged as presence-only when all of its constituent
predicates are presence-only, fixing the false advice emission issue that
contradicts the file's contract. Apply the same fix to both the allOf/anyOf case
block starting around line 42 and the similar logic at line 58-60.

In `@packages/server/src/tools/snapshot-cost.test.ts`:
- Around line 6-11: Remove the internal design-doc identifiers M0 and M2 from
the comment block in the snapshot-cost.test.ts file. Specifically, remove "M0 —
a reproducible measurement of the" and replace it with a direct description, and
remove "M2" references so the comment describes the measurement approach without
internal tracking codes. Apply the same fix to all other locations in the file
where these design-doc reference patterns appear (at lines 39-40, 59-60, 78, and
87-88), ensuring all letter-digit patterns like N5, G4, M8, etc. are removed
from comments, test titles, and log labels throughout the file.

---

Nitpick comments:
In `@packages/server/src/domain/domain-model.test.ts`:
- Around line 59-67: Add a new test case in the test file after the existing
test that verifies when a flow defines a signal anchor (via the signal property
in flow()) but does not assert it with expect.signal or success.signal, the
signal is still properly flagged in declaredUntestedSignals. Use
buildDomainModel, flow, and contract functions similar to the existing test
pattern to construct a scenario where a flow references a signal without
asserting it, then verify that signal appears in the
gaps.declaredUntestedSignals array to protect the stated asserted signal
contract.

In `@packages/server/src/domain/flow-risk.test.ts`:
- Around line 29-52: The test suite for flowRisk is missing coverage for the
FlowAssertionGrade.PRESENCE_ONLY case, which could allow regressions to go
undetected. Add a new test case in the describe block that exercises the
PRESENCE_ONLY grade by calling flowRisk with FlowAssertionGrade.PRESENCE_ONLY as
the first argument and a run result as the second argument (similar to the
existing test cases like the assertion-free flow test), then assert the expected
RiskLevel that should be returned for this grade to ensure the branch is
properly tested and documented.

In `@packages/server/src/events/predicate.test.ts`:
- Around line 228-311: Extract all inline domain/wire/UI strings from the
settled predicate test suite (the describe block starting at line 228) into
file-level named constants. This includes predicate kinds like 'settled',
'signal', and 'allOf', signal names like 'deploy:shipped' and 'x', URLs like
'/api/x' and '/api/deploy', event property names and values, and failure reason
strings like 'not settled'. Replace all occurrences of these inline literals
throughout the test cases with references to the corresponding named constants
to ensure compliance with the coding guideline that all domain/wire/UI strings
must be named constants.

In `@packages/server/src/events/predicate.ts`:
- Around line 363-373: The inline strings `'no activity to settle'` (used as the
note value) and the failureReason string template (used in the failureReason
property) need to be extracted to named constants following the repository's
coding guidelines. Define these strings as named constants at the module level
or in a centralized constants location, then replace the inline string literals
with references to those constants. Ensure the failureReason constant properly
handles the dynamic values by using a template string with the placeholders for
lastType, quietForMs, and quietMs.

In `@packages/server/src/flows/flow-success.ts`:
- Around line 30-75: Extract all hardcoded string literals from the successLabel
and successToPredicate functions into named constants at the module level.
Replace all occurrences of 'signal', 'net', 'element', 'allOf', 'testid',
'role', 'name', and 'success' string literals with these named constants
throughout both functions to comply with the domain/wire string literal
guidelines.

In `@packages/server/src/init/run.test.ts`:
- Around line 61-67: Add a new regression test case in the same test suite after
the existing "errors cleanly without a package.json" test. Create a test that
verifies the runInit function handles malformed JSON content gracefully. Use
memoryIo to provide a package.json file with invalid JSON syntax (such as
incomplete or syntactically broken JSON), call runInit with OPTS and the io
object, and verify that the result has ok set to false and that io.lines
contains an appropriate error message indicating the JSON parsing failure. This
test will prevent crashes when package.json exists but contains invalid JSON.

In `@packages/server/src/init/vite-config.test.ts`:
- Around line 30-34: Add a new test case after the existing idempotency test in
the test file to cover the regression scenario where a Vite config already has
the import statement for `@syrin/iris/vite` but is missing the iris() plugin in
the plugins array. Create a test config string that includes the import line but
lacks the iris() function call in the plugins configuration, then call
patchViteConfig on this config and assert that the returned kind is
VitePatchKind.APPLY, confirming that the function correctly identifies and
applies the patch for this incomplete state.

In `@packages/server/src/session/output-budget.ts`:
- Line 46: Extract the hardcoded recommendation message string currently
assigned to base.recommendation into a named constant at the module level. The
constant should contain the template with placeholders for the dynamic values
(events count and estimated tokens), and then reference this constant in the
assignment while still providing the formatted parameters. This ensures the
domain/wire string is not a free string in the code but follows the guideline of
being a named constant.

In `@packages/server/src/tools/assert-grade.test.ts`:
- Around line 5-60: The test suite in isPresenceOnlyAssertion contains many
inline string literals for predicate kinds (element, text, signal, net, allOf,
not, route, settled, console) and test data values (button, Saved, order:placed,
/api/order, Done, Welcome, /success, error, etc.). Define named constants at the
top of the test file for all these domain/wire/UI strings and replace each
inline string literal throughout all test cases in the describe block with
references to the corresponding constant. This ensures consistency and makes the
strings reusable across the test suite.

In `@packages/server/src/tools/tools.near-miss.test.ts`:
- Around line 79-127: The token budget tests in the describe block contain
hardcoded string literals for URLs, console messages, and log levels that should
be extracted to named constants. Identify all inline strings in the test cases
including the URLs '/1', '/2', '/3' used in iris_network tests, the messages
'a', 'b', 'c' used in iris_console tests, and the level string 'error' used in
the iris_console test. Create named constants for each of these values and
replace the inline strings throughout the test methods (in the ev() calls,
handler calls, and expect assertions) with references to these constants to
ensure compliance with the coding guideline that all domain/wire strings must be
named constants.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 47fd35ff-a94f-48c2-880e-ff8bf8781c13

📥 Commits

Reviewing files that changed from the base of the PR and between ff54d8d and 3b0e8e0.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (89)

• CHANGELOG.md
• apps/e2e/specs/new-features-test.mjs
• docs/agent-cheatsheet.md
• docs/getting-started.md
• docs/integrate-with-claude-code.md
• docs/token-efficiency.md
• docs/usage.md
• packages/babel-plugin/package.json
• packages/browser/package.json
• packages/browser/src/observers/console.test.ts
• packages/browser/src/observers/console.ts
• packages/browser/src/observers/network.test.ts
• packages/browser/src/observers/network.ts
• packages/browser/src/observers/route.test.ts
• packages/browser/src/observers/route.ts
• packages/eslint-plugin/package.json
• packages/iris/package.json
• packages/iris/src/vite.ts
• packages/iris/tsup.config.ts
• packages/next/package.json
• packages/protocol/package.json
• packages/protocol/src/constants.ts
• packages/protocol/src/types.ts
• packages/react/package.json
• packages/server/package.json
• packages/server/src/cli.test.ts
• packages/server/src/cli.ts
• packages/server/src/domain/domain-model.test.ts
• packages/server/src/domain/domain-model.ts
• packages/server/src/domain/domain-tools.ts
• packages/server/src/domain/flow-risk.test.ts
• packages/server/src/domain/flow-risk.ts
• packages/server/src/events/predicate.test.ts
• packages/server/src/events/predicate.ts
• packages/server/src/flows/flow-classify.test.ts
• packages/server/src/flows/flow-classify.ts
• packages/server/src/flows/flow-replay.dynamic.test.ts
• packages/server/src/flows/flow-replay.test.ts
• packages/server/src/flows/flow-replay.ts
• packages/server/src/flows/flow-success.test.ts
• packages/server/src/flows/flow-success.ts
• packages/server/src/flows/flow-tools.ts
• packages/server/src/flows/flows.heal.test.ts
• packages/server/src/flows/flows.ts
• packages/server/src/flows/heal-proposal.test.ts
• packages/server/src/flows/heal.ts
• packages/server/src/flows/tools.flow-replay.test.ts
• packages/server/src/flows/tools.flows.test.ts
• packages/server/src/index.ts
• packages/server/src/init/cursor.test.ts
• packages/server/src/init/cursor.ts
• packages/server/src/init/detect.test.ts
• packages/server/src/init/detect.ts
• packages/server/src/init/mcp.test.ts
• packages/server/src/init/mcp.ts
• packages/server/src/init/node-io.ts
• packages/server/src/init/plan.test.ts
• packages/server/src/init/plan.ts
• packages/server/src/init/run.test.ts
• packages/server/src/init/run.ts
• packages/server/src/init/snippets.ts
• packages/server/src/init/vite-config.test.ts
• packages/server/src/init/vite-config.ts
• packages/server/src/session/output-budget.test.ts
• packages/server/src/session/output-budget.ts
• packages/server/src/session/tools.live-control.test.ts
• packages/server/src/tools/assert-grade.test.ts
• packages/server/src/tools/assert-grade.ts
• packages/server/src/tools/query-paginate.test.ts
• packages/server/src/tools/query-paginate.ts
• packages/server/src/tools/snapshot-cost.test.ts
• packages/server/src/tools/snapshot-delta.test.ts
• packages/server/src/tools/snapshot-delta.ts
• packages/server/src/tools/tool-names.ts
• packages/server/src/tools/tools.assert-advice.test.ts
• packages/server/src/tools/tools.near-miss.test.ts
• packages/server/src/tools/tools.ts
• packages/test/package.json
• packages/test/src/flow-spec.test.ts
• packages/test/src/register.test.ts
• packages/test/src/success-assert.test.ts
• packages/test/src/success-assert.ts
• packages/vite-plugin/README.md
• packages/vite-plugin/package.json
• packages/vite-plugin/src/build.integration.test.ts
• packages/vite-plugin/src/index.test.ts
• packages/vite-plugin/src/index.ts
• packages/vite-plugin/tsconfig.json
• tsconfig.json

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Guarantee teardown with try/finally around the e2e run.

Any thrown await in the flow skips b.close()/server.close(), which can leak resources and hang CI jobs.

🛠️ Suggested hardening

-const b = await chromium.launch({ headless: true });
-const p = await b.newPage();
-await p.goto('http://localhost:4310/?session=demo', { waitUntil: 'networkidle' });
-for (let i = 0; i < 200 && server.bridge.sessions.count() === 0; i++) await sleep(50);
+let b;
+let p;
+try {
+  b = await chromium.launch({ headless: true });
+  p = await b.newPage();
+  await p.goto('http://localhost:4310/?session=demo', { waitUntil: 'networkidle' });
+  for (let i = 0; i < 200 && server.bridge.sessions.count() === 0; i++) await sleep(50);
@@
-console.log(`\n${fail === 0 ? '✅ NEW FEATURES VERIFIED' : '❌ FAILED'} (${pass} passed, ${fail} failed)`);
-await b.close();
-await server.close();
+  console.log(`\n${fail === 0 ? '✅ NEW FEATURES VERIFIED' : '❌ FAILED'} (${pass} passed, ${fail} failed)`);
+} finally {
+  await p?.close();
+  await b?.close();
+  await server.close();
+}
 process.exit(fail === 0 ? 0 : 1);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/e2e/specs/new-features-test.mjs` around lines 54 - 91, The test code
lacks proper error handling and resource cleanup. If any await statement throws
an error before reaching b.close() and server.close(), resources will leak and
hang the CI. Wrap all the test logic (from chromium.launch through the final chk
call) in a try block, and move the b.close() and server.close() calls into a
finally block that runs regardless of success or failure. Keep the process.exit
call after the finally block to ensure it only executes after cleanup is
complete.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Signal-gap computation currently over-credits non-asserting flows.

On Line 80, flowSignals includes anchor signals, but declaredUntestedSignals is defined as signals that no flow asserts. A flow that only references a signal anchor (without expect.signal/success.signal) will be treated as covered, which can suppress real intent gaps.

Suggested fix

 function flowSignals(flow: FlowFile): string[] {
   const set = new Set<string>();
   for (const step of flatten(flow.steps)) {
-    if (step.anchor.kind === AnchorKind.SIGNAL) set.add(step.anchor.name);
     if (step.expect?.signal !== undefined) set.add(step.expect.signal);
   }
   if (flow.success?.signal !== undefined) set.add(flow.success.signal);
   return [...set];
 }

Also applies to: 133-136

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/domain/domain-model.ts` around lines 77 - 85, The
flowSignals function incorrectly includes anchor signals in addition to asserted
signals, which causes flows that only reference a signal anchor to be treated as
tested even when they don't actually assert or expect that signal. Remove the
line that adds anchor signals to the set (the condition checking if
step.anchor.kind === AnchorKind.SIGNAL) so that only signals that are explicitly
asserted through expect.signal or success.signal are counted as covered by the
flow.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift

Extract runtime/domain strings into named constants.

Lines 174–190 introduce multiple free strings in tool-facing output. This violates the repo rule and makes wording changes harder to maintain consistently.

As per coding guidelines, “All domain/wire/UI strings must be named constants, never free strings in code.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/domain/domain-model.ts` around lines 174 - 190, Extract
all hardcoded strings in the coverage status message building code into named
constants at the module or class level. This includes the "No saved flows yet"
message, the template strings used for constructing the parts array such as
"flow"/"flows", "test first: ", "declared signal(s) no flow asserts (", and
"flow(s) assert no consequence". Replace each free string in the code with a
reference to its corresponding named constant to ensure consistency and
maintainability of domain strings throughout the codebase.

Source: Coding guidelines

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift

Move tool-facing strings to named constants.

This file introduces multiple free strings in tool description and schema metadata. Please extract them to constants to satisfy the repo string policy.

As per coding guidelines, “All domain/wire/UI strings must be named constants, never free strings in code.”

Also applies to: 31-33, 57-58

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/domain/domain-tools.ts` around lines 17 - 19, Extract all
free string literals from the tool definition (including the long description
string in the description field, and any strings at the locations mentioned in
lines 31-33 and 57-58) into named constants at the top of the file, then replace
each free string with a reference to its corresponding constant. This ensures
all domain/wire/UI strings follow the repository policy of being named constants
rather than inline literals.

Source: Coding guidelines

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

outputSchema.flows is missing the optional risk field returned by the handler.

The handler returns buildDomainModel(...) (Line 71), and DomainFlowSummary includes risk when run history exists. But outputSchema.flows doesn’t declare it, creating a wire-contract mismatch for schema-aware consumers.

Suggested schema addition

       flows: z.array(
         z.object({
           name: z.string(),
           steps: z.number(),
           grade: z.string(),
           asserts: z.boolean(),
@@
           warning: z.string().optional(),
           signals: z.array(z.string()),
           testids: z.array(z.string()),
+          risk: z
+            .object({
+              level: z.string(),
+              reason: z.string(),
+              lastStatus: z.string().optional(),
+            })
+            .optional(),
         }),
       ),

Also applies to: 61-72

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/domain/domain-tools.ts` around lines 23 - 37, The
outputSchema.flows object definition is missing the optional risk field that is
actually returned by the handler's buildDomainModel function call, causing a
schema contract mismatch for consumers. Add an optional risk field to the Zod
schema object within the flows definition (around the z.object block), using the
same pattern as the other optional fields like mustHold and warning, declaring
it as z.string().optional() or with an appropriate type based on what
buildDomainModel returns.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift

Extract remaining step title/detail literals into named constants.

This file still has many inline domain/UI strings in plan steps; centralizing them as constants will align with the repo rule and reduce drift in CLI messaging.

As per coding guidelines, All domain/wire/UI strings must be named constants, never free strings in code.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/init/plan.ts` around lines 68 - 255, Extract the inline
string literals for step titles and details throughout the file into named
constants at the top, following the pattern of CLAUDE_MCP_TITLE and
CURSOR_MCP_TITLE. This applies to strings in the installStep, viteSteps,
nextSteps, and buildPlan functions including titles like "Install dependency",
"Vite plugin", "IrisDev component", "Next config (withIris)", "Mount IrisDev",
"Connect snippet", and their corresponding detail messages. Replace each inline
string literal with the appropriate constant reference to ensure all domain/UI
strings are centralized and follow the repository's coding guidelines.

Source: Coding guidelines

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Handle malformed package.json without crashing iris init.

Line 71 can throw during parse, and that exception is currently uncaught in the runInit path. This turns a recoverable input error into a hard CLI failure.

💡 Proposed fix

 export function runInit(options: InitOptions, io: InitIo): InitResult {
   const pkgRaw = io.readFile(PACKAGE_JSON);
   if (pkgRaw === null) {
     io.print('No package.json found. Run `iris init` from your project root.');
     return { ok: false, applied: 0, manual: 0 };
   }

-  const plan = buildPlan(gatherPlanInput(options, io, pkgRaw));
+  let plan: Plan;
+  try {
+    plan = buildPlan(gatherPlanInput(options, io, pkgRaw));
+  } catch {
+    io.print('Invalid package.json. Fix JSON syntax and re-run `iris init`.');
+    return { ok: false, applied: 0, manual: 0 };
+  }
   const failed = options.dryRun ? new Set<string>() : applyEffects(plan, io);
   return report(plan, options.dryRun, failed, io);
 }

Also applies to: 157-166

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/init/run.ts` around lines 70 - 71, The JSON.parse call in
the gatherPlanInput function at line 71 can throw an exception if the pkgRaw
string contains malformed JSON, causing the CLI to crash. Wrap the
JSON.parse(pkgRaw) call in a try-catch block to handle the parse error
gracefully, and either throw a custom error with a user-friendly message or
return an error state that the caller can handle. Similarly, check the related
code around lines 157-166 where similar JSON parsing may occur and apply the
same error handling pattern to ensure all JSON parsing in the runInit path
handles malformed input without crashing.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

ALREADY detection is too broad and can skip required plugin injection.

Checking only @syrin/iris/vite presence can return ALREADY when the config has the import (or even just a comment) but no iris(...) in plugins, leaving setup incomplete.

Suggested fix

 const IRIS_MARKER = '`@syrin/iris/vite`';
+const IRIS_PLUGIN_IN_PLUGINS = /plugins\s*:\s*\[[\s\S]*?\biris\s*\(/;

 function insertImport(source: string): string {
+  if (source.includes(IRIS_MARKER)) return source;
   const matches = [...source.matchAll(IMPORT_LINE)];
   const last = matches[matches.length - 1];
   if (last?.index === undefined) {
     return `${VITE_IMPORT}\n${source}`;
   }
   const end = last.index + last[0].length;
   return `${source.slice(0, end)}\n${VITE_IMPORT}${source.slice(end)}`;
 }

 export function patchViteConfig(source: string, port?: number): VitePatch {
-  if (source.includes(IRIS_MARKER)) {
+  if (source.includes(IRIS_MARKER) && IRIS_PLUGIN_IN_PLUGINS.test(source)) {
     return { kind: VitePatchKind.ALREADY };
   }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/init/vite-config.ts` around lines 49 - 57, The ALREADY
detection in patchViteConfig function is too broad because checking only if the
source includes IRIS_MARKER can match occurrences in comments or imports without
verifying the iris plugin is actually in the plugins array. Replace the simple
source.includes(IRIS_MARKER) check with a more robust validation that confirms
the iris() plugin call is present in the plugins array, similar to how
PLUGINS_ARRAY.test(source) validates the plugins array structure. This ensures
ALREADY is only returned when the plugin injection is truly complete.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Snapshot diff cache key can collide across sessions when sessionId is omitted.

At Line 350, sessionId ?? 'default' is used with a process-wide SNAPSHOT_CACHE. Different sessions that omit sessionId can share one cache key and get deltas computed from another session’s prior snapshot, which is both incorrect and a privacy boundary risk.

Proposed fix

     handler: (deps, args) => {
-      const sessionId = asString(args['sessionId']);
+      const requestedSessionId = asString(args['sessionId']);
+      const resolvedSessionId = deps.sessions.resolve(requestedSessionId).id;
       const mode = asString(args['mode']) ?? SnapshotMode.FULL;
-      return commandOrThrow(deps, sessionId, IrisCommand.SNAPSHOT, {
+      return commandOrThrow(deps, resolvedSessionId, IrisCommand.SNAPSHOT, {
         scope: args['scope'],
         mode,
       }).then((raw) =>
         withSizeCost(
           applySnapshotDelta(
             raw,
             {
-              sessionId: sessionId ?? 'default',
+              sessionId: resolvedSessionId,
               scope: asString(args['scope']) ?? '',
               mode,
               diff: args['diff'] === true,
             },
             SNAPSHOT_CACHE,
           ),
         ),
       );
     },

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/tools/tools.ts` around lines 339 - 356, The snapshot
cache key generation in the handler function uses a fallback value of 'default'
when sessionId is not provided, causing different sessions without an explicit
sessionId to share the same cache entry in the process-wide SNAPSHOT_CACHE. This
creates privacy and correctness issues as unrelated sessions can get deltas
computed from another session's prior snapshot. Remove the fallback to 'default'
in the sessionId field passed to applySnapshotDelta and ensure each session has
a uniquely identifiable sessionId rather than silently defaulting multiple
sessions to the same cache key value.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | 🏗️ Heavy lift

tools.ts exceeds the repository’s 500-line file limit.

This file now reaches at least Line 1299. Please split tool definitions into smaller modules (for example: snapshot/query/assert/network-console groups) and compose them in TOOLS to stay within the limit.

As per coding guidelines, **/*.{ts,tsx,js,jsx} requires that no file exceeds 500 lines.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/server/src/tools/tools.ts` at line 1299, The tools.ts file exceeds
the repository's 500-line file limit at 1299 lines. Refactor by extracting
related tool definition groups (such as snapshot tools, query tools, assert
tools, and network-console tools) into separate dedicated modules. Then import
these extracted tool groups back into tools.ts and compose them together in the
DOMAIN_TOOLS spread operator to maintain the same public API while keeping each
file within the 500-line limit.

Source: Coding guidelines