@tshu-w/pi-agents 0.0.0-stage → 0.1.0

package/src/roots/guard.mjs

@@ -0,0 +1,227 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { closeSync, openSync, readFileSync, readSync, writeFileSync } from 'node:fs';
+import { acquireLock, canonicalPath, SessionOccupiedError } from './locks.mjs';
+import { resolvePath } from './paths.mjs';
+
+/** The ID in a Session file's header, its first parseable entry. Reads only up to that entry. */
+export function readSessionId(path) {
+  let fd;
+  try { fd = openSync(path, 'r'); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  try {
+    let rest = Buffer.alloc(0);
+    for (;;) {
+      // Grow reads with an unfinished line so long lines stay linear.
+      const chunk = Buffer.alloc(Math.max(65536, rest.length));
+      const bytes = readSync(fd, chunk);
+      const data = Buffer.concat([rest, chunk.subarray(0, bytes)]);
+      const end = bytes ? data.lastIndexOf(10) + 1 : data.length;
+      for (const line of data.subarray(0, end).toString('utf8').split('\n')) {
+        let entry;
+        try { entry = JSON.parse(line); } catch { continue; }
+        if (entry) return entry.type === 'session' && typeof entry.id === 'string' ? entry.id : undefined;
+      }
+      if (!bytes) return;
+      rest = data.subarray(end);
+    }
+  } finally { closeSync(fd); }
+}
+
+const installed = Symbol.for('pi-agents.guard');
+
+/** Patches Pi's Session classes so every persisted Session holds its locks. Idempotent across /reload. */
+export function installGuard({ SessionManager, AgentSession, AgentSessionRuntime, parseSessionEntries, stateDir }) {
+  const p = SessionManager.prototype;
+  if (Object.hasOwn(p, installed)) return p[installed];
+  const states = new WeakMap();
+  const operations = new AsyncLocalStorage();
+
+  function state(sm) {
+    let value = states.get(sm);
+    if (!value) {
+      value = { held: new Map(), depth: 0, disposed: false };
+      states.set(sm, value);
+      const scope = operations.getStore();
+      if (scope?.collect) scope.managers.add(sm);
+    }
+    if (value.disposed) throw new Error('Session lock has been released');
+    return value;
+  }
+  function drop(resource) {
+    if (--resource.refs === 0) resource.lock.release();
+  }
+  function reserve(held, key) {
+    if (held.has(key)) return;
+    const scope = operations.getStore();
+    const borrowed = scope?.borrow?.get(key) ?? scope?.reserved?.get(key);
+    const resource = borrowed ?? { lock: acquireLock({ stateDir, sessionId: key }), refs: 0 };
+    resource.refs++;
+    held.set(key, resource);
+  }
+  function reserveFile(held, file) {
+    reserve(held, `path:${canonicalPath(file)}`);
+    const id = readSessionId(file);
+    if (id !== undefined) reserve(held, `id:${id}`);
+  }
+  function keys(sm) {
+    return [`path:${canonicalPath(sm.getSessionFile())}`, `id:${sm.getSessionId()}`];
+  }
+  function ensure(sm) {
+    if (!sm.isPersisted()) return;
+    const s = state(sm);
+    for (const key of keys(sm)) reserve(s.held, key);
+  }
+  function release(sm) {
+    if (!sm.isPersisted()) return;
+    const s = states.get(sm);
+    if (!s || s.disposed) return;
+    s.disposed = true;
+    for (const resource of s.held.values()) drop(resource);
+    s.held.clear();
+  }
+  for (const name of ['_setSessionFile', 'newSession', '_loadEntries', 'createBranchedSession']) {
+    const original = p[name];
+    p[name] = function (...args) {
+      if (!this.isPersisted()) return original.apply(this, args);
+      const s = state(this);
+      if (s.depth) return original.apply(this, args);
+      const snapshot = Object.fromEntries(Object.entries(this).map(([key, value]) => [key, value instanceof Map ? new Map(value) : value]));
+      const oldKeys = new Set(s.held.keys());
+      s.depth++;
+      try {
+        if (name === '_setSessionFile') {
+          const file = resolvePath(args[0]);
+          // Native loading can repair trailing newlines before migration.
+          reserveFile(s.held, file);
+        }
+        const result = original.apply(this, args);
+        ensure(this);
+        const keep = new Set(keys(this));
+        for (const [key, resource] of s.held) {
+          if (!keep.has(key)) { drop(resource); s.held.delete(key); }
+        }
+        return result;
+      } catch (error) {
+        Object.assign(this, snapshot);
+        for (const [key, resource] of s.held) {
+          if (!oldKeys.has(key)) { drop(resource); s.held.delete(key); }
+        }
+        throw error;
+      } finally {
+        s.depth--;
+        if (name === '_setSessionFile' && operations.getStore()) operations.getStore().borrow = undefined;
+      }
+    };
+  }
+  for (const name of ['_persist', '_rewriteFile']) {
+    const original = p[name];
+    p[name] = function (...args) { ensure(this); return original.apply(this, args); };
+  }
+  const open = SessionManager.open;
+  SessionManager.open = function (file, ...args) {
+    const parent = operations.getStore();
+    const scope = { managers: parent?.managers ?? new Set(), reserved: new Map(parent?.reserved), borrow: parent?.borrow, collect: parent?.collect ?? true };
+    for (const resource of scope.reserved.values()) resource.refs++;
+    return operations.run(scope, () => {
+      let result;
+      try {
+        reserveFile(scope.reserved, resolvePath(file));
+        result = open.call(this, file, ...args);
+        return result;
+      } finally {
+        if (parent) {
+          parent.borrow = undefined;
+          // Import reservations protect the copy; the opened manager now owns it.
+          for (const resource of parent.reserved.values()) drop(resource);
+          parent.reserved.clear();
+        }
+        for (const resource of scope.reserved.values()) drop(resource);
+        if (!parent) for (const sm of scope.managers) if (sm !== result) release(sm);
+      }
+    });
+  };
+  SessionManager.forkFrom = function (source, cwd, dir, options) {
+    const scope = { managers: new Set(), reserved: new Map(), collect: true };
+    return operations.run(scope, () => {
+      let result;
+      try {
+        const sourcePath = resolvePath(source);
+        // Fork history is a read-only snapshot; the source runtime may stay open.
+        const entries = parseSessionEntries(readFileSync(sourcePath, 'utf8')).filter(Boolean);
+        if (entries[0]?.type !== 'session' || typeof entries[0].id !== 'string') throw new Error(`Cannot fork: invalid session: ${sourcePath}`);
+        // Native forkFrom writes before constructing its manager. Create the native
+        // manager first so both its generated path and ID are reserved before IO.
+        const manager = SessionManager.create(cwd, dir, options);
+        const header = { ...manager.getHeader(), parentSession: sourcePath };
+        const content = [header, ...entries.filter(entry => entry.type !== 'session')];
+        writeFileSync(manager.getSessionFile(), `${content.map(entry => JSON.stringify(entry)).join('\n')}\n`, { flag: 'wx' });
+        manager.setSessionFile(manager.getSessionFile());
+        result = manager;
+        return result;
+      } finally {
+        for (const resource of scope.reserved.values()) drop(resource);
+        for (const sm of scope.managers) if (sm !== result) release(sm);
+      }
+    });
+  };
+  const dispose = AgentSession.prototype.dispose;
+  AgentSession.prototype.dispose = function (...args) {
+    const result = dispose.apply(this, args);
+    release(this.sessionManager);
+    return result;
+  };
+  const rp = AgentSessionRuntime.prototype;
+  const teardown = rp.teardownCurrent;
+  rp.teardownCurrent = function (...args) {
+    const scope = operations.getStore();
+    if (scope) scope.collect = false;
+    return teardown.apply(this, args);
+  };
+  const beforeFork = rp.emitBeforeFork;
+  rp.emitBeforeFork = async function (...args) {
+    const result = await beforeFork.apply(this, args);
+    const scope = operations.getStore();
+    if (!result.cancelled && scope?.kind === 'fork') {
+      scope.collect = true;
+      scope.borrow = state(this.session.sessionManager).held;
+    }
+    return result;
+  };
+  const beforeSwitch = rp.emitBeforeSwitch;
+  rp.emitBeforeSwitch = async function (...args) {
+    const result = await beforeSwitch.apply(this, args);
+    const scope = operations.getStore();
+    if (!result.cancelled && scope) scope.collect = true;
+    if (!result.cancelled && scope?.kind === 'importFromJsonl') {
+      const file = resolvePath(scope.input);
+      reserveFile(scope.reserved, file);
+      reserve(scope.reserved, `path:${canonicalPath(resolvePath(args[1]))}`);
+    }
+    return result;
+  };
+  for (const kind of ['switchSession', 'newSession', 'fork', 'importFromJsonl']) {
+    const original = rp[kind];
+    rp[kind] = async function (...args) {
+      const previous = this.session;
+      const scope = { kind, input: args[0], managers: new Set(), reserved: new Map(), collect: false };
+      return operations.run(scope, async () => {
+        try { return await original.apply(this, args); }
+        catch (error) {
+          if (error instanceof SessionOccupiedError && this.session === previous && !states.get(previous.sessionManager)?.disposed) {
+            previous.extensionRunner.createContext().ui.notify(error.message, 'warning');
+            return { cancelled: true };
+          }
+          throw error;
+        } finally {
+          scope.borrow = undefined;
+          for (const resource of scope.reserved.values()) drop(resource);
+          scope.reserved.clear();
+          for (const sm of scope.managers) if (sm !== this.session.sessionManager) release(sm);
+        }
+      });
+    };
+  }
+  const guard = { release };
+  Object.defineProperty(p, installed, { value: guard });
+  return guard;
+}

package/src/roots/lock-extension.mjs

@@ -0,0 +1,167 @@
+import { canonicalPath, reserve } from './locks.mjs';
+import { resolvePath, statePaths } from './paths.mjs';
+import { readSessionId } from './guard.mjs';
+
+// Pi reloads extension modules but keeps the SessionManager. Retain its lock
+// across reload without allowing a different manager to borrow it.
+const locks = globalThis[Symbol.for('pi-agents.extension-locks')] ??= new WeakMap();
+const pending = globalThis[Symbol.for('pi-agents.pending-locks')] ??= new Map();
+
+const switchers = globalThis[Symbol.for('pi-agents.switch-session')] ??= { byManager: new WeakMap(), patched: false };
+
+/**
+ * Pi gives `switchSession` only to command handlers. Keep the one it binds to each runner, by
+ * Session manager, so a handover can switch without a command. Relies on a private member of
+ * `ExtensionRunner`; check it when Pi is updated.
+ */
+function captureSwitchSession(Runner) {
+  if (switchers.patched) return;
+  switchers.patched = true;
+  const bind = Runner.prototype.bindCommandContext;
+  Runner.prototype.bindCommandContext = function (actions) {
+    if (actions?.switchSession) switchers.byManager.set(this.sessionManager, actions.switchSession);
+    return bind.call(this, actions);
+  };
+}
+
+/**
+ * Holds the current Session's lock so one runtime uses a Session at a time.
+ * An occupied Session is quarantined.
+ */
+export default function lockExtension(pi, runtime = {}) {
+  if (runtime.runner) captureSwitchSession(runtime.runner);
+  const paths = statePaths();
+  const stateDir = paths.locks;
+  let blocked = 'Session lock has not been acquired';
+  let reopen;
+  let replacing = false;
+  let alive = true;
+  const pendingKey = file => `${stateDir}\n${canonicalPath(file)}`;
+  function savePending(file, id, lock) {
+    const key = pendingKey(file);
+    const value = { id, lock };
+    pending.set(key, value);
+    return value;
+  }
+  function discardPending(file, value) {
+    if (pending.get(pendingKey(file)) !== value) return;
+    pending.delete(pendingKey(file));
+    value.lock.release();
+  }
+
+  function notify(ctx, message) {
+    if (ctx.hasUI) ctx.ui.notify(message, 'error');
+    else console.error(message);
+  }
+
+  function scheduleReopen(ctx) {
+    // Session replacement must run after the current hooks.
+    setTimeout(async () => {
+      if (!alive || !reopen) return;
+      const { file, value } = reopen;
+      reopen = undefined;
+      replacing = true;
+      try {
+        const switchSession = switchers.byManager.get(ctx.sessionManager);
+        if (!switchSession) throw new Error('Session handover is unavailable; reopen the Session with /resume.');
+        const result = await switchSession(file);
+        if (result.cancelled) {
+          notify(ctx, 'Session handover reload was cancelled.');
+          blocked = undefined;
+        }
+      } catch (error) {
+        notify(ctx, error.message);
+        blocked = undefined;
+      } finally {
+        replacing = false;
+        discardPending(file, value);
+      }
+    }, 0);
+  }
+
+  pi.on('session_start', async (event, ctx) => {
+    const manager = ctx.sessionManager;
+    const file = manager.getSessionFile();
+    try {
+      if (file && !locks.has(manager)) {
+        const transfer = pending.get(pendingKey(file));
+        if (event.reason === 'resume' && transfer?.id === manager.getSessionId()) {
+          pending.delete(pendingKey(file));
+          locks.set(manager, transfer.lock);
+        } else {
+          // Target loading has already happened. A takeover here would leave
+          // stale shutdown writers attached to the same Session file.
+          locks.set(manager, reserve(stateDir, file, manager.getSessionId()));
+        }
+      }
+      if (runtime.start) await runtime.start(ctx);
+      blocked = undefined;
+    } catch (error) {
+      blocked = error.message;
+      if (ctx.mode === 'tui' && error.code === 'SESSION_OCCUPIED') {
+        await ctx.ui.select(blocked, ['Quit']);
+      } else notify(ctx, blocked);
+      // A thrown session_start error is swallowed by Pi. Explicitly quarantine
+      // normal input/tool execution while the host performs graceful shutdown.
+      ctx.shutdown();
+    }
+  });
+
+  pi.on('session_before_switch', (event, ctx) => {
+    if (blocked && !replacing) return { cancel: true };
+    if (event.reason !== 'resume' || !event.targetSessionFile) return;
+    try {
+      const file = resolvePath(event.targetSessionFile);
+      const current = ctx.sessionManager.getSessionFile();
+      if (current && canonicalPath(file) === canonicalPath(current)) return;
+      const transfer = pending.get(pendingKey(file));
+      if (transfer) return;
+      const id = readSessionId(file);
+      const acquired = lock => {
+        if (!alive || !lock) {
+          lock?.release();
+          return { cancel: true };
+        }
+        const value = savePending(file, id, lock);
+        reopen = { file, value };
+        blocked = 'Switching to the latest Session';
+        // Switch again later so a cancellation releases the lock.
+        scheduleReopen(ctx);
+        return { cancel: true };
+      };
+      const lock = reserve(stateDir, file, id);
+      if (ctx.mode === 'tui' && id) return acquired(lock);
+      lock.release();
+    } catch (error) {
+      notify(ctx, error.message);
+      return { cancel: true };
+    }
+  });
+
+  pi.on('session_shutdown', async (event, ctx) => {
+    alive = false;
+    if (runtime.stop) await runtime.stop(ctx);
+    if (event.reason === 'reload') {
+      // Cancel the old continuation and release its unclaimed target lock.
+      if (reopen) discardPending(reopen.file, reopen.value);
+      reopen = undefined;
+      return;
+    }
+    if (event.reason === 'quit' && reopen) {
+      discardPending(reopen.file, reopen.value);
+      reopen = undefined;
+    }
+    locks.get(ctx.sessionManager)?.release();
+    locks.delete(ctx.sessionManager);
+  });
+  pi.on('input', (_event, ctx) => {
+    if (!blocked) return;
+    notify(ctx, blocked);
+    return { action: 'handled' };
+  });
+  pi.on('tool_call', () => blocked ? { block: true, reason: blocked, terminate: true } : undefined);
+  pi.on('user_bash', () => blocked ? { result: { output: blocked, exitCode: 1, cancelled: true, truncated: false } } : undefined);
+  for (const event of ['session_before_compact', 'session_before_tree', 'session_before_fork']) {
+    pi.on(event, () => blocked ? { cancel: true } : undefined);
+  }
+}

package/src/roots/locks.mjs

@@ -0,0 +1,167 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { closeSync, constants, lstatSync, mkdirSync, openSync, readdirSync, realpathSync, unlinkSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+/** The Session ID of a lock key: `id:<id>`, or `path:<file>` whose name ends with `_<id>.jsonl`. */
+function sessionLabel(key) {
+  if (key.startsWith('id:')) return key.slice(3);
+  return basename(key.slice(5), '.jsonl').split('_').pop();
+}
+
+export class SessionOccupiedError extends Error {
+  constructor(sessionId, owner) {
+    const label = sessionLabel(sessionId);
+    super(`[pi-agents] Session ${label} is in use${owner ? ` (PID ${owner.pid})` : ''}. Quit the other Pi instance.`);
+    this.name = 'SessionOccupiedError';
+    this.code = 'SESSION_OCCUPIED';
+    this.sessionId = sessionId;
+    this.owner = owner;
+  }
+}
+
+// Each contender for a lock creates its own file, `<key hash>.<pid>-<start>.lock`, and holds the
+// lock if no other live process has such a file. Only its creator or a pruner of a dead process
+// removes a file, so a holder's file never disappears under it.
+const RETRIES = 3;
+
+function pidAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { if (error.code === 'ESRCH') return false; if (error.code === 'EPERM') return true; throw error; }
+}
+
+/** When the process started, as ps reports it, or NaN without ps. */
+function startOf(pid) {
+  const ps = spawnSync('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', env: { ...process.env, LC_ALL: 'C' } });
+  return ps.status === 0 ? Date.parse(ps.stdout.trim()) : NaN;
+}
+
+// The process's own start comes from ps too, since a wrapper may have exec'd Node long after the PID began.
+// Without ps it is unknown (0), and others then trust the PID alone.
+let selfStart;
+const ownStart = () => selfStart ??= startOf(process.pid) || 0;
+
+/** Whether a lock's holder still runs. A process that reused its PID started later; without a known start, the PID is trusted. */
+function alive(owner) {
+  if (owner.pid === process.pid) return owner.start === ownStart();
+  if (!pidAlive(owner.pid)) return false;
+  if (owner.start === 0) return true;
+  const started = startOf(owner.pid);
+  return Number.isNaN(started) || Math.abs(owner.start - started) < 3000;
+}
+
+const keyHash = sessionId => createHash('sha256').update(sessionId).digest('hex');
+
+/** The lock files in `stateDir`, optionally only those of one key, with their holders. */
+function lockFiles(stateDir, hash) {
+  let names;
+  try { names = readdirSync(stateDir); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  return names.flatMap(name => {
+    const match = /^([0-9a-f]{64})\.(\d+)-(\d+)\.lock$/.exec(name);
+    if (!match || (hash && match[1] !== hash)) return [];
+    return [{ path: join(stateDir, name), owner: { pid: Number(match[2]), start: Number(match[3]) } }];
+  });
+}
+
+function removeFile(path) {
+  try { unlinkSync(path); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+
+const pause = new Int32Array(new SharedArrayBuffer(4));
+
+function createLock({ stateDir, sessionId }) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) throw new Error('Session ID is required');
+  mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const directory = lstatSync(stateDir);
+  if (!directory.isDirectory() || directory.uid !== process.getuid() || (directory.mode & 0o077) !== 0) {
+    throw new Error(`Lock directory must be a private directory owned by the current user: ${stateDir}`);
+  }
+  const hash = keyHash(sessionId);
+  const owner = { pid: process.pid, start: ownStart() };
+  const path = join(stateDir, `${hash}.${owner.pid}-${owner.start}.lock`);
+  for (let attempt = 0; ; attempt++) {
+    closeSync(openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600));
+    let other;
+    for (const lock of lockFiles(stateDir, hash)) {
+      if (lock.path === path) continue;
+      if (alive(lock.owner)) other ??= lock;
+      else removeFile(lock.path);
+    }
+    if (!other) return { owner, release() { removeFile(path); } };
+    removeFile(path);
+    // Contenders that see each other both back off; a short random pause lets one of them win.
+    if (attempt === RETRIES) throw new SessionOccupiedError(sessionId, other.owner);
+    Atomics.wait(pause, 0, 0, 5 + Math.random() * 20);
+  }
+}
+
+/** Removes the lock files of processes that ended without releasing them. */
+export function pruneLocks(stateDir) {
+  for (const lock of lockFiles(stateDir)) if (!alive(lock.owner)) removeFile(lock.path);
+}
+
+// A process's own lock reads as held, so the extension, the guard and a
+// /resume wait share each lock through one reference-counted table.
+const locks = globalThis[Symbol.for('pi-agents.locks')] ??= new Map();
+
+const tableKey = (stateDir, sessionId) => `${resolve(stateDir)}\n${sessionId}`;
+
+export function acquireLock(options) {
+  const key = tableKey(options.stateDir, options.sessionId);
+  let entry = locks.get(key);
+  if (!entry) {
+    entry = { lock: createLock(options), refs: 0 };
+    locks.set(key, entry);
+  }
+  entry.refs++;
+  let released = false;
+  return {
+    owner: entry.lock.owner,
+    release() {
+      if (released) return;
+      released = true;
+      if (--entry.refs > 0) return;
+      locks.delete(key);
+      entry.lock.release();
+    },
+  };
+}
+
+export function canonicalPath(path) {
+  try { return realpathSync(path); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return join(canonicalPath(dirname(path)), basename(path));
+  }
+}
+
+export function lockKeys(sessionFile, id) {
+  return [`path:${canonicalPath(sessionFile)}`, ...(id ? [`id:${id}`] : [])];
+}
+
+function reserveKeys(stateDir, keys) {
+  const held = [];
+  try {
+    for (const sessionId of keys) held.push(acquireLock({ stateDir, sessionId }));
+  } catch (error) {
+    for (const lock of held) lock.release();
+    throw error;
+  }
+  return { release() { for (const lock of held) lock.release(); } };
+}
+
+// This process may acquire its own locks again, so only another process can hold them.
+function heldElsewhere(stateDir, sessionId) {
+  if (locks.has(tableKey(stateDir, sessionId))) return false;
+  return lockFiles(stateDir, keyHash(sessionId)).some(lock => alive(lock.owner));
+}
+
+/** Whether `reserve` would find the Session occupied, without creating or acquiring its locks. */
+export function isLocked(stateDir, sessionFile, id) {
+  return lockKeys(sessionFile, id).some(key => heldElsewhere(stateDir, key));
+}
+
+export function reserve(stateDir, sessionFile, id) {
+  return reserveKeys(stateDir, lockKeys(sessionFile, id));
+}

package/src/roots/paths.mjs

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { lstat, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Pi does not export its resolvePath; session paths only need ~ and file:// handling.
+export function resolvePath(input) {
+  const path = input.startsWith('file://') ? fileURLToPath(input) : input;
+  return resolve(path === '~' ? homedir() : path.startsWith('~/') ? join(homedir(), path.slice(2)) : path);
+}
+
+/**
+ * Kept data lives in the state directory; locks and sockets, which live only while their process
+ * does, in `$XDG_RUNTIME_DIR` (macOS has none, so `runtime/` in the state directory).
+ */
+export function statePaths(env = process.env) {
+  const state = env.PI_AGENTS_STATE_DIR
+    ? resolve(env.PI_AGENTS_STATE_DIR)
+    : join(env.XDG_STATE_HOME ?? join(homedir(), '.local/state'), 'pi/agents');
+  const runtime = !env.PI_AGENTS_STATE_DIR && env.XDG_RUNTIME_DIR ? join(env.XDG_RUNTIME_DIR, 'pi-agents') : join(state, 'runtime');
+  return {
+    state,
+    runtime,
+    workbench: join(state, 'workbench.json'),
+    hostLog: join(state, 'host.log'),
+    daemonLog: join(state, 'daemon.log'),
+    host(pid) { return join(runtime, `h-${pid}.sock`); },
+    locks: join(runtime, 'locks'),
+    daemon: join(runtime, 'daemon.sock'),
+    session(id) { return join(runtime, `s-${createHash('sha256').update(id).digest('hex').slice(0, 24)}.sock`); },
+  };
+}
+
+/** Pi's agent directory: PI_CODING_AGENT_DIR, or ~/.pi/agent. */
+export function agentDir(env = process.env) {
+  return env.PI_CODING_AGENT_DIR ? resolvePath(env.PI_CODING_AGENT_DIR) : join(homedir(), '.pi/agent');
+}
+
+/** The session directory configured without `--session-dir`: PI_CODING_AGENT_SESSION_DIR, then the global `sessionDir` setting. */
+export function configuredSessionDir(env = process.env) {
+  if (env.PI_CODING_AGENT_SESSION_DIR) return resolvePath(env.PI_CODING_AGENT_SESSION_DIR);
+  let setting;
+  try { setting = JSON.parse(readFileSync(join(agentDir(env), 'settings.json'), 'utf8').replace(/^\uFEFF/, '')).sessionDir; }
+  catch (error) { if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) throw error; }
+  if (typeof setting === 'string' && setting) return resolvePath(setting);
+}
+
+/** Pi's session directory without `--session-dir`: the configured one, or `sessions/` in the agent directory. */
+export function sessionDir(env = process.env) {
+  return configuredSessionDir(env) ?? join(agentDir(env), 'sessions');
+}
+
+/** The directory Pi keeps a cwd's Sessions in when none is configured. */
+export function defaultSessionDir(cwd, env = process.env) {
+  return join(agentDir(env), 'sessions', `--${resolve(cwd).replace(/^\//, '').replace(/[/\\:]/g, '-')}--`);
+}
+
+export async function prepareDirectory(directory) {
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.uid !== process.getuid() || (info.mode & 0o077)) {
+    throw new Error(`Agent runtime directory must be private and owned by the current user: ${directory}`);
+  }
+}