@rmrdeveloper/sideroom-pi 9.0.0 → 9.1.0

package/README.md

@@ -1,4 +1,4 @@
-# Sideroom Pi — the side room your agent was missing
+# Sideroom Pi: make "done" mean done
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/logo.png" alt="The Sideroom Pi mark" width="640">
@@ -8,8 +8,9 @@
 [![npm monthly downloads](https://img.shields.io/npm/dm/@rmrdeveloper/sideroom-pi?label=downloads&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 
-**Asks before it guesses. Shows the plan. Enforces the style. Refuses to
-call it done in red.**
+**The open-source quality layer for Pi.** Your agent asks before it guesses,
+follows your code rules on the lines it writes, and cannot call a task
+finished while your project's own checks are still red.
 
 ```bash
 pi install npm:@rmrdeveloper/sideroom-pi
@@ -17,18 +18,16 @@ pi install npm:@rmrdeveloper/sideroom-pi
 
 ![Sideroom asking a multi-question batch and keeping the live board below it](https://raw.githubusercontent.com/RMRdeveloper/sideroom-pi/main/media/preview.png)
 
-> Coding agents fail in predictable ways: they guess instead of asking, they
-> bury progress in chat scroll, they litter your repo with `TODO.md` files,
-> every session writes code in a slightly different style, and they declare
-> victory while the project checks are still red.
+> "Done, everything works." You open the project. The tests are red.
 >
-> **Sideroom fixes all of it — without touching your repository.**
+> Sideroom is for people who use Pi on real work and are tired of reviewing
+> and redoing what the agent delivered. Same freedom and price as Pi; the
+> discipline you expect from a senior review.
 
-Sideroom Pi is a global [Pi package](https://pi.dev/docs/latest/packages)
-that gives the parent agent a *side room* next to your code: a place to ask
-sharp questions, show live progress, track what changed, and stay honest
-about code quality. The room lives in the Pi session, not in your repo. No
-`.pi` config, no task graph, no Sideroom files left behind.
+For developers who chose Pi for control or cost and need the result to be
+actually ready: Sideroom is the quality layer that makes Pi follow your
+rules, ask when there are two reasonable paths, and not say "done" until
+your project passes its own checks.
 
 ## Why Sideroom exists
 
@@ -285,16 +284,13 @@ nothing is detectable, the gate does nothing.
 
 ### Explain — the walkthrough offer
 
-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_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.
+When a review, style correction, or check already requires a closing
+continuation, `explain` can add a walkthrough offer through `sideroom_ask`:
+changes only, test steps only, both, or nothing. The instruction asks the agent
+to finish the work, review and checks before offering. It never opens a turn
+solely for an offer. Once per user turn, only after at least five distinct
+files changed, and only in the TUI. Aborts, errors and queued messages postpone
+it. No tool, widget or persisted state.
 
 ## Quick path
 
@@ -467,14 +463,13 @@ itself.
   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.
+- Delivery: joins an existing necessary settle continuation through the shared
+  supplement event, in any extension load order. If none is needed, stays silent.
 - 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.
-- At most one offer per turn. The flag is set before the steer, so the turn the
-  offer triggers cannot re-trigger it.
+- At most one offer per turn. The flag is set only when the supplement is
+  appended; the offer never triggers its own continuation.
 - No green-check requirement: red checks still produce the offer.
 
 ### Grill contract

package/assets/visual-context/browser/background.js

@@ -210,7 +210,7 @@ function scheduleReconnect(entry) {
   entry.retry = setTimeout(() => {
     void reconnect(entry);
   }, RETRY_MS);
-  // Alarms wake the worker after it has been suspended while Pi is closed.
+
   void chrome.alarms.create(RETRY_ALARM, { periodInMinutes: 1 });
 }
 
@@ -284,7 +284,7 @@ async function openConnection(entry) {
             });
             return;
           }
-          // Older brokers and connection failures can only identify the installation.
+
           for (const selectionId of [...receipts.keys()]) {
             await notifyReceipt({
               endpoint: entry.endpoint,

package/assets/visual-context/browser/popup.js

@@ -6,8 +6,7 @@ const disconnect = document.querySelector('#disconnect');
 const forget = document.querySelector('#forget');
 const destination = document.querySelector('#destination');
 const connect = document.querySelector('#connect');
-// Edge keeps the Chromium shortcut page under its own scheme; every other
-// Chromium browser the companion supports answers on chrome://.
+
 const SHORTCUT_PAGE = navigator.userAgent.includes('Edg/')
   ? 'edge://extensions/shortcuts'
   : 'chrome://extensions/shortcuts';

package/extensions/ask/index.ts

@@ -23,7 +23,6 @@ export const ASK_PROMPT_GUIDELINES = [
   'sideroom_ask only works in the interactive TUI; it errors in print, JSON, and RPC modes.',
 ];
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerAsk(pi: ExtensionAPI): void {
   pi.registerTool({
     name: TOOL_NAME,

package/extensions/ask/model.ts

@@ -423,7 +423,7 @@ function schemaErrorMessage(value: unknown): string {
     return `Error: Option ${String(optionIndex + 1)} for question '${id}' may contain at most ${String(MAX_OPTION_LABEL_LENGTH)} characters`;
   }
 
-  return `Error: Invalid sideroom_ask parameters`;
+  return 'Error: Invalid sideroom_ask parameters';
 }
 
 function questionId(

package/extensions/ask/selection.ts

@@ -1,9 +1,5 @@
 import type { AskAnswer, AskQuestion, AskSelection } from './model.ts';
 
-/**
- * Sorted ascending so the answer and its rendering stay stable no matter the
- * order the user toggled the options in.
- */
 export function toggleSelection(
   selected: readonly number[],
   optionIndex: number,

package/extensions/done/guard.ts

@@ -6,8 +6,10 @@ import {
   isToolCallEventType,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
+import { registerCheckStatus } from '../shared/check-status.ts';
 import {
   registerSettleGuard,
+  registerSettleSupplement,
   SETTLE_PRIORITY,
   withHiddenSteer,
 } from '../shared/settle.ts';
@@ -46,6 +48,13 @@ export function registerDoneGuard({
   const checkRuns = new Set<string>();
   const mutationPaths = new Map<string, string>();
 
+  registerCheckStatus(pi, (ctx) => {
+    const check = resolveCommand(ctx);
+    return check === undefined
+      ? undefined
+      : { command: check.display, green: state.checksGreen };
+  });
+
   pi.on('tool_call', (event, ctx) => {
     if (
       isToolCallEventType('write', event) ||
@@ -86,6 +95,17 @@ export function registerDoneGuard({
     }
   });
 
+  registerSettleSupplement(pi, (ctx) => {
+    if (!shouldNoticeMissingTest(state, resolveTestSetup(ctx))) {
+      return undefined;
+    }
+    state.noticedMissingTest = true;
+    return {
+      customType: MISSING_TEST_NOTICE_TYPE,
+      content: formatMissingTestNotice(),
+    };
+  });
+
   registerSettleGuard(pi, {
     priority: SETTLE_PRIORITY.done,
     pending: (ctx) =>

package/extensions/done/index.ts

@@ -15,7 +15,6 @@ import {
 } from './guard.ts';
 import { createDoneState, resetDoneRun } from './model.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerDone(pi: ExtensionAPI): void {
   const state = createDoneState();
   const cache = new Map<string, CheckCommand | undefined>();

package/extensions/done/model.ts

@@ -15,8 +15,6 @@ export const MISSING_TEST_NOTICE_TYPE = 'sideroom-missing-test-notice';
 
 const TEST_DIRECTORY = /(?:^|\/)(?:__tests__|tests?|specs?)(?:\/|$)/;
 
-// Test paths are recognised by name only: the notice never claims the right
-// test exists, so a missed convention only costs a nudge, never a false pass.
 const TEST_FILE =
   /(?:^|\/)(?:test_[\w.-]*\.py|[\w.-]*[._](?:test|spec)\.[\w.-]+|[\w.-]*(?:Test|Tests)\.java)$/;
 
@@ -82,5 +80,5 @@ export function formatDoneSteer(display: string): string {
 }
 
 export function formatMissingTestNotice(): string {
-  return 'This run changed code files and no test file. Check whether existing tests cover the changed behavior; add or update a test if coverage is missing, then rerun the relevant checks before finishing.';
+  return 'This run changed code files and no test file. Check whether existing tests cover the changed behavior; add or update a test if coverage is missing, reuse relevant checks that already passed after the latest mutation, and run missing, failed, or stale checks before finishing. Any code or test edit makes earlier checks stale.';
 }

package/extensions/explain/guard.ts

@@ -3,12 +3,7 @@ import {
   isEditToolResult,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
-import {
-  registerSettleGuard,
-  SETTLE_PRIORITY,
-  startsUserTurn,
-  withHiddenSteer,
-} from '../shared/settle.ts';
+import { registerSettleSupplement, startsUserTurn } from '../shared/settle.ts';
 import {
   applyOfferDecision,
   decideOffer,
@@ -43,7 +38,7 @@ export function registerExplainGuard(
     if (!isEditToolResult(event) && !isWriteToolResult(event)) {
       return;
     }
-    // SAFETY: Pi validates built-in file-tool inputs before emitting tool_result.
+
     const input = event.input as unknown as FileToolInput;
     const pathKey = mutationPathKey(ctx.cwd, input.path);
     if (pathKey === undefined) {
@@ -52,19 +47,14 @@ export function registerExplainGuard(
     recordMutation(state, pathKey);
   });
 
-  // 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.
-  registerSettleGuard(pi, {
-    priority: SETTLE_PRIORITY.explain,
-    pending: (ctx) => decideOffer(state, ctx.mode) === EXPLAIN_DECISION.send,
-    handle: (event, ctx) => {
-      applyOfferDecision(state, decideOffer(state, ctx.mode));
-      return withHiddenSteer({
-        event,
-        customType: EXPLAIN_OFFER_TYPE,
-        content: EXPLAIN_OFFER,
-      });
-    },
+  registerSettleSupplement(pi, (ctx) => {
+    if (decideOffer(state, ctx.mode) !== EXPLAIN_DECISION.send) {
+      return undefined;
+    }
+    applyOfferDecision(state, EXPLAIN_DECISION.send);
+    return {
+      customType: EXPLAIN_OFFER_TYPE,
+      content: `After finishing the requested work, review, and checks: ${EXPLAIN_OFFER}`,
+    };
   });
 }

package/extensions/explain/index.ts

@@ -2,7 +2,6 @@ import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { registerExplainGuard } from './guard.ts';
 import { createExplainState, resetExplainTurn } from './model.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerExplain(pi: ExtensionAPI): void {
   const state = createExplainState();
   registerExplainGuard(pi, state);

package/extensions/explain/model.ts

@@ -2,8 +2,6 @@ import { resolveFileToolPath } from '../shared/file-path.ts';
 
 export const EXPLAIN_OFFER_TYPE = 'sideroom-explain-offer';
 
-// Five is the point where a turn stopped being an adjustment and became work
-// worth walking the user through.
 export const EXPLAIN_FILE_THRESHOLD = 5;
 
 const TUI_MODE = 'tui';
@@ -36,8 +34,6 @@ export function resetExplainTurn(state: ExplainState): void {
   state.offeredThisTurn = false;
 }
 
-// Pi reports the path as the model wrote it, so use the built-in file-tool
-// semantics and canonicalize existing aliases before counting the file.
 export function mutationPathKey(cwd: string, path: string): string | undefined {
   return resolveFileToolPath(cwd, path);
 }
@@ -46,7 +42,6 @@ export function recordMutation(state: ExplainState, pathKey: string): void {
   state.mutatedFilesThisTurn.add(pathKey);
 }
 
-// The shared settle guard gives review and checks priority over the offer.
 export function decideOffer(
   state: ExplainState,
   mode: string,

package/extensions/guidelines/execute.ts

@@ -6,15 +6,29 @@ export interface GuidelinesToolResult {
   readonly details: { readonly paths: readonly string[] };
 }
 
+interface GuidelinesLoadOptions {
+  readonly loadedPaths?: ReadonlySet<string>;
+  readonly readDocument?: (path: string) => string;
+}
+
 export function executeGuidelines(
   path: string,
-  readDocument: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+  {
+    loadedPaths = new Set(),
+    readDocument = (path) => readFileSync(path, 'utf8'),
+  }: GuidelinesLoadOptions = {},
 ): GuidelinesToolResult {
   const guidePath = languageGuideFor(path);
   const paths = [
     GUIDELINE_SKILL_PATH,
     ...(guidePath === undefined ? [] : [guidePath]),
-  ];
+  ].filter((documentPath) => !loadedPaths.has(documentPath));
+  if (paths.length === 0) {
+    return {
+      content: [{ type: 'text', text: 'The required complete guidelines are already loaded in this run.' }],
+      details: { paths },
+    };
+  }
   const content = paths.map((documentPath) => {
     const text = readDocument(documentPath);
     if (text.trim().length === 0) {

package/extensions/guidelines/guard.ts

@@ -46,7 +46,7 @@ export function registerGuidelineGuard(
   pi: ExtensionAPI,
   state: GuidelineReadState,
 ): void {
-  // This notification follows every tool_result handler, including redactors.
+
   pi.on('tool_execution_end', (event, ctx) => {
     if (event.toolName !== GUIDELINES_TOOL_NAME) {
       return;
@@ -78,7 +78,6 @@ export function registerGuidelineGuard(
       return;
     }
 
-    // SAFETY: Pi validates built-in read arguments before emitting tool_result.
     const input = event.input as unknown as ReadInput;
     if (
       input.offset !== undefined ||

package/extensions/guidelines/index.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
-import { GUIDELINES_TOOL_NAME } from './catalog.ts';
+import { GUIDELINE_SKILL_PATH, GUIDELINES_TOOL_NAME } from './catalog.ts';
 import { executeGuidelines } from './execute.ts';
 import {
   createGuidelineReadState,
@@ -14,7 +14,6 @@ import {
   resetReviewTurn,
 } from './review.ts';
 
-// Pi loads extensions/*/index.ts through export default.
 export default function registerGuidelines(pi: ExtensionAPI): void {
   const readState = createGuidelineReadState();
   registerGuidelineGuard(pi, readState);
@@ -35,10 +34,13 @@ export default function registerGuidelines(pi: ExtensionAPI): void {
     executionMode: 'sequential',
     async execute(toolCallId, { path }, signal) {
       signal?.throwIfAborted();
-      const loaded = executeGuidelines(path);
+      const loadedPaths = new Set(readState.languageGuidesRead);
+      if (readState.skillRead) {
+        loadedPaths.add(GUIDELINE_SKILL_PATH);
+      }
+      const loaded = executeGuidelines(path, { loadedPaths });
       signal?.throwIfAborted();
-      // Keep an independent receipt: changed or partial tool results cannot
-      // authorize mutations, and resets discard receipts still awaiting delivery.
+
       readState.pendingLoads.set(toolCallId, {
         content: loaded.content.map((part) => ({ ...part })),
         details: { paths: [...loaded.details.paths] },
@@ -63,8 +65,6 @@ export default function registerGuidelines(pi: ExtensionAPI): void {
     return { systemPrompt };
   });
 
-  // Compaction may summarize the loaded guides out of context mid-run; force
-  // a fresh read instead of trusting a now-stale in-memory flag.
   pi.on('session_compact', () => {
     resetGuidelineReadState(readState);
   });

package/extensions/guidelines/prompt.ts

@@ -5,8 +5,6 @@ export { LANGUAGE_GUIDE_FILES } from './catalog.ts';
 export const GUIDELINES_REMINDER_HEADING =
   'Sideroom coding guidelines (always-on reminder):';
 
-// One dense index instead of one sentence per language: the same paths and the
-// same requirement, a fraction of the tokens every turn.
 const LANGUAGE_GUIDE_INDEX = LANGUAGE_GUIDES.map(
   ({ extensions, path }) => `${extensions.join('/')} ${path}`,
 ).join('; ');

package/extensions/guidelines/review.ts

@@ -3,6 +3,7 @@ import {
   isEditToolResult,
   isWriteToolResult,
 } from '@earendil-works/pi-coding-agent';
+import { readCheckStatus } from '../shared/check-status.ts';
 import { isReviewNote, REVIEW_NOTE_EVENT } from '../shared/review-note.ts';
 import {
   registerSettleGuard,
@@ -14,13 +15,13 @@ import {
 export const REVIEW_STEER_TYPE = 'sideroom-guidelines-review';
 
 export const REVIEW_STEER =
-  'Finish any remaining requested implementation before reviewing. Review the changes this run introduced against the loaded Sideroom language guide: fix only demonstrated violations caused by those changes, preserving all requested requirements and existing behavior. KISS and YAGNI do not justify removing required error handling, compatibility, or tests. Include rule 20, Decomposition by intent: names and contracts should separate orchestration from coherent implementation details, even with one caller. Do not split solely for line count or separate tightly coupled steps into shared mutable state, excessive parameters, or functions that must be read together. Do not refactor unrelated code. Then run the relevant formatter, linter, type checks, and tests. If the guide is no longer in context, re-read it in full first.';
+  'Finish any remaining requested implementation before reviewing. Review the changes this run introduced against the loaded Sideroom language guide: fix only demonstrated violations caused by those changes, preserving all requested requirements and existing behavior. KISS and YAGNI do not justify removing required error handling, compatibility, or tests. Include rule 20, Decomposition by intent: names and contracts should separate orchestration from coherent implementation details, even with one caller. Do not split solely for line count or separate tightly coupled steps into shared mutable state, excessive parameters, or functions that must be read together. Do not refactor unrelated code. Reuse relevant checks that already passed in this user turn after the latest file mutation. Run only missing, failed, or stale formatter, linter, type checks, and tests; any further file mutation makes earlier checks stale. If the guide is no longer in context, re-read it in full first.';
 
 export const WORKFLOW_REVIEW_STEER =
   'Verify the semantic notes below against the visible evidence and the questionnaire or task contract. Correct only demonstrated ambiguity or contradictions; respect user answers and ask again only when clarification is necessary. Missing evidence is not proof of unfinished work. Do not create unrelated implementation work. Run project checks only if code changes.';
 
 export const REVIEW_NOTES_STEER =
-  'Additional semantic notes arrived after the review. Verify each against the loaded Sideroom language guide, fix only demonstrated violations introduced by this run without removing required behavior or refactoring unrelated code, then rerun the relevant checks.';
+  'Additional semantic notes arrived after the review. Verify each against the loaded Sideroom language guide, fix only demonstrated violations introduced by this run without removing required behavior or refactoring unrelated code, reuse checks that remain valid, and run only missing, failed, or stale checks after any corrective edit.';
 
 export interface ReviewState {
   mutated: boolean;
@@ -49,8 +50,6 @@ export function shouldReview(state: ReviewState): boolean {
   return (state.mutated || state.notes.length > 0) && !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(
@@ -110,23 +109,23 @@ export function registerReviewGuard(
     }
   });
 
-  // 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.
   registerSettleGuard(pi, {
     priority: SETTLE_PRIORITY.review,
     pending: () => pendingReviewSteer(state) !== undefined,
-    handle: (event) => {
+    handle: (event, ctx) => {
       const steer = pendingReviewSteer(state);
       if (steer === undefined) {
         return;
       }
       markReviewSteered(state);
+      const check = readCheckStatus(pi, ctx);
+      const checkNote = check?.green
+        ? `\n\nThe detected project check \`${check.command}\` passed after the latest successful file mutation in this user turn. Reuse that result if this review changes no files; rerun it after any further mutation.`
+        : '';
       return withHiddenSteer({
         event,
         customType: REVIEW_STEER_TYPE,
-        content: steer,
+        content: steer + checkNote,
       });
     },
   });

package/extensions/jev/client.ts

@@ -49,8 +49,6 @@ export interface JevAttempt {
   readonly failure: JevFailure | undefined;
 }
 
-// The endpoint is a package constant, never a value from the environment or the
-// session, so the outbound URL cannot be steered by the repository being edited.
 export function createFetchTransport(
   timeoutMs: number = JEV_REQUEST_TIMEOUT_MS,
 ): JevTransport {
@@ -68,8 +66,6 @@ export function createFetchTransport(
   };
 }
 
-// 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,
@@ -97,9 +93,6 @@ export function classifyStatus(status: number): JevFailure | undefined {
   return undefined;
 }
 
-// A Jev failure is a missing note, never an error: the mutation already
-// succeeded and the mechanical rules already ran. So this returns a value
-// instead of throwing, and the caller only decides whether to keep calling.
 export async function askJev(
   transport: JevTransport,
   apiKey: string,

package/extensions/jev/context.ts

@@ -29,7 +29,6 @@ interface ScanResult {
   readonly partial: boolean;
 }
 
-// Keep the edited file complete. Other files are included whole or not at all.
 export function buildContextualState(
   cwd: string,
   path: string,
@@ -339,7 +338,6 @@ function matchesReference(names: ReadonlySet<string>, path: string): boolean {
   return false;
 }
 
-// Naming is evidence only for a sibling test, never for a repository-wide basename match.
 function isCompanionTest(source: string, candidate: string): boolean {
   if (
     isTestPath(source) ||