pi-orchestrator-config 4.8.4 → 4.9.0

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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
@@ -75,6 +75,7 @@ for `git-expert` to commit.
 | `/refine-review <url>`                                                                          | Refine and improve existing PR review comments                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `/coderabbit-rate-limit [number\|url]`                                                          | Handle CodeRabbit rate limiting on PRs                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `/create-coms-feature-manager`                                                                  | Generate a coms feature-manager prompt customized for the current project (source template: `templates/coms-feature-manager-prompt.md`)                                                                                                                                                                                                                                                                                                                    |
+| `/create-commit <message>`                                                                      | Commit and push the current change set via git-expert (source template: `templates/commit-prompt.md` — stage exact files, commit, push, report sha)                                                                                                                                                                                                                                                                                                       |
 | `/query-db <command>`                                                                           | Query the review comments database                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `/external-ai <agent> [--model <model>] [--session-id <id>] [--fix\|--peer\|--resume] <prompt>` | Run prompts via AI CLIs directly (cursor, claude, gemini) — full model access                                                                                                                                                                                                                                                                                                                                                                              |
 | `/external-ai-models-refresh`                                                                   | Refresh cached AI CLI models for autocomplete                                                                                                                                                                                                                                                                                                                                                                                                              |
@@ -305,7 +306,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 +369,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 +484,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 +501,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
 
@@ -767,12 +768,30 @@ PI_PIDIFF_ENABLE=false pi
 | `myk-pi-tools pr claude-md`            | Fetch `CLAUDE.md` and `AGENTS.md` content for a PR's repository                                                                                |
 | `myk-pi-tools release create`          | Create a GitHub release with changelog                                                                                                         |
 | `myk-pi-tools db`                      | Review database query commands                                                                                                                 |
-| `myk-pi-tools reviews`                 | Review handling commands                                                                                                                       |
+| `myk-pi-tools reviews`                 | Review handling commands (fetch, poll, address, post, store)                                                                                   |
+| `myk-pi-tools reviews address`         | Apply replies/statuses to a fetched reviews JSON, then post and store it (see below)                                                           |
 | `myk-pi-tools memory`                  | Project memory commands — persistent per-repo learning                                                                                         |
 | `myk-pi-tools ai-cli`                  | AI CLI commands (cursor, claude, gemini)                                                                                                       |
 | `myk-pi-tools coderabbit`              | CodeRabbit commands (check, trigger, retry)                                                                                                    |
 | `myk-pi-tools settings get [key ...]`  | Resolve settings (project → global → env → default). No args = all keys                                                                        |
 
+`reviews address` — bulk-apply replies to a fetched reviews JSON, then post and store it:
+
+```bash
+myk-pi-tools reviews address [--json <reviews.json>] [--replies <mapping.txt>] [--set <status>]
+```
+
+- `--json`: reviews JSON to process (default: newest `pr-*-reviews.json` in `.pi/tmp`)
+- `--replies`: mapping file, one rule per line — `<path>:<line>|<reply>` or `*|<reply>` (matches all pending findings);
+  `#` comments and blank lines ignored
+- `--set`: target status for matched findings — `addressed` (default), `skipped`, `not_addressed`, or `failed`
+- Without `--replies`, pending findings that already carry a reply only get their status flipped (status-only mode)
+- Exit code `0` = replies posted and stored; non-zero = nothing matched, validation failed, or posting failed
+  (the JSON is kept for retry — re-running with the same or a corrected mapping resumes unposted entries)
+- Validation failures change nothing: a rule matching several distinct findings at one location, or a status `post`
+  rejects for Qodo sticky findings (`not_addressed`/`failed`; `skipped` only with an issue-spec-update reply),
+  exits non-zero before the JSON is saved
+
 ### What's protected
 
 **Filesystem isolation** — the container cannot access anything outside the mounted volumes:
@@ -917,6 +936,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/agents/git-expert.md

@@ -135,7 +135,7 @@ Format rules:
 **Commit changes:**
 
 1. `git status` to see changes
-2. `git add <specific files>` for each file (NEVER `git add .`)
+2. `git add -- <specific files>` for each file (NEVER `git add .`; the `--` terminator prevents paths being read as options)
 3. Commit with proper format
 4. Report the result
 

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

@@ -1,7 +1,7 @@
 {
   "name": "pidiff-ui",
   "private": true,
-  "version": "4.8.4",
+  "version": "4.9.0",
   "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.9.0",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"

package/prompts/create-commit.md

@@ -0,0 +1,58 @@
+---
+description: "Commit and push the current change set via git-expert — /create-commit <message>"
+argument-hint: "<message>"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+# Create Commit Prompt
+
+Generates the git-expert commit delegation from the template instead of composing
+the instruction prose. Only the file list and message vary per commit.
+
+## Workflow
+
+### Step 1: Read the Template
+
+Read the template file:
+
+```text
+~/.pi/agent/npm/node_modules/pi-orchestrator-config/templates/commit-prompt.md
+```
+
+Developer checkout fallback: `templates/commit-prompt.md` in the pi-config repo.
+This is the immutable source template. NEVER modify it.
+
+### Step 2: Fill Placeholders
+
+| Placeholder | Value |
+|-------------|-------|
+| `{{FILES}}` | Every file to commit, one hyphen bullet per file, exact paths — parse `git status --porcelain=v1 -z` per the rules below |
+| `{{MESSAGE}}` | Commit subject — the FIRST LINE of the raw arguments, nothing more. If empty, draft a conventional `type(scope): description` subject from the change set and confirm with the user |
+| `{{BODY}}` | The remainder of the raw arguments after the first line, if any — never duplicates `{{MESSAGE}}` content. Empty by default |
+
+**Parsing `git status --porcelain=v1 -z`** (NUL-delimited; avoids quote ambiguity):
+
+- Rename (`R`) and copy (`C`) records: list only the NEW/destination path
+- C-escaped quoted paths: decode to the real path; deleted paths: keep as-is
+- Paths containing newlines or control characters: render them in `printf '%q'` shell-escaped form so the bullet keeps one line — git-expert decodes before staging
+
+If `git status` shows files that clearly should not be committed (generated
+artifacts, `.env`, secrets), exclude them from `{{FILES}}` and say so.
+
+Never leave a `{{...}}` token in the output. If the commit text contains a run of
+four or more backticks, lengthen the template's code fences to exceed it
+(fences must always out-length any backtick run inside).
+
+### Step 3: Delegate
+
+Delegate the filled template to `git-expert` **verbatim** — no extra prose,
+no re-wording, no added instructions.
+
+### Step 4: Report
+
+Report git-expert's result: commit sha, branch, push outcome.

package/prompts/review-handler.md

@@ -371,11 +371,27 @@ No "this looks similar to the one I already fixed."**
 
 If any approved tasks weren't implemented, review with user.
 
-### Phase 5: Persist Decisions
+### Phase 5: Prepare Reply Mappings
 
-Update each JSON entry with `status` and `reply` fields before posting.
+🚨 **NEVER hand-edit the reviews JSON.** No python heredocs, no `jq`, no manual
+`status`/`reply` field mutation. The `myk-pi-tools reviews address` command applies
+replies, flips statuses, posts, and stores in one step — you only prepare mapping files.
 
-**Valid status values:**
+Write one mapping file per target status. Each line targets one finding:
+
+```text
+<path>:<line>|<reply>
+```
+
+- `<path>:<line>` — the finding's fetched `path` and `line`. A thread finding and its
+  paired sticky finding are addressed together automatically (the command handles
+  dedupe and pairing — you never target stickies separately).
+- `*` — matches ALL pending findings (single-line mapping file).
+- Group findings by their target status — Phase 8 runs one `reviews address` call per
+  status group.
+- Posting happens in Phase 8, AFTER commit/push — do not post before the fixes are pushed.
+
+**Valid status values (the `--set` flag for each mapping group):**
 
 | Status | Behavior |
 |--------|----------|
@@ -438,44 +454,52 @@ Skip asking the user — commit and push automatically.
 Code must be pushed before posting replies so that reviewers can see the fixes
 when threads are resolved.
 
-### Phase 8: Post Replies
+### Phase 8: Post Replies (via reviews address)
 
-Post all replies to GitHub and store results in the database.
-
-**Body comments (outside-diff, major, minor, nitpick, duplicate, qodo sticky):**
-
-Comments that don't have GitHub review threads (e.g., CodeRabbit outside-diff,
-major, minor, nitpick, and duplicate comments) are replied to via a single
-consolidated PR comment per reviewer. The comment mentions the reviewer (e.g., `@coderabbitai`)
-and includes sections for each comment with the decision made. This ensures
-automated reviewers know their comments were reviewed and won't re-raise them.
-
-Post replies to GitHub:
+Run one `reviews address` call per status group prepared in Phase 5 — each call applies
+the mapping, posts replies, resolves threads, and stores to the database:
 
 ```bash
-myk-pi-tools reviews post {json_path}
+myk-pi-tools reviews address --json {json_path} --replies {mapping_file} --set addressed
+myk-pi-tools reviews address --json {json_path} --replies {mapping_file} --set skipped
 ```
 
-If the command exits with a non-zero code, some threads failed to post.
-The command prints an ACTION REQUIRED message with the exact retry command.
-Re-run it to retry — only unposted entries are retried. Repeat until all succeed.
-
-**Output verification (MANDATORY):**
-
-After `reviews post` completes successfully, check the output:
+The command picks the newest `pr-*-reviews.json` in `.pi/tmp` when `--json` is omitted.
 
-- `Processed N threads` — N should equal the number of entries with status `addressed`, `not_addressed`, `skipped`, or `failed` (everything except `pending`)
-- `Resolved: N` — should be non-zero if any entries have status `addressed` or if AI-source entries have status `skipped`/`not_addressed`
-- If `Processed 0 threads`, the status values in the JSON are wrong — fix them to use valid values from the table above and re-run before proceeding
-- If output shows `Warning: Unknown status`, fix those entries — e.g., `"done"` or `"completed"` are not valid, use `"addressed"` instead
+**Multi-group retention:** while any findings remain pending (unposted, not
+auto-skipped), a successful run posts its group but does NOT store — the JSON is
+kept on disk for the remaining status-group runs. The final run (nothing pending)
+stores to the database and consumes the JSON. Run the groups in any order.
 
-Do NOT proceed to `reviews store` until `reviews post` shows the expected thread count.
-
-Store to database:
+**Body comments (outside-diff, major, minor, nitpick, duplicate, qodo sticky):**
 
-```bash
-myk-pi-tools reviews store {json_path}
-```
+Comments that don't have GitHub review threads (e.g., CodeRabbit outside-diff,
+major, minor, nitpick, and duplicate comments) are replied to via a single
+consolidated PR comment per reviewer — `reviews address` handles this exactly like
+`reviews post` did: the comment mentions the reviewer (e.g., `@coderabbitai`) and
+includes sections for each comment with the decision made. This ensures automated
+reviewers know their comments were reviewed and won't re-raise them.
+
+**Failure semantics (MANDATORY):**
+
+- **Exit 0** → all matched findings posted. Threads are resolved per the
+  Phase 5 status table — `addressed` (and AI-source `skipped`/`not_addressed`) threads
+  are resolved; **human `skipped`/`not_addressed` threads intentionally stay open** for
+  follow-up. Exit 0 never means every thread is resolved.
+  Storage happens only on the FINAL group: while pending findings remain the run posts
+  without storing (results live in the retained JSON until the last group's run stores
+  and consumes it).
+- **Non-zero exit** → the JSON is RETAINED on disk for a corrected re-run.
+  Read the printed error:
+  - `no findings matched` → a mapping `path:line` matches no pending finding — fix the
+    mapping file and re-run. Already-posted entries are never touched again, so re-runs
+    are always safe.
+  - Post/resolve failures → the output names the entries that failed; re-run the same
+    command. Re-runs retry BOTH unposted entries AND posted-but-unresolved threads
+    (entries with `posted_at` but no resolution are resumed automatically — a failed
+    resolve retries the already-posted thread).
+- **NEVER delete or hand-edit a retained JSON** — correct the mapping file and re-run
+  `reviews address`.
 
 ### Phase 9: Auto Polling Loop (--autorabbit / --autoqodo mode)
 

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` |

package/templates/commit-prompt.md

@@ -0,0 +1,38 @@
+# Commit Delegation — Template
+
+> **Usage:** The orchestrator fills every `{{PLACEHOLDER}}` and delegates the
+> filled text to git-expert. Delete this usage block when done.
+
+---
+
+Commit and push the current change set.
+
+**Files to stage — EXACTLY these, never `git add .` or `git add -A`:**
+
+{{FILES}}
+
+**Commit message** (subject only — never body content):
+
+````text
+{{MESSAGE}}
+````
+
+**Commit body** (omit entirely if empty):
+
+````text
+{{BODY}}
+````
+
+**Steps:**
+
+1. Stage each file listed above individually — always `git add -- <file>`
+   (the `--` terminator is mandatory; never let a path be read as an option),
+   one command naming every file is fine. Quote paths containing spaces or
+   special characters; if a path contains glob characters or pathspec magic
+   (`*`, `?`, `:` …), stage it as `git add -- ':(literal)<file>'` so it is
+   treated as an exact path, never a pattern. If a path was rendered in
+   shell-escaped form (`printf '%q'`), decode it before staging.
+2. Commit with the message (and body if present) above — use a HEREDOC for multi-line.
+   The message and body must never duplicate each other.
+3. Push the current branch to origin (set upstream with `-u` if the branch has none).
+4. Report: commit sha, branch, push result.