@astrofoundry/pi-astro 0.26.2 → 0.26.3

package/package.json

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

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";
@@ -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/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 });
+    }
+}