@rmrdeveloper/sideroom-pi 8.9.0 → 8.11.0

package/README.md

@@ -55,8 +55,8 @@ Sideroom answers each one with a small, opinionated surface:
 | Invisible monorepo skills | `monorepo-skills` — trusted child folders join Pi's available skill list |
 | Vague plans | `sideroom-grill` — an interview that settles the words before the work |
 | Unapplied guidelines | `sideroom_rules` — mechanical checks that block or flag the lines you add |
-| Unchecked judgment rules | `jev` — asks a decision model about the six rules no check can decide |
-| Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of jargon it invented |
+| Unchecked judgment rules | `jev` — asks a decision model about guide rules with visible evidence |
+| Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of unnecessary technical words |
 | Premature completion | `sideroom_done` — steers back to the project's check command before finishing |
 | Work left unexplained | `explain` — offers a walkthrough and how to test it once the work settles |
 
@@ -140,9 +140,13 @@ project are labelled `external`. A new session starts clean.
 
 An on-demand skill for fuzzy plans. It interviews you in `sideroom_ask`
 rounds — reading the codebase first so it never asks what the code already
-says — until you share one understanding. Resolved terms land in
-`CONTEXT.md` the moment they resolve; hard decisions land as ADRs under
-`docs/adr/`. Everything else stays in the conversation, ready to become a
+says — until you share one understanding. Its recommendations favor choices
+that are easy to maintain and meet known growth needs over the cheapest initial
+build. It names the upfront cost; if a missing fact could change the choice,
+it asks for that fact before recommending a solution. Resolved terms land in
+`CONTEXT.md` the moment they resolve. Only hard-to-reverse, surprising choices
+with a real trade-off qualify for a record under `docs/adr/`; the user is asked
+first. Everything else stays in the conversation, ready to become a
 spec or an implementation. Vocabulary sharpening during the rounds follows
 the companion `sideroom-domain-modeling` skill, which also runs on its own
 whenever the words — not the plan — are the problem. And when there is no
@@ -189,19 +193,24 @@ written, no config read: the catalog ships with the package.
 
 ### Jev — judgment where no check reaches
 
-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.
-
-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.
+Reading the guide covers the mechanical rules. `jev` makes one optional call
+to TypeSafe's decision model about the changed file and, when available, up to
+four directly related source files. It checks guard clauses, fail fast,
+command/query separation, null handling, immutability, repeated validation,
+responsibility, dependency direction, and comments only when the supplied
+files support the question. An answer above the cutoff travels with the
+end-of-run guidelines review 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. No conversation or session
+content leaves the machine. Related source excludes ignored, hidden, sensitive-
+named and symlinked paths; a normal source file can still contain a secret.
 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.
 
@@ -210,12 +219,12 @@ without ever writing it to the session.
 `sideroom_persona` is the agent's voice, and there is exactly one of it. A
 short reminder rides the system prompt on every turn, so it survives
 compaction; the full guide lives in the on-demand `sideroom-persona` skill.
-The voice is direct and dry, free of filler, and plain enough to leave no
-doubt about what is being discussed — while calling things by the names the
-user already uses. Emojis and decorative symbols in the lines a `write`/`edit`
-adds block the mutation; flattering openers, hedging, automatic apologies, and
-AI meta-commentary are answered with a capped steer. No profiles to switch and
-no profile selection to store.
+The voice is direct and dry, free of filler. It uses everyday words even when
+you use technical terms. It keeps a technical term only when needed to
+understand or act, and explains it the first time. Emojis and decorative
+symbols in the lines a `write`/`edit` adds block the mutation; flattering
+openers, hedging, automatic apologies, and AI meta-commentary are answered
+with a capped steer. No profiles to switch and no profile selection to store.
 
 ### Done — done means green
 
@@ -230,11 +239,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 +322,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 +359,23 @@ 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 applicable `noul` questions on the complete
+  changed file and up to four directly related source files.
+- The official 32k-token state-plus-longest-question and 64k-token request
+  limits are observed conservatively using 32,000 and 64,000 UTF-8 bytes.
+  Oversized neighbours are omitted whole; if the changed file cannot fit,
+  the call is skipped. An answer at or above `0.8` 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 +410,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/ask/index.ts

@@ -15,8 +15,9 @@ export const ASK_PROMPT_SNIPPET =
   'Ask the user one or more questions with a recommended option, in their language.';
 
 export const ASK_PROMPT_GUIDELINES = [
-  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it drives sideroom_ask rounds. One sideroom_ask call is one batch; call it again for another round.',
-  'A decision the repository already settles consistently is a project fact: read the code and reuse it. A decision that materially affects architecture, dependencies, cost, security, operations, persistence, public contracts, or future change difficulty is an architectural decision: never assume it; follow the sideroom-architecture skill and expose it through sideroom_ask before committing, with the practical consequences of each alternative and one recommendation carrying a one-line justification, never technology names. If the repository shows two inconclusive patterns for the same decision, name the inconsistency in the prompt. Everything else is a minor decision: take it yourself.',
+  'Follow the sideroom-grill skill before non-trivial work without a settled spec. One sideroom_ask call is one batch; call again for another round.',
+  'Read the repository first: reuse a consistent project fact. An architectural decision (boundaries, dependencies, cost, security, operations, persistence, public contracts, future change difficulty) is never settled silently: never assume it. Follow the sideroom-architecture skill; ask through sideroom_ask with practical consequences and a one-line justification for one recommendation. Name inconsistent patterns in the prompt. Take minor decisions yourself.',
+  'Recommend evidence-backed long-term quality: maintainability and growth for known needs over initial speed. State the upfront cost; avoid speculative capacity. If decisive facts or figures are missing, ask for them first through sideroom_ask; recommend gathering evidence, not an unsupported solution.',
   'Write sideroom_ask prompts, tab labels, option labels, and option descriptions in the language the user is speaking; keep ids and option values in English.',
   'sideroom_ask always adds Out of scope and a write-your-own answer; never send them yourself. A single-selection question needs recommendationIndex; a multiple-selection question needs recommendedIndices and never recommendationIndex.',
   'sideroom_ask only works in the interactive TUI; it errors in print, JSON, and RPC modes.',

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,21 @@ export async function askJev(
   transport: JevTransport,
   apiKey: string,
   file: JevFileState,
+  signal: AbortSignal | undefined,
 ): Promise<JevAttempt> {
-  const body = JSON.stringify(buildRequestBody(file));
+  const requestBody = buildRequestBody(file);
+  const body = JSON.stringify(requestBody);
   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,
     };
   }
 
@@ -99,7 +131,10 @@ export async function askJev(
     return { findings: [], model: undefined, failure: undefined };
   }
   return {
-    findings: readFindings(envelope),
+    findings: readFindings(
+      envelope,
+      new Set(Object.keys(requestBody.questions)),
+    ),
     model: envelope.model,
     failure: undefined,
   };