@astrofoundry/pi-astro 0.26.2 → 0.26.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrofoundry/pi-astro",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "description": "Personal pi customizations (extensions, subagents, skills, prompts, themes) for the pi coding agent.",
   "keywords": [
     "pi-package"

package/skills/edge/SKILL.md

@@ -23,7 +23,7 @@ Fetches `https://auth.37pla.net/.well-known/openid-configuration` through the VP
 | `bouncer` | bouncer unit status and the nftables set of blocked addresses |
 | `updates` | upgradable packages from the local apt index (not refreshed, so it can lag the mirror) and the packages that need a reboot |
 | `package <name>` | refreshes the apt index, then the installed version (`dpkg-query`) and the candidate with its origin (`apt-cache policy`) |
-| `changelog <name>` | first 80 lines of the candidate's Debian changelog from the Debian servers; each security upload lists the CVEs it fixes, so this is the proof that a version fixes a CVE |
+| `changelog <name>` | first 80 lines of the Debian changelog: the installed package's own copy from `/usr/share/doc`, or the candidate's from the Debian servers when nothing is installed; each security upload lists the CVEs it fixes, so this is the proof that a version fixes a CVE. The servers answer 404 for many fresh security uploads; the installed copy does not have that problem |
 | `auto-upgrades` | the apt timers with their next run, the last three days of `apt-daily` and `apt-daily-upgrade` journal, the unattended-upgrades log tail, and the last dpkg upgrades |
 | `deploy-nginx` | install the tracked `nginx.conf`: `nginx -t` on the staged file, install, `nginx -t`, reload |
 | `reboot --confirm` | `systemctl reboot` |

package/specialists/AGENTS.md

@@ -41,6 +41,7 @@ Wrappers ship as TypeScript and run under Node 24 type stripping: erasable synta
 - Fixed remote commands: `DMZ_COMMANDS`, `PULSAR_COMMANDS`, `VPS_COMMANDS`, `OBS_COMMANDS`, `BACKUP_COMMANDS`, `HOST_COMMANDS`, and `INFERENCE_COMMANDS` must match the entry scripts in `entry/remote/` and their tracked copies in the homelab repository (`02-pulsar-proxmox/dmz/system/`, `02-pulsar-proxmox/pulsar/system/`, `00-frontdoor-vps/system/`, `02-pulsar-proxmox/observability/system/`, `02-pulsar-proxmox/hermes/system/`, `04-nexus-macstudio/system/`, and `host/` of the `astronaute77/arcane` repository). Pulsar's root `authorized_keys` carries one forced key per specialist (network, backup, proxmox, inference), each pinned to its own entry script. Change both sides in the same commit and redeploy the remote script. A new privileged step on the VPS also needs its exact line in `spc-edge-frontdoor-sudoers`.
 - Repository access is `lib/repo.ts` (`repoCommand`, `RepoSpec`, `trackedFile`): one clone per specialist under `~/.specialists/work/<checkoutName>` (`homelab-edge`, `homelab-identity`; never share a checkout between specialists), a write deploy key, and an optional `writeRoot` that limits `git write`. `edge` (`deploy-nginx`) and `identity` (`dmz deploy-config`) deploy only what origin has: `trackedFile` refuses a dirty, ahead, or behind checkout. The DMZ entry keeps the previous template and restores it when render or restart fails.
 - `network` firewall policy writes are `policyWrite`: JSON body from the agent, checked for the documented required fields, sent as `POST`, `PUT`, or `DELETE` through the same pinned request; UniFi validates the rest.
+- Pi executes sibling tool calls in parallel, so two wrapper processes of the same specialist can run at once. `lib/lock.ts` (`withLock`, a directory lock under `~/.specialists/work/locks`, stale after 10 minutes) serialises shared resources; `edge` holds `edge-tunnel` around the fixed IAP port and the gcloud configuration directory. `repo.ts` checkouts are not locked yet.
 - `edge` retries one SSH call through the IAP tunnel when the first connection is closed during setup (`isTransientSshFailure`: exit 255 with "closed by remote host" or a reset), except `reboot`. The IAP tunnel is `lib/tunnel.ts`: `gcloud compute start-iap-tunnel <instance> 22 --local-host-port=localhost:<port>` (a documented flag; the hidden `--listen-on-stdin` is not used), ready when the port accepts a connection, closed after the ssh call. `gcloud auth activate-service-account` runs before every tunnel with `CLOUDSDK_CONFIG` under `~/.specialists/work/gcloud` and `CLOUDSDK_PYTHON` from the config, because the Homebrew cask ships no interpreter.
 - `dns` builds every Technitium call from `TECHNITIUM_READS` and `TECHNITIUM_WRITES`; `key=value` record parameters pass through by name (`token` and `node` refused) because the API documents dozens of type-specific parameters. Writes are refused on the secondary in code: the catalog zone is the only replication path.
 - `security` parses Wazuh alert lines locally (`summariseWazuh`, `summariseVulns`) so the guest never needs `jq`; `wazuh-vulns` is a local view over the same `wazuh-alerts` dump, not a guest command.

package/specialists/edge/run.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 import { readConfig } from "../lib/config.ts";
 import { ServiceError, UsageError } from "../lib/errors.ts";
+import { withLock } from "../lib/lock.ts";
 import { main } from "../lib/main.ts";
 import { printJson, printRaw } from "../lib/output.ts";
 import { specialistsHome, workDir } from "../lib/paths.ts";
@@ -61,7 +62,7 @@ export const VPS_COMMANDS: Readonly<Record<string, { args: number; help: string;
     bouncer: { args: 0, help: "crowdsec-firewall-bouncer status and the nftables block set" },
     updates: { args: 0, help: "upgradable packages (local index, not refreshed) and the packages that need a reboot" },
     package: { args: 1, help: "package <name>    refresh the apt index, then installed and candidate versions of one package" },
-    changelog: { args: 1, help: "changelog <name>  Debian changelog of the candidate version, first 80 lines; it names the CVEs each upload fixes" },
+    changelog: { args: 1, help: "changelog <name>  Debian changelog, first 80 lines: the installed package's own copy, else the candidate's from the Debian servers; it names the CVEs each upload fixes" },
     "auto-upgrades": { args: 0, help: "unattended-upgrades: apt timers, last daily runs, recent log, dpkg upgrades" },
     "deploy-nginx": { args: 0, help: "install the tracked nginx.conf from the pushed homelab checkout (nginx -t, install, reload)", stdin: true },
     reboot: { args: 0, help: "systemctl reboot (needs --confirm)" },
@@ -125,7 +126,12 @@ async function activateServiceAccount(config: EdgeConfig): Promise<void> {
 }
 
 /** Opens the IAP tunnel, runs one fixed command over it, closes the tunnel. */
-async function overTunnel(config: EdgeConfig, remote: string, timeoutMs: number, input?: string): Promise<{ stdout: string; stderr: string; code: number }> {
+/** One tunnel at a time: the local port and the gcloud configuration directory are shared by every edge process. */
+function overTunnel(config: EdgeConfig, remote: string, timeoutMs: number, input?: string): Promise<{ stdout: string; stderr: string; code: number }> {
+    return withLock("edge-tunnel", () => tunnelCall(config, remote, timeoutMs, input), { timeoutMs: timeoutMs + 60_000 });
+}
+
+async function tunnelCall(config: EdgeConfig, remote: string, timeoutMs: number, input?: string): Promise<{ stdout: string; stderr: string; code: number }> {
     await activateServiceAccount(config);
     const tunnel = await openTunnel(
         config.gcloud,

package/specialists/entry/remote/spc-edge-frontdoor-entry.sh

@@ -45,7 +45,13 @@ case "$name" in
   changelog)
     pkg="$rest"
     printf '%s' "$pkg" | grep -Eq '^[a-z0-9][a-z0-9+.-]{0,63}$' || { echo "bad package name" >&2; exit 2; }
-    apt-get changelog "$pkg" 2>&1 | head -n 80 ;;
+    if [ -r "/usr/share/doc/$pkg/changelog.Debian.gz" ]; then
+      echo "installed changelog (/usr/share/doc/$pkg/changelog.Debian.gz):"
+      zcat "/usr/share/doc/$pkg/changelog.Debian.gz" | head -n 80
+    else
+      echo "no installed changelog under /usr/share/doc/$pkg; candidate changelog from the Debian servers:"
+      apt-get changelog "$pkg" 2>&1 | head -n 80
+    fi ;;
   auto-upgrades)
     systemctl list-timers apt-daily.timer apt-daily-upgrade.timer --all --no-pager
     echo "--- apt-daily and apt-daily-upgrade journal, 3 days:"

package/specialists/lib/lock.test.ts

@@ -0,0 +1,42 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { withLock } from "./lock.ts";
+
+describe("withLock", () => {
+    let dir: string;
+    beforeEach(() => {
+        dir = mkdtempSync(join(tmpdir(), "astro-lock-"));
+    });
+    afterEach(() => rmSync(dir, { recursive: true, force: true }));
+
+    it("serialises concurrent holders and releases the lock afterwards", async () => {
+        const order: string[] = [];
+        const hold = (tag: string, ms: number) =>
+            withLock("edge", async () => {
+                order.push(`${tag} start`);
+                await new Promise((r) => setTimeout(r, ms));
+                order.push(`${tag} end`);
+            }, { dir });
+        await Promise.all([hold("a", 120), hold("b", 10)]);
+        expect(order).toEqual(["a start", "a end", "b start", "b end"]);
+        expect(existsSync(join(dir, "edge.lock"))).toBe(false);
+    });
+
+    it("removes a stale lock and reports a busy one", async () => {
+        const lock = join(dir, "edge.lock");
+        mkdirSync(lock);
+        const old = new Date(Date.now() - 20 * 60_000);
+        utimesSync(lock, old, old);
+        expect(await withLock("edge", async () => "ran", { dir })).toBe("ran");
+        mkdirSync(lock);
+        await expect(withLock("edge", async () => "never", { dir, timeoutMs: 300 })).rejects.toThrow(/busy/);
+        expect(existsSync(lock)).toBe(true);
+    });
+
+    it("releases the lock when the work throws", async () => {
+        await expect(withLock("edge", async () => { throw new Error("boom"); }, { dir })).rejects.toThrow("boom");
+        expect(existsSync(join(dir, "edge.lock"))).toBe(false);
+    });
+});

package/specialists/lib/lock.ts

@@ -0,0 +1,49 @@
+import { mkdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { ServiceError } from "./errors.ts";
+import { workDir } from "./paths.ts";
+
+/** A lock older than this belongs to a process that died without releasing it. */
+const STALE_MS = 10 * 60_000;
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Runs `fn` while holding an exclusive directory lock, so concurrent wrapper
+ * processes (Pi runs sibling tool calls in parallel) take turns on a shared
+ * resource such as a fixed tunnel port or a gcloud configuration directory.
+ */
+export async function withLock<T>(name: string, fn: () => Promise<T>, options: { dir?: string; timeoutMs?: number; staleMs?: number } = {}): Promise<T> {
+    const root = options.dir ?? workDir("locks");
+    const lock = join(root, `${name}.lock`);
+    const deadline = Date.now() + (options.timeoutMs ?? 120_000);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    for (;;) {
+        try {
+            mkdirSync(lock);
+            break;
+        } catch (err) {
+            if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+        }
+        let age: number;
+        try {
+            age = Date.now() - statSync(lock).mtimeMs;
+        } catch {
+            // The holder released it between our attempt and the check; try again at once.
+            continue;
+        }
+        if (age > (options.staleMs ?? STALE_MS)) {
+            rmSync(lock, { recursive: true, force: true });
+            continue;
+        }
+        if (Date.now() > deadline) throw new ServiceError(`${name} is busy: another call has held it for ${Math.round(age / 1000)} s`);
+        await sleep(200);
+    }
+    try {
+        return await fn();
+    } finally {
+        rmSync(lock, { recursive: true, force: true });
+    }
+}