@rmrdeveloper/sideroom-pi 8.9.0 → 8.10.0

package/README.md

@@ -193,15 +193,19 @@ Reading the guide covers the mechanical rules. `jev` covers the other kind: one
 optional call to TypeSafe's Jev decision model about the six guide rules a
 single file can answer (guard clauses, fail fast, command/query separation,
 null handling, immutability, validate once) on the file a `write` or `edit` just
-changed. The answer arrives as a probability, and a note is appended to the tool
-result when it clears the cutoff.
+changed. The answer arrives as a probability, and when it clears the cutoff the
+note travels with the guidelines review at the end of the run instead of
+interrupting each edit. READMEs, JSON, lockfiles, deletion-only edits, and files
+outside the project are never sent.
 
 It never blocks and never enters the system prompt. The state is the file and
 the added lines and nothing else — no conversation, no session, no neighbours.
 The footer counts the calls the session made, and `F10` shows the same count
 beside the key source. Without a key nothing is called, and when Jev runs out of
 quota, rejects the key,
-or stops answering, the extension goes quiet without touching the turn. The key
+or stops answering, the extension goes quiet without touching the turn. A rate
+limit only pauses it until your next prompt, and Escape cuts a request in
+flight. The key
 lives in `TYPESAFE_API_KEY` or in your agent directory, and `F10` captures it
 without ever writing it to the session.
 
@@ -230,11 +234,12 @@ nothing is detectable, the gate does nothing.
 
 When an implementation settles, `explain` steers the agent to offer a
 walkthrough through `sideroom_ask`: explain the changes only, how to test them
-only, both, or nothing. It fires on `agent_settled`, the point where
-no retry, compaction, or queued message is left, so the offer never lands on
-work that is about to be redone. It waits one settle so the guidelines review
-runs first; both fire on `agent_settled`, and Pi would otherwise order them by
-extension load. Once per turn, only when the turn touched at least five distinct
+only, both, or nothing. It fires on `agent_before_settle`, after every retry
+and compaction recovery, so the offer never lands on work that is about to be
+redone, and it stays inside the same run. It waits one boundary so the
+guidelines review runs first; both use the same event, and Pi would otherwise
+order them by extension load. It stays quiet after Escape, after an error, and
+while a message you typed is waiting. Once per turn, only when the turn touched at least five distinct
 files, and only in the TUI, because `sideroom_ask` cannot run anywhere else. No
 tool, no widget, no persisted state.
 
@@ -312,10 +317,12 @@ also fully read the packaged guide matching the target path. Reads with
 The extension blocks the mutation until the required reads succeed; unsupported
 languages use the shared table. Do not route around
 the gate through Bash or another file-mutation path. After any successful
-`write`/`edit`, one hidden review steer fires on `agent_settled` (at most once
-per turn) asking the agent to re-check every changed file against the loaded
-guide and run the relevant project checks. Interactive input clears the steer
-flags; `before_agent_start` does not, so a steer continuation never re-triggers
+`write`/`edit`, one hidden review steer fires on `agent_before_settle` (at most
+once per turn) asking the agent to re-check every changed file against the
+loaded guide and run the relevant project checks. It is skipped after Escape,
+after an error, and while a user message is pending. Interactive input sent
+while the agent is idle clears the steer flags; a message typed during a run
+and `before_agent_start` do not, so a steer continuation never re-triggers
 itself.
 
 ### Monorepo-skills contract
@@ -347,15 +354,21 @@ itself.
 
 - Off without a key: no request, and behavior identical to a package without
   this extension.
-- Warn only. A finding is text appended to the tool result; nothing blocks and
-  nothing reaches the system prompt.
-- One request per successful `write`/`edit`, with six `noul` questions on one
-  shared state of the file body and the added lines.
-- A body over 60k characters is skipped rather than truncated. An answer at or
-  above `0.8` probability becomes a note.
-- Quota (`402`) and a rejected key (`401`, `403`) stop the calls immediately;
-  network errors, `429` and `5xx` stop after three consecutive failures. A
-  success rearms the breaker, and `F10` rearms it by hand.
+- Warn only. A finding goes to the guidelines review on `sideroom:review-note`
+  and rides its end-of-run steer, with one follow-up per turn for notes that
+  arrive after the review fired; nothing blocks and nothing reaches the system
+  prompt.
+- One request per successful `write`/`edit` of a project file in a supported
+  language that added lines, with six `noul` questions on one shared state of
+  the project-relative path, the file body, and the added lines.
+- A serialized state over 60k characters is skipped rather than truncated. An
+  answer at or above `0.8` probability becomes a note.
+- The request follows the run's abort signal; a cancelled request is not a
+  failure.
+- Quota (`402`) and a rejected key (`401`, `403`) stop the calls immediately. A
+  rate limit (`429`) pauses them until the next idle prompt. Network errors and
+  other `4xx`/`5xx` stop after three consecutive failures. A success rearms the
+  breaker, and `F10` rearms it by hand.
 - Every request increments a session call counter, shown in the footer and on
   `F10`; it resets on `session_start` and is never persisted.
 - The key comes from `TYPESAFE_API_KEY` or from
@@ -390,12 +403,13 @@ itself.
 
 ### Explain contract
 
-- Trigger: `agent_settled` with at least five distinct files mutated since the
-  last user prompt, in TUI mode. File identity follows Pi's path aliases and
-  canonicalizes existing paths.
-- One settle of delay: the guidelines review steers on the same event, and Pi
-  runs both deferred steers in extension load order, so `explain` offers at the
-  next settle.
+- Trigger: `agent_before_settle` with at least five distinct files mutated
+  since the last idle user prompt, in TUI mode, on a completed run with no user
+  message pending. File identity follows Pi's path aliases and canonicalizes
+  existing paths.
+- One boundary of delay: the guidelines review steers on the same event, and Pi
+  runs both handlers in extension load order, so `explain` offers at the next
+  boundary.
 - The steer names the intent; the agent writes the question in the user's
   language with four options, one of them a decline, and one recommendation.
   `sideroom_ask` still adds *Out of scope* and the custom answer.

package/extensions/explain/guard.ts

@@ -3,6 +3,11 @@ import {
   isEditToolResult,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
+import {
+  acceptsSettleSteer,
+  startsUserTurn,
+  withHiddenSteer,
+} from '../shared/settle.ts';
 import {
   applyOfferDecision,
   decideOffer,
@@ -24,7 +29,7 @@ export function registerExplainGuard(
   state: ExplainState,
 ): void {
   pi.on('input', (event) => {
-    if (event.source !== 'interactive' && event.source !== 'rpc') {
+    if (!startsUserTurn(event)) {
       return;
     }
     resetExplainTurn(state);
@@ -46,21 +51,18 @@ export function registerExplainGuard(
     recordMutation(state, pathKey);
   });
 
-  // agent_settled is the only point with no retry, compaction, or queued
-  // continuation left, so the walkthrough is never offered over reworked work.
-  pi.on('agent_settled', (_event, ctx) => {
+  // agent_before_settle runs after retries and compaction recovery, so the
+  // walkthrough is never offered over reworked work, and its continuation
+  // stays inside the same run instead of starting a second one.
+  pi.on('agent_before_settle', (event, ctx) => {
+    if (!acceptsSettleSteer(event)) {
+      return;
+    }
     const decision = decideOffer(state, ctx.mode);
     applyOfferDecision(state, decision);
     if (decision !== EXPLAIN_DECISION.send) {
       return;
     }
-    pi.sendMessage(
-      {
-        customType: EXPLAIN_OFFER_TYPE,
-        content: EXPLAIN_OFFER,
-        display: false,
-      },
-      { triggerTurn: true, deliverAs: 'steer' },
-    );
+    return withHiddenSteer(event, EXPLAIN_OFFER_TYPE, EXPLAIN_OFFER);
   });
 }

package/extensions/explain/model.ts

@@ -54,9 +54,10 @@ export function recordMutation(state: ExplainState, pathKey: string): void {
   state.mutatedSinceSettle = true;
 }
 
-// The guidelines review steers at the first settle after a mutation, and
-// agent_settled runs both deferred steers in extension load order. Explain
-// holds its own steer back one settle so the review always runs first.
+// The guidelines review steers at the first settle boundary after a mutation,
+// and both handlers run in an extension load order Sideroom does not control.
+// Explain holds its steer back one boundary so the review always runs first;
+// the review's continuation is what brings the next boundary.
 export function decideOffer(
   state: ExplainState,
   mode: string,

package/extensions/guidelines/review.ts

@@ -3,36 +3,82 @@ import {
   isEditToolResult,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
+import { isReviewNote, REVIEW_NOTE_EVENT } from '../shared/review-note.ts';
+import {
+  acceptsSettleSteer,
+  startsUserTurn,
+  withHiddenSteer,
+} from '../shared/settle.ts';
 
 export const REVIEW_STEER_TYPE = 'sideroom-guidelines-review';
 
 export const REVIEW_STEER =
   'Review every file this run changed against the loaded Sideroom language guide: fix any mechanical, structural, or architectural rule violations in those files, then run the relevant formatter, linter, type checks, and tests. If the guide is no longer in context, re-read it in full first.';
 
+export const REVIEW_NOTES_STEER =
+  'Files changed during the review drew the semantic notes below. Verify each against the loaded Sideroom language guide, fix only real violations, then rerun the relevant checks.';
+
 export interface ReviewState {
   mutated: boolean;
   steeredThisTurn: boolean;
+  notesSteeredThisTurn: boolean;
+  notes: string[];
 }
 
 export function createReviewState(): ReviewState {
-  return { mutated: false, steeredThisTurn: false };
+  return {
+    mutated: false,
+    steeredThisTurn: false,
+    notesSteeredThisTurn: false,
+    notes: [],
+  };
 }
 
 export function resetReviewTurn(state: ReviewState): void {
   state.mutated = false;
   state.steeredThisTurn = false;
+  state.notesSteeredThisTurn = false;
+  state.notes = [];
 }
 
 export function shouldReview(state: ReviewState): boolean {
   return state.mutated && !state.steeredThisTurn;
 }
 
+// Notes that arrive after the review fired get one follow-up per turn, so a
+// fix that draws new notes cannot keep the run going.
+export function pendingReviewSteer(state: ReviewState): string | undefined {
+  if (shouldReview(state)) {
+    return withNotes(REVIEW_STEER, state.notes);
+  }
+  if (
+    state.steeredThisTurn &&
+    !state.notesSteeredThisTurn &&
+    state.notes.length > 0
+  ) {
+    return withNotes(REVIEW_NOTES_STEER, state.notes);
+  }
+  return undefined;
+}
+
+export function markReviewSteered(state: ReviewState): void {
+  if (state.steeredThisTurn) {
+    state.notesSteeredThisTurn = true;
+  }
+  state.steeredThisTurn = true;
+  state.notes = [];
+}
+
+function withNotes(lead: string, notes: readonly string[]): string {
+  return [lead, ...notes].join('\n\n');
+}
+
 export function registerReviewGuard(
   pi: ExtensionAPI,
   state: ReviewState,
 ): void {
   pi.on('input', (event) => {
-    if (event.source !== 'interactive' && event.source !== 'rpc') {
+    if (!startsUserTurn(event)) {
       return;
     }
     resetReviewTurn(state);
@@ -48,23 +94,22 @@ export function registerReviewGuard(
     state.mutated = true;
   });
 
-  // agent_settled is the only point with no retry, compaction, or queued
-  // continuation left, so the review never lands on work a retry is about to
-  // redo. Mark the flag before sending so the continuation this steer starts
-  // cannot re-trigger it; sendMessage is intentionally not awaited, matching
-  // explain, so the settle handler returns immediately.
-  pi.on('agent_settled', () => {
-    if (!shouldReview(state)) {
+  pi.events.on(REVIEW_NOTE_EVENT, (payload) => {
+    if (isReviewNote(payload)) {
+      state.notes.push(payload.text);
+    }
+  });
+
+  // agent_before_settle runs after retries and compaction recovery, and its
+  // continuation stays inside the same run. agent_settled is notification-only:
+  // a steer sent there starts a second run after the user already saw the
+  // agent stop, and it fires even when the user pressed Escape.
+  pi.on('agent_before_settle', (event) => {
+    const steer = pendingReviewSteer(state);
+    if (steer === undefined || !acceptsSettleSteer(event)) {
       return;
     }
-    state.steeredThisTurn = true;
-    pi.sendMessage(
-      {
-        customType: REVIEW_STEER_TYPE,
-        content: REVIEW_STEER,
-        display: false,
-      },
-      { triggerTurn: true, deliverAs: 'steer' },
-    );
+    markReviewSteered(state);
+    return withHiddenSteer(event, REVIEW_STEER_TYPE, steer);
   });
 }

package/extensions/jev/client.ts

@@ -12,7 +12,17 @@ export const JEV_REQUEST_TIMEOUT_MS = 3_000;
 export const JEV_FAILURE = {
   quota: 'quota',
   auth: 'auth',
+  rateLimited: 'rateLimited',
   transient: 'transient',
+  cancelled: 'cancelled',
+} as const;
+
+const HTTP_STATUS = {
+  unauthorized: 401,
+  paymentRequired: 402,
+  forbidden: 403,
+  tooManyRequests: 429,
+  firstClientError: 400,
 } as const;
 
 export type JevFailure = (typeof JEV_FAILURE)[keyof typeof JEV_FAILURE];
@@ -20,6 +30,7 @@ export type JevFailure = (typeof JEV_FAILURE)[keyof typeof JEV_FAILURE];
 export interface JevHttpRequest {
   readonly apiKey: string;
   readonly body: string;
+  readonly signal: AbortSignal | undefined;
 }
 
 export interface JevHttpResponse {
@@ -50,20 +61,36 @@ export function createFetchTransport(
         'Content-Type': 'application/json',
       },
       body: request.body,
-      signal: AbortSignal.timeout(timeoutMs),
+      signal: requestSignal(timeoutMs, request.signal),
     });
     return { status: response.status, text: await response.text() };
   };
 }
 
+// Pi waits for every tool_result handler before the result reaches the model,
+// so the user's Escape has to cut the request, not only the timeout.
+function requestSignal(
+  timeoutMs: number,
+  runSignal: AbortSignal | undefined,
+): AbortSignal {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  if (runSignal === undefined) {
+    return timeout;
+  }
+  return AbortSignal.any([timeout, runSignal]);
+}
+
 export function classifyStatus(status: number): JevFailure | undefined {
-  if (status === 401 || status === 403) {
+  if (status === HTTP_STATUS.unauthorized || status === HTTP_STATUS.forbidden) {
     return JEV_FAILURE.auth;
   }
-  if (status === 402) {
+  if (status === HTTP_STATUS.paymentRequired) {
     return JEV_FAILURE.quota;
   }
-  if (status >= 400) {
+  if (status === HTTP_STATUS.tooManyRequests) {
+    return JEV_FAILURE.rateLimited;
+  }
+  if (status >= HTTP_STATUS.firstClientError) {
     return JEV_FAILURE.transient;
   }
   return undefined;
@@ -76,16 +103,20 @@ export async function askJev(
   transport: JevTransport,
   apiKey: string,
   file: JevFileState,
+  signal: AbortSignal | undefined,
 ): Promise<JevAttempt> {
   const body = JSON.stringify(buildRequestBody(file));
   let response: JevHttpResponse;
   try {
-    response = await transport({ apiKey, body });
+    response = await transport({ apiKey, body, signal });
   } catch {
     return {
       findings: undefined,
       model: undefined,
-      failure: JEV_FAILURE.transient,
+      failure:
+        signal?.aborted === true
+          ? JEV_FAILURE.cancelled
+          : JEV_FAILURE.transient,
     };
   }
 

package/extensions/jev/guard.ts

@@ -6,8 +6,13 @@ import {
   isWriteToolResult,
   type ToolCallEvent,
 } from '@earendil-works/pi-coding-agent';
-import { resolveFileToolPath } from '../shared/file-path.ts';
+import {
+  projectRelativePath,
+  resolveFileToolPath,
+} from '../shared/file-path.ts';
 import { readFileIfExists } from '../shared/read-file.ts';
+import { REVIEW_NOTE_EVENT, type ReviewNote } from '../shared/review-note.ts';
+import { startsUserTurn } from '../shared/settle.ts';
 import {
   askJev,
   JEV_FAILURE,
@@ -21,6 +26,7 @@ import {
   buildFileState,
   findingKey,
   formatFindings,
+  isReviewablePath,
   type JevFinding,
   stateFitsBudget,
 } from './model.ts';
@@ -37,13 +43,18 @@ export const JEV_STATUS = {
   noKey: 'noKey',
   quota: 'quota',
   auth: 'auth',
+  rateLimited: 'rateLimited',
   unavailable: 'unavailable',
 } as const;
 
 export type JevStatus = (typeof JEV_STATUS)[keyof typeof JEV_STATUS];
 
-interface PendingMutation {
-  readonly path: string;
+interface MutationTarget {
+  readonly absolutePath: string;
+  readonly relativePath: string;
+}
+
+interface PendingMutation extends MutationTarget {
   readonly kind: string;
   readonly lines: readonly AddedLine[];
 }
@@ -51,6 +62,7 @@ interface PendingMutation {
 export interface JevGuardState {
   halted: JevStatus | undefined;
   transientFailures: number;
+  rateLimitedThisTurn: boolean;
   lastModel: string | undefined;
   calls: number;
   readonly pending: Map<string, PendingMutation>;
@@ -67,6 +79,7 @@ export function createJevGuardState(): JevGuardState {
   return {
     halted: undefined,
     transientFailures: 0,
+    rateLimitedThisTurn: false,
     lastModel: undefined,
     calls: 0,
     pending: new Map(),
@@ -78,17 +91,25 @@ export function createJevGuardState(): JevGuardState {
 export function resetJevGuard(state: JevGuardState): void {
   state.halted = undefined;
   state.transientFailures = 0;
+  state.rateLimitedThisTurn = false;
 }
 
-// Usage belongs to the active session: a new session starts counting from zero.
-export function resetJevUsage(state: JevGuardState): void {
+// Usage and per-turn memory belong to the active session: a new session starts
+// counting from zero. The breaker stays, because it tracks the key.
+export function resetJevSession(state: JevGuardState): void {
   state.calls = 0;
+  state.rateLimitedThisTurn = false;
+  state.pending.clear();
+  state.notedThisTurn.clear();
 }
 
 export function guardStatus(state: JevGuardState): JevStatus {
   if (state.halted !== undefined) {
     return state.halted;
   }
+  if (state.rateLimitedThisTurn) {
+    return JEV_STATUS.rateLimited;
+  }
   return state.transientFailures > 0
     ? JEV_STATUS.unavailable
     : JEV_STATUS.ready;
@@ -97,6 +118,7 @@ export function guardStatus(state: JevGuardState): JevStatus {
 export function shouldCallJev(state: JevGuardState): boolean {
   return (
     state.halted === undefined &&
+    !state.rateLimitedThisTurn &&
     state.transientFailures < JEV_TRANSIENT_FAILURE_LIMIT
   );
 }
@@ -107,17 +129,24 @@ export function registerJevGuard(
   dependencies: JevGuardDependencies,
 ): void {
   pi.on('input', (event) => {
-    if (event.source !== 'interactive' && event.source !== 'rpc') {
+    if (!startsUserTurn(event)) {
       return;
     }
     state.notedThisTurn.clear();
+    state.rateLimitedThisTurn = false;
+  });
+
+  // A call another extension blocks in tool_call never reaches tool_result,
+  // and every result of a turn lands before its turn_end.
+  pi.on('turn_end', () => {
+    state.pending.clear();
   });
 
   // The added lines are read before the mutation lands, because after a write
   // the previous content is gone. The body is read after, from disk.
   pi.on('tool_call', (event, ctx) => {
     const mutation = extractMutation(event, ctx.cwd);
-    if (mutation === undefined) {
+    if (mutation === undefined || !isWorthAsking(mutation)) {
       return undefined;
     }
     state.pending.set(event.toolCallId, mutation);
@@ -144,8 +173,17 @@ export function registerJevGuard(
       return undefined;
     }
 
-    const body = readMutationBody(ctx.cwd, pending.path);
-    if (body === undefined || !stateFitsBudget(body)) {
+    const body = readFileIfExists(pending.absolutePath);
+    if (body === undefined) {
+      return undefined;
+    }
+    const fileState = buildFileState(
+      pending.relativePath,
+      body,
+      pending.kind,
+      pending.lines,
+    );
+    if (!stateFitsBudget(fileState) || ctx.signal?.aborted === true) {
       return undefined;
     }
 
@@ -153,7 +191,8 @@ export function registerJevGuard(
     const attempt = await askJev(
       dependencies.transport,
       apiKey,
-      buildFileState(pending.path, body, pending.kind, pending.lines),
+      fileState,
+      ctx.signal,
     );
     if (attempt.failure !== undefined) {
       registerFailure(state, attempt.failure);
@@ -169,18 +208,17 @@ export function registerJevGuard(
 
     const findings = attempt.findings ?? [];
     const fresh = findings.filter((finding) =>
-      isUnnoted(state, pending.path, finding),
+      isUnnoted(state, pending.relativePath, finding),
     );
     if (fresh.length === 0) {
       return undefined;
     }
-    markNoted(state, pending.path, fresh);
-    return {
-      content: [
-        ...event.content,
-        { type: 'text' as const, text: formatFindings(pending.path, fresh) },
-      ],
+    markNoted(state, pending.relativePath, fresh);
+    const note: ReviewNote = {
+      text: formatFindings(pending.relativePath, fresh),
     };
+    pi.events.emit(REVIEW_NOTE_EVENT, note);
+    return undefined;
   });
 }
 
@@ -202,7 +240,16 @@ function markNoted(
   }
 }
 
+// A user abort says nothing about the service, and a rate limit clears on its
+// own, so neither may count toward switching Jev off.
 function registerFailure(state: JevGuardState, failure: JevFailure): void {
+  if (failure === JEV_FAILURE.cancelled) {
+    return;
+  }
+  if (failure === JEV_FAILURE.rateLimited) {
+    state.rateLimitedThisTurn = true;
+    return;
+  }
   if (failure === JEV_FAILURE.quota) {
     state.halted = JEV_STATUS.quota;
     return;
@@ -222,24 +269,37 @@ function registerSuccess(state: JevGuardState): void {
   state.transientFailures = 0;
 }
 
+// A deletion-only edit leaves nothing for the six questions to read, and only
+// the project-relative path of a supported language may leave the machine.
+function isWorthAsking(mutation: PendingMutation): boolean {
+  return mutation.lines.length > 0 && isReviewablePath(mutation.relativePath);
+}
+
 function extractMutation(
   event: ToolCallEvent,
   cwd: string,
 ): PendingMutation | undefined {
   if (isToolCallEventType('write', event)) {
-    const absolutePath = resolveFileToolPath(cwd, event.input.path);
+    const target = resolveTarget(cwd, event.input.path);
+    if (target === undefined) {
+      return undefined;
+    }
     return {
-      path: event.input.path,
+      ...target,
       kind: MUTATION_KIND.write,
       lines: addedLinesForWrite(
-        absolutePath === undefined ? undefined : readFileIfExists(absolutePath),
+        readFileIfExists(target.absolutePath),
         event.input.content,
       ),
     };
   }
   if (isToolCallEventType('edit', event)) {
+    const target = resolveTarget(cwd, event.input.path);
+    if (target === undefined) {
+      return undefined;
+    }
     return {
-      path: event.input.path,
+      ...target,
       kind: MUTATION_KIND.edit,
       lines: addedLinesForEdit(event.input.edits),
     };
@@ -247,10 +307,14 @@ function extractMutation(
   return undefined;
 }
 
-function readMutationBody(cwd: string, path: string): string | undefined {
+function resolveTarget(cwd: string, path: string): MutationTarget | undefined {
   const absolutePath = resolveFileToolPath(cwd, path);
   if (absolutePath === undefined) {
     return undefined;
   }
-  return readFileIfExists(absolutePath);
+  const relativePath = projectRelativePath(cwd, absolutePath);
+  if (relativePath === undefined) {
+    return undefined;
+  }
+  return { absolutePath, relativePath };
 }

package/extensions/jev/index.ts

@@ -11,7 +11,7 @@ import {
   type JevStatus,
   registerJevGuard,
   resetJevGuard,
-  resetJevUsage,
+  resetJevSession,
 } from './guard.ts';
 import {
   clearStoredKey,
@@ -75,7 +75,7 @@ export default function registerJev(pi: ExtensionAPI): void {
   });
 
   pi.on('session_start', (_event, ctx) => {
-    resetJevUsage(guardState);
+    resetJevSession(guardState);
     publish(currentStatus(), ctx);
   });
 

package/extensions/jev/model.ts

@@ -1,4 +1,4 @@
-import { languageForPath } from '../rules/catalog.ts';
+import { LANGUAGE, languageForPath } from '../rules/catalog.ts';
 import { type AddedLine, addedLines } from '../rules/model.ts';
 
 export type { AddedLine } from '../rules/model.ts';
@@ -11,8 +11,9 @@ export const JEV_MODEL = 'jev-latest';
 // noise on every edit.
 export const VIOLATION_PROBABILITY = 0.8;
 
-// The state must stay well under the two documented budgets (64k tokens for the
-// whole request, 32k for the state plus the longest question). A file that does
+// The serialized state must stay well under the two documented budgets (64k
+// tokens for the whole request, 32k for the state plus the longest question). A
+// new file travels twice, as the body and as its added lines. A state that does
 // not fit is skipped, never truncated: half a file reads as a distorted picture
 // and Jev answers it with the same confidence.
 export const MAX_STATE_CHARACTERS = 60_000;
@@ -167,8 +168,14 @@ export function addedLinesForEdit(
   return edits.flatMap((edit) => addedLines(edit.oldText, edit.newText));
 }
 
-export function stateFitsBudget(body: string): boolean {
-  return body.length <= MAX_STATE_CHARACTERS;
+// The six questions are about code structure; a README or a lockfile would
+// spend a call on answers that mean nothing.
+export function isReviewablePath(path: string): boolean {
+  return languageForPath(path) !== LANGUAGE.generic;
+}
+
+export function stateFitsBudget(state: JevFileState): boolean {
+  return JSON.stringify(state).length <= MAX_STATE_CHARACTERS;
 }
 
 export function buildRequestBody(file: JevFileState): JevRequestBody {

package/extensions/jev/ui.ts

@@ -30,6 +30,7 @@ const STATUS_LABEL: Readonly<Record<JevStatus, string>> = {
   [JEV_STATUS.noKey]: 'jev: no key (F10)',
   [JEV_STATUS.quota]: 'jev: out of quota (F10)',
   [JEV_STATUS.auth]: 'jev: key rejected (F10)',
+  [JEV_STATUS.rateLimited]: 'jev: rate limited',
   [JEV_STATUS.unavailable]: 'jev: unreachable',
 };
 

package/extensions/shared/file-path.ts

@@ -1,6 +1,6 @@
 import { realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const FILE_URL_PREFIX = 'file://';
@@ -29,6 +29,31 @@ export function resolveFileToolPath(
   return realpathOr(absolutePath);
 }
 
+// A file that does not exist yet keeps its unresolved path, so it is matched
+// against the literal working directory as well as the canonical one.
+export function projectRelativePath(
+  cwd: string,
+  absolutePath: string,
+): string | undefined {
+  const literalRoot = resolve(cwd);
+  for (const root of new Set([realpathOr(literalRoot), literalRoot])) {
+    const relativePath = relative(root, absolutePath);
+    if (isInsideRoot(relativePath)) {
+      return relativePath;
+    }
+  }
+  return undefined;
+}
+
+function isInsideRoot(relativePath: string): boolean {
+  return (
+    relativePath.length > 0 &&
+    relativePath !== '..' &&
+    !relativePath.startsWith(`..${sep}`) &&
+    !isAbsolute(relativePath)
+  );
+}
+
 function normalizeFileToolPath(path: string): string {
   const normalizedSpaces = path.replace(UNICODE_SPACES, ' ');
   const withoutAtPrefix = normalizedSpaces.startsWith('@')

package/extensions/shared/review-note.ts

@@ -0,0 +1,14 @@
+export const REVIEW_NOTE_EVENT = 'sideroom:review-note';
+
+export interface ReviewNote {
+  readonly text: string;
+}
+
+export function isReviewNote(value: unknown): value is ReviewNote {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'text' in value &&
+    typeof value.text === 'string'
+  );
+}

package/extensions/shared/settle.ts

@@ -0,0 +1,50 @@
+import type {
+  AgentBeforeSettleEvent,
+  AgentBeforeSettleEventResult,
+  InputEvent,
+  InputSource,
+} from '@earendil-works/pi-coding-agent';
+
+const COMPLETED_OUTCOME = 'completed';
+const USER_ROLE = 'user';
+const CUSTOM_MESSAGE_ENTRY = 'custom_message';
+const USER_INPUT_SOURCES: ReadonlySet<InputSource> = new Set([
+  'interactive',
+  'rpc',
+]);
+
+// A message typed while the agent runs joins the current run as a steer or
+// follow-up; only input that arrives idle opens a new turn.
+export function startsUserTurn(event: InputEvent): boolean {
+  return (
+    USER_INPUT_SOURCES.has(event.source) &&
+    event.streamingBehavior === undefined
+  );
+}
+
+// An aborted run is the user stopping the agent, an errored run has nothing
+// worth reviewing, and a pending user message already decides what comes next.
+export function acceptsSettleSteer(event: AgentBeforeSettleEvent): boolean {
+  if (event.outcome !== COMPLETED_OUTCOME) {
+    return false;
+  }
+  return !event.context.pendingMessages.some(
+    (message) => message.role === USER_ROLE,
+  );
+}
+
+// Handlers chain on agent_before_settle, so keep the entries earlier handlers
+// proposed; replacing them would drop another extension's steer.
+export function withHiddenSteer(
+  event: AgentBeforeSettleEvent,
+  customType: string,
+  content: string,
+): AgentBeforeSettleEventResult {
+  return {
+    entries: [
+      ...event.entries,
+      { type: CUSTOM_MESSAGE_ENTRY, customType, content, display: false },
+    ],
+    continue: true,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.9.0",
+  "version": "8.10.0",
   "description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
   "type": "module",
   "files": [
@@ -89,8 +89,8 @@
     "@changesets/cli": "^3.0.2",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
     "@types/node": "^22.20.1",
     "typebox": "1.3.7",
     "typescript": "^5.6.0"

package/skills/sideroom-persona/SKILL.md

@@ -77,9 +77,12 @@ dead-locked.
 ### What steering means
 
 The extension sends a corrective steer after a degraded artifact block or a
-prohibited assistant message. Steers use `triggerTurn: true` so they reach the
-model even when the run is already idle. At most three steers are sent per
-agent run.
+prohibited assistant message. Both moments happen while the agent is working, so
+the steer travels through `pi.sendMessage` with `{ triggerTurn: true, deliverAs:
+'steer' }` and joins the current run. A steer sent after the run ended belongs
+to the guidelines review and the walkthrough offer, which append a
+`custom_message` entry on `agent_before_settle` instead.
+At most three steers are sent per agent run.
 
 ## Boundaries