@mgiles/perk 3.1.0 → 3.3.0

package/extension/substrate/worktreeResolverLock.ts

@@ -0,0 +1,261 @@
+// Participating submit/address writers exclude each other by canonical worktree Git identity.
+// There is NO reclamation policy. Death, age, reload and cancellation cannot prove quiescence.
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
+  readSync,
+  type Stats,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { worktreeGitDir } from "./git.ts";
+
+const OWNER_LIMIT = 16 * 1024;
+export const WORKTREE_RESOLVER_LOCK = "perk-submit-conflict.lock";
+
+interface LockRecord {
+  schema: 1;
+  token: string;
+  pid: number;
+  parentSessionId: string;
+  ownerRunId: string;
+  requestId: string;
+  worktreeIdentity: string;
+  createdAt: string;
+}
+export type LockOwner = Omit<LockRecord, "token" | "schema">;
+export type LockFinish = {
+  kind: "released" | "retained" | "ownership-error" | "io-error";
+  path: string;
+};
+export interface WorktreeResolverClaim {
+  readonly path: string;
+  check(): "owned" | "ownership-error" | "io-error";
+  /** First choice wins, locally idempotent. Retain closes resources but never removes metadata. */
+  finish(disposition: "release" | "retain"): LockFinish;
+}
+export type WorktreeResolverAcquisition =
+  | { kind: "acquired"; claim: WorktreeResolverClaim }
+  | { kind: "unavailable" }
+  | { kind: "busy"; path: string; owner?: LockOwner }
+  | { kind: "io-error"; path: string; residue: boolean };
+
+/** Only deterministic filesystem fault tests substitute these operations. */
+export interface WorktreeLockFs {
+  open: typeof openSync;
+  close: typeof closeSync;
+  fstat: (fd: number) => Stats;
+  lstat: (path: string) => Stats;
+  read: (fd: number, buffer: Buffer, offset: number, length: number, position: number) => number;
+  write: (fd: number, data: string) => void;
+  sync: (fd: number) => void;
+  unlink: (path: string) => void;
+}
+const realFs: WorktreeLockFs = {
+  open: openSync,
+  close: closeSync,
+  fstat: fstatSync,
+  lstat: lstatSync,
+  read: readSync,
+  write: (fd, data) => writeFileSync(fd, data, "utf8"),
+  sync: fsyncSync,
+  unlink: unlinkSync,
+};
+function code(error: unknown): unknown {
+  return typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+}
+function sameFile(a: Stats, b: Stats): boolean {
+  return a.isFile() && b.isFile() && a.dev === b.dev && a.ino === b.ino;
+}
+function readRecord(fs: WorktreeLockFs, fd: number): LockRecord | null {
+  const size = fs.fstat(fd).size;
+  if (size <= 0 || size > OWNER_LIMIT) return null;
+  const bytes = Buffer.alloc(size);
+  let read = 0;
+  while (read < size) {
+    const n = fs.read(fd, bytes, read, size - read, read);
+    if (n === 0) return null;
+    read += n;
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+  if (
+    r.schema !== 1 ||
+    typeof r.token !== "string" ||
+    !r.token ||
+    typeof r.pid !== "number" ||
+    !Number.isInteger(r.pid) ||
+    r.pid <= 0
+  )
+    return null;
+  for (const field of [
+    "parentSessionId",
+    "ownerRunId",
+    "requestId",
+    "worktreeIdentity",
+    "createdAt",
+  ] as const) {
+    if (typeof r[field] !== "string" || !r[field]) return null;
+  }
+  return r as unknown as LockRecord;
+}
+function ownerOf(r: LockRecord): LockOwner {
+  return {
+    pid: r.pid,
+    parentSessionId: r.parentSessionId,
+    ownerRunId: r.ownerRunId,
+    requestId: r.requestId,
+    worktreeIdentity: r.worktreeIdentity,
+    createdAt: r.createdAt,
+  };
+}
+
+function incumbent(fs: WorktreeLockFs, path: string): WorktreeResolverAcquisition {
+  let fd: number | undefined;
+  try {
+    const stat = fs.lstat(path);
+    if (!stat.isFile() || stat.size > OWNER_LIMIT) return { kind: "busy", path };
+    fd = fs.open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!sameFile(stat, fs.fstat(fd))) return { kind: "busy", path };
+    const record = readRecord(fs, fd);
+    return { kind: "busy", path, ...(record ? { owner: ownerOf(record) } : {}) };
+  } catch (error) {
+    // Even a disappearing incumbent doesn't invite a retry. A racing external replacement is
+    // outside the protocol; ELOOP never follows the new symlink for diagnostic reads.
+    if (code(error) === "ENOENT" || code(error) === "ELOOP") return { kind: "busy", path };
+    return { kind: "io-error", path, residue: true };
+  } finally {
+    if (fd !== undefined) fs.close(fd);
+  }
+}
+
+export function acquireWorktreeResolverLock(
+  cwd: string,
+  parent: { sessionId: string; runId: string; requestId: string },
+  opts: {
+    fs?: Partial<WorktreeLockFs>;
+    gitDir?: (cwd: string) => string | null;
+    /** The token minter (default `randomUUID`) — only deterministic fault tests substitute it. */
+    token?: () => string;
+  } = {},
+): WorktreeResolverAcquisition {
+  const identity = (opts.gitDir ?? worktreeGitDir)(cwd);
+  if (identity === null) return { kind: "unavailable" };
+  const path = join(identity, WORKTREE_RESOLVER_LOCK);
+  const fs = { ...realFs, ...opts.fs };
+  let fd: number;
+  try {
+    fd = fs.open(path, "wx", 0o600);
+  } catch (error) {
+    if (code(error) === "EEXIST") {
+      try {
+        return incumbent(fs, path);
+      } catch {
+        return { kind: "io-error", path, residue: true };
+      }
+    }
+    return { kind: "io-error", path, residue: false };
+  }
+  // Everything after the exclusive create runs inside the cleanup-protected block — the record
+  // construction included: a token-minting failure must take the same identity-fenced unlink
+  // path as a write failure, never escape with the descriptor open and an empty lock file that
+  // would wedge every later acquisition as busy.
+  let stat: Stats | undefined;
+  let token: string;
+  try {
+    stat = fs.fstat(fd);
+    if (!stat.isFile()) throw new Error("not a regular file");
+    token = (opts.token ?? randomUUID)();
+    const record: LockRecord = {
+      schema: 1,
+      token,
+      pid: process.pid,
+      parentSessionId: parent.sessionId,
+      ownerRunId: parent.runId,
+      requestId: parent.requestId,
+      worktreeIdentity: identity,
+      createdAt: new Date().toISOString(),
+    };
+    fs.write(fd, `${JSON.stringify(record)}\n`);
+    fs.sync(fd);
+  } catch {
+    let residue = true;
+    try {
+      if (stat && sameFile(stat, fs.lstat(path))) {
+        fs.unlink(path);
+        residue = false;
+      }
+    } catch {
+      /* Report residue; never remove an unidentified or successor file. */
+    }
+    try {
+      fs.close(fd);
+    } catch {
+      residue = true;
+    }
+    return { kind: "io-error", path, residue };
+  }
+  const acquiredStat = stat;
+  let finished: LockFinish | undefined;
+  function check(): "owned" | "ownership-error" | "io-error" {
+    if (finished) return "ownership-error";
+    try {
+      if (!sameFile(acquiredStat, fs.lstat(path)) || !sameFile(acquiredStat, fs.fstat(fd)))
+        return "ownership-error";
+      const reader = fs.open(
+        path,
+        constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK,
+      );
+      try {
+        if (!sameFile(acquiredStat, fs.fstat(reader))) return "ownership-error";
+        return readRecord(fs, reader)?.token === token ? "owned" : "ownership-error";
+      } finally {
+        fs.close(reader);
+      }
+    } catch (error) {
+      return code(error) === "ENOENT" ? "ownership-error" : "io-error";
+    }
+  }
+  return {
+    kind: "acquired",
+    claim: {
+      path,
+      check,
+      finish(disposition) {
+        if (finished) return finished;
+        let kind: LockFinish["kind"] = "retained";
+        try {
+          if (disposition === "release") {
+            const ownership = check();
+            if (ownership === "owned") {
+              fs.unlink(path);
+              kind = "released";
+            } else kind = ownership;
+          }
+        } catch {
+          kind = "io-error";
+        } finally {
+          try {
+            fs.close(fd);
+          } catch {
+            kind = "io-error";
+          }
+        }
+        finished = { kind, path };
+        return finished;
+      },
+    },
+  };
+}

package/extension/surfaces/surfaces.ts

@@ -6,11 +6,11 @@
 // surfaces module" is surfaces.ts + report.ts for the surfaces guard).
 //
 // Perk status (charter §6 D2): perk presents ONE footer status under the single
-// `perk` slot — the single-value objective segment (the checkpoint substrate is retired, so
-// there is no composition step). The per-feature status slots and widgets are retired (D8
-// sanctioned). The perk-owned footer (`perkFooter`/`installPerkFooter` below) renders the value
-// directly; the `perk` status slot keeps publishing — it is the RPC-visible surface (setFooter
-// is an RPC no-op).
+// `perk` slot — the objective segment composed with the ref-counted activity facet
+// (`<objective> · <activity>`, either half optional). The per-feature status slots and widgets
+// are retired (D8 sanctioned). The perk-owned footer (`perkFooter`/`installPerkFooter` below)
+// renders the value directly; the `perk` status slot keeps publishing — it is the RPC-visible
+// surface (setFooter is an RPC no-op).
 
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { ReportDetailSink } from "./report.ts";
@@ -35,6 +35,19 @@ export const STATUS_SLOT_PERK = "perk";
 // --- footer identity marks (charter §5 / D3: emoji are footer-only identity, 2 cells wide) ---
 export const MARK_OBJECTIVE = "🎯";
 
+// --- activity vocabulary (the optional second half of the composed `perk` status) ---
+// Plain text, no emoji (D3 keeps emoji as identity marks): a Perk-owned wait the operator
+// cannot otherwise see.
+export const ACTIVITY_BROWSER_REVIEW = "waiting on browser review";
+/** The slice an activity owner takes: begin a wait with its text, receive the matching `end`. */
+export type ActivitySink = (text: string) => () => void;
+/**
+ * The least-capable slice a wiring layer threads toward an activity owner: begin a wait against
+ * the live target, nothing else. The full `PerkStatusHandle` stays at the composition root, the
+ * objective publisher and the footer.
+ */
+export type ActivityHandle = Pick<PerkStatusHandle, "beginActivity">;
+
 // --- glyph vocabulary (charter §5 / D3) — charter-law data, pinned by tests ---
 export type GlyphKind = "done" | "current" | "pending" | "warning" | "failure";
 export const GLYPHS: Record<GlyphKind, { glyph: string; themeColor: string }> = {
@@ -101,41 +114,80 @@ export function setWorkingMessage(target: WorkingMessageTarget, message?: string
 // --- the perk status (charter D2) --------------------------------------------
 
 /**
- * The single-value status handle: the objective publisher sets the one value through `set`, and
- * the handle republishes the single `perk` status slot. The footer reads the value back via `get`
- * and repaints via `subscribe` — the slot's `setStatus` dual-publish is deliberate (RPC clients
- * see the slot; setFooter is an RPC no-op).
+ * The composed status handle: the objective publisher sets its half through `set`, activity
+ * owners hold ref-counted waits through `beginActivity`, and the handle republishes the single
+ * `perk` status slot with the composed value. The footer reads it back via `get` and repaints via
+ * `subscribe` — the slot's `setStatus` dual-publish is deliberate (RPC clients see the slot;
+ * setFooter is an RPC no-op).
  */
 export interface PerkStatusHandle {
-  /** Set (or clear, with undefined) the one value; publishes the slot. No-op headless. */
+  /** Set (or clear, with undefined) the objective half; publishes the slot. No-op headless. */
   set(target: StandingTarget, text: string | undefined): void;
-  /** The current text (undefined when unset). */
+  /**
+   * Begin one activity wait: the newest live wait's text shows while any begun wait is unended;
+   * returns this wait's `end` (idempotent; inert after a reset — no publish). No-op headless
+   * (returns a no-op `end`, records nothing).
+   */
+  beginActivity(target: StandingTarget, text: string): () => void;
+  /** Reset every wait (session shutdown); a late `end` of a reset wait is inert. No-op headless. */
+  clearActivity(target: StandingTarget): void;
+  /** The composed value (`<objective> · <activity>`, either half optional; undefined when neither). */
   get(): string | undefined;
   /**
-   * Subscribe to publishes: the listener fires after every headful `set` (headless `set`
-   * calls are full no-ops, so nothing fires). Returns an unsubscribe.
+   * Subscribe to publishes: the listener fires after every headful `set`, begin, end and clear
+   * (headless calls are full no-ops, so nothing fires). Returns an unsubscribe.
    */
   subscribe(listener: () => void): () => void;
 }
 
 /**
- * Create the single-value `perk` status handle (one per extension instance — created in index.ts
- * and passed to the objective publisher; no hidden module state). Headless calls are full no-ops
- * (never record the text, so headless-era text can't resurrect in a later headful render).
- * `undefined` clears the slot. No width handling: pi's footer truncates the status line itself.
+ * Create the composed `perk` status handle (one per extension instance — created in index.ts
+ * and passed to the objective publisher and the activity owners; no hidden module state).
+ * Headless calls are full no-ops (never record text, so headless-era text can't resurrect in a
+ * later headful render). The activity is a SET of live wait tokens, not a set/clear: the browser
+ * doors accept a concurrent double-open, so an older wait's settle must not blank a newer one —
+ * the text clears only when the LAST wait ends (the newest live wait's text shows meanwhile, so
+ * ending one restores the remainder). An ended or reset token is simply absent, so its late `end`
+ * finds nothing to remove and publishes nothing — a wait begun after a reset can never be
+ * consumed by a stale `end`. No width handling: pi's footer truncates.
  */
 export function createPerkStatus(): PerkStatusHandle {
-  let value: string | undefined;
+  let objective: string | undefined;
+  const live = new Set<{ text: string }>(); // insertion-ordered: the last entry is the newest
   const listeners = new Set<() => void>();
+  const compose = (): string | undefined => {
+    const activity = [...live].at(-1)?.text;
+    const halves = [objective, activity].filter((half) => half !== undefined);
+    return halves.length === 0 ? undefined : halves.join(" · ");
+  };
+  const publish = (target: StandingTarget): void => {
+    target.ui.setStatus(STATUS_SLOT_PERK, compose());
+    for (const listener of listeners) listener();
+  };
   return {
     set(target, text) {
       if (!target.hasUI) return;
-      value = text;
-      target.ui.setStatus(STATUS_SLOT_PERK, text);
-      for (const listener of listeners) listener();
+      objective = text;
+      publish(target);
+    },
+    beginActivity(target, text) {
+      if (!target.hasUI) return () => {};
+      const token = { text };
+      live.add(token);
+      publish(target);
+      return () => {
+        // Already ended, or reset by `clearActivity`: nothing to remove, nothing to publish.
+        if (!live.delete(token)) return;
+        publish(target);
+      };
+    },
+    clearActivity(target) {
+      if (!target.hasUI) return;
+      live.clear();
+      publish(target);
     },
     get() {
-      return value;
+      return compose();
     },
     subscribe(listener) {
       listeners.add(listener);
@@ -155,7 +207,7 @@ export function createPerkStatus(): PerkStatusHandle {
 export interface FooterParts {
   /** e.g. `perk v0.0.1` — standing identity (D7), dim. */
   identity: string;
-  /** The 🎯 objective segment, verbatim (`handle.get()`). */
+  /** The composed perk status value (`handle.get()`), verbatim — it carries its own 🎯 mark. */
   objective?: string;
   /** Git branch (dim); omitted when not in a repo. */
   branch?: string;
@@ -329,9 +381,9 @@ export type PerkFooterFactory = (
 /**
  * The perk-owned footer factory (charter D2): replaces pi's default footer wholesale with one
  * line in the intended split layout. `render` gathers everything live per call (D10 stateless
- * render): the objective value via the handle, branch/guests via `footerData` (excluding perk's
- * own `STATUS_SLOT_PERK` — the slot keeps publishing for RPC, but the footer renders the value
- * directly), model/cache/context via the deps closures. Reactivity (the D2 contract): repaints on
+ * render): the composed status value via the handle, branch/guests via `footerData` (excluding
+ * perk's own `STATUS_SLOT_PERK` — the slot keeps publishing for RPC, but the footer renders the
+ * value directly), model/cache/context via the deps closures. Reactivity (the D2 contract): repaints on
  * every handle recompose and on branch change; `dispose` detaches both. Lifecycle (pi ≥ 0.84,
  * verified at 0.84.1): `setExtensionFooter` disposes a replaced factory's component, and pi's
  * `resetExtensionUI` restores the built-in footer (disposing this one) on /reload and before
@@ -412,7 +464,7 @@ export function formatBudgetLine(args: { tokens: number; elapsedMs: number }): s
 }
 
 // --- display-only transcript entry renderers -----------------------------------------------------
-// The audit §2.3 verdict (docs/design/pi-adoption-audit.md): perk's custom-entry families are
+// The audit §2.3 verdict (docs/design/archive/pi-adoption-audit.md): perk's custom-entry families are
 // display-only. Most render as durable one-line transition markers; report detail is the generic
 // full-diagnostic family and always renders every logical row. Renderer BODIES live here (a
 // transcript renderer IS a rich-UI surface the surfaces module owns); registration is wiring at the