pi-scout 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,11 +1,24 @@
 # Changelog
 
+## 0.1.4 - 2026-07-17
+
 All notable changes to this project will be documented in this file.
 
 This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
 
 ## [Unreleased]
 
+### Fixed
+
+- Store temporary clones in a private per-user directory and reject unsafe clone roots.
+- Serialize repository state mutations and persist state through atomic file replacement.
+
+## [0.1.3] - 2026-07-01
+
+### Changed
+
+- Update Pi core development dependency for Pi 0.80 compatibility.
+
 ## [0.1.2] - 2026-06-06
 
 ### Changed

package/README.md

@@ -13,7 +13,7 @@ A source-distributed [Pi](https://pi.dev) package for registering local referenc
 - Compact per-turn system prompt guidance with registered repo names and local clone paths.
 - Automatic pruning: if the OS cleans a temporary clone, Pi Scout removes that stale entry before adding prompt context.
 
-Registered repositories are cloned under `/tmp/pi-scout/<name>-<id>` on Unix-like systems, or the OS temp directory on Windows. Set `PI_SCOUT_TMPDIR` to override the parent temp directory. Pi Scout uses shallow clones with depth `1` by default because it is for code exploration, not history exploration. Pi Scout keeps records in Pi's agent directory and reuses them across sessions while the cloned directories still exist.
+Registered repositories are cloned in a private, per-user directory under the OS temp directory (`<temp>/pi-scout-<uid>` on Unix-like systems). Root and clone permissions are restricted to the current user on Unix. Set `PI_SCOUT_TMPDIR` to override the parent temp directory. Pi Scout uses shallow clones with depth `1` by default because it is for code exploration, not history exploration. Pi Scout keeps records in Pi's agent directory and reuses them across sessions while the cloned directories still exist.
 
 ## Installation
 
@@ -87,6 +87,7 @@ After a repository is registered, the agent sees its local path in the system pr
 - Pi Scout uses local file access for exploration. It does not provide web search or remote content-fetching tools.
 - Registering a Git URL still uses `git clone`, so Git may contact the configured remote.
 - Registered repositories are intended as read-only references unless the user explicitly asks otherwise.
+- Repository state changes are serialized and persisted with atomic file replacement.
 - The system prompt includes only registered repo names and local paths, not origin URLs or branch metadata.
 
 ## Development
@@ -94,5 +95,6 @@ After a repository is registered, the agent sees its local path in the system pr
 ```bash
 npm install
 npm run check
+npm test
 npm run pack:dry-run
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-scout",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Register local reference codebases for Pi agent exploration.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
   "scripts": {
     "check": "tsc --noEmit",
     "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.mjs",
     "pack:dry-run": "npm pack --dry-run"
   },
   "peerDependencies": {
@@ -51,9 +52,10 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.75.4",
-    "@types/node": "^25.6.2",
-    "typebox": "^1.1.33",
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@types/node": "^26.1.0",
+    "tsx": "^4.23.0",
+    "typebox": "^1.3.4",
     "typescript": "^6.0.3"
   },
   "publishConfig": {

package/src/repo.ts

@@ -1,9 +1,9 @@
-import { mkdir, rm } from "node:fs/promises";
+import { chmod, lstat, mkdir, rm } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { platform, tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { loadPrunedState, saveState, type ScoutRepo } from "./state.js";
+import { mutateState, type ScoutRepo } from "./state.js";
 
 export interface RegisterRepoOptions {
   source: string;
@@ -21,7 +21,8 @@ export async function registerRepo(pi: ExtensionAPI, options: RegisterRepoOption
   const name = sanitizeName(options.name?.trim() || inferName(source) || `repo-${id}`);
   const root = getScoutCloneRoot();
   const destination = join(root, `${name}-${id}`);
-  await mkdir(root, { recursive: true });
+  await ensurePrivateCloneRoot(root);
+  await mkdir(destination, { mode: 0o700 });
 
   const args = ["clone"];
   if (options.branch?.trim()) args.push("--branch", options.branch.trim());
@@ -31,9 +32,11 @@ export async function registerRepo(pi: ExtensionAPI, options: RegisterRepoOption
 
   const result = await pi.exec("git", args, { signal: options.signal, timeout: 120_000 });
   if (result.code !== 0) {
+    await rm(destination, { recursive: true, force: true });
     const stderr = result.stderr?.trim() || result.stdout?.trim() || "git clone failed";
     throw new Error(stderr);
   }
+  if (platform() !== "win32") await chmod(destination, 0o700);
 
   const now = new Date().toISOString();
   const repo: ScoutRepo = {
@@ -46,9 +49,9 @@ export async function registerRepo(pi: ExtensionAPI, options: RegisterRepoOption
     lastSeenAt: now,
   };
 
-  const state = await loadPrunedState();
-  state.repos.push(repo);
-  await saveState(state);
+  await mutateState((state) => {
+    state.repos.push(repo);
+  });
   return repo;
 }
 
@@ -56,12 +59,11 @@ export async function removeRepo(idOrName: string, options: { deleteClone?: bool
   const needle = idOrName.trim();
   if (!needle) return undefined;
 
-  const state = await loadPrunedState();
-  const index = state.repos.findIndex((repo) => repo.id === needle || repo.name === needle);
-  if (index === -1) return undefined;
-
-  const [removed] = state.repos.splice(index, 1);
-  await saveState(state);
+  const removed = await mutateState((state) => {
+    const index = state.repos.findIndex((repo) => repo.id === needle || repo.name === needle);
+    if (index === -1) return undefined;
+    return state.repos.splice(index, 1)[0];
+  });
 
   if (options.deleteClone && removed) {
     await rm(removed.path, { recursive: true, force: true });
@@ -75,10 +77,29 @@ export function formatRepo(repo: ScoutRepo): string {
   return `${repo.name}${branch}\n  id: ${repo.id}\n  source: ${repo.source}\n  path: ${repo.path}`;
 }
 
-function getScoutCloneRoot(): string {
-  if (process.env.PI_SCOUT_TMPDIR) return join(process.env.PI_SCOUT_TMPDIR, "pi-scout");
-  if (platform() !== "win32") return "/tmp/pi-scout";
-  return join(tmpdir(), "pi-scout");
+export function getScoutCloneRoot(): string {
+  const parent = process.env.PI_SCOUT_TMPDIR || tmpdir();
+  if (platform() === "win32") return join(parent, "pi-scout");
+  return join(parent, `pi-scout-${getCurrentUid()}`);
+}
+
+export async function ensurePrivateCloneRoot(root: string): Promise<void> {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  if (platform() === "win32") return;
+
+  const info = await lstat(root);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new Error(`Unsafe Pi Scout clone root: ${root} is not a real directory.`);
+  }
+  if (info.uid !== getCurrentUid()) {
+    throw new Error(`Unsafe Pi Scout clone root: ${root} is not owned by current user.`);
+  }
+  await chmod(root, 0o700);
+}
+
+function getCurrentUid(): number {
+  if (!process.getuid) throw new Error("Pi Scout cannot determine current user ID.");
+  return process.getuid();
 }
 
 function inferName(source: string): string {

package/src/state.ts

@@ -1,6 +1,7 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 export interface ScoutRepo {
   id: string;
@@ -36,7 +37,25 @@ export async function loadState(): Promise<ScoutState> {
 
 export async function saveState(state: ScoutState): Promise<void> {
   await mkdir(STATE_DIR, { recursive: true });
-  await writeFile(STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  const temporaryPath = join(dirname(STATE_PATH), `.${basename(STATE_PATH)}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    await rename(temporaryPath, STATE_PATH);
+  } catch (error) {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+export async function mutateState<T>(
+  mutation: (state: ScoutState) => Promise<T> | T,
+): Promise<T> {
+  return withFileMutationQueue(STATE_PATH, async () => {
+    const state = (await pruneMissingRepos(await loadState())).state;
+    const result = await mutation(state);
+    await saveState(state);
+    return result;
+  });
 }
 
 export async function pruneMissingRepos(state: ScoutState): Promise<{ state: ScoutState; removed: ScoutRepo[] }> {
@@ -52,13 +71,15 @@ export async function pruneMissingRepos(state: ScoutState): Promise<{ state: Sco
     }
   }
 
-  const next = { repos };
-  if (removed.length > 0) await saveState(next);
-  return { state: next, removed };
+  return { state: { repos }, removed };
 }
 
 export async function loadPrunedState(): Promise<ScoutState> {
-  return (await pruneMissingRepos(await loadState())).state;
+  return withFileMutationQueue(STATE_PATH, async () => {
+    const { state, removed } = await pruneMissingRepos(await loadState());
+    if (removed.length > 0) await saveState(state);
+    return state;
+  });
 }
 
 async function pathExists(path: string): Promise<boolean> {