@bigking67/pi-67 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## [0.10.6]
+
+- Adds runtime request retry to the canonical `xtalpi-pi-tools` provider path,
+  including attempt/retry/suppression telemetry in debug JSONL output.
+- Adds final-answer compliance repair to Bash and PowerShell xtalpi smoke:
+  validated tool runs that only miss required final text get one `--no-tools`
+  repair pass instead of rerunning tools.
+- Accepts `pi-67 doctor --no-skill-list` and raises doctor skill-list timeout
+  defaults to 60 seconds.
+- Supports command-level `pi-67 report --json`, emitting either a dry-run JSON
+  object or the generated report JSON.
+- Runs full `scripts/pi67-smoke.sh --ci` in the npm publish workflow before
+  pack/publish.
+
+## [0.10.5]
+
+- Uses `git fetch` plus `git merge --ff-only FETCH_HEAD` in Bash and
+  PowerShell updaters, allowing the updater to inspect incoming changed paths
+  before deciding whether dirty preserved runtime files need temporary cleanup.
+- Keeps dirty runtime config in place without creating a backup when the remote
+  is already current or incoming changed paths do not touch those files.
+- Reports `preserve-in-place-no-backup` from `pi-67 update --check` when a
+  dirty runtime marker is harmless and the remote already matches local HEAD.
+- Updates docs to separate current `~/.pi/pi67/backups/` runtime backups from
+  legacy read-only `~/.pi/agent-backups/` conflict snapshots.
+- Tightens release/smoke gates by checking README version drift, rejecting
+  simulated placeholder final answers, and requiring package metadata smoke
+  cases to include the real package version.
+- Adds `pi-67 xtalpi run` and a Windows PowerShell xtalpi launcher. The stable
+  launcher defaults `PI_OBSERVATIONAL_MEMORY_PASSIVE=true` to keep post-final
+  observational-memory background writes from holding the main task lifecycle
+  open.
+- Bounds `pi skill list` in doctor with POSIX
+  `--skill-list-timeout-seconds` and PowerShell `-SkillListTimeoutSeconds`.
+- Removes legacy `xtalpi-compat` runtime path examples from bootstrap docs.
+
 ## [0.10.4]
 
 - Makes all command-level `--help` paths side-effect free, including

package/README.md

@@ -52,6 +52,14 @@ For automation, `pi-67 update --check --json` includes explicit `actions`,
 `blocked`, and `warnings` arrays. Each action lists planned writes and preserved
 paths, so update previews stay auditable instead of relying on prose output.
 
+Long or slow doctor runs can skip Pi's live skill listing while still checking
+local metadata, config, provider/model, shared skill files, and endpoint
+contracts:
+
+```bash
+pi-67 doctor --no-skill-list
+```
+
 If the local manager may be stale, run the latest npm package for one repair:
 
 ```bash
@@ -77,13 +85,17 @@ Before a real `update` or `repair`, the npm manager builds the update plan,
 blocks unsafe non-runtime dirty worktrees, and acquires
 `~/.pi/pi67/locks/update.lock`. Runtime config backup/restore is delegated to
 the Bash or PowerShell updater script only when an in-place checkout needs to
-temporarily clear dirty preserved runtime files for `git pull --ff-only`. Those
-script-level snapshots live under `~/.pi/pi67/backups/pre-update-runtime-*`.
-This keeps `--help`, blocked update plans, and the public `npx -y
+temporarily clear dirty preserved runtime files. The updater fetches first,
+compares incoming `HEAD..FETCH_HEAD` changed paths, and creates a runtime
+snapshot only when the incoming update touches those dirty preserved files.
+Those script-level snapshots live under
+`~/.pi/pi67/backups/pre-update-runtime-*`.
+This keeps `--help`, blocked update plans, already-up-to-date updates,
+non-overlapping incoming updates, and the public `npx -y
 @bigking67/pi-67@latest update --repair` orchestration path free of duplicate
-manager-owned runtime backups. If an identical runtime snapshot already exists,
-the script-level updater reuses it instead of writing another timestamped
-directory.
+manager-owned runtime backups. If a backup is actually needed and an identical
+runtime snapshot already exists, the script-level updater reuses it instead of
+writing another timestamped directory.
 
 Runtime backups are first-class CLI state:
 
@@ -139,6 +151,7 @@ pi-67 doctor
 pi-67 smoke --quick
 pi-67 status
 pi-67 report
+pi-67 report --json
 pi-67 version
 pi-67 xtalpi health
 pi-67 xtalpi smoke --quick

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigking67/pi-67",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "description": "Cross-platform manager CLI for the pi-67 Pi Coding Agent distribution.",
   "type": "module",
   "bin": {

package/scripts/check.mjs

@@ -59,6 +59,14 @@ function runArgsSelfTests() {
     parseCommandOptions(["--help"], { bools: [] }).options.help,
     "command option parser must accept --help for every command",
   );
+  assert(
+    parseCommandOptions(["--no-skill-list"], { bools: ["no-skill-list"] }).options.noSkillList,
+    "command option parser must accept doctor --no-skill-list",
+  );
+  assert(
+    parseCommandOptions(["--json"], { bools: ["json"] }).options.json,
+    "command option parser must accept command-level --json",
+  );
 }
 
 function runCliHelpContractSelfTests() {
@@ -347,6 +355,18 @@ function runUpdatePlanSelfTests() {
     "dirty runtime config alone must not block the distro update plan",
   );
 
+  const dirtyRuntimeRemoteCurrent = decisionsFixture({
+    git: { dirty: true, short: " M settings.json", commit: "abcdef123456" },
+    remote: { ok: true, commit: "abcdef1234567890" },
+  });
+  const currentRemoteAction = buildPlanDecisions(dirtyRuntimeRemoteCurrent).actions.find((item) => item.id === "user-runtime-config");
+  assert(
+    currentRemoteAction?.operation === "preserve-in-place-no-backup" &&
+      currentRemoteAction.createsNewBackup === false &&
+      currentRemoteAction.writes.length === 0,
+    "dirty runtime config must not plan a new backup when the remote already matches local HEAD",
+  );
+
   const dirtyReadme = decisionsFixture({
     git: { dirty: true, short: " M README.md" },
   });

package/src/commands/doctor.mjs

@@ -4,8 +4,8 @@ import { isWindows } from "../lib/platform.mjs";
 
 export async function doctorCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
-    bools: ["json", "quiet", "dry-run", "deep-mcp", "strict-shared-skills"],
-    strings: ["mcp-timeout-ms"],
+    bools: ["json", "quiet", "dry-run", "deep-mcp", "no-skill-list", "strict-shared-skills"],
+    strings: ["mcp-timeout-ms", "skill-list-timeout-seconds"],
   });
   if (options.help) {
     printDoctorHelp();
@@ -19,6 +19,10 @@ export async function doctorCommand(ctx, argv) {
   if (options.strictSharedSkills) args.push(isWindows() ? "-StrictSharedSkills" : "--strict-shared-skills");
   if (!isWindows() && options.deepMcp) args.push("--deep-mcp");
   if (!isWindows() && options.mcpTimeoutMs) args.push("--mcp-timeout-ms", options.mcpTimeoutMs);
+  if (!isWindows() && options.noSkillList) args.push("--no-skill-list");
+  if (options.skillListTimeoutSeconds) {
+    args.push(isWindows() ? "-SkillListTimeoutSeconds" : "--skill-list-timeout-seconds", options.skillListTimeoutSeconds);
+  }
   runDistroScript(ctx, { sh: "pi67-doctor.sh", ps1: "pi67-doctor.ps1" }, args, {
     dryRun: ctx.dryRun || options.dryRun,
   });
@@ -35,6 +39,9 @@ Options:
   --quiet                 Reduce human output where supported.
   --deep-mcp              Run deeper MCP probes on POSIX platforms.
   --mcp-timeout-ms N      Timeout for deep MCP probes on POSIX platforms.
+  --no-skill-list         Skip pi skill list on POSIX platforms; accepted as a no-op on Windows.
+  --skill-list-timeout-seconds N
+                          Timeout for pi skill list where enabled.
   --strict-shared-skills  Treat differing shared skills as blocking.
   --dry-run               Print the script invocation without running it.
 

package/src/commands/report.mjs

@@ -1,10 +1,13 @@
+import fs from "node:fs";
+import path from "node:path";
 import { parseCommandOptions } from "../lib/args.mjs";
 import { runDistroScript } from "../lib/distro-scripts.mjs";
 import { isWindows } from "../lib/platform.mjs";
+import { printJson } from "../lib/output.mjs";
 
 export async function reportCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
-    bools: ["dry-run", "no-doctor"],
+    bools: ["json", "dry-run", "no-doctor"],
     strings: ["operation", "output"],
   });
   if (options.help) {
@@ -15,21 +18,39 @@ export async function reportCommand(ctx, argv) {
     ? ["-AgentDir", ctx.agentDir, "-RepoRoot", ctx.repoRoot, "-SkillsDir", ctx.skillsDir]
     : ["--agent-dir", ctx.agentDir, "--repo-root", ctx.repoRoot, "--skills-dir", ctx.skillsDir];
   if (options.operation) args.push(isWindows() ? "-Operation" : "--operation", options.operation);
-  if (options.output) args.push(isWindows() ? "-Output" : "--output", options.output);
+  const outputPath = options.output || path.join(ctx.agentDir, "pi67-report.json");
+  const resolvedOutputPath = path.isAbsolute(outputPath) ? outputPath : path.resolve(ctx.repoRoot, outputPath);
+  args.push(isWindows() ? "-Output" : "--output", outputPath);
   if (options.noDoctor) args.push(isWindows() ? "-NoDoctor" : "--no-doctor");
   if (ctx.dryRun || options.dryRun) args.push(isWindows() ? "-DryRun" : "--dry-run");
+  const json = ctx.json || options.json;
+  if (json && (ctx.dryRun || options.dryRun)) {
+    printJson({
+      schema: "pi67.report-command.v1",
+      dryRun: true,
+      output: resolvedOutputPath,
+      operation: options.operation || "manual",
+      doctor: options.noDoctor ? "skipped" : "enabled",
+    });
+    return;
+  }
   runDistroScript(ctx, { sh: "pi67-report.sh", ps1: "pi67-report.ps1" }, args, {
     dryRun: false,
+    stdio: json ? "pipe" : "inherit",
   });
+  if (json) {
+    process.stdout.write(fs.readFileSync(resolvedOutputPath, "utf8"));
+  }
 }
 
 function printReportHelp() {
   process.stdout.write(`pi-67 report - generate pi67-report.json
 
 Usage:
-  pi-67 report [--operation NAME] [--output FILE] [--no-doctor] [--dry-run]
+  pi-67 report [--json] [--operation NAME] [--output FILE] [--no-doctor] [--dry-run]
 
 Options:
+  --json           Emit the generated report JSON to stdout.
   --operation NAME  Operation label to embed in the report.
   --output FILE     Output path. Defaults to the distro report location.
   --no-doctor       Skip doctor data collection where supported.

package/src/commands/update.mjs

@@ -135,7 +135,9 @@ function printPlan(plan) {
   if (plan.actions?.length > 0) {
     section("Planned safe actions");
     for (const action of plan.actions) {
-      info(`${action.id}: ${action.operation}; writes=${action.writes.join(", ")}; preserves=${action.preserves.join(", ")}`);
+      const writes = action.writes?.length ? action.writes.join(", ") : "none";
+      const suffix = action.backupCondition ? `; backup=${action.backupCondition}` : "";
+      info(`${action.id}: ${action.operation}; writes=${writes}; preserves=${action.preserves.join(", ")}${suffix}`);
     }
   }
   if (plan.blocked?.length > 0) {
@@ -174,8 +176,9 @@ Options:
 
 Safety:
   Runtime config backup/restore is owned by the platform updater script when
-  preserved runtime files are dirty. The npm manager owns the update lock and
-  never creates a runtime backup for --help or a blocked update plan.
+  dirty preserved runtime files overlap incoming changed paths. The npm manager
+  owns the update lock and never creates a runtime backup for --help, a blocked
+  update plan, or an already-up-to-date update.
 
 Examples:
   pi-67 update --check

package/src/commands/xtalpi.mjs

@@ -16,6 +16,7 @@ export async function xtalpiCommand(ctx, argv) {
   if (sub === "trend") return trend(ctx, rest);
   if (sub === "drift") return drift(ctx, rest);
   if (sub === "stress") return stress(ctx, rest);
+  if (sub === "run") return run(ctx, rest);
   throw new CliError(`unknown xtalpi command: ${sub}`, 2);
 }
 
@@ -110,6 +111,47 @@ function stress(ctx, argv) {
   return smoke(ctx, ["--profile", options.profile || "full-suite", ...(options.dryRun ? ["--dry-run"] : [])]);
 }
 
+function run(ctx, argv) {
+  const passthroughIndex = argv.indexOf("--");
+  const optionArgv = passthroughIndex === -1 ? argv : argv.slice(0, passthroughIndex);
+  const passthrough = passthroughIndex === -1 ? [] : argv.slice(passthroughIndex + 1);
+  const { options, positionals } = parseCommandOptions(optionArgv, {
+    strings: ["model", "provider"],
+    bools: ["dry-run", "no-passive-observational-memory"],
+  });
+  if (options.help) return printXtalpiHelp();
+  const provider = options.provider || "xtalpi-pi-tools";
+  const model = options.model || "deepseek-v4-pro";
+  const piArgs = [...positionals, ...passthrough];
+  const env = {};
+  if (options.noPassiveObservationalMemory) {
+    env.PI_OBSERVATIONAL_MEMORY_PASSIVE = "false";
+  }
+  if (isWindows()) {
+    const pwsh = findPowerShell();
+    if (!pwsh) throw new CliError("PowerShell executable not found");
+    const args = [
+      "-NoProfile",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-File",
+      scriptPath(ctx, "pi67-xtalpi-pi-tools.ps1"),
+      "-Provider",
+      provider,
+      "-Model",
+      model,
+      ...piArgs,
+    ];
+    runCommand(pwsh, args, { cwd: ctx.repoRoot, dryRun: ctx.dryRun || options.dryRun, env });
+    return;
+  }
+  runCommand("bash", [scriptPath(ctx, "pi67-xtalpi-pi-tools.sh"), ...piArgs], {
+    cwd: ctx.repoRoot,
+    dryRun: ctx.dryRun || options.dryRun,
+    env: { PROVIDER: provider, MODEL: model, ...env },
+  });
+}
+
 function profileFromOptions(options) {
   if (options.profile) return options.profile;
   if (options.extensionLowRisk) return "extension-low-risk";
@@ -129,11 +171,16 @@ Usage:
   pi-67 xtalpi trend [--limit N] [--profile NAME] [--json] [--out-dir DIR]
   pi-67 xtalpi drift [--limit N] [--run-kind LIST] [--json] [--out-dir DIR]
   pi-67 xtalpi stress --until-done
+  pi-67 xtalpi run [--provider ID] [--model NAME] [--no-passive-observational-memory] [-- <pi args>]
 
 Notes:
   xtalpi-pi-tools treats xtalpi as plain chat-completions transport. Pi local
   code owns tool protocol parsing, validation, repair, retry classification,
   tool execution, and smoke gates.
+  xtalpi run uses the stable launcher and defaults
+  PI_OBSERVATIONAL_MEMORY_PASSIVE=true so post-final background memory writes
+  cannot hold the main task lifecycle open. Pass --no-passive-observational-memory
+  only when you explicitly want pi-observational-memory to record after final.
   xtalpi drift defaults to --run-kind full-suite so targeted one-off smoke
   artifacts do not create expected case-set drift noise.
 
@@ -144,5 +191,6 @@ Examples:
   pi-67 xtalpi trend --json
   pi-67 xtalpi drift --json
   pi-67 xtalpi stress --until-done
+  pi-67 xtalpi run
 `);
 }

package/src/lib/distro-scripts.mjs

@@ -17,11 +17,15 @@ export function runDistroScript(ctx, names, args = [], options = {}) {
       cwd: ctx.repoRoot,
       dryRun: options.dryRun,
       env: options.env,
+      stdio: options.stdio,
+      timeoutMs: options.timeoutMs,
     });
   }
   return runCommand("bash", [file, ...args], {
     cwd: ctx.repoRoot,
     dryRun: options.dryRun,
     env: options.env,
+    stdio: options.stdio,
+    timeoutMs: options.timeoutMs,
   });
 }

package/src/lib/update-plan.mjs

@@ -75,6 +75,7 @@ export async function buildUpdatePlan(ctx, options = {}) {
     git,
     benignRuntime,
     managerRegistry,
+    remote,
     manifest,
     skills,
     external,
@@ -167,23 +168,35 @@ export function buildPlanDecisions(context) {
       recovery: "commit/stash intentional changes or rerun the script-level updater with an explicit dirty override",
     });
   } else if (context.git.dirty && dirty.preservedRuntime.length > 0) {
+    const remoteStatus = classifyIncomingRemoteStatus(context.git, context.remote);
+    const preserveInPlace = remoteStatus.upToDate;
     actions.push({
       id: "user-runtime-config",
       kind: "runtime-config",
-      operation: "backup-and-restore-during-update",
-      writes: ["~/.pi/pi67/backups/pre-update-runtime-*"],
+      operation: preserveInPlace
+        ? "preserve-in-place-no-backup"
+        : "conditional-backup-if-incoming-update-touches-runtime-config",
+      writes: preserveInPlace
+        ? []
+        : ["~/.pi/pi67/backups/pre-update-runtime-* only if incoming update touches preserved runtime files"],
       preserves: dirty.preservedRuntime,
       risk: "low",
-      reason: benignRuntime.benign
-        ? `benign runtime marker only: ${benignRuntime.reasons.join("; ")}`
-        : "only user-owned runtime config files are dirty; update snapshots and restores them instead of overwriting",
+      reason: runtimeConfigActionReason({ benignRuntime, preserveInPlace, remoteStatus }),
       benign: benignRuntime.benign,
       benignReasons: benignRuntime.reasons,
+      createsNewBackup: !preserveInPlace,
+      backupCondition: preserveInPlace
+        ? "none: remote already matches the local checkout"
+        : "only when fetched incoming changes overlap preserved runtime files",
     });
     warnings.push(
-      benignRuntime.benign
-        ? `benign user runtime marker will be preserved across update: ${dirty.preservedRuntime.join(", ")}`
-        : `dirty user runtime config will be preserved across update: ${dirty.preservedRuntime.join(", ")}`,
+      preserveInPlace
+        ? `dirty user runtime config will stay in place; current remote is already at the local commit: ${dirty.preservedRuntime.join(", ")}`
+        : (
+          benignRuntime.benign
+            ? `benign user runtime marker will be preserved; backup is conditional on incoming path overlap: ${dirty.preservedRuntime.join(", ")}`
+            : `dirty user runtime config will be preserved; backup is conditional on incoming path overlap: ${dirty.preservedRuntime.join(", ")}`
+        ),
     );
   }
   if (context.git?.dirty && dirty.untracked.length > 0) {
@@ -289,6 +302,30 @@ export function buildPlanDecisions(context) {
   return { actions, blocked, warnings };
 }
 
+function classifyIncomingRemoteStatus(git, remote) {
+  if (remote?.skipped) return { upToDate: false, known: false, reason: "remote check skipped" };
+  if (!remote?.commit || !git?.commit) return { upToDate: false, known: false, reason: remote?.message || "remote commit unknown" };
+  const local = String(git.commit);
+  const remoteCommit = String(remote.commit);
+  return {
+    upToDate: remoteCommit.startsWith(local),
+    known: true,
+    reason: remoteCommit.startsWith(local)
+      ? "remote already matches local commit"
+      : "remote differs from local commit; updater will inspect changed paths after fetch",
+  };
+}
+
+function runtimeConfigActionReason({ benignRuntime, preserveInPlace, remoteStatus }) {
+  const prefix = benignRuntime.benign
+    ? `benign runtime marker only: ${benignRuntime.reasons.join("; ")}`
+    : "only user-owned runtime config files are dirty";
+  if (preserveInPlace) {
+    return `${prefix}; ${remoteStatus.reason}; no runtime backup is needed`;
+  }
+  return `${prefix}; updater fetches first and creates a runtime backup only if incoming changes touch these preserved files`;
+}
+
 export function classifyGitShort(short) {
   const preserved = new Set(PRESERVED_RUNTIME_FILES);
   const result = {