@bigking67/pi-67 0.10.4 → 0.10.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [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

@@ -77,13 +77,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:
 

package/package.json

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

package/scripts/check.mjs

@@ -347,6 +347,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

@@ -5,7 +5,7 @@ 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"],
+    strings: ["mcp-timeout-ms", "skill-list-timeout-seconds"],
   });
   if (options.help) {
     printDoctorHelp();
@@ -19,6 +19,9 @@ 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 (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 +38,8 @@ 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.
+  --skill-list-timeout-seconds N
+                          Timeout for pi skill list on POSIX platforms.
   --strict-shared-skills  Treat differing shared skills as blocking.
   --dry-run               Print the script invocation without running it.
 

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/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 = {