pi-orchestrator-config 4.8.4 → 4.8.5

package/README.md

@@ -14,8 +14,8 @@ Single extension that provides:
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Subagent tool**             | Delegate tasks to specialist agents (single, parallel, chain, async modes); optional `model` param for model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **`list_models`**             | List available models and providers for subagent model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **Async background agents**   | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`: `x` kills, `Space` multi-selects, `a` kills all). On **acpx** parents, optional async is coerced to sync; dream/cron need `internal_operations_provider` + `internal_operations_model`. `cli-*` providers support async natively (see `dev-docs/cli-provider.md`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| **CLI / ACPX providers**      | Optional `cli_agents` / `acpx_agents` register `cli-*` / `acpx-*` via native `createProvider` (pi ≥ 0.84): `/login cli-<agent>` or `/login acpx-<agent>`, model refresh, filter when unavailable. Missing context window / maxTokens / cost filled from models.dev (`~/.pi/pi-config/models.dev.json`, 1-day refresh). Cold-start default restore (#753): gates `startup`\|`new`, empty `enabledModels`, trusted project merge — see `dev-docs/cli-provider.md`. Headless Cursor `--approve-mcps` when `CLI_APPROVE_MCPS` is set (`false` opts out) or the process is a sidecar (`SIDECAR_PORT`; `startSidecar()` stamps it while running and restores it on `close()`). Executable sidecar consumers should call `bindSidecarListenExit()` so bind/`stopped` fatals exit 1. Headless Gemini defaults `GEMINI_CLI_TRUST_WORKSPACE=true` and preserves an explicit parent value (including `false`). |
+| **Async background agents**   | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`: `x` kills, `Space` multi-selects, `a` kills all). On **acpx** parents, optional async is coerced to sync; dream/cron need `internal_operations_provider` + `internal_operations_model`. `cli-*` providers support async natively (see `docs/cli-provider.md`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **CLI / ACPX providers**      | Optional `cli_agents` / `acpx_agents` register `cli-*` / `acpx-*` via native `createProvider` (pi ≥ 0.84): `/login cli-<agent>` or `/login acpx-<agent>`, model refresh, filter when unavailable. Missing context window / maxTokens / cost filled from models.dev (`~/.pi/pi-config/models.dev.json`, 1-day refresh). Cold-start default restore (#753): gates `startup`\|`resume` (`new` only when no model is selected), empty `enabledModels`, trusted project merge — see `docs/cli-provider.md`. Headless Cursor `--approve-mcps` when `CLI_APPROVE_MCPS` is set (`false` opts out) or the process is a sidecar (`SIDECAR_PORT`; `startSidecar()` stamps it while running and restores it on `close()`). Executable sidecar consumers should call `bindSidecarListenExit()` so bind/`stopped` fatals exit 1. Headless Gemini defaults `GEMINI_CLI_TRUST_WORKSPACE=true` and preserves an explicit parent value (including `false`). |
 | **`/btw` command**            | Quick side questions without polluting conversation history — ephemeral overlay                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | **`/async-status` command**   | Show status of background agents — select one for live output streaming, multi-select and kill (`x`), or kill everything (`a`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | **`ask_user` tool**           | Structured user input with options and free-text — used by workflows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -305,7 +305,7 @@ See [`pi-config-settings.example.jsonc`](pi-config-settings.example.jsonc) for a
 
 Resolution order: project file → global `~/.pi/pi-config-settings.json` → env var → default.
 
-See `dev-docs/project-settings.md` for the full settings table.
+See `docs/configuration.md` for the full settings table.
 
 #### Reviewer Environment Variables
 
@@ -368,7 +368,7 @@ Rules auto-load alphabetically. Same-filename entries are overridden (project >
 
 Rules support settings/feature conditionals at prompt assembly (`assembleRuleText` in
 `rule-placeholders.ts`). Full syntax, truthiness, and assembly order:
-**[dev-docs/project-settings.md](dev-docs/project-settings.md)** (Rules assembly).
+**[docs/rules-and-layers.md](docs/rules-and-layers.md)** (Rules assembly).
 
 Markers: `{{IF:key}}…{{/IF}}`, `{{IFNOT:key}}…{{/IFNOT}}`, comparisons
 `{{IF:key==value}}` / `{{IF:key!=value}}`. Whole-file frontmatter: `requires_setting` /
@@ -483,7 +483,7 @@ that directory. Do not stop running containers merely to test this PR.
 After register, `filterModels` hides models when unavailable: PATH cleared while
 agent state remains, restore PATH; after `session_shutdown` (AgentState cleared
 and `initialized` reset) the next factory re-registers on `/new`|`/resume`|`/fork`
-(PATH alone is not enough). See `dev-docs/cli-provider.md`.
+(PATH alone is not enough). See `docs/cli-provider.md`.
 
 **ACPX provider agents (optional `acpx_agents`):** ACPX wraps CLI agents via the
 ACP runtime. Supported agents: `cursor`, `claude`, `gemini`. Enable with
@@ -500,10 +500,10 @@ symlinks package `agents/*.md` into the mounted project:
 
 Uses `ln -sfn` (safe if multiple `pi-docker` sessions share the same folder). Those three
 directories are added to the container global gitignore. **Native** installs do not auto-
-sync — copy or symlink yourself (see `dev-docs/cli-provider.md`).
+sync — copy or symlink yourself (see `docs/cli-provider.md`).
 
 **Extension ops logs:** `cli-provider` and dreaming write to `~/.pi/logs/` (not the chat
-UI). Fallback: `$TMPDIR/pi-logs/`. Details in `dev-docs/cli-provider.md` (Logging).
+UI). Fallback: `$TMPDIR/pi-logs/`. Details in `docs/cli-provider.md` (Logging).
 
 ### Pre-built image
 
@@ -917,6 +917,10 @@ CLI commands: `npx pi-sidecar` (start server), `npx pi-sidecar-start` (backgroun
 
 `GET /providers` lists registered providers and whether each supports a session API key, even when no models or credentials are available. The Python client exposes this as `await SidecarClient.get_providers()`.
 
+The sidecar's internal agent dir is configurable (startSidecar `agentDir` option / `PI_SIDECAR_AGENT_DIR`, default `/tmp/pi-sidecar-agent`) so
+deployments can supply custom providers, auth, and settings — see
+[`packages/pi-sidecar/README.md`](packages/pi-sidecar/README.md).
+
 See [`packages/pi-sidecar/README.md`](packages/pi-sidecar/README.md) for full documentation.
 See [`packages/pi-sidecar/CONSUMER-GUIDE.md`](packages/pi-sidecar/CONSUMER-GUIDE.md) for integration best practices.
 

package/agents/code-reviewer-docs.md

@@ -76,8 +76,8 @@ Use this documentation updates table:
 | Change | Check these files |
 |--------|-------------------|
 | New feature/command/tool | `README.md` (feature table, usage examples) |
-| New or modified extension module | `dev-docs/repo-structure.md` (repository structure) |
-| New agent added/removed | `dev-docs/repo-structure.md`, routing rules, bug reporting agent list |
+| New or modified extension module | `contributing/repo-structure.md` (repository structure) |
+| New agent added/removed | `contributing/repo-structure.md`, routing rules, bug reporting agent list |
 | New prompt template | `README.md` (prompt templates table) |
 | Docker/container changes | `README.md` (Docker section), `Dockerfile` |
 | New CLI tool or dependency | `README.md` (tools table), `Dockerfile` |
@@ -119,7 +119,7 @@ Flag audit failures as `[WARNING]` with the specific checklist item that failed.
 
 ### 5. Cross-File Consistency
 
-- Do README.md, AGENTS.md, and dev-docs agree on commands, structure, and workflows?
+- Do README.md, AGENTS.md, and contributing/ agree on commands, structure, and workflows?
 - Are version numbers, feature lists, and agent counts consistent?
 - Do referenced files actually exist?
 

package/extensions/pidiff/pidiff-ui/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pidiff-ui",
   "private": true,
-  "version": "4.8.4",
+  "version": "4.8.5",
   "type": "module",
   "scripts": {
     "dev": "vite",

package/extensions/providers/index.ts

@@ -67,7 +67,7 @@ import {
   isProvidersInitialized,
   markProvidersInitialized,
 } from "./initialized-guard.js";
-import { restoreDefaultModelOnSessionStart } from "./restore-default-model.js";
+import { registerModelRestoreOnSessionStart } from "./model-restore-wiring.js";
 import { registerLastThinkingLevel } from "./last-thinking-level.js";
 import { teardownProvidersOnSessionShutdown } from "./session-shutdown.js";
 
@@ -631,6 +631,22 @@ export default async function (
     }
   };
 
+  // Cold-start default model restore (#753), wired as its own session_start
+  // handler (multiple registrations are fine) so the wiring is unit-testable.
+  // Registered before the discovery-summary handler; the restore itself is
+  // fire-and-forget so ordering with the summary/thinking handler is benign.
+  registerModelRestoreOnSessionStart(pi, {
+    argv: testOptions?.argv,
+    onRestoreModel: (model, setSelected) => {
+      log.debug("onRestoreModel handoff", { provider: model.provider, id: model.id });
+      return lastThinking.restoreModel(model as Model<any>, setSelected);
+    },
+    onRestoreSettled: (event, ctx, modelRestore) => {
+      log.debug("onRestoreSettled handoff", { reason: (event as { reason?: string })?.reason });
+      return void lastThinking.applyAfterModelRestore(event, ctx, modelRestore);
+    },
+  });
+
   pi.on("session_start", (event, ctx) => {
     const reason = typeof event?.reason === "string" ? event.reason : "";
     const summary = `Providers: ${providerSummaryParts.join(", ")}`;
@@ -651,46 +667,6 @@ export default async function (
         ? { id: ctx.model.id, provider: String(ctx.model.provider) }
         : undefined,
     );
-    // agentDir via PI_CODING_AGENT_DIR / ~/.pi/agent only (ctx has cwd, not agentDir).
-    // Merge global + cwd/.pi/settings.json (project wins) only when trusted —
-    // same gate as pi SettingsManager (ctx.isProjectTrusted). Fail closed.
-    const cwd = typeof ctx.cwd === "string" ? ctx.cwd : undefined;
-    let projectTrusted = false;
-    try {
-      projectTrusted = typeof ctx.isProjectTrusted === "function"
-        ? ctx.isProjectTrusted() === true
-        : false;
-    } catch (err) {
-      log.debug(
-        "restore-default-model isProjectTrusted failed",
-        err instanceof Error ? err.message : String(err),
-      );
-      projectTrusted = false;
-    }
-    const modelRestore = restoreDefaultModelOnSessionStart({
-      ctx: {
-        model: ctx.model
-          ? { id: ctx.model.id, provider: String(ctx.model.provider) }
-          : undefined,
-        modelRegistry: ctx.modelRegistry,
-      },
-      reason,
-      cwd,
-      projectTrusted,
-      argv: testOptions?.argv,
-      getCurrentModel: () =>
-        ctx.model
-          ? { id: ctx.model.id, provider: String(ctx.model.provider) }
-          : undefined,
-      setModel: (model) => lastThinking.restoreModel(model as Model<any>, (selected) => pi.setModel(selected)),
-    }).catch((err) => {
-      log.warn(
-        "restore-default-model session_start error",
-        err instanceof Error ? err.message : String(err),
-      );
-      return false;
-    });
-    void lastThinking.applyAfterModelRestore(event, ctx, modelRestore);
   });
 
   pi.on("model_select", (event) => {

package/extensions/providers/model-restore-wiring.ts

@@ -0,0 +1,120 @@
+/**
+ * session_start wiring for the cold-start default model restore (#753).
+ *
+ * Extracted from extensions/providers/index.ts so the handler wiring —
+ * reason forwarding, setModel plumbing, cwd/projectTrusted extraction,
+ * fire-and-forget .catch, applyAfterModelRestore handoff — can be unit
+ * tested with a fake pi object. A wiring bug here (wrong reason, broken
+ * setModel) would otherwise reset the model undetected (#901 finding).
+ *
+ * Kept free of @earendil-works/pi-ai imports beyond the Model type so unit
+ * tests can import under tsx.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createLogger } from "../shared/logger.js";
+import { restoreDefaultModelOnSessionStart, type ModelLike } from "./restore-default-model.js";
+
+const log = createLogger("providers");
+
+/** Raw selection call (pi.setModel) handed to onRestoreModel. */
+export type ModelRestoreSetModel = (model: ModelLike) => Promise<boolean>;
+
+export type RegisterModelRestoreOnSessionStartOpts = {
+  /** CLI argv to scan for --model / --provider / --models (user override). */
+  argv?: string[];
+  /**
+   * setModel wrapper invoked by the restore. Receives the resolved default
+   * model and a raw setSelected that performs the actual selection
+   * (pi.setModel). Defaults to calling setSelected directly. index.ts passes
+   * lastThinking.restoreModel so thinking preferences follow the switch.
+   */
+  onRestoreModel?: (
+    model: ModelLike,
+    setSelected: ModelRestoreSetModel,
+  ) => Promise<boolean>;
+  /**
+   * Hook receiving the fire-and-forget (already caught) restore promise —
+   * index.ts passes lastThinking.applyAfterModelRestore so the saved thinking
+   * level is applied once the model restore settles. Optional.
+   */
+  onRestoreSettled?: (
+    event: any,
+    ctx: any,
+    modelRestore: Promise<boolean>,
+  ) => void;
+};
+
+/**
+ * Register a session_start handler that restores the saved default model
+ * when the #753 gates pass (see restore-default-model.ts). Fire-and-forget:
+ * session_start is not blocked by retries.
+ */
+export function registerModelRestoreOnSessionStart(
+  pi: ExtensionAPI,
+  opts: RegisterModelRestoreOnSessionStartOpts = {},
+): void {
+  const onRestoreModel =
+    opts.onRestoreModel ?? ((model, setSelected) => setSelected(model));
+  log.debug("model-restore-wiring: registering session_start handler");
+
+  pi.on("session_start", (event, ctx) => {
+    const reason = typeof event?.reason === "string" ? event.reason : "";
+    log.debug("model-restore-wiring session_start", { reason });
+
+    // agentDir via PI_CODING_AGENT_DIR / ~/.pi/agent only (ctx has cwd, not agentDir).
+    // Merge global + cwd/.pi/settings.json (project wins) only when trusted —
+    // same gate as pi SettingsManager (ctx.isProjectTrusted). Fail closed.
+    const cwd = typeof ctx.cwd === "string" ? ctx.cwd : undefined;
+    let projectTrusted = false;
+    try {
+      projectTrusted = typeof ctx.isProjectTrusted === "function"
+        ? ctx.isProjectTrusted() === true
+        : false;
+    } catch (err) {
+      log.debug(
+        "restore-default-model isProjectTrusted failed",
+        {
+          cwd,
+          reason,
+          error: err instanceof Error ? err.message : String(err),
+        },
+      );
+      projectTrusted = false;
+    }
+    // Fire-and-forget restore so session_start is not blocked by retries (#753).
+    // Omit registeredProviders: cli/acpx-only lists falsely fail-fast native defaults.
+    const modelRestore = restoreDefaultModelOnSessionStart({
+      ctx: {
+        model: ctx.model
+          ? { id: ctx.model.id, provider: String(ctx.model.provider) }
+          : undefined,
+        modelRegistry: ctx.modelRegistry,
+      },
+      reason,
+      cwd,
+      projectTrusted,
+      argv: opts.argv,
+      getCurrentModel: () =>
+        ctx.model
+          ? { id: ctx.model.id, provider: String(ctx.model.provider) }
+          : undefined,
+      setModel: (model) =>
+        onRestoreModel(model, (selected) =>
+          pi.setModel(selected as Model<any>),
+        ),
+    }).catch((err) => {
+      log.warn(
+        "restore-default-model session_start error",
+        err instanceof Error ? err.message : String(err),
+      );
+      return false;
+    });
+    if (opts.onRestoreSettled) {
+      opts.onRestoreSettled(event, ctx, modelRestore);
+    } else {
+      void modelRestore;
+    }
+  });
+}

package/extensions/providers/restore-default-model.ts

@@ -7,7 +7,8 @@
  * On session_start (providers already registered), restore the saved default
  * when current differs (or is missing), unless the user passed --model /
  * --provider / --models, enabledModels scopes the model list, or the session
- * is fork/reload.
+ * is fork/reload. "/new" keeps a selected model but still fills an empty
+ * selection (#901).
  *
  * Kept free of @earendil-works/pi-ai so unit tests can import under tsx.
  */
@@ -20,14 +21,17 @@ import { createLogger } from "../shared/logger.js";
 const log = createLogger("providers");
 
 /** session_start reasons where cold-start restore is allowed. */
-export const RESTORE_ALLOWED_REASONS = new Set(["startup", "new", "resume"]);
+export const RESTORE_ALLOWED_REASONS = new Set(["startup", "resume"]);
 
 export type RestoreDefaultModelOpts = {
   defaultProvider?: string | null;
   defaultModelId?: string | null;
   currentProvider?: string | null;
   currentModelId?: string | null;
-  /** session_start reason; only "startup" | "new" | "resume" may restore. */
+  /**
+   * session_start reason; "startup" | "resume" may restore, and "new" only
+   * when no model is currently selected (empty selection is filled).
+   */
   reason?: string | null;
   /**
    * CLI argv to scan for --model / --provider / --models (user override).
@@ -78,14 +82,33 @@ export function hasEnabledModelsScope(
  *
  * Gates (all must pass):
  * 1. defaultProvider and defaultModelId both non-empty
- * 2. reason is startup|new|resume
+ * 2. reason is startup|resume; "new" is allowed only when the current model
+ *    is missing (an existing selection is kept — nothing to preserve when
+ *    empty). fork/reload never restore.
  * 3. current missing OR current provider/id ≠ default
- * 4. argv does not contain --model, --provider, or --models
- * 5. enabledModels is missing or empty (non-empty scopes like --models)
+ * 4. argv does not contain --model, --provider, or --models (blocks in all
+ *    cases, including "new" with a missing model)
+ * 5. enabledModels is missing or empty (non-empty scopes like --models;
+ *    blocks in all cases)
  */
 export function shouldRestoreDefaultModel(opts: RestoreDefaultModelOpts): boolean {
   const reason = typeof opts.reason === "string" ? opts.reason.trim() : "";
-  if (!RESTORE_ALLOWED_REASONS.has(reason)) {
+
+  const currentProvider = typeof opts.currentProvider === "string"
+    ? opts.currentProvider.trim()
+    : "";
+  const currentModelId = typeof opts.currentModelId === "string"
+    ? opts.currentModelId.trim()
+    : "";
+  const currentMissing = !currentProvider || !currentModelId;
+
+  // Reason gate: startup|resume always eligible; "new" only when no model is
+  // selected (fills an empty selection; an existing selection is kept, #901).
+  if (
+    !RESTORE_ALLOWED_REASONS.has(reason)
+    && !(reason === "new" && currentMissing)
+  ) {
+    log.debug("shouldRestoreDefaultModel reject", { stage: "reason-gate", reason, currentMissing });
     return false;
   }
 
@@ -96,25 +119,26 @@ export function shouldRestoreDefaultModel(opts: RestoreDefaultModelOpts): boolea
     ? opts.defaultModelId.trim()
     : "";
 
-  if (!provider || !modelId) return false;
+  if (!provider || !modelId) {
+    log.debug("shouldRestoreDefaultModel reject", { stage: "missing-defaults", reason });
+    return false;
+  }
 
   if (argvHasModelOrProviderOverride(opts.argv)) {
+    log.debug("shouldRestoreDefaultModel reject", { stage: "argv-override", reason });
     return false;
   }
 
   if (hasEnabledModelsScope(opts.enabledModels)) {
+    log.debug("shouldRestoreDefaultModel reject", { stage: "enabled-models-scope", reason });
     return false;
   }
 
-  const currentProvider = typeof opts.currentProvider === "string"
-    ? opts.currentProvider.trim()
-    : "";
-  const currentModelId = typeof opts.currentModelId === "string"
-    ? opts.currentModelId.trim()
-    : "";
-
-  if (!currentProvider || !currentModelId) return true;
-  return currentProvider !== provider || currentModelId !== modelId;
+  const decision = currentMissing
+    || currentProvider !== provider
+    || currentModelId !== modelId;
+  log.debug("shouldRestoreDefaultModel decision", { reason, decision });
+  return decision;
 }
 
 export type PiAgentDefaults = {
@@ -425,6 +449,10 @@ export async function restoreDefaultModelOnSessionStart(opts: {
   const currentProvider = current?.provider;
   const currentModelId = current?.id;
   const argv = opts.argv ?? process.argv;
+  // Normalize once: the decision gate trims the reason, so the mid-flight
+  // abort guard must compare the trimmed value too — a padded reason (e.g.
+  // " new ") must not split the two code paths.
+  const reason = typeof opts.reason === "string" ? opts.reason.trim() : "";
   const argvOverride = argvHasModelOrProviderOverride(argv);
   const enabledModelsScope = hasEnabledModelsScope(enabledModels);
 
@@ -439,7 +467,7 @@ export async function restoreDefaultModelOnSessionStart(opts: {
   })) {
     log.debug(
       "restore-default-model skip",
-      `reason=${opts.reason ?? "?"} default=${defaultProvider ?? "?"}/${defaultModel ?? "?"} ` +
+      `reason=${reason || "?"} default=${defaultProvider ?? "?"}/${defaultModel ?? "?"} ` +
         `current=${currentProvider ?? "?"}/${currentModelId ?? "?"} ` +
         `argvOverride=${argvOverride} enabledModelsScope=${enabledModelsScope}` +
         (enabledModelsScope ? ` enabledModels=${enabledModels!.length}` : ""),
@@ -473,7 +501,7 @@ export async function restoreDefaultModelOnSessionStart(opts: {
     log.warn(
       "restore-default-model fail-fast",
       `registeredProviders lack ${defaultProvider} (count=${count}): ${label} ` +
-        `(session_start reason=${opts.reason ?? "?"})`,
+        `(session_start reason=${reason || "?"})`,
     );
     return false;
   }
@@ -503,6 +531,18 @@ export async function restoreDefaultModelOnSessionStart(opts: {
         return true;
       }
     } else {
+      // Empty /new snapshot: any model that appeared is a selection (user or
+      // picker) — abort rather than overwrite it with the saved default.
+      // The baseline path below is only for startup/resume, where the first
+      // live model may be the race-recovered initial pick, not user intent.
+      if (reason === "new") {
+        log.debug(
+          "restore-default-model abort",
+          `empty /new session; live selection appeared ` +
+            `${live.provider}/${live.id} (${phase} attempt ${attempt}/${retries})`,
+        );
+        return true;
+      }
       // Empty snapshot: first non-default live model is baseline, not abort.
       // Only abort when live later *changes* from that mid-flight selection.
       if (!firstSeenLive) {
@@ -568,7 +608,7 @@ export async function restoreDefaultModelOnSessionStart(opts: {
           "restore-default-model",
           `restored ${label} ` +
             `(was ${currentProvider ?? "none"}/${currentModelId ?? "none"}; ` +
-            `session_start reason=${opts.reason ?? "?"}; attempt ${attempt}/${retries})`,
+            `session_start reason=${reason || "?"}; attempt ${attempt}/${retries})`,
         );
         return true;
       }
@@ -590,7 +630,7 @@ export async function restoreDefaultModelOnSessionStart(opts: {
   log.warn(
     "restore-default-model exhausted",
     `${lastFailReason} after ${retries} attempts ` +
-      `(session_start reason=${opts.reason ?? "?"})`,
+      `(session_start reason=${reason || "?"})`,
   );
   return false;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.8.4",
+  "version": "4.8.5",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"

package/rules/20-code-review-loop.md

@@ -48,7 +48,7 @@ mentally or separately.
 
 The review loop repeats for at most `review_loop_max_cycles` cycles (default `3`, range `1`-`10` only;
 current value: `{{REVIEW_LOOP_MAX_CYCLES}}`), including the first cycle. Invalid values fall through to the
-next resolution layer / default `3` — see `dev-docs/project-settings.md` for the full resolution order.
+next resolution layer / default `3` — see `docs/project-settings.md` for the full resolution order.
 Disable the review loop via `review_loop_enforcement: false` — not via max_cycles.
 
 Cap check is after 5a; it only blocks `go to 2` (re-dispatch of step 2 / all 6 agents,

package/rules/25-documentation-updates.md

@@ -5,8 +5,8 @@ After ANY code is added, changed, or removed, check if documentation needs updat
 | Change | Check these files |
 |--------|-------------------|
 | New feature/command/tool | `README.md` (feature table, usage examples) |
-| New or modified extension module | `dev-docs/repo-structure.md` (repository structure) |
-| New agent added/removed | `dev-docs/repo-structure.md` (structure), `rules/10-agent-routing.md` (routing table), `rules/50-agent-bug-reporting.md` (agent list) |
+| New or modified extension module | `contributing/repo-structure.md` (repository structure) |
+| New agent added/removed | `contributing/repo-structure.md` (structure), `rules/10-agent-routing.md` (routing table), `rules/50-agent-bug-reporting.md` (agent list) |
 | New prompt template | `README.md` (prompt templates table) |
 | Docker/container changes | `README.md` (Docker section, shell alias, mounts), `Dockerfile` |
 | New CLI tool or dependency | `README.md` (tools table), `Dockerfile` |