piher 0.0.0-stage → 0.2.0

package/src/lock-core.ts

@@ -0,0 +1,200 @@
+/**
+ * M18 file-level write locks (S2: soft veto by default, `PIHER_WRITE_LOCK=1` makes it hard).
+ *
+ * A lock is a *beacon*, not a mutex: the terminal editing a file sets a label on itself
+ * (`piher.lock.<hash>` → `terminalId|path`) and every other terminal reads the live terminals' labels
+ * to warn or block. Each terminal writes only its own labels, so beacons never race; a finished
+ * terminal drops out of `terminal.list`, so its beacons expire with it.
+ */
+import { resolve, sep } from 'node:path';
+
+export const WRITE_LOCK_ENV = 'PIHER_WRITE_LOCK';
+export const WRITE_TOOLS = ['write', 'edit'] as const;
+export const LOCK_TOKEN_PREFIX = 'piher.lock.';
+
+export interface LockAgentView {
+  paneId: string;
+  tokens: Record<string, string | null>;
+}
+
+/** Case-folded, separator-unified absolute path: the key every lock lookup agrees on. */
+export function normalizeLockPath(p: string, cwd: string): string {
+  const abs = resolve(cwd, p);
+  const unified = sep === '\\' ? abs.replace(/\\/g, '/') : abs;
+  return unified.toLowerCase().replace(/\/+$/, '');
+}
+
+export function fnv1a64(s: string): string {
+  let h = 0xcbf29ce484222325n;
+  for (let i = 0; i < s.length; i++) {
+    h ^= BigInt(s.charCodeAt(i));
+    h = (h * 0x100000001b3n) & 0xffffffffffffffffn;
+  }
+  return h.toString(16).padStart(16, '0');
+}
+
+export function lockTokenKey(normPath: string): string {
+  return `${LOCK_TOKEN_PREFIX}${fnv1a64(normPath)}`;
+}
+
+export function lockTokenValue(normPath: string, paneId: string): string {
+  return `${paneId}|${normPath}`;
+}
+
+export function parseLockTokenValue(v: string): { holderPaneId: string; path: string } | null {
+  const i = v.indexOf('|');
+  if (i <= 0 || i === v.length - 1) return null;
+  return { holderPaneId: v.slice(0, i), path: v.slice(i + 1) };
+}
+
+export function isLockTokenKey(key: string): boolean {
+  return key.startsWith(LOCK_TOKEN_PREFIX) && key.length > LOCK_TOKEN_PREFIX.length;
+}
+
+export function writePathsOfTool(toolName: string, input: unknown): string[] {
+  if (!(WRITE_TOOLS as readonly string[]).includes(toolName)) return [];
+  const p = (input as { path?: unknown } | null | undefined)?.path;
+  return typeof p === 'string' && p.trim() ? [p] : [];
+}
+
+/**
+ * B7: write-locks only see the write/edit tools, so a `bash` command that redirects into a file bypasses
+ * the beacon entirely (`> file`, `>> file`, `tee file`, `sed -i`, `truncate -s 0`). We do not try to parse
+ * shell: this extracts the *obvious* targets so the lock layer can warn (never block) — a false negative is
+ * cheap, a false block is not.
+ */
+export function bashWriteTargets(command: unknown): string[] {
+  if (typeof command !== 'string' || command.trim() === '') return [];
+  const found: string[] = [];
+  // Quoted or bare targets; stops at shell metacharacters, ignores process substitution.
+  const target = String.raw`(?:'([^']+)'|"([^"]+)"|([^\s;|&<>()]+))`;
+  const patterns = [
+    new RegExp(String.raw`(?:^|[^0-9>])>>?\s*` + target, 'g'), // > file, >> file
+    new RegExp(String.raw`\btee\s+(?:-a\s+)?` + target, 'g'), // tee [-a] file
+    new RegExp(String.raw`\btruncate\s+-s\s*0\s+` + target, 'g'), // truncate -s 0 file
+  ];
+  for (const re of patterns) {
+    for (const m of command.matchAll(re)) {
+      const path = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+      const quoted = m[1] !== undefined || m[2] !== undefined;
+      if (isObviousPath(path, quoted)) found.push(path);
+    }
+  }
+  // `sed -i '' 's/a/b/' file`: the first argument is the (possibly empty) backup suffix and the
+  // second the expression, so the LAST argument is the file.
+  for (const m of command.matchAll(/\bsed\s+-i[^\s]*\s+([^|;&\n]+)/g)) {
+    const args = splitShellWords(m[1] ?? '');
+    for (let i = args.length - 1; i >= 0; i -= 1) {
+      const candidate = args[i]!;
+      if (candidate.startsWith('-')) continue;
+      if (isObviousPath(candidate)) found.push(candidate);
+      break;
+    }
+  }
+  return [...new Set(found)];
+}
+
+/** Only unquoted, metacharacter-free paths count as "obvious" (anything else is left to the shell). */
+function isObviousPath(path: string, quoted = false): boolean {
+  if (path === '' || path === '/' || path.startsWith('$')) return false;
+  if (/['"`$*?{}()[\]]/.test(path)) return false; // Never a literal path (expansion, glob, nested quotes).
+  return quoted ? true : !/\s/.test(path); // An explicitly quoted target may contain spaces.
+}
+
+/** Whitespace split that keeps quoted segments together and strips their quotes. */
+function splitShellWords(input: string): string[] {
+  const out: string[] = [];
+  for (const m of input.matchAll(/'([^']*)'|"([^"]*)"|(\S+)/g)) out.push(m[1] ?? m[2] ?? m[3] ?? '');
+  return out.filter((s) => s !== '');
+}
+
+/** Soft hint shown after a bash call that wrote into a path another pane has locked. */
+function formatBashLockHint(normPath: string, holders: readonly string[]): string {
+  return `Note: this bash command wrote to ${normPath}, which ${holdersLabel(holders)} is editing. `
+    + `Write-locks only cover the write/edit tools, so this write was not blocked: re-read the file before your next edit.`;
+}
+
+/** Every *other* pane holding a beacon for this path (deduped, in list order — several panes can hold
+ *  the same path, so callers get the whole list). */
+export function findLockHolders(
+  agents: readonly LockAgentView[],
+  ownPaneId: string,
+  normPath: string,
+): string[] {
+  const key = lockTokenKey(normPath);
+  const holders: string[] = [];
+  for (const a of agents) {
+    const v = a.tokens[key];
+    if (typeof v !== 'string' || !v) continue;
+    const parsed = parseLockTokenValue(v);
+    if (parsed && parsed.holderPaneId !== ownPaneId && !holders.includes(parsed.holderPaneId)) {
+      holders.push(parsed.holderPaneId);
+    }
+  }
+  return holders;
+}
+
+/** Where to look for the full holder table: humans use the slash command, agents read core labels. */
+const LOCK_HOLDERS_HINT =
+  'holders: /piher-locks (human view in this pane) · `hc ls` → labels piher.lock.* (agent-readable)';
+
+function holdersLabel(holders: readonly string[]): string {
+  return holders.length === 1 ? `pane ${holders[0]}` : `panes ${holders.join(', ')}`;
+}
+
+function formatConflictWarning(normPath: string, holders: readonly string[]): string {
+  return `⚠️ write conflict: ${normPath} is locked by ${holdersLabel(holders)} (edited in another pane that has not settled). This write went through (soft mode) — coordinate to avoid clobbering each other's changes. ${LOCK_HOLDERS_HINT}`;
+}
+
+export type WriteGuardPlan =
+  | { kind: 'skip' }
+  | { kind: 'pass'; paths: string[] }
+  | { kind: 'warn'; paths: string[]; holderPaneIds: string[]; warning: string }
+  | { kind: 'block'; paths: string[]; holderPaneIds: string[]; reason: string };
+
+export function planWriteGuard(opts: {
+  toolName: string;
+  input: unknown;
+  agents: readonly LockAgentView[];
+  ownPaneId: string;
+  cwd: string;
+  hard: boolean;
+}): WriteGuardPlan {
+  const isBash = opts.toolName === 'bash';
+  const raw = isBash
+    ? bashWriteTargets((opts.input as { command?: unknown } | null | undefined)?.command)
+    : writePathsOfTool(opts.toolName, opts.input);
+  if (raw.length === 0) return { kind: 'skip' };
+  const paths = raw.map((p) => normalizeLockPath(p, opts.cwd));
+  for (const norm of paths) {
+    const holders = findLockHolders(opts.agents, opts.ownPaneId, norm);
+    if (holders.length === 0) continue;
+    if (opts.hard && !isBash) {
+      return {
+        kind: 'block',
+        paths,
+        holderPaneIds: holders,
+        reason: `file locked by ${holdersLabel(holders)}: ${norm} is being edited in another pane. Wait for it to settle, or coordinate before writing. ${LOCK_HOLDERS_HINT}`,
+      };
+    }
+    return {
+      kind: 'warn',
+      paths,
+      holderPaneIds: holders,
+      warning: isBash ? formatBashLockHint(norm, holders) : formatConflictWarning(norm, holders),
+    };
+  }
+  return { kind: 'pass', paths };
+}
+
+export function acquireTokensFor(normPaths: readonly string[], paneId: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const p of normPaths) out[lockTokenKey(p)] = lockTokenValue(p, paneId);
+  return out;
+}
+
+export function releaseTokensFor(normPaths: readonly string[]): Record<string, null> {
+  const out: Record<string, null> = {};
+  for (const p of normPaths) out[lockTokenKey(p)] = null;
+  return out;
+}

package/src/manifest-compose.ts

@@ -0,0 +1,103 @@
+/**
+ * Manifest composition (C7 v2 three-state permissions): role baseline ∪ model suggestion,
+ * minus deny rules, with the D82 unknown-tools stance carried through.
+ */
+import type { PermissionAction, RoleManifest, UnknownToolStance } from './role-manifest.ts';
+import type { RuntimeRoleManifest } from './tool-gate.ts';
+import { loadRoleConfig } from './role-loader.ts';
+
+export interface ManifestSources {
+  roleBaseline: readonly string[];
+  modelSuggested: readonly string[];
+  rulePermissions: Record<string, PermissionAction>;
+  /** D82: stance for tools outside the composed set. */
+  unknownTools?: UnknownToolStance;
+}
+
+/** What composeManifest produces: the runtime manifest minus the identity/section fields. */
+export type ComposedManifest = Omit<RuntimeRoleManifest, 'role' | 'version' | 'guidelines' | 'instructions'>;
+
+export class ManifestError extends Error {
+  readonly code: 'EMPTY_MANIFEST' | 'INVALID_ROLE_CONFIG';
+  constructor(code: 'EMPTY_MANIFEST' | 'INVALID_ROLE_CONFIG', message: string) {
+    super(message);
+    this.name = 'ManifestError';
+    this.code = code;
+  }
+}
+
+export interface ComposedForRole {
+  role: RoleManifest;
+  manifest: ComposedManifest;
+}
+
+export function composeManifest(sources: ManifestSources): ComposedManifest {
+  const baseline = sources.roleBaseline.filter((t): t is string => typeof t === 'string' && t.trim() !== '');
+  if (baseline.length === 0) {
+    throw new ManifestError(
+      'INVALID_ROLE_CONFIG',
+      'INVALID_ROLE_CONFIG: baseline tools must not be empty',
+    );
+  }
+  const candidates = new Set<string>([
+    ...baseline,
+    ...sources.modelSuggested.filter((t): t is string => typeof t === 'string' && t.trim() !== ''),
+  ]);
+  const rules = sources.rulePermissions ?? {};
+  const defaultAction: PermissionAction = rules['*'] ?? 'allow';
+
+  const tools: string[] = [];
+  const permissions: Record<string, PermissionAction> = {};
+  // Rule keys outside the candidate set stay in permissions: an allow-stance role keeps its
+  // deny rules for tools the model never suggested (D82 excluded families).
+  for (const [key, action] of Object.entries(rules)) {
+    if (key !== '*') permissions[key] = action;
+  }
+  for (const tool of candidates) {
+    const action = rules[tool] ?? defaultAction;
+    permissions[tool] = action;
+    if (action !== 'deny') tools.push(tool);
+  }
+
+  if (tools.length === 0) {
+    throw new ManifestError(
+      'EMPTY_MANIFEST',
+      `Trimmed manifest is empty (deny-all trap?). Baseline: ${baseline.join(', ') || '(empty)'}; ` +
+        `model suggestions: ${sources.modelSuggested.join(', ') || '(none)'}; ` +
+        `rules: ${JSON.stringify(rules)}`,
+    );
+  }
+
+  tools.sort();
+  return { tools, permissions, unknownTools: sources.unknownTools ?? 'deny' };
+}
+
+export function composeForRole(
+  roleName: string,
+  modelSuggested: readonly string[],
+  opts?: { loadRole?: typeof loadRoleConfig; loadRoleOpts?: Parameters<typeof loadRoleConfig>[1] },
+): ComposedForRole {
+  const load = opts?.loadRole ?? loadRoleConfig;
+  const role = load(roleName, opts?.loadRoleOpts);
+  const manifest = composeManifest({
+    roleBaseline: role.manifest.tools,
+    modelSuggested,
+    rulePermissions: role.manifest.rules ?? { '*': 'allow' },
+    unknownTools: role.manifest.unknownTools,
+  });
+  return { role, manifest };
+}
+
+/** Project a composed profile onto the runtime shape — the one place role-file fields become runtime fields. */
+export function toRuntimeManifest(composed: ComposedForRole): RuntimeRoleManifest {
+  const { role, manifest } = composed;
+  return {
+    role: role.role,
+    version: role.version,
+    tools: manifest.tools,
+    permissions: manifest.permissions,
+    unknownTools: manifest.unknownTools,
+    ...(role.guidelines?.length ? { guidelines: role.guidelines } : {}),
+    ...(role.instructions ? { instructions: role.instructions } : {}),
+  };
+}

package/src/options.ts

@@ -0,0 +1,78 @@
+/**
+ * Environment options. `PIHER_*` is the one namespace for *piher options* (timeouts,
+ * windows, toggles), and this file is their single registry.
+ *
+ * `PIHER_SUBAGENT`, `PIHER_DELEGATION`, `PIHER_ROLE_MANIFEST` and `PIHER_ROLE_BASE` are not
+ * listed here: they are *contracts* handed to the child process at spawn, not knobs a user sets.
+ *
+ * `optionValue()` is the single reader; this registry is also the single source of the numeric
+ * bounds/defaults behind `runtimePolicy` (runtime-policy.ts) and the `/piher-config` catalog
+ * (config-catalog-core.ts), so a knob cannot mean three different things.
+ */
+
+/** RuntimePolicy field fed by an integer option (see runtime-policy.ts). */
+export type PolicyField =
+  | 'subagentTimeoutMs'
+  | 'gcTickMs'
+  | 'pollIntervalMs'
+  | 'settleWindowMs'
+  | 'sessionTtlSeconds'
+  | 'gitTimeoutMs'
+  | 'readinessTimeoutMs';
+
+export interface OptionSpec {
+  readonly name: string;
+  /** Default when the variable is unset (or empty). */
+  readonly fallback: string;
+  readonly description: string;
+  /** Integer option: smallest value the readers accept (omitted for string/enum options). */
+  readonly min?: number;
+  /** Integer option read into `RuntimePolicy`. */
+  readonly policy?: PolicyField;
+}
+
+/** Every option, with its default and bounds. */
+export const OPTION_SPECS: readonly OptionSpec[] = [
+  { name: 'PIHER_GIT_TIMEOUT_MS', fallback: '10000', min: 1, policy: 'gitTimeoutMs', description: 'git command timeout (worktree list and status probes)' },
+  { name: 'PIHER_SUBAGENT_TIMEOUT_MS', fallback: '300000', min: 1000, policy: 'subagentTimeoutMs', description: 'how long a subagent may stay silent before the master is told it never reported' },
+  { name: 'PIHER_READY_TIMEOUT_MS', fallback: '90000', min: 1000, policy: 'readinessTimeoutMs', description: 'how long to wait for a spawned pane to open its pipe (a dead pane fails fast)' },
+  { name: 'PIHER_SETTLE_WINDOW_MS', fallback: '4000', min: 0, policy: 'settleWindowMs', description: 'debounce after a subagent turn ends before it is called settled (a new turn cancels it)' },
+  { name: 'PIHER_POLL_INTERVAL_MS', fallback: '30000', min: 1000, policy: 'pollIntervalMs', description: 'safety re-check of a subagent when no core event arrives (events drive settlement)' },
+  { name: 'PIHER_GC_TICK_MS', fallback: '30000', min: 1000, policy: 'gcTickMs', description: 'idle GC sweep cadence (panes)' },
+  { name: 'PIHER_SESSION_TTL_SECONDS', fallback: '600', min: 0, policy: 'sessionTtlSeconds', description: 'session retention after a subagent exits, before GC' },
+  { name: 'PIHER_WRITE_LOCK', fallback: '', description: '1 makes a conflicting write/edit block instead of warn (read by the lock layer)' },
+  { name: 'PIHER_JOBS_DIR', fallback: '(system temp)/piher-jobs', description: 'directory receiving one log file per background job' },
+  { name: 'PIHER_HMR', fallback: '', description: 'dev: enable the cordis HMR boundary (requires --expose-internals)' },
+];
+
+/** A knob's effective value, or undefined when it is unset (an empty string counts as unset). */
+export function optionValue(
+  name: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const raw = env[name];
+  return typeof raw === 'string' && raw.trim() !== '' ? raw : undefined;
+}
+
+export function optionRows(env: NodeJS.ProcessEnv = process.env): Array<{
+  name: string;
+  value: string;
+  source: 'env' | 'default';
+  description: string;
+}> {
+  return OPTION_SPECS.map((spec) => {
+    const value = optionValue(spec.name, env);
+    return {
+      name: spec.name,
+      value: value ?? spec.fallback,
+      source: value === undefined ? 'default' : 'env',
+      description: spec.description,
+    } as const;
+  });
+}
+
+/** `/piher-config doctor` table, one line per option: `NAME = value (source) — description`. */
+export function formatOptionRows(env: NodeJS.ProcessEnv = process.env): string[] {
+  return optionRows(env).map((row) =>
+    `  ${row.name} = ${row.value}  (${row.source})  — ${row.description}`);
+}

package/src/pi-surface.ts

@@ -0,0 +1,140 @@
+/**
+ * Proxy the pi ExtensionAPI registration surface (D79).
+ *
+ * pi 0.86+ `pi.on()` returns an unsubscribe, so event handlers are truly removed when their generation
+ * retires (RFC docs/rfc-pi-0.86-dynamic-tools.md §5). Tools and commands have no unregister API: tools
+ * overwrite by name, so retired generations keep tombstoned wrappers there. HMR emits reload after
+ * mounting the replacement, so mounting a key retires older generations immediately; the ledger then
+ * collects only generations registered through the reload boundary.
+ */
+import type { DisposeLedger } from './ledger.ts';
+
+/** Minimal pi ToolResult shape used when a disposed tool is invoked. */
+const INERT_TOOL_RESULT = {
+  content: [{ type: 'text' as const, text: 'Error: tool module disposed (hot-reloaded away); the new version has re-registered it.' }],
+  details: {},
+};
+
+/** Module-scoped surface: tombstone tools and events, while command replacement is safe because pi stores commands in a Map. */
+export interface ScopedSurface {
+  registerTool(def: Record<string, unknown> & { name: string }): void;
+  registerCommand(name: string, options: Record<string, unknown>): void;
+  on(event: string, handler: (...args: unknown[]) => unknown): void;
+}
+
+interface Group {
+  alive: boolean;
+  /** Monotonic mount generation used by the ledger disposer to determine its collection boundary. */
+  epoch: number;
+  unsubscribes: Array<() => void>;
+}
+
+/** Flip the tombstone and drain any native unsubscribes; retirement must never throw. */
+function retireGroup(group: Group): void {
+  group.alive = false;
+  for (const off of group.unsubscribes) {
+    try {
+      off();
+    } catch {
+    }
+  }
+  group.unsubscribes.length = 0;
+}
+
+/** Proxy for pi's registration surface (D79); non-registration methods (append/exec/setActiveTools, etc.) pass through raw. */
+export class PiSurface<P extends object> {
+  private groups = new Map<string, Group>();
+  /** Generation history per key; mounting retires older generations so at most one stays alive until ledger collection. */
+  private generations = new Map<string, Group[]>();
+  private epochCounter = 0;
+  /** Ledger generation boundary; disposal collects epochs up to this value, then the next mount registers again. */
+  private ledgerEntryEpoch = new Map<string, number>();
+  private readonly pi: P;
+  private readonly ledger?: DisposeLedger;
+
+  constructor(pi: P, ledger?: DisposeLedger) {
+    this.pi = pi;
+    this.ledger = ledger;
+  }
+
+  /** Raw pi surface, bypassing wrappers; migrated modules must not use it for registration. */
+  get raw(): P {
+    return this.pi;
+  }
+
+  /** Get a module-scoped registration surface; each call creates a new generation, retiring older ones
+   *  for the same key. The ledger registers each key once and again only after its entry is consumed. */
+  forModule(key: string): ScopedSurface {
+    this.epochCounter += 1;
+    const epoch = this.epochCounter;
+    for (const g of this.generations.get(key) ?? []) retireGroup(g);
+    const group: Group = { alive: true, epoch, unsubscribes: [] };
+    this.generations.set(key, [group]);
+    this.groups.set(key, group);
+    if (this.ledger && !this.ledgerEntryEpoch.has(key)) {
+      this.ledgerEntryEpoch.set(key, epoch);
+      this.ledger.add(key, () => {
+        const bound = this.ledgerEntryEpoch.get(key) ?? epoch;
+        this.ledgerEntryEpoch.delete(key);
+        this.generations.set(
+          key,
+          (this.generations.get(key) ?? []).filter((g) => {
+            if (g.epoch <= bound) {
+              retireGroup(g);
+              return false;
+            }
+            return true;
+          }),
+        );
+      });
+    }
+    return {
+      registerTool: (def) => {
+        const original = def.execute as ((...a: unknown[]) => unknown) | undefined;
+        const wrapped = original
+          ? async (...a: unknown[]) => {
+            if (!group!.alive) return INERT_TOOL_RESULT;
+            return original(...a);
+          }
+          : undefined;
+        (this.pi as { registerTool?: (d: unknown) => void }).registerTool?.(
+          wrapped ? { ...def, execute: wrapped } : def,
+        );
+      },
+      registerCommand: (name, options) => {
+        // pi stores commands as Map<name>, so same-name registration replaces safely; the handler
+        // tombstone is a symmetry safeguard even though the old handler will no longer be called.
+        const handler = options.handler as ((...a: unknown[]) => unknown) | undefined;
+        const wrapped = handler
+          ? (...a: unknown[]) => (group!.alive ? handler(...a) : undefined)
+          : undefined;
+        (this.pi as { registerCommand?: (n: string, o: Record<string, unknown>) => void })
+          .registerCommand?.(name, wrapped ? { ...options, handler: wrapped } : options);
+      },
+      on: (event, handler) => {
+        // Pass-through while alive, tombstone after retirement; when pi (0.86+) returns an unsubscribe,
+        // retirement also removes the registration so HMR churn cannot grow the dispatch list.
+        const wrapped = (...a: unknown[]) => (group!.alive ? handler(...a) : undefined);
+        const unsubscribe: unknown = (
+          this.pi as { on?: (e: string, h: (...a: unknown[]) => unknown) => unknown }
+        ).on?.(event, wrapped);
+        if (typeof unsubscribe === 'function') {
+          group.unsubscribes.push(unsubscribe as () => void);
+        }
+      },
+    };
+  }
+
+  disposeModule(key: string): boolean {
+    const had = this.groups.has(key);
+    for (const g of this.generations.get(key) ?? []) retireGroup(g);
+    this.generations.delete(key);
+    this.groups.delete(key);
+    this.ledgerEntryEpoch.delete(key);
+    return had;
+  }
+
+  get moduleCount(): number {
+    return this.groups.size;
+  }
+}