@bigking67/pi-67 0.10.6 → 0.10.8

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.10.8]
+
+- Adds actionable `pi-67 version` recommendations when the npm manager has
+  been updated but the local distro checkout is still old or `settings.json`
+  still has runtime-marker dirty state.
+
+## [0.10.7]
+
+- Migrates `settings.json.lastChangelogVersion` into ignored manager state at
+  `~/.pi/pi67/state.json`, normalizes the runtime-only marker out of
+  `settings.json`, and installs a local Git clean filter so future marker
+  writes cannot be carried into normal diffs or commits.
+- Renames shared-skill drift in human-facing output from "conflicts" to
+  "preserved user-modified" while keeping the JSON `conflicts` compatibility
+  field.
+
 ## [0.10.6]
 
 - Adds runtime request retry to the canonical `xtalpi-pi-tools` provider path,

package/README.md

@@ -129,8 +129,9 @@ The explicit theme setter also writes a runtime backup before changing
 `settings.json`; normal update never changes the selected theme.
 
 The manager writes lightweight state outside the repo at `~/.pi/pi67/state.json`.
-It records versions, paths, theme, provider/model, and commit information; it
-does not store API keys.
+It records versions, paths, theme, provider/model, commit information, and
+runtime-only UI markers such as `settings.json.lastChangelogVersion` after
+migrating them out of tracked config; it does not store API keys.
 
 ## Main commands
 

package/package.json

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

package/schemas/pi67-state.schema.json

@@ -25,6 +25,32 @@
     },
     "lastTheme": {
       "type": "string"
+    },
+    "runtimeMarkers": {
+      "type": "object",
+      "description": "Runtime-only UI markers migrated out of tracked runtime config files.",
+      "properties": {
+        "lastChangelogVersion": {
+          "type": "object",
+          "required": ["value", "storage"],
+          "properties": {
+            "value": {
+              "type": "string"
+            },
+            "source": {
+              "type": "string"
+            },
+            "storage": {
+              "type": "string"
+            },
+            "updatedAt": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
     }
   },
   "additionalProperties": true

package/scripts/check.mjs

@@ -8,6 +8,11 @@ import { commandCandidatesForPlatform } from "../src/lib/shell-runner.mjs";
 import { parseCommandOptions, splitGlobalArgs } from "../src/lib/args.mjs";
 import { readExtensionRegistry, validateExtensionRegistry } from "../src/lib/extension-registry.mjs";
 import { buildPlanDecisions, classifyGitShort } from "../src/lib/update-plan.mjs";
+import {
+  mergeSettingsRuntimeMarkerIntoState,
+  settingsRuntimeMarkerFromObject,
+  stripSettingsRuntimeMarkerText,
+} from "../src/lib/settings-runtime-state.mjs";
 import {
   beginUpdateLifecycle,
   inspectLegacyConflictBackup,
@@ -32,9 +37,11 @@ for (const file of files.filter((item) => item.endsWith(".json"))) {
 await runNpmRegistrySelfTests();
 runArgsSelfTests();
 runCliHelpContractSelfTests();
+runVersionRecommendationSelfTests();
 runPublishTargetSelfTests();
 runShellRunnerSelfTests();
 runExtensionRegistrySelfTests();
+runSettingsRuntimeStateSelfTests();
 runUpdatePlanSelfTests();
 runUpdateSafetySelfTests();
 
@@ -116,6 +123,68 @@ function runCliHelpContractSelfTests() {
   fs.rmSync(tmpRoot, { recursive: true, force: true });
 }
 
+function runVersionRecommendationSelfTests() {
+  if (spawnSync("git", ["--version"], { encoding: "utf8" }).status !== 0) return;
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi67-version-recommendation-"));
+  const home = path.join(tmpRoot, "home");
+  const repo = path.join(tmpRoot, "agent");
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(repo, { recursive: true });
+  fs.writeFileSync(path.join(repo, "VERSION"), "0.10.0\n");
+  fs.writeFileSync(path.join(repo, "settings.json"), "{\n  \"lastChangelogVersion\": \"0.80.3\",\n  \"theme\": \"gruvbox-dark\"\n}\n");
+  for (const args of [
+    ["-C", repo, "init", "-q"],
+    ["-C", repo, "config", "user.email", "pi67-check@example.invalid"],
+    ["-C", repo, "config", "user.name", "pi67-check"],
+    ["-C", repo, "add", "VERSION", "settings.json"],
+    ["-C", repo, "commit", "-q", "-m", "init"],
+  ]) {
+    const result = spawnSync("git", args, { encoding: "utf8" });
+    assert(result.status === 0, `git setup failed for version recommendation self-test: git ${args.join(" ")}\n${result.stderr}`);
+  }
+  fs.writeFileSync(path.join(repo, "settings.json"), "{\n  \"lastChangelogVersion\": \"0.80.4\",\n  \"theme\": \"gruvbox-dark\"\n}\n");
+  const env = { ...process.env, HOME: home, USERPROFILE: home };
+  const result = spawnSync(process.execPath, [
+    path.join(root, "bin", "pi-67.mjs"),
+    "--agent-dir",
+    repo,
+    "--repo-root",
+    repo,
+    "version",
+  ], {
+    cwd: root,
+    env,
+    encoding: "utf8",
+  });
+  assert(result.status === 0, `version recommendation command failed\n${result.stderr || result.stdout}`);
+  assert(
+    result.stdout.includes("npm install updated only the manager package") &&
+      result.stdout.includes("update --repair") &&
+      result.stdout.includes("settings.json has Pi runtime changelog marker state"),
+    `version output must explain manager/distro mismatch and runtime marker repair\n${result.stdout}`,
+  );
+  const json = spawnSync(process.execPath, [
+    path.join(root, "bin", "pi-67.mjs"),
+    "--agent-dir",
+    repo,
+    "--repo-root",
+    repo,
+    "version",
+    "--json",
+  ], {
+    cwd: root,
+    env,
+    encoding: "utf8",
+  });
+  assert(json.status === 0, `version --json recommendation command failed\n${json.stderr || json.stdout}`);
+  const parsed = JSON.parse(json.stdout);
+  assert(
+    parsed.recommendations?.some((item) => item.message.includes("update --repair")),
+    "version --json must include actionable recommendations",
+  );
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+}
+
 function runPublishTargetSelfTests() {
   const unpublished = {
     skipped: false,
@@ -322,6 +391,22 @@ function runExtensionRegistrySelfTests() {
   );
 }
 
+function runSettingsRuntimeStateSelfTests() {
+  const input = "{\n  \"lastChangelogVersion\": \"0.80.3\",\n  \"theme\": \"gruvbox-dark\"\n}\n";
+  const stripped = JSON.parse(stripSettingsRuntimeMarkerText(input));
+  assert(
+    stripped.lastChangelogVersion === undefined && stripped.theme === "gruvbox-dark",
+    "settings runtime clean filter must remove only lastChangelogVersion",
+  );
+  const marker = settingsRuntimeMarkerFromObject({ lastChangelogVersion: "0.80.3" });
+  const state = mergeSettingsRuntimeMarkerIntoState({ schema: "pi67.state.v1" }, marker, "2026-07-08T00:00:00.000Z");
+  assert(
+    state.runtimeMarkers?.lastChangelogVersion?.value === "0.80.3" &&
+      state.runtimeMarkers.lastChangelogVersion.storage === "state.json",
+    "settings runtime marker must migrate into state runtimeMarkers",
+  );
+}
+
 function runUpdatePlanSelfTests() {
   assert(
     classifyGitShort(" M settings.json\n?? tmp.txt").preservedRuntime.includes("settings.json"),
@@ -396,8 +481,8 @@ function runUpdatePlanSelfTests() {
     skills: { summary: { missing: 0, conflicts: 2 } },
   });
   assert(
-    buildPlanDecisions(sharedSkillConflict).warnings.some((item) => item.includes("preserves existing different skills")),
-    "shared skill conflicts must warn and preserve by default",
+    buildPlanDecisions(sharedSkillConflict).warnings.some((item) => item.includes("preserved user-modified global skills")),
+    "preserved user-modified shared skills must warn and preserve by default",
   );
   const strictSharedSkillConflict = decisionsFixture({
     strictSharedSkills: true,

package/src/commands/doctor.mjs

@@ -42,7 +42,7 @@ Options:
   --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.
+  --strict-shared-skills  Treat preserved user-modified shared skills as blocking.
   --dry-run               Print the script invocation without running it.
 
 Examples:

package/src/commands/install.mjs

@@ -7,6 +7,7 @@ import { runDistroScript } from "../lib/distro-scripts.mjs";
 import { isWindows } from "../lib/platform.mjs";
 import { CliError, info, warn } from "../lib/output.mjs";
 import { writeState } from "../lib/state-store.mjs";
+import { migrateSettingsRuntimeState } from "../lib/settings-runtime-state.mjs";
 
 export async function installCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
@@ -47,7 +48,25 @@ export async function installCommand(ctx, argv) {
     if (dryRun) args.push("--dry-run");
     runCommand("bash", [path.join(ctx.repoRoot, "install.sh"), ...args], { cwd: ctx.repoRoot, dryRun: false });
   }
-  if (!dryRun) writeState(ctx, "install");
+  if (!dryRun) {
+    writeState(ctx, "install");
+    const runtimeState = migrateSettingsRuntimeState(ctx, {
+      normalizeSettingsJson: true,
+      installGitFilter: true,
+    });
+    if (runtimeState.markerFound && runtimeState.stateWritten) {
+      info("Migrated settings.json lastChangelogVersion to ignored state: ~/.pi/pi67/state.json");
+    }
+    if (runtimeState.settingsNormalized) {
+      info("Normalized settings.json by removing runtime-only lastChangelogVersion.");
+    }
+    if (runtimeState.gitFilterInstalled) {
+      info("Installed local git clean filter for future settings.json runtime markers.");
+    }
+    for (const error of runtimeState.errors) {
+      warn(`settings runtime marker migration skipped: ${error}`);
+    }
+  }
   info("Install finished. Run `pi-67 doctor` next.");
 }
 

package/src/commands/skills.mjs

@@ -26,9 +26,9 @@ function inventory(ctx, argv) {
   keyValue("Target", data.skillsDir);
   keyValue("Identical", data.summary.identical);
   keyValue("Missing", data.summary.missing);
-  keyValue("Conflicts", data.summary.conflicts);
+  keyValue("Preserved user-modified", preservedUserModified(data.summary));
   for (const entry of data.entries.filter((item) => !item.identical)) {
-    const status = entry.conflict ? "conflict" : "missing";
+    const status = entry.conflict ? "preserved user-modified" : "missing";
     info(`${status}: ${entry.name}`);
   }
 }
@@ -43,7 +43,7 @@ function plan(ctx, argv) {
   keyValue("Target", data.skillsDir);
   keyValue("Selected", data.selected.length === 0 ? "all changed skills" : data.selected.join(", "));
   keyValue("Missing", data.actions.filter((item) => item.action === "copy-missing").length);
-  keyValue("Conflicts", data.actions.filter((item) => item.action === "preserve-conflict").length);
+  keyValue("Preserved user-modified", data.actions.filter((item) => item.action === "preserve-conflict").length);
   for (const action of data.actions) {
     const command = action.conflict
       ? `inspect: pi-67 skills diff ${action.name}; explicit sync: pi-67 skills sync ${action.name} --dry-run`
@@ -100,7 +100,11 @@ function migrate(ctx, argv) {
   section("pi-67 skills migrate preview");
   warn("migrate is intentionally dry-run in the npm manager; use `pi-67 skills sync` to copy missing skills.");
   keyValue("Missing", data.summary.missing);
-  keyValue("Conflicts", data.summary.conflicts);
+  keyValue("Preserved user-modified", preservedUserModified(data.summary));
+}
+
+function preservedUserModified(summary) {
+  return summary?.preservedUserModified ?? summary?.conflicts ?? 0;
 }
 
 function printSkillsHelp() {
@@ -115,8 +119,9 @@ Usage:
 
 Safety:
   Missing skills are copied by default. Existing different global skills are
-  preserved unless you name the skill explicitly and pass --yes. Bulk conflict
-  overwrite is intentionally blocked.
+  preserved as user-modified unless you name the skill explicitly and pass
+  --yes. Bulk overwrite of preserved user-modified skills is intentionally
+  blocked.
 
 Examples:
   pi-67 skills inventory

package/src/commands/status.mjs

@@ -21,7 +21,11 @@ export async function statusCommand(ctx, argv) {
   keyValue("Provider", plan.settings.defaultProvider || "unset");
   keyValue("Model", plan.settings.defaultModel || "unset");
   keyValue("Theme", plan.settings.theme || "unset");
-  keyValue("Shared skills", `${plan.skills.identical} ok, ${plan.skills.missing} missing, ${plan.skills.conflicts} conflicts`);
+  keyValue("Shared skills", `${plan.skills.identical} ok, ${plan.skills.missing} missing, ${preservedUserModified(plan.skills)} preserved user-modified`);
+}
+
+function preservedUserModified(skills) {
+  return skills?.preservedUserModified ?? skills?.conflicts ?? 0;
 }
 
 function printStatusHelp() {

package/src/commands/update.mjs

@@ -6,6 +6,7 @@ import { isWindows } from "../lib/platform.mjs";
 import { runCommand } from "../lib/shell-runner.mjs";
 import { writeState } from "../lib/state-store.mjs";
 import { beginUpdateLifecycle } from "../lib/update-safety.mjs";
+import { migrateSettingsRuntimeState } from "../lib/settings-runtime-state.mjs";
 
 export async function updateCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
@@ -65,7 +66,10 @@ export async function updateCommand(ctx, argv) {
     : buildBashUpdateArgs(ctx, options, dryRun);
   try {
     runDistroScript(ctx, { sh: "pi67-update.sh", ps1: "pi67-update.ps1" }, args, { dryRun: false });
-    if (!dryRun) writeState(ctx, options.repair ? "repair" : "update");
+    if (!dryRun) {
+      writeState(ctx, options.repair ? "repair" : "update");
+      reportSettingsRuntimeStateMigration(ctx);
+    }
   } finally {
     lifecycle.release();
   }
@@ -82,6 +86,25 @@ export async function updateCommand(ctx, argv) {
   }
 }
 
+function reportSettingsRuntimeStateMigration(ctx) {
+  const result = migrateSettingsRuntimeState(ctx, {
+    normalizeSettingsJson: true,
+    installGitFilter: true,
+  });
+  if (result.markerFound && result.stateWritten) {
+    info("Migrated settings.json lastChangelogVersion to ignored state: ~/.pi/pi67/state.json");
+  }
+  if (result.settingsNormalized) {
+    info("Normalized settings.json by removing runtime-only lastChangelogVersion.");
+  }
+  if (result.gitFilterInstalled) {
+    info("Installed local git clean filter for future settings.json runtime markers.");
+  }
+  for (const error of result.errors) {
+    warn(`settings runtime marker migration skipped: ${error}`);
+  }
+}
+
 function buildBashUpdateArgs(ctx, options, dryRun) {
   const args = ["--agent-dir", ctx.agentDir, "--repo-root", ctx.repoRoot, "--skills-dir", ctx.skillsDir];
   if (dryRun) args.push("--dry-run");
@@ -128,7 +151,7 @@ function printPlan(plan) {
   keyValue("Model", plan.settings.defaultModel || "unset");
   keyValue("Theme", plan.settings.theme || "unset");
   keyValue("Theme installed", plan.settings.themeInstalled ? "yes" : "no");
-  keyValue("Shared skills", `${plan.skills.identical} ok, ${plan.skills.missing} missing, ${plan.skills.conflicts} conflicts`);
+  keyValue("Shared skills", `${plan.skills.identical} ok, ${plan.skills.missing} missing, ${preservedUserModified(plan.skills)} preserved user-modified`);
   for (const repo of plan.external) {
     keyValue(`External ${repo.name}`, repo.exists ? `${repo.git?.dirty ? "dirty" : "clean"} ${repo.git?.commit || ""}` : "missing");
   }
@@ -153,6 +176,10 @@ function printPlan(plan) {
   if (!plan.git?.dirty) pass("update check completed without local dirty blocker");
 }
 
+function preservedUserModified(skills) {
+  return skills?.preservedUserModified ?? skills?.conflicts ?? 0;
+}
+
 function printUpdateHelp() {
   process.stdout.write(`pi-67 update - update pi-67 safely
 
@@ -167,7 +194,7 @@ Options:
   --no-remote             Skip remote git/npm registry checks where supported.
   --no-npm                Skip npm package sync in the distro updater.
   --allow-dirty           Let the script-level updater handle non-runtime dirty files.
-  --strict-shared-skills  Treat differing shared skills as blocking.
+  --strict-shared-skills  Treat preserved user-modified shared skills as blocking.
   --include-pi            Also run upstream \`pi update --all\` when paired with --yes.
   --include-external      Report explicit external repo update commands.
   --all                   Alias for --include-pi --include-external.

package/src/commands/version.mjs

@@ -1,9 +1,10 @@
 import { captureCommand } from "../lib/shell-runner.mjs";
 import { gitStatus } from "../lib/git.mjs";
 import { currentTheme } from "../lib/theme-policy.mjs";
-import { keyValue, printJson } from "../lib/output.mjs";
+import { info, keyValue, printJson, section, warn } from "../lib/output.mjs";
 import { platformName } from "../lib/platform.mjs";
 import { readCliPackageJson, readTextIfExists } from "../lib/paths.mjs";
+import { readJsonFileIfExists } from "../lib/config-json.mjs";
 import { parseCommandOptions } from "../lib/args.mjs";
 import path from "node:path";
 
@@ -17,6 +18,8 @@ export async function versionCommand(ctx, argv) {
   const pkg = readCliPackageJson();
   const git = gitStatus(ctx.repoRoot);
   const pi = captureCommand("pi", ["--version"]);
+  const distroVersion = readTextIfExists(path.join(ctx.repoRoot, "VERSION")).trim();
+  const settings = readJsonFileIfExists(path.join(ctx.agentDir, "settings.json")) || {};
   const data = {
     schema: "pi67.version.v1",
     manager: {
@@ -24,7 +27,7 @@ export async function versionCommand(ctx, argv) {
       version: pkg.version,
     },
     distro: {
-      version: readTextIfExists(path.join(ctx.repoRoot, "VERSION")).trim(),
+      version: distroVersion,
       commit: git.commit || "",
       branch: git.branch || "",
       dirty: Boolean(git.dirty),
@@ -42,6 +45,7 @@ export async function versionCommand(ctx, argv) {
     },
     theme: currentTheme(ctx),
   };
+  data.recommendations = buildVersionRecommendations(ctx, data, git, settings);
   if (json) {
     printJson(data);
     return;
@@ -54,6 +58,79 @@ export async function versionCommand(ctx, argv) {
   keyValue("platform", data.runtime.platform);
   keyValue("agentDir", data.paths.agentDir);
   keyValue("theme", data.theme || "unset");
+  printRecommendations(data.recommendations);
+}
+
+function buildVersionRecommendations(ctx, data, git, settings) {
+  const recommendations = [];
+  const managerVsDistro = compareSemver(data.manager.version, data.distro.version);
+  const settingsDirty = git.short
+    .split(/\r?\n/)
+    .some((line) => line.trim().endsWith("settings.json"));
+  const hasRuntimeMarker = settings && Object.prototype.hasOwnProperty.call(settings, "lastChangelogVersion");
+  const updateCommand = `pi-67 --agent-dir "${ctx.agentDir}" --repo-root "${ctx.repoRoot}" update --repair`;
+
+  if (managerVsDistro > 0) {
+    recommendations.push({
+      level: "WARN",
+      message: `manager is ${data.manager.version} but local distro is ${data.distro.version || "unknown"}; npm install updated only the manager package.`,
+    });
+    recommendations.push({
+      level: "INFO",
+      message: `Run: ${updateCommand}`,
+    });
+  } else if (managerVsDistro < 0) {
+    recommendations.push({
+      level: "WARN",
+      message: `local distro ${data.distro.version} is newer than manager ${data.manager.version}; update the manager with npm install -g ${data.manager.package}@latest.`,
+    });
+  }
+
+  if (settingsDirty && hasRuntimeMarker) {
+    recommendations.push({
+      level: "INFO",
+      message: "settings.json has Pi runtime changelog marker state; update --repair migrates it into ~/.pi/pi67/state.json and normalizes settings.json.",
+    });
+  } else if (settingsDirty) {
+    recommendations.push({
+      level: "INFO",
+      message: "settings.json is dirty; inspect with git diff -- settings.json before updating if it contains personal provider/model/theme edits.",
+    });
+  }
+
+  if (!data.runtime.pi) {
+    recommendations.push({
+      level: "INFO",
+      message: "`pi` is not on PATH in this shell; this does not block pi-67 manager updates.",
+    });
+  }
+  return recommendations;
+}
+
+function printRecommendations(recommendations) {
+  if (!recommendations?.length) return;
+  section("Next steps");
+  for (const item of recommendations) {
+    if (item.level === "WARN") warn(item.message);
+    else info(item.message);
+  }
+}
+
+function compareSemver(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  if (!a || !b) return 0;
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] > b[index]) return 1;
+    if (a[index] < b[index]) return -1;
+  }
+  return 0;
+}
+
+function parseSemver(value) {
+  const match = String(value || "").trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+  if (!match) return null;
+  return match.slice(1, 4).map((item) => Number(item));
 }
 
 function printVersionHelp() {

package/src/lib/settings-runtime-clean.mjs

@@ -0,0 +1,20 @@
+export const SETTINGS_RUNTIME_MARKER_KEY = "lastChangelogVersion";
+
+export function stripSettingsRuntimeMarker(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const next = { ...value };
+  delete next[SETTINGS_RUNTIME_MARKER_KEY];
+  return next;
+}
+
+export function stripSettingsRuntimeMarkerText(text) {
+  try {
+    return stableSettingsJson(stripSettingsRuntimeMarker(JSON.parse(String(text || "").replace(/^\uFEFF/, ""))));
+  } catch {
+    return String(text || "");
+  }
+}
+
+export function stableSettingsJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}

package/src/lib/settings-runtime-state.mjs

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import path from "node:path";
+import { captureCommand } from "./shell-runner.mjs";
+import { isGitRepo } from "./git.mjs";
+import { readJsonFileIfExists, writeJsonAtomic } from "./config-json.mjs";
+import {
+  SETTINGS_RUNTIME_MARKER_KEY,
+  stableSettingsJson,
+  stripSettingsRuntimeMarker,
+  stripSettingsRuntimeMarkerText,
+} from "./settings-runtime-clean.mjs";
+
+export const SETTINGS_RUNTIME_FILTER_NAME = "pi67-settings-runtime-state";
+export const SETTINGS_RUNTIME_FILTER_SCRIPT = "packages/pi67-cli/src/tools/settings-runtime-state-filter.mjs";
+
+export { SETTINGS_RUNTIME_MARKER_KEY, stripSettingsRuntimeMarker, stripSettingsRuntimeMarkerText };
+
+export function settingsRuntimeMarkerFromObject(settings) {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) return null;
+  const value = settings[SETTINGS_RUNTIME_MARKER_KEY];
+  if (value === undefined || value === null || String(value).trim() === "") return null;
+  return {
+    key: SETTINGS_RUNTIME_MARKER_KEY,
+    value: String(value),
+  };
+}
+
+export function settingsRuntimeMarkerFromState(state) {
+  const marker = state?.runtimeMarkers?.[SETTINGS_RUNTIME_MARKER_KEY];
+  if (!marker || marker.value === undefined || marker.value === null || String(marker.value).trim() === "") {
+    return null;
+  }
+  return {
+    key: SETTINGS_RUNTIME_MARKER_KEY,
+    value: String(marker.value),
+  };
+}
+
+export function mergeSettingsRuntimeMarkerIntoState(state, marker, now = new Date().toISOString()) {
+  const next = { ...(state || {}) };
+  const runtimeMarkers = { ...(next.runtimeMarkers || {}) };
+  if (marker?.value) {
+    runtimeMarkers[SETTINGS_RUNTIME_MARKER_KEY] = {
+      value: marker.value,
+      source: "settings.json",
+      storage: "state.json",
+      updatedAt: now,
+    };
+  }
+  if (Object.keys(runtimeMarkers).length > 0) {
+    next.runtimeMarkers = runtimeMarkers;
+  }
+  return next;
+}
+
+export function migrateSettingsRuntimeState(ctx, options = {}) {
+  const normalizeSettingsJson = Boolean(options.normalizeSettingsJson);
+  const installGitFilter = Boolean(options.installGitFilter);
+  const dryRun = Boolean(options.dryRun);
+  const settingsPath = path.join(ctx.agentDir, "settings.json");
+  const statePath = path.join(ctx.stateDir, "state.json");
+  const result = {
+    schema: "pi67.settings-runtime-state.v1",
+    settingsPath,
+    statePath,
+    markerFound: false,
+    markerValue: "",
+    stateWritten: false,
+    settingsNormalized: false,
+    gitFilterInstalled: false,
+    skipped: [],
+    errors: [],
+  };
+
+  if (!fs.existsSync(settingsPath)) {
+    result.skipped.push("settings.json missing");
+  } else {
+    let settingsText = "";
+    let settings = null;
+    try {
+      settingsText = fs.readFileSync(settingsPath, "utf8").replace(/^\uFEFF/, "");
+      settings = JSON.parse(settingsText);
+    } catch (error) {
+      result.errors.push(`settings.json is not valid JSON: ${error.message}`);
+    }
+
+    const marker = settingsRuntimeMarkerFromObject(settings);
+    if (marker) {
+      result.markerFound = true;
+      result.markerValue = marker.value;
+      if (!dryRun) {
+        const previous = readJsonFileIfExists(statePath) || {};
+        writeJsonAtomic(statePath, mergeSettingsRuntimeMarkerIntoState(previous, marker));
+        result.stateWritten = true;
+      }
+      if (normalizeSettingsJson) {
+        const normalizedText = stableSettingsJson(stripSettingsRuntimeMarker(settings));
+        if (normalizedText !== settingsText) {
+          if (!dryRun) {
+            fs.writeFileSync(settingsPath, normalizedText, "utf8");
+          }
+          result.settingsNormalized = true;
+        }
+      }
+    } else {
+      result.skipped.push("settings.json runtime marker absent");
+    }
+  }
+
+  if (installGitFilter) {
+    const filterResult = installSettingsRuntimeGitFilter(ctx, { dryRun });
+    result.gitFilterInstalled = filterResult.installed;
+    if (filterResult.skipped) result.skipped.push(filterResult.skipped);
+    if (filterResult.error) result.errors.push(filterResult.error);
+  }
+
+  return result;
+}
+
+export function installSettingsRuntimeGitFilter(ctx, options = {}) {
+  const result = {
+    installed: false,
+    skipped: "",
+    error: "",
+  };
+  if (options.dryRun) {
+    result.installed = true;
+    return result;
+  }
+  if (!isGitRepo(ctx.repoRoot)) {
+    result.skipped = "repo root is not a git checkout";
+    return result;
+  }
+  const scriptPath = path.join(ctx.repoRoot, SETTINGS_RUNTIME_FILTER_SCRIPT);
+  if (!fs.existsSync(scriptPath)) {
+    result.skipped = `settings runtime filter script missing: ${SETTINGS_RUNTIME_FILTER_SCRIPT}`;
+    return result;
+  }
+
+  const cleanCommand = `node ${SETTINGS_RUNTIME_FILTER_SCRIPT} --clean`;
+  const clean = captureCommand("git", [
+    "-C",
+    ctx.repoRoot,
+    "config",
+    "--local",
+    `filter.${SETTINGS_RUNTIME_FILTER_NAME}.clean`,
+    cleanCommand,
+  ]);
+  if (!clean.ok) {
+    result.error = clean.stderr || clean.error || "failed to configure settings runtime clean filter";
+    return result;
+  }
+  const required = captureCommand("git", [
+    "-C",
+    ctx.repoRoot,
+    "config",
+    "--local",
+    `filter.${SETTINGS_RUNTIME_FILTER_NAME}.required`,
+    "false",
+  ]);
+  if (!required.ok) {
+    result.error = required.stderr || required.error || "failed to configure settings runtime filter required=false";
+    return result;
+  }
+  result.installed = true;
+  return result;
+}

package/src/lib/skill-policy.mjs

@@ -16,6 +16,7 @@ export function inventorySkills(ctx) {
     const conflict = targetExists && !identical;
     return { name, source, target, sourceHash, targetExists, targetHash, identical, conflict };
   });
+  const conflicts = entries.filter((entry) => entry.conflict).length;
   return {
     schema: "pi67.skills-inventory.v1",
     sourceRoot,
@@ -24,7 +25,8 @@ export function inventorySkills(ctx) {
       source: entries.length,
       missing: entries.filter((entry) => !entry.targetExists).length,
       identical: entries.filter((entry) => entry.identical).length,
-      conflicts: entries.filter((entry) => entry.conflict).length,
+      conflicts,
+      preservedUserModified: conflicts,
     },
     entries,
   };
@@ -79,7 +81,7 @@ export function planSkills(ctx, { names = [] } = {}) {
     conflict: entry.conflict,
     action: entry.conflict ? "preserve-conflict" : "copy-missing",
     reason: entry.conflict
-      ? "target differs; default update preserves the existing global skill"
+      ? "target differs; default update preserves this user-modified global skill"
       : "target is missing and can be copied safely",
   }));
   return {
@@ -112,7 +114,7 @@ export function syncSkills(ctx, { dryRun = false, names = [], yes = false } = {}
           action: "warn",
           reason: targeted
             ? "target differs; rerun with --yes to replace this explicitly named skill after backup"
-            : "target differs; bulk conflict overwrite is intentionally blocked",
+            : "target differs; bulk overwrite of preserved user-modified skills is intentionally blocked",
         });
         continue;
       }

package/src/lib/state-store.mjs

@@ -4,11 +4,18 @@ import { gitStatus } from "./git.mjs";
 import { currentTheme } from "./theme-policy.mjs";
 import { readJsonFileIfExists, writeJsonAtomic } from "./config-json.mjs";
 import { readCliPackageJson, readTextIfExists } from "./paths.mjs";
+import {
+  mergeSettingsRuntimeMarkerIntoState,
+  settingsRuntimeMarkerFromObject,
+  settingsRuntimeMarkerFromState,
+} from "./settings-runtime-state.mjs";
 
 export function writeState(ctx, operation) {
   const pkg = readCliPackageJson();
   const git = gitStatus(ctx.repoRoot);
   const settings = readJsonFileIfExists(path.join(ctx.agentDir, "settings.json")) || {};
+  const statePath = path.join(ctx.stateDir, "state.json");
+  const previous = readJsonFileIfExists(statePath) || {};
   const state = {
     schema: "pi67.state.v1",
     updatedAt: new Date().toISOString(),
@@ -25,7 +32,12 @@ export function writeState(ctx, operation) {
     lastProvider: settings.defaultProvider || "",
     lastModel: settings.defaultModel || "",
   };
+  const mergedState = mergeSettingsRuntimeMarkerIntoState(
+    state,
+    settingsRuntimeMarkerFromObject(settings) || settingsRuntimeMarkerFromState(previous),
+    state.updatedAt,
+  );
   fs.mkdirSync(ctx.stateDir, { recursive: true });
-  writeJsonAtomic(path.join(ctx.stateDir, "state.json"), state);
-  return state;
+  writeJsonAtomic(statePath, mergedState);
+  return mergedState;
 }

package/src/lib/update-plan.mjs

@@ -9,6 +9,7 @@ import { readCliPackageJson, readTextIfExists } from "./paths.mjs";
 import { npmLatestVersion } from "./npm-registry.mjs";
 import { buildDistroManifest } from "./distro-manifest.mjs";
 import { PRESERVED_RUNTIME_FILES } from "./update-safety.mjs";
+import { settingsRuntimeMarkerFromObject } from "./settings-runtime-state.mjs";
 
 export async function buildUpdatePlan(ctx, options = {}) {
   const versionFile = path.join(ctx.repoRoot, "VERSION");
@@ -39,6 +40,7 @@ export async function buildUpdatePlan(ctx, options = {}) {
     currentVersion: pkg.version,
     noRemote: options.noRemote,
   });
+  const settingsRuntimeMarker = settingsRuntimeMarkerFromObject(settings);
   const dirtyClass = classifyGitShort(git?.short || "");
   const benignRuntime = classifyBenignRuntimeDiff(ctx, dirtyClass.preservedRuntime);
 
@@ -54,15 +56,14 @@ export async function buildUpdatePlan(ctx, options = {}) {
   } else if (git.dirty && dirtyClass.unsafeTracked.length > 0) {
     recommendations.push("Resolve or commit local changes before pi-67 update.");
   } else if (git.dirty && benignRuntime.benign) {
-    recommendations.push("No manual action required for benign settings runtime markers; pi-67 can preserve them during update.");
-    recommendations.push("Optional: normalize local settings runtime marker if you want a clean git status.");
+    recommendations.push("No manual action required for benign settings runtime markers; pi-67 migrates lastChangelogVersion to ignored state during update/repair.");
   } else if (git.dirty) {
     recommendations.push("No manual action required for user runtime config; pi-67 backs up/restores it during update.");
   } else {
     recommendations.push("Run: pi-67 update");
   }
   if (skills.summary.conflicts > 0) {
-    recommendations.push("Run: pi-67 skills inventory and resolve differing global skills manually.");
+    recommendations.push("Run: pi-67 skills inventory to inspect preserved user-modified global skills.");
   }
   if (theme && !hasTheme(ctx, theme)) {
     recommendations.push(`Current theme is missing: ${theme}. Run: pi-67 themes list`);
@@ -74,6 +75,7 @@ export async function buildUpdatePlan(ctx, options = {}) {
     ctx,
     git,
     benignRuntime,
+    settingsRuntimeMarker,
     managerRegistry,
     remote,
     manifest,
@@ -122,6 +124,11 @@ export async function buildUpdatePlan(ctx, options = {}) {
     scripts: scriptStatus,
     manifest: manifest.summary,
     skills: skills.summary,
+    runtimeState: {
+      settingsLastChangelogVersion: settingsRuntimeMarker?.value || "",
+      storage: "~/.pi/pi67/state.json",
+      policy: "settings.json lastChangelogVersion is runtime-only and is normalized into ignored state on update/repair",
+    },
     external,
     actions: decisions.actions,
     blocked: decisions.blocked,
@@ -139,6 +146,7 @@ export function buildPlanDecisions(context) {
   ];
   const dirty = classifyGitShort(context.git?.short || "");
   const benignRuntime = context.benignRuntime || { benign: false, reasons: [] };
+  const settingsRuntimeMarker = context.settingsRuntimeMarker || null;
 
   if (context.managerRegistry.outdated) {
     actions.push({
@@ -153,6 +161,19 @@ export function buildPlanDecisions(context) {
     });
   }
 
+  if (settingsRuntimeMarker?.value || benignRuntime.benign) {
+    actions.push({
+      id: "settings-runtime-state",
+      kind: "runtime-state",
+      operation: "migrate-lastChangelogVersion-to-ignored-state",
+      writes: ["~/.pi/pi67/state.json", "settings.json only when removing runtime-only lastChangelogVersion"],
+      preserves: ["settings.json.theme", "settings.json.defaultProvider", "settings.json.defaultModel", "settings.json.packages"],
+      risk: "low",
+      reason: "lastChangelogVersion is Pi runtime UI state, not pi-67 source configuration",
+      benign: true,
+    });
+  }
+
   if (!context.git?.isRepo) {
     blocked.push({
       id: "repo-root",
@@ -257,16 +278,16 @@ export function buildPlanDecisions(context) {
     });
   }
   if (context.skills.summary.conflicts > 0) {
-    const conflictMessage = `${context.skills.summary.conflicts} shared skills differ from the bundled baseline`;
+    const conflictMessage = `${context.skills.summary.conflicts} preserved user-modified global skills differ from the bundled baseline`;
     if (context.strictSharedSkills) {
       blocked.push({
         id: "shared-skills",
         kind: "skill-pack",
-        reason: `${conflictMessage}; strict mode blocks instead of overwriting`,
+        reason: `${conflictMessage}; strict mode blocks instead of overwriting user-modified skills`,
         recovery: "inspect with pi-67 skills inventory, then sync or resolve manually",
       });
     } else {
-      warnings.push(`${conflictMessage}; default update preserves existing different skills`);
+      warnings.push(`${conflictMessage}; default update preserves them`);
     }
   }
 

package/src/tools/settings-runtime-state-filter.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+
+if (args.includes("--clean")) {
+  const { stripSettingsRuntimeMarkerText } = await import("../lib/settings-runtime-clean.mjs");
+  const input = fs.readFileSync(0, "utf8");
+  process.stdout.write(stripSettingsRuntimeMarkerText(input));
+  process.exit(0);
+}
+
+if (args.includes("--migrate")) {
+  const { migrateSettingsRuntimeState } = await import("../lib/settings-runtime-state.mjs");
+  const ctx = {
+    agentDir: path.resolve(valueAfter("--agent-dir") || process.cwd()),
+    repoRoot: path.resolve(valueAfter("--repo-root") || process.cwd()),
+    stateDir: path.resolve(valueAfter("--state-dir") || path.join(os.homedir(), ".pi", "pi67")),
+  };
+  const result = migrateSettingsRuntimeState(ctx, {
+    normalizeSettingsJson: args.includes("--normalize"),
+    installGitFilter: args.includes("--install-git-filter"),
+    dryRun: args.includes("--dry-run"),
+  });
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    printHuman(result);
+  }
+  process.exit(result.errors.length > 0 ? 1 : 0);
+}
+
+process.stderr.write(`Usage:
+  settings-runtime-state-filter.mjs --clean
+  settings-runtime-state-filter.mjs --migrate --agent-dir DIR --repo-root DIR [--state-dir DIR] [--normalize] [--install-git-filter] [--json] [--dry-run]
+`);
+process.exit(2);
+
+function valueAfter(name) {
+  const index = args.indexOf(name);
+  if (index === -1) return "";
+  return args[index + 1] || "";
+}
+
+function printHuman(result) {
+  if (result.markerFound) {
+    console.log(`PASS migrated settings.json lastChangelogVersion to ${result.statePath}`);
+  } else {
+    console.log("PASS settings.json runtime marker is already absent");
+  }
+  if (result.settingsNormalized) {
+    console.log("PASS normalized settings.json by removing runtime-only lastChangelogVersion");
+  }
+  if (result.gitFilterInstalled) {
+    console.log("PASS installed local git clean filter for settings.json runtime marker");
+  }
+  for (const item of result.skipped) {
+    console.log(`INFO ${item}`);
+  }
+  for (const item of result.errors) {
+    console.error(`FAIL ${item}`);
+  }
+}