@alphacoder-v0/pi-loops 0.17.3 → 0.17.4

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 All notable changes to pi-loops are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow SemVer.
 
+## [0.17.4] - 2026-09-14
+
+### Added
+- **pi-loops is on npm, and the documents say so.** `@alphacoder-v0/pi-loops` was published at
+  0.17.3, installed from the registry into a clean directory, its `pi-loops` bin run from that
+  `node_modules` layout, and loaded with `pi -e npm:@alphacoder-v0/pi-loops` before anything here
+  changed. `piLoops.publishedToNpm` is now `true`, which is the one line `check:docs` was waiting
+  for, and both READMEs lead with `pi install npm:@alphacoder-v0/pi-loops` — without a version,
+  because pi treats an npm spec without an exact version as one `pi update --extensions` moves, and
+  that is what someone who did not ask for a pin wants. GitHub stays the pinned route. The launcher
+  instructions, the upgrade notes, the uninstall line and `docs/troubleshooting.md` name the npm
+  install beside the git one.
+
+### Fixed
+- **`pi-loops upgrade` pinned an npm install that was following releases.** It answered every npm
+  copy with `npm:<name>@<version>`, and pi skips an exact version in every later
+  `pi update --extensions` — so the first upgrade of a bare install would also have been the last one
+  anything but `upgrade` ever did. It now reads the entry pi recorded in the `settings.json` beside
+  the install root (`~/.pi/agent/settings.json` for `~/.pi/agent/npm`, `.pi/settings.json` for a
+  project's `.pi/npm`): an exact pin stays a pin, moved to the new version; a bare name, `@latest` or
+  a range gets `npm:<name>@latest`. Not the bare name, which reads as the obvious answer and is wrong:
+  over an existing install, `npm install <name>` keeps the range it saved the first time and installs
+  nothing, so `upgrade` would have printed "upgraded" over the version it started from — checked
+  against npm itself, not assumed. With no entry to read, it pins, as before. The unknown-command hint
+  names the same spec.
+
 ## [0.17.3] - 2026-09-13
 
 ### Fixed

package/README.md

@@ -36,7 +36,8 @@ one message, make sure you get an answer. pi-loops runs sub-agents while you are
 the first sign of credentials that do not work should not be an empty inbox tomorrow morning.
 
 ```bash
-pi install git:github.com/alphacoder-v0/pi-loops@v0.17.3    # from GitHub, at a pinned tag
+pi install npm:@alphacoder-v0/pi-loops                      # from npm, following new releases
+pi install git:github.com/alphacoder-v0/pi-loops@v0.17.4    # or from GitHub, at a pinned tag
 pi install /path/to/pi-loops                                # or a local checkout — `pi install .` in this repo
 pi -e /path/to/pi-loops                                     # or none of them: try it for one run, installing nothing
 ```
@@ -182,7 +183,8 @@ directory rather than on your `PATH`, so the command does not exist yet — the
 
 ```bash
 # or from a shell, in the directory pi installed the package into
-cd ~/.pi/agent/git/github.com/alphacoder-v0/pi-loops
+cd ~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops    # installed from npm
+cd ~/.pi/agent/git/github.com/alphacoder-v0/pi-loops       # installed from GitHub
 node src/cli-entry.mjs install-launcher
 ```
 
@@ -235,18 +237,23 @@ pi-loops upgrade --check              # just say whether there is one
 ```
 
 It reads the release tags from the repository this copy came from, compares them with what you are
-running, and installs the newest — which `pi update --extensions` will not do, because pi pins the
-ref you asked for and keeps the clone on *that* ref ([docs/cli.md](docs/cli.md)).
+running, and installs the newest the same way this copy was installed. For a GitHub install that is
+the only way to move: `pi update --extensions` keeps the clone on the ref you pinned
+([docs/cli.md](docs/cli.md)). An npm install made without a version is one `pi update --extensions`
+moves as well, and `upgrade` leaves it that way; one pinned to an exact version stays pinned, to the
+new one.
 
-Restart pi (or run `pi-loops` again) to load it. The launcher does not need reinstalling: pi keeps
-each git package at `~/.pi/agent/git/<host>/<owner>/<repo>`, so a version change keeps the path.
+Restart pi (or run `pi-loops` again) to load it. The launcher does not need reinstalling: pi keeps a
+package at the same path whatever its version — `~/.pi/agent/npm/node_modules/<name>` or
+`~/.pi/agent/git/<host>/<owner>/<repo>`.
 
-Releases are tags on GitHub; [CHANGELOG.md](CHANGELOG.md) says what is in each one.
+Releases are tags on GitHub, published to npm under the same version; [CHANGELOG.md](CHANGELOG.md)
+says what is in each one.
 
 ### Uninstall
 
 ```bash
-pi remove git:github.com/alphacoder-v0/pi-loops   # or the checkout path — whatever you installed
+pi remove npm:@alphacoder-v0/pi-loops             # or git:github.com/alphacoder-v0/pi-loops, or the checkout path — whatever you installed
 ```
 
 State stays in `~/.pi/agent/loops` until you delete it.

package/README.zh-CN.md

@@ -27,7 +27,7 @@ pi-loops --tui                        # 猜错时强制终端
 pi-loops --continue                   # 接着这个目录里最新的那个会话
 pi-loops sessions [--all]             # 这个目录（或整台机器）记下的会话
 pi-loops inspect <file>               # 别人发来的 .pisession，导入前先看清里面是什么
-pi-loops upgrade                      # 从 GitHub 装最新的发布版
+pi-loops upgrade                      # 装最新的发布版，当初从哪装就从哪装
 pi-loops host status                  # 看一眼没有 pi 开着时在跑的自动化
 ```
 
@@ -44,11 +44,12 @@ pi-loops 自己没有任何运行时依赖。
 ### 2. 装上
 
 ```bash
-pi install git:github.com/alphacoder-v0/pi-loops@v0.17.3    # 从 GitHub 装，钉住一个 tag
+pi install npm:@alphacoder-v0/pi-loops                      # 从 npm 装，跟着新版本走
+pi install git:github.com/alphacoder-v0/pi-loops@v0.17.4    # 或者从 GitHub 装，钉住一个 tag
 pi install /path/to/pi-loops                                # 或者本地检出；本仓库里就是 pi install .
 ```
 
-**两种装法挑一种，不要装两份。** 两份副本注册同名工具，pi 会拒绝加载第二份并直接退出（`Tool "cron_create" conflicts with …`）。如果你在改这份代码，留本地检出那份。
+**几种装法挑一种，不要装两份。** 两份副本注册同名工具，pi 会拒绝加载第二份并直接退出（`Tool "cron_create" conflicts with …`）。如果你在改这份代码，留本地检出那份。
 
 重启 pi，装到这里就够了——那四个斜杠命令现在就能用。下面这步只跟 `pi-loops` 这个命令有关：浏览器窗口和几个 shell 子命令靠它，不要浏览器窗口可以先跳过。
 
@@ -60,7 +61,8 @@ pi install /path/to/pi-loops                                # 或者本地检出
 
 ```bash
 # 或者在 shell 里，进到 pi 装包的那个目录
-cd ~/.pi/agent/git/github.com/alphacoder-v0/pi-loops
+cd ~/.pi/agent/npm/node_modules/@alphacoder-v0/pi-loops    # 从 npm 装的
+cd ~/.pi/agent/git/github.com/alphacoder-v0/pi-loops       # 从 GitHub 装的
 node src/cli-entry.mjs install-launcher
 ```
 
@@ -152,18 +154,19 @@ pi-loops upgrade                                   # 装最新的发布版
 pi-loops upgrade --check                           # 只看看有没有新的
 ```
 
-它从这份副本的来源仓库读 release tag，和你正在跑的版本比，然后装最新那个。
+它从这份副本的来源仓库读 release tag，和你正在跑的版本比，然后按这份副本当初的装法装最新那个。
 
-`pi update --extensions` **有意**不做这件事：pi 钉住你写的那个 ref，并且只把克隆对齐到**那个** ref。换版本是另一个决定，而做这个决定得先知道哪个 tag 最新——本该命令替你查，不是你查完再手打回来。
+从 GitHub 装的，只能靠它换版本：`pi update --extensions` **有意**不做这件事，pi 钉住你写的那个 ref，并且只把克隆对齐到**那个** ref。换版本是另一个决定，而做这个决定得先知道哪个 tag 最新——本该命令替你查，不是你查完再手打回来。从 npm 装、没写版本号的，`pi update --extensions` 本来就会升，`upgrade` 升完也保持不钉版本；钉了精确版本的，升完仍然钉着，钉到新版本上。
 
-装完重启 pi（或者再跑一次 `pi-loops`）就生效。启动器不用重装：pi 把每个 git 包固定放在 `~/.pi/agent/git/<host>/<owner>/<repo>`，换版本路径不变。
+装完重启 pi（或者再跑一次 `pi-loops`）就生效。启动器不用重装：pi 放包的路径不随版本变——`~/.pi/agent/npm/node_modules/<包名>` 或 `~/.pi/agent/git/<host>/<owner>/<repo>`。
 
-版本就是 GitHub 上的 tag，每个 tag 里有什么见 [CHANGELOG.md](CHANGELOG.md)。
+版本就是 GitHub 上的 tag，同一个版本号也发到 npm，每个 tag 里有什么见 [CHANGELOG.md](CHANGELOG.md)。
 
 ## 卸载
 
 ```bash
-pi remove git:github.com/alphacoder-v0/pi-loops    # 当初怎么装的就怎么删：git: ref 或检出路径
+pi remove npm:@alphacoder-v0/pi-loops              # 当初怎么装的就怎么删：npm: 包名、git: ref 或检出路径
+pi remove git:github.com/alphacoder-v0/pi-loops
 pi -e /path/to/pi-loops                            # 或者：只在这次启动试用，什么都不装
 pi update --extensions                             # 对齐已安装的包
 ```

package/docs/cli.md

@@ -184,9 +184,19 @@ It reads release tags from the repository this copy came from (`repository.url`
 numerically, so `v0.10.0` beats `v0.9.0` — and runs `pi install` for it. Release candidates and
 branch-shaped tags are ignored: those are not things to move someone onto without being asked.
 
-`pi update --extensions` does something different and both are useful: it reconciles every package
-to the ref already pinned in your settings, which is how you repair a clone, not how you take a new
-version.
+The spec it installs follows how this copy was installed, because a spec from another source adds a
+second package instead of replacing this one. A git install gets `git:<host>/<owner>/<repo>@<tag>`.
+An npm install gets its spec from the entry pi recorded in `settings.json`: pinned to an exact
+version, it is pinned to the new one (`npm:@alphacoder-v0/pi-loops@<version>`); installed without a
+version, with `@latest` or with a range, it gets `npm:@alphacoder-v0/pi-loops@latest` — not the bare
+name, which over an existing install makes npm keep the range it saved and install nothing, and not
+an exact version, which pi would then skip in every later update. If there is no entry to read, it
+pins.
+
+`pi update --extensions` does something different and both are useful: for a git package it
+reconciles the clone to the ref already pinned in your settings, which is how you repair a clone,
+not how you take a new version. For an npm package installed without an exact version it does take
+the newest release, and `upgrade` and it then agree.
 
 ## The tools
 

package/docs/troubleshooting.md

@@ -15,14 +15,15 @@ card and in `/cron trace <job> 1 checker`.
 
 **`Tool "cron_create" conflicts with …`, and pi exits.** The package is installed twice, and this
 is fatal rather than cosmetic: the second copy fails to load and pi stops. It happens easily —
-a local checkout you are working on plus `pi install git:…` of the published one both sit in
-`packages` in `~/.pi/agent/settings.json`, and both register the same tools. (An older, milder
-symptom of the same thing was commands appearing as `/cron:1`.)
+a local checkout you are working on plus `pi install npm:…` or `pi install git:…` of the published
+one all sit in `packages` in `~/.pi/agent/settings.json`, and each registers the same tools. (An
+older, milder symptom of the same thing was commands appearing as `/cron:1`.)
 
 Keep one:
 
 ```bash
-pi remove git:github.com/alphacoder-v0/pi-loops    # keep the checkout you are working on
+pi remove npm:@alphacoder-v0/pi-loops              # keep the checkout you are working on (installed from npm)
+pi remove git:github.com/alphacoder-v0/pi-loops    # keep the checkout you are working on (installed from GitHub)
 pi remove /path/to/your/checkout                   # or keep the installed one
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphacoder-v0/pi-loops",
-  "version": "0.17.3",
+  "version": "0.17.4",
   "description": "An automation layer for pi: cron + stateful loops with a triage inbox, maker/checker verification, dynamic triggers, MCP notifications and tools, lifecycle hooks, session archives. A non-invasive pi extension.",
   "type": "module",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "access": "public"
   },
   "piLoops": {
-    "publishedToNpm": false
+    "publishedToNpm": true
   },
   "scripts": {
     "ci": "npm run typecheck && npm run lint && npm run check:scripts && npm run check:docs && npm test",

package/src/cli.ts

@@ -367,7 +367,7 @@ export async function runCli(argv: string[], out: (line: string) => void = conso
 		out(`unknown command ${JSON.stringify(command)} (this is pi-loops v${PI_LOOPS_VERSION})`);
 		// The route has to match how this copy was installed, for the same reason `upgrade` does: a
 		// spec from the other one installs a second copy rather than replacing this one.
-		const spec = upgradeSpec(packageRoot(), manifest().name ?? "", agentDir, "<newer release>");
+		const spec = upgradeSpec(packageRoot(), manifest().name ?? "", agentDir, "<newer release>", configuredNpmSource(packageRoot(), manifest().name ?? ""));
 		out(`if you expected it, the copy you are running may be older than the command: ${spec ? `pi install ${spec}` : checkoutUpgradeHint()}`);
 		out("");
 	}
@@ -442,11 +442,17 @@ function manifest(): { name?: string; repositoryUrl?: string } {
  * path — and a local checkout is in neither place. A checkout has no install to redo: it has a
  * remote, and `git pull` is its upgrade.
  */
-export function upgradeSpec(packageDir: string, packageName: string, agentDir: string, tag: string): string | undefined {
-	const segments = path.resolve(packageDir).split(path.sep).filter(Boolean);
-	// A scoped name is two segments on disk, so compare as many as the name has.
-	const name = packageName.split("/").filter(Boolean);
-	if (name.length && segments.slice(-name.length).join("/") === name.join("/") && segments[segments.length - name.length - 1] === "node_modules") {
+export function upgradeSpec(packageDir: string, packageName: string, agentDir: string, tag: string, configuredSource?: string): string | undefined {
+	if (npmInstallRoot(packageDir, packageName)) {
+		// pi skips an exact npm version when it updates packages and moves anything else, so the
+		// answer has to keep whichever of the two the install was. Pinning a bare install here would
+		// make this upgrade the last one `pi update` ever does. The moving answer is `@latest`, not the
+		// bare name: `npm install <name>` over an existing install keeps the range it saved and changes
+		// nothing, while `@latest` is what pi's own update asks npm for and is not a pin to pi. Not
+		// knowing how it was installed keeps the exact pin: it is the reading that cannot move a
+		// package somewhere it was not asked to go.
+		const configured = configuredSource === undefined ? undefined : npmSourceVersion(configuredSource, packageName);
+		if (configured !== undefined && !isExactNpmVersion(configured)) return `npm:${packageName}@latest`;
 		// Release tags are `v0.17.0`; the version npm knows the same release by is `0.17.0`.
 		return `npm:${packageName}@${tag.replace(/^v/, "")}`;
 	}
@@ -459,6 +465,58 @@ export function upgradeSpec(packageDir: string, packageName: string, agentDir: s
 	return undefined;
 }
 
+/** The directory `npm install` ran in (the one holding `node_modules`), if this copy is an npm install. */
+function npmInstallRoot(packageDir: string, packageName: string): string | undefined {
+	const segments = path.resolve(packageDir).split(path.sep).filter(Boolean);
+	// A scoped name is two segments on disk, so compare as many as the name has.
+	const name = packageName.split("/").filter(Boolean);
+	if (!name.length || segments.slice(-name.length).join("/") !== name.join("/") || segments[segments.length - name.length - 1] !== "node_modules") return undefined;
+	return path.join(path.parse(path.resolve(packageDir)).root, ...segments.slice(0, -name.length - 1));
+}
+
+/**
+ * The version an `npm:` source gives `packageName` — `""` for none — or undefined if it names some
+ * other package. The name is known, so this compares a prefix rather than parsing a spec: a project's
+ * `.pi/settings.json` can come from a cloned repository, and a general spec regex backtracks
+ * quadratically on an entry built for it.
+ */
+function npmSourceVersion(source: string, packageName: string): string | undefined {
+	const spec = source.trim().replace(/^npm:/, "").trim();
+	if (!spec.startsWith(packageName)) return undefined;
+	const rest = spec.slice(packageName.length);
+	if (rest === "") return "";
+	return rest.startsWith("@") ? rest.slice(1) : undefined;
+}
+
+/** What pi counts as pinned: a valid semver, which it also accepts with a leading `v`. */
+function isExactNpmVersion(version: string): boolean {
+	return /^v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version);
+}
+
+/**
+ * The `npm:` source this install is recorded under, as written. pi keeps a user install in
+ * `<agent dir>/npm` and records it in `<agent dir>/settings.json`, and a project one in `.pi/npm`
+ * recorded in `.pi/settings.json` — in both, the settings file sits beside the install root.
+ */
+export function configuredNpmSource(packageDir: string, packageName: string): string | undefined {
+	const root = npmInstallRoot(packageDir, packageName);
+	if (!root) return undefined;
+	let packages: unknown;
+	try {
+		packages = JSON.parse(fs.readFileSync(path.join(path.dirname(root), "settings.json"), "utf8"))?.packages;
+	} catch {
+		// Missing (an older pi's global install has no settings beside it) or unreadable: not knowing
+		// how this was installed is an answer `upgradeSpec` handles, not a reason to fail an upgrade.
+		return undefined;
+	}
+	if (!Array.isArray(packages)) return undefined;
+	for (const entry of packages) {
+		const source = typeof entry === "string" ? entry : typeof entry?.source === "string" ? entry.source : undefined;
+		if (source?.trim().startsWith("npm:") && npmSourceVersion(source, packageName) !== undefined) return source;
+	}
+	return undefined;
+}
+
 /** What to tell someone whose copy is a checkout: there is nothing for `pi install` to do. */
 function checkoutUpgradeHint(): string {
 	return `git pull in ${packageRoot()}, then restart pi`;
@@ -490,7 +548,7 @@ async function upgrade(checkOnly: boolean, out: (line: string) => void): Promise
 		out("already up to date");
 		return 0;
 	}
-	const spec = upgradeSpec(packageRoot(), name ?? "", getAgentDir(), latest);
+	const spec = upgradeSpec(packageRoot(), name ?? "", getAgentDir(), latest, configuredNpmSource(packageRoot(), name ?? ""));
 	if (!spec) {
 		// Nothing failed, so this is not an error: the newest release is out and the way to it is a
 		// pull, not an install that would leave a second copy beside the checkout.