@narumitw/pi-sync 0.54.2 → 0.56.0

package/src/sync/continuous-lease.ts

@@ -0,0 +1,221 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, readFileSync, rmdirSync, type Stats, stat } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+import { withLock } from "../state/lock.js";
+import { LOCKFILE_FS_ADAPTER } from "../state/lockfile-fs.js";
+import {
+  continuousRoot,
+  prepareContinuousRoot,
+  readContinuousPrivate,
+  writeContinuousPrivate,
+} from "./continuous-storage.js";
+
+const STALE_MS = 30_000;
+const localLeases = new Set<string>();
+const futureGuards = new Map<string, { identity: string; since: number }>();
+interface Owner {
+  version: 1;
+  id: string;
+  pid: number;
+  binding: string;
+}
+export interface ContinuousLease {
+  signal: AbortSignal;
+  assert(): void;
+  release(): Promise<void>;
+}
+function validOwner(value: unknown): value is Owner {
+  if (!value || typeof value !== "object") return false;
+  const owner = value as Owner;
+  return (
+    Object.keys(owner).sort().join(",") === "binding,id,pid,version" &&
+    owner.version === 1 &&
+    typeof owner.id === "string" &&
+    /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u.test(owner.id) &&
+    Number.isSafeInteger(owner.pid) &&
+    owner.pid > 0 &&
+    owner.pid <= 2147483647 &&
+    typeof owner.binding === "string" &&
+    /^[a-f0-9]{64}$/u.test(owner.binding)
+  );
+}
+
+/** Advisory only: never authority for a transfer or lease takeover. */
+export async function continuousLeaseOwner(binding: string): Promise<string> {
+  const owner = await readContinuousPrivate("owner.json");
+  if (owner === undefined) return "Local scheduler lease: not observed; waiting for an eligible session";
+  if (!validOwner(owner)) throw new Error("Invalid continuous sync owner");
+  try {
+    const guard = await fs.lstat(path.join(continuousRoot(), "scheduler.lock"));
+    if (
+      guard.isDirectory() &&
+      !guard.isSymbolicLink() &&
+      Date.now() - guard.mtimeMs <= STALE_MS &&
+      owner.binding === binding
+    )
+      return `Local scheduler lease: observed for pid ${owner.pid}; this can be another session`;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  return "Local scheduler lease: not observed; waiting for an eligible session";
+}
+
+/** Caller holds state-directory access during acquisition; the renewable guard prevents live migration. */
+export async function acquireContinuousLease(binding: string): Promise<ContinuousLease | undefined> {
+  await prepareContinuousRoot();
+  const file = path.join(continuousRoot(), "scheduler");
+  const guardPath = `${file}.lock`;
+  if (localLeases.has(file)) return undefined;
+  const previousOwner = await readContinuousPrivate("owner.json");
+  if (previousOwner !== undefined && !validOwner(previousOwner))
+    throw new Error("Invalid continuous sync owner; evidence retained.");
+  if (localLeases.has(file)) return undefined;
+  localLeases.add(file);
+  const acquiredAt = performance.now();
+  const ownerPath = path.join(continuousRoot(), "owner.json");
+  const controller = new AbortController();
+  const owner: Owner = { version: 1, id: randomUUID(), pid: process.pid, binding };
+  let identity: { dev: number; ino: number } | undefined;
+  let published = false;
+  // proper-lockfile also uses rmdirSync at process exit. Fence both cleanup paths.
+  const removeGuard = (target: string) => {
+    if (identity) {
+      const current = lstatSync(target);
+      if (current.dev !== identity.dev || current.ino !== identity.ino) return;
+    }
+    let current: unknown;
+    try {
+      const record = lstatSync(ownerPath);
+      if (
+        !record.isFile() ||
+        record.isSymbolicLink() ||
+        record.nlink !== 1 ||
+        record.size > 4096 ||
+        (process.platform !== "win32" && record.mode & 0o077)
+      )
+        return;
+      current = JSON.parse(readFileSync(ownerPath, "utf8"));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    if (published && current === undefined) return;
+    if (
+      current !== undefined &&
+      (!validOwner(current) ||
+        (current.id !== owner.id && (published || current.id !== (previousOwner as Owner | undefined)?.id)))
+    )
+      return;
+    rmdirSync(target);
+  };
+  const adapter = {
+    ...LOCKFILE_FS_ADAPTER,
+    stat: (target: string, callback: (error: NodeJS.ErrnoException | null, value?: Stats) => void) =>
+      stat(target, (error, value) => {
+        if (!error && value.mtimeMs > Date.now() + STALE_MS) {
+          const identity = `${value.dev}:${value.ino}:${value.mtimeMs}`;
+          const previous = futureGuards.get(target);
+          if (!previous || previous.identity !== identity)
+            futureGuards.set(target, { identity, since: performance.now() });
+          else if (performance.now() - previous.since > STALE_MS) value.mtime = new Date(Date.now() - STALE_MS - 1);
+        } else futureGuards.delete(target);
+        callback(error, value);
+      }),
+    rmdirSync: removeGuard,
+    rmdir: (target: string, callback: (error?: NodeJS.ErrnoException | null) => void) => {
+      try {
+        removeGuard(target);
+        callback();
+      } catch (error) {
+        callback(error as NodeJS.ErrnoException);
+      }
+    },
+  };
+  let compromised = false;
+  let unlock: () => Promise<void>;
+  try {
+    unlock = await lockfile.lock(file, {
+      fs: adapter,
+      realpath: false,
+      stale: STALE_MS,
+      update: 10_000,
+      retries: 0,
+      onCompromised: () => {
+        compromised = true;
+        controller.abort(new DOMException("Continuous sync ownership lost", "AbortError"));
+      },
+    });
+  } catch (error) {
+    localLeases.delete(file);
+    if ((error as NodeJS.ErrnoException).code === "ELOCKED") return undefined;
+    throw error;
+  }
+  let released = false;
+  const release = async () => {
+    if (released) return;
+    released = true;
+    controller.abort(new DOMException("Continuous sync owner released", "AbortError"));
+    try {
+      if (!compromised) await unlock();
+    } finally {
+      localLeases.delete(file);
+      futureGuards.delete(guardPath);
+    }
+  };
+  try {
+    identity = await fs.lstat(guardPath);
+    await withLock("continuous-owner", async () => {
+      const previous = await readContinuousPrivate("owner.json");
+      if (previous !== undefined && !validOwner(previous))
+        throw new Error("Invalid continuous sync owner; evidence retained.");
+      if (
+        (previous as Owner | undefined)?.id !== (previousOwner as Owner | undefined)?.id ||
+        performance.now() - acquiredAt > STALE_MS
+      )
+        throw new Error("Continuous lease generation changed before publication.");
+      const current = lstatSync(guardPath);
+      if (controller.signal.aborted || current.dev !== identity?.dev || current.ino !== identity.ino)
+        throw new Error("Continuous lease changed before publication.");
+      await writeContinuousPrivate("owner.json", owner);
+      published = true;
+    });
+    const assert = () => {
+      controller.signal.throwIfAborted();
+      try {
+        const root = lstatSync(continuousRoot());
+        if (!root.isDirectory() || root.isSymbolicLink() || (process.platform !== "win32" && root.mode & 0o077))
+          throw new Error("Unsafe lease root");
+        const stat = lstatSync(guardPath);
+        if (
+          stat.isSymbolicLink() ||
+          !stat.isDirectory() ||
+          stat.dev !== identity?.dev ||
+          stat.ino !== identity.ino ||
+          Date.now() - stat.mtimeMs > STALE_MS
+        )
+          throw new Error("Lease guard changed");
+        const record = lstatSync(ownerPath);
+        if (
+          !record.isFile() ||
+          record.isSymbolicLink() ||
+          record.nlink !== 1 ||
+          record.size > 4096 ||
+          (process.platform !== "win32" && record.mode & 0o077)
+        )
+          throw new Error("Unsafe owner record");
+        const value: unknown = JSON.parse(readFileSync(ownerPath, "utf8"));
+        if (!validOwner(value) || value.id !== owner.id || value.binding !== binding || value.pid !== process.pid)
+          throw new Error("Lease owner changed");
+      } catch {
+        controller.abort(new DOMException("Continuous sync ownership lost", "AbortError"));
+        controller.signal.throwIfAborted();
+      }
+    };
+    assert();
+    return { signal: controller.signal, assert, release };
+  } catch (error) {
+    await release();
+    throw error;
+  }
+}

package/src/sync/continuous-record.ts

@@ -0,0 +1,179 @@
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { withLock } from "../state/lock.js";
+import { withStateDirectoryAccess } from "../state/state-directory.js";
+import { ContinuousError, type ContinuousErrorKind } from "./continuous-errors.js";
+import { type ContinuousLease, continuousLeaseOwner } from "./continuous-lease.js";
+import { continuousBinding, readContinuousPrivate, writeContinuousPrivate } from "./continuous-storage.js";
+
+export const REQUEST_WINDOW_MS = 15 * 60_000;
+export interface ContinuousRecord {
+  version: 1;
+  binding: string;
+  pending: boolean;
+  phase: "waiting" | "syncing" | "retry" | "blocked";
+  next: number;
+  failures: number;
+  evidence?: string;
+  recovery?: string;
+  notice?: string;
+  configuration?: string;
+  error?: ContinuousErrorKind;
+  checked?: number;
+  transferred?: number;
+  calls: { key: string; at: number }[];
+  attempts: Record<string, number>;
+}
+const digest = (value: unknown) => typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+const timestamp = (value: unknown) =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && value <= 8_640_000_000_000_000;
+export function validateContinuousRecord(value: unknown, binding: string): asserts value is ContinuousRecord {
+  const record = value as ContinuousRecord;
+  if (
+    !record ||
+    typeof record !== "object" ||
+    record.version !== 1 ||
+    record.binding !== binding ||
+    Object.keys(record).some(
+      (key) =>
+        ![
+          "version",
+          "binding",
+          "pending",
+          "phase",
+          "next",
+          "failures",
+          "evidence",
+          "recovery",
+          "notice",
+          "configuration",
+          "error",
+          "checked",
+          "transferred",
+          "calls",
+          "attempts",
+        ].includes(key),
+    ) ||
+    typeof record.pending !== "boolean" ||
+    !["waiting", "syncing", "retry", "blocked"].includes(record.phase) ||
+    !timestamp(record.next) ||
+    !timestamp(record.failures) ||
+    record.failures > 30 ||
+    (record.evidence !== undefined && !digest(record.evidence)) ||
+    (record.recovery !== undefined && !digest(record.recovery)) ||
+    (record.notice !== undefined && !digest(record.notice)) ||
+    (record.configuration !== undefined && !digest(record.configuration)) ||
+    (record.error !== undefined &&
+      ![
+        "transient",
+        "contention",
+        "stale",
+        "authentication",
+        "storage",
+        "unsafe",
+        "model",
+        "budget",
+        "unknown",
+      ].includes(record.error)) ||
+    (record.checked !== undefined && !timestamp(record.checked)) ||
+    (record.transferred !== undefined && !timestamp(record.transferred)) ||
+    !Array.isArray(record.calls) ||
+    record.calls.length > 2 ||
+    record.calls.some(
+      (call) => !call || Object.keys(call).sort().join(",") !== "at,key" || !digest(call.key) || !timestamp(call.at),
+    ) ||
+    !record.attempts ||
+    typeof record.attempts !== "object" ||
+    Array.isArray(record.attempts) ||
+    Object.entries(record.attempts).some(
+      ([key, count]) => !digest(key) || !Number.isInteger(count) || count < 1 || count > 2,
+    ) ||
+    record.calls.some(
+      (call) => (record.attempts[call.key] ?? 0) < record.calls.filter((other) => other.key === call.key).length,
+    )
+  )
+    throw new Error("Invalid continuous sync state; evidence retained.");
+}
+export async function readContinuousRecord(binding: string): Promise<ContinuousRecord> {
+  const value = await readContinuousPrivate(`${binding}.json`);
+  if (value === undefined)
+    return { version: 1, binding, pending: true, phase: "waiting", next: 0, failures: 0, calls: [], attempts: {} };
+  validateContinuousRecord(value, binding);
+  return value;
+}
+export async function updateContinuousRecord<T>(
+  binding: string,
+  lease: ContinuousLease,
+  update: (record: ContinuousRecord) => T,
+): Promise<T> {
+  return withStateDirectoryAccess(() =>
+    withLock("continuous-state", async () => {
+      lease.assert();
+      const record = await readContinuousRecord(binding);
+      lease.assert();
+      const result = update(record);
+      validateContinuousRecord(record, binding);
+      lease.assert();
+      await writeContinuousPrivate(`${binding}.json`, record);
+      lease.assert();
+      return result;
+    }),
+  );
+}
+export function normalizeContinuousClock(record: ContinuousRecord, now: number) {
+  // A backward wall-clock jump cannot grant more calls: retain them for a full window.
+  record.calls = record.calls
+    .map((call) => ({ ...call, at: Math.min(call.at, now) }))
+    .filter((call) => now - call.at < REQUEST_WINDOW_MS);
+  record.next = Math.min(record.next, now + (record.error === "budget" ? REQUEST_WINDOW_MS : 300_000));
+}
+export async function reserveContinuousRequest(
+  binding: string,
+  lease: ContinuousLease,
+  key: string,
+  clock: () => number = Date.now,
+) {
+  if (!digest(key)) throw new Error("Invalid continuous candidate key.");
+  let failure: ContinuousError | undefined;
+  await updateContinuousRecord(binding, lease, (record) => {
+    const now = clock();
+    normalizeContinuousClock(record, now);
+    if ((record.attempts[key] ?? 0) >= 2)
+      failure = new ContinuousError(
+        "model",
+        "Automatic request limit reached for this evidence. Use Sync now for an explicit retry.",
+      );
+    else if (record.calls.length >= 2)
+      failure = new ContinuousError(
+        "budget",
+        "Automatic request window is full.",
+        Math.max(0, (record.calls[0]?.at ?? now) + REQUEST_WINDOW_MS - now),
+      );
+    else {
+      record.attempts[key] = (record.attempts[key] ?? 0) + 1;
+      record.calls.push({ key, at: now });
+    }
+  });
+  if (failure) throw failure;
+}
+
+/** Read-only status: no directory creation, lease, mutation, request reservation or provider call. */
+export async function continuousStatusLines(config: AnySyncConfig): Promise<string[]> {
+  if (!config.continuous) return ["Continuous sync: Off"];
+  if (!config.agentMode) return ["Continuous sync: paused; enable Agent mode first"];
+  try {
+    const record = await readContinuousRecord(await continuousBinding(config));
+    return [
+      `Continuous sync: ${record.phase}${record.error ? ` (${record.error})` : ""}`,
+      await continuousLeaseOwner(record.binding),
+      `Last successful background check: ${record.checked ? new Date(record.checked).toISOString() : "not yet checked"}`,
+      `Last successful background transfer: ${record.transferred ? new Date(record.transferred).toISOString() : "none"}`,
+      ...(record.phase === "retry" ? [`Next background attempt: ${new Date(record.next).toISOString()}`] : []),
+      ...(record.phase === "blocked"
+        ? ["Background sync needs changed evidence or repair. Review /sync, or use Sync now for an explicit retry."]
+        : []),
+      "Monitoring requires an eligible open Pi session. Status does not spend model requests or clear retry limits.",
+    ];
+  } catch {
+    return ["Continuous sync: private state unavailable; retain evidence and repair access before retrying."];
+  }
+}

package/src/sync/continuous-storage.ts

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { backendIdentityCoordinates } from "../backends/backend-identity.js";
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import { writeJson } from "../state/json-file.js";
+import { stateDir } from "../state/state-directory.js";
+import { ensureStateDir } from "../state/sync-state-store.js";
+
+export function hashContinuous(value: unknown) {
+  return createHash("sha256")
+    .update(JSON.stringify(value) ?? "null")
+    .digest("hex");
+}
+export async function continuousBinding(config: AnySyncConfig) {
+  return hashContinuous([await fs.realpath(getAgentDir()), config.setupName, backendIdentityCoordinates(config)]);
+}
+export function continuousRoot() {
+  return path.join(stateDir(), "continuous");
+}
+export async function prepareContinuousRoot() {
+  await ensureStateDir();
+  await fs.mkdir(continuousRoot(), { recursive: true, mode: 0o700 });
+  await checkContinuousRoot();
+}
+export async function checkContinuousRoot() {
+  const stat = await fs.lstat(continuousRoot());
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (process.platform !== "win32" && stat.mode & 0o077))
+    throw new Error("Unsafe continuous sync directory; evidence retained.");
+}
+export async function readContinuousPrivate(name: string): Promise<unknown> {
+  try {
+    await checkContinuousRoot();
+    const file = path.join(continuousRoot(), name);
+    const stat = await fs.lstat(file);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.nlink !== 1 ||
+      stat.size > 131072 ||
+      (process.platform !== "win32" && stat.mode & 0o077)
+    )
+      throw new Error("Unsafe continuous sync record; evidence retained.");
+    return JSON.parse(await fs.readFile(file, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+export async function writeContinuousPrivate(name: string, value: unknown) {
+  await checkContinuousRoot();
+  await readContinuousPrivate(name); // Never replace unsafe or malformed evidence.
+  await writeJson(path.join(continuousRoot(), name), value, { maxBytes: 131072 });
+}