@narumitw/pi-sync 0.54.2 → 0.56.0

package/src/sync/agent-store.ts

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+import { writeJson } from "../state/json-file.js";
+import { withLock } from "../state/lock.js";
+import { LOCK_GUARD_STALE_MS, LOCK_GUARD_UPDATE_MS } from "../state/lock-policy.js";
+import { LOCKFILE_FS_ADAPTER } from "../state/lockfile-fs.js";
+import { stateDir } from "../state/state-directory.js";
+import { AGENT_OUTPUT_BYTES } from "./agent-policy.js";
+import { ContinuousError } from "./continuous-errors.js";
+
+interface Claim {
+  version: 1;
+  id: string;
+  pid: number;
+}
+function paths() {
+  const root = path.join(stateDir(), "agent-resolver");
+  return { root, claim: path.join(root, "claim.json") };
+}
+async function directory() {
+  const { root } = paths();
+  await fs.mkdir(root, { mode: 0o700 });
+}
+async function checkDirectory() {
+  const stat = await fs.lstat(paths().root);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (process.platform !== "win32" && stat.mode & 0o077))
+    throw new Error("Unsafe agent resolver directory; evidence retained.");
+}
+async function readPrivate(file: string): Promise<unknown> {
+  try {
+    await checkDirectory();
+    const stat = await fs.lstat(file);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.nlink !== 1 ||
+      stat.size > AGENT_OUTPUT_BYTES * 2 ||
+      (process.platform !== "win32" && stat.mode & 0o077)
+    )
+      throw new Error("Unsafe agent resolver record; evidence retained.");
+    return JSON.parse(await fs.readFile(file, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new Error("Unreadable agent resolver record; evidence retained.");
+  }
+}
+async function readClaim(): Promise<Claim | undefined> {
+  const value = await readPrivate(paths().claim);
+  if (value === undefined) return;
+  const claim = value as Claim;
+  if (
+    claim?.version !== 1 ||
+    typeof claim.id !== "string" ||
+    !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/u.test(claim.id) ||
+    Object.keys(claim).sort().join(",") !== "id,pid,version" ||
+    !Number.isSafeInteger(claim.pid) ||
+    claim.pid < 1 ||
+    claim.pid > 2_147_483_647
+  )
+    throw new Error("Invalid agent resolver claim; evidence retained.");
+  return claim;
+}
+function alive(pid: number) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+/** Caller retains the state-directory migration guard; claim changes use a separate short-lived guard. */
+export async function withAgentClaim<T>(fn: (assertOwner: () => Promise<void>) => Promise<T>): Promise<T> {
+  const claim: Claim = { version: 1, id: randomUUID(), pid: process.pid };
+  let armed = false;
+  const assertOwner = async () => {
+    const current = await readClaim();
+    if (current?.id !== claim.id || current.pid !== process.pid)
+      throw new Error("Agent resolver ownership changed; candidate not applied.");
+  };
+  try {
+    await withLock("agent-claim", async () => {
+      try {
+        await directory();
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      }
+      await checkDirectory();
+      await withClaimGuard(async () => {
+        const existing = await readClaim();
+        if (existing && alive(existing.pid))
+          throw new ContinuousError("contention", "Agent mode deferred: another local resolver is running.");
+        // A durability failure can occur after rename: cleanup must own partial initialization too.
+        armed = true;
+        await writeJson(paths().claim, claim);
+      });
+    });
+    return await fn(assertOwner);
+  } finally {
+    if (armed) await releaseClaim(claim);
+  }
+}
+async function releaseClaim(claim: Claim) {
+  // Ordinary transfers may hold the operation lock for an arbitrary time.
+  // Cleanup needs only the claim guard; it never waits for that operation lock.
+  await withClaimGuard(async () => {
+    const current = await readClaim();
+    if (current?.id === claim.id && current.pid === claim.pid) await fs.rm(paths().claim);
+  });
+}
+async function withClaimGuard<T>(run: () => Promise<T>): Promise<T> {
+  await checkDirectory();
+  let compromisedError: Error | undefined;
+  const release = await lockfile.lock(paths().claim, {
+    fs: LOCKFILE_FS_ADAPTER,
+    realpath: false,
+    stale: LOCK_GUARD_STALE_MS,
+    update: LOCK_GUARD_UPDATE_MS,
+    retries: { retries: 100, factor: 1.2, minTimeout: 10, maxTimeout: 100 },
+    onCompromised: (error) => {
+      compromisedError = error;
+    },
+  });
+  try {
+    const result = await run();
+    if (compromisedError) throw compromisedError;
+    return result;
+  } finally {
+    await release();
+  }
+}
+function candidatePath(key: string) {
+  if (!/^[a-f0-9]{64}$/u.test(key)) throw new Error("Invalid agent candidate key.");
+  return path.join(paths().root, `${key}.json`);
+}
+export async function readAgentCandidate(key: string): Promise<unknown> {
+  return readPrivate(candidatePath(key));
+}
+export async function saveAgentCandidate(key: string, candidate: unknown) {
+  await checkDirectory();
+  const target = candidatePath(key);
+  const existing = await readPrivate(target);
+  if (existing !== undefined) {
+    if (JSON.stringify(existing) !== JSON.stringify(candidate))
+      throw new Error("Agent candidate changed before save; existing evidence retained.");
+    return;
+  }
+  await writeJson(target, candidate, { maxBytes: AGENT_OUTPUT_BYTES * 2 });
+}

package/src/sync/agent-sync.ts

@@ -0,0 +1,91 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CommandOptions } from "../commands/command-types.js";
+import { withLock } from "../state/lock.js";
+import { setSyncStatus } from "../ui/sync-status.js";
+import { AGENT_MAX_ATTEMPTS } from "./agent-policy.js";
+import { type AgentAcceptance, AgentResolutionRequired } from "./agent-request.js";
+import { ContinuousError } from "./continuous-errors.js";
+
+/** All callers retain their existing state-directory access guard. Off stays lazy. */
+export async function withAgentSyncLock<T>(
+  ctx: ExtensionContext,
+  options: CommandOptions,
+  run: (options: CommandOptions) => Promise<T>,
+): Promise<T> {
+  let request: AgentResolutionRequired;
+  const background = options.background;
+  try {
+    return await withLock("sync", () => run(options));
+  } catch (error) {
+    if (!(error instanceof AgentResolutionRequired)) throw error;
+    request = error;
+  }
+  const { withAgentClaim, readAgentCandidate, saveAgentCandidate } = await import("./agent-store.js");
+  const { parseAgentCandidate } = await import("./agent-candidate.js");
+  const { runAgentResolver } = await import("./agent-runner.js");
+  return withAgentClaim(async (assertOwner) => {
+    const clearStatus = () => setSyncStatus(ctx, undefined);
+    const onAbort = () => {
+      try {
+        clearStatus();
+      } catch {
+        /* UI can already be disposed. */
+      }
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      options.signal?.throwIfAborted();
+      for (let attempt = 0; attempt < AGENT_MAX_ATTEMPTS; attempt++) {
+        const validate = () =>
+          withLock("agent-validate", async () => {
+            options.signal?.throwIfAborted();
+            await assertOwner();
+            await request.validate();
+            options.signal?.throwIfAborted();
+          });
+        await validate();
+        setSyncStatus(ctx, "sync resolving");
+        const cached = await withLock("agent-cache-read", async () => {
+          await assertOwner();
+          return readAgentCandidate(request.key);
+        });
+        const raw =
+          cached === undefined
+            ? await runAgentResolver(
+                ctx,
+                request.evidence,
+                validate,
+                options.signal,
+                background ? () => background.reserve(request.key) : undefined,
+              )
+            : JSON.stringify(cached);
+        let candidate: ReturnType<typeof parseAgentCandidate>;
+        try {
+          candidate = parseAgentCandidate(raw, request.evidence);
+        } catch {
+          throw new ContinuousError("model", "Agent mode paused: invalid resolver output; evidence retained.");
+        }
+        await validate();
+        await withLock("agent-cache-save", async () => {
+          await assertOwner();
+          await saveAgentCandidate(request.key, candidate);
+        });
+        const acceptance: AgentAcceptance = { key: request.key, candidate };
+        try {
+          return await withLock("sync", async () => {
+            await assertOwner();
+            options.signal?.throwIfAborted();
+            return run({ ...options, agentAcceptance: acceptance });
+          });
+        } catch (error) {
+          if (!(error instanceof AgentResolutionRequired)) throw error;
+          request = error;
+        }
+      }
+      throw new ContinuousError("stale", "Agent mode paused: content changed repeatedly; retry later.");
+    } finally {
+      options.signal?.removeEventListener("abort", onAbort);
+      if (!options.signal?.aborted) clearStatus();
+    }
+  });
+}

package/src/sync/apply-review.ts

@@ -0,0 +1,63 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { agentDir } from "../snapshot/session-paths.js";
+import { addTopLevelCaseVariantDeletes } from "../snapshot/snapshot-apply.js";
+import type { Snapshot } from "../snapshot/snapshot-types.js";
+import { throwIfAborted } from "./signals.js";
+
+export interface CaseCleanupReview {
+  path: string;
+  fingerprint: string;
+}
+
+/** Inspect the apply engine's additional alias removals, which logical snapshots omit. */
+export async function inspectCaseCleanup(snapshot: Snapshot, signal?: AbortSignal): Promise<CaseCleanupReview[]> {
+  throwIfAborted(signal);
+  const root = agentDir();
+  const plan = await addTopLevelCaseVariantDeletes(root, { writes: [], deletes: [] }, snapshot);
+  throwIfAborted(signal);
+  const review: CaseCleanupReview[] = [];
+  for (const target of plan.deletes.sort()) {
+    const stat = await fs.lstat(target);
+    throwIfAborted(signal);
+    const hash = createHash("sha256");
+    if (stat.isSymbolicLink()) hash.update(await fs.readlink(target));
+    else {
+      if (!stat.isFile()) throw new Error("Case-variant path is no longer a regular file or symlink.");
+      const handle = await fs.open(
+        target,
+        constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0),
+      );
+      try {
+        throwIfAborted(signal);
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino)
+          throw new Error("Case-variant file changed while preparing review.");
+        for await (const bytes of handle.createReadStream({ autoClose: false, signal })) {
+          throwIfAborted(signal);
+          hash.update(bytes);
+        }
+      } finally {
+        await handle.close();
+      }
+    }
+    throwIfAborted(signal);
+    review.push({
+      path: path.basename(target),
+      fingerprint: `${stat.dev}:${stat.ino}:${stat.mode}:${hash.digest("hex")}`,
+    });
+  }
+  return review;
+}
+
+export async function revalidateCaseCleanup(
+  expected: readonly CaseCleanupReview[],
+  snapshot: Snapshot,
+  signal?: AbortSignal,
+) {
+  const current = await inspectCaseCleanup(snapshot, signal);
+  if (JSON.stringify(current) !== JSON.stringify(expected))
+    throw new Error("Case-variant paths changed during transfer review; reopen the preview.");
+}

package/src/sync/automatic-sync.ts

@@ -12,7 +12,9 @@ import { stateDirectoryMigrationNotice } from "../state/state-directory.js";
 import { ensureStateDir, readStateForConfig } from "../state/sync-state-store.js";
 import { configureSyncStatus, setSyncStatus } from "../ui/sync-status.js";
 import { safeTerminalText } from "../ui/terminal-text.js";
+import { startupTransferEnabled } from "./agent-policy.js";
 import { throwIfAborted } from "./signals.js";
+import { createStartupTimings } from "./startup-timings.js";
 import { errorMessage } from "./sync-errors.js";
 import type { SyncLoaders } from "./sync-loaders.js";
 import { captureMutationOwner } from "./sync-local.js";
@@ -28,44 +30,55 @@ const AUTO_SYNC_OPTIONS: CommandOptions = {
 };
 
 export async function startSession(ctx: ExtensionContext, signal: AbortSignal) {
-  throwIfAborted(signal);
-  const stateNotice = stateDirectoryMigrationNotice();
-  if (stateNotice && ctx.hasUI) ctx.ui.notify(stateNotice, "warning");
-  // Recovery can restore managed files: finish it before Pi accepts user edits.
-  // Unlike remote inspection, it must never be detached behind startup.
-  const validateMutation = captureMutationOwner(ctx, signal);
-  const currentFile = ctx.sessionManager.getSessionFile?.();
-  await recoverSnapshotTransactionsOnStartup({
-    signal,
-    sessionDir: sessionDirFromContext(ctx),
-    protectedTargets: currentFile ? [currentFile] : [],
-    validateMutation,
-  });
-  throwIfAborted(signal);
+  const timings = createStartupTimings();
+  let debug = false;
+  let outcome: "completed" | "stopped" = "stopped";
   try {
-    const settings = await readLocalConfigObject();
     throwIfAborted(signal);
-    const names = settings ? Object.keys(settings.syncSetups).sort((left, right) => left.localeCompare(right)) : [];
-    setSyncSetupCompletions(names);
-    configureSyncStatus(ctx, settings?.showStatus ?? true);
-  } catch {
-    if (signal.aborted) return;
-    setSyncSetupCompletions([]);
-  }
-  const migrationNotice = consumeLocalConfigMigrationNotice();
-  if (migrationNotice && ctx.hasUI) ctx.ui.notify(migrationNotice, "warning");
-  throwIfAborted(signal);
-  if (!ctx.hasUI) return;
-  try {
-    const config = await loadConfig();
+    const stateNotice = stateDirectoryMigrationNotice();
+    if (stateNotice && ctx.hasUI) ctx.ui.notify(stateNotice, "warning");
+    // Recovery can restore managed files: finish it before Pi accepts user edits.
+    // Unlike remote inspection, it must never be detached behind startup.
+    const validateMutation = captureMutationOwner(ctx, signal);
+    const currentFile = ctx.sessionManager.getSessionFile?.();
+    await timings.measure("transaction recovery", () =>
+      recoverSnapshotTransactionsOnStartup({
+        signal,
+        sessionDir: sessionDirFromContext(ctx),
+        protectedTargets: currentFile ? [currentFile] : [],
+        validateMutation,
+      }),
+    );
     throwIfAborted(signal);
-    configureSyncStatus(ctx, config.showStatus);
-    return config.automatic || config.automaticTransfer ? config : undefined;
-  } catch (error) {
+    try {
+      const settings = await timings.measure("settings read", () => readLocalConfigObject());
+      throwIfAborted(signal);
+      debug = settings?.debug ?? false;
+      const names = settings ? Object.keys(settings.syncSetups).sort((left, right) => left.localeCompare(right)) : [];
+      setSyncSetupCompletions(names);
+      configureSyncStatus(ctx, settings?.showStatus ?? true);
+    } catch {
+      if (signal.aborted) return;
+      setSyncSetupCompletions([]);
+    }
+    const migrationNotice = consumeLocalConfigMigrationNotice();
+    if (migrationNotice && ctx.hasUI) ctx.ui.notify(migrationNotice, "warning");
     throwIfAborted(signal);
-    if (!isMissingConfigError(error)) {
-      ctx.ui.notify(`pi-sync startup check skipped: ${safeTerminalText(errorMessage(error))}`, "warning");
+    if (!ctx.hasUI) return;
+    try {
+      const config = await timings.measure("config resolution", () => loadConfig());
+      throwIfAborted(signal);
+      configureSyncStatus(ctx, config.showStatus);
+      outcome = "completed";
+      return config.automatic || startupTransferEnabled(config) ? config : undefined;
+    } catch (error) {
+      throwIfAborted(signal);
+      if (!isMissingConfigError(error)) {
+        ctx.ui.notify(`pi-sync startup check skipped: ${safeTerminalText(errorMessage(error))}`, "warning");
+      }
     }
+  } finally {
+    timings.publish(ctx, debug, signal, "local initialization", outcome);
   }
 }
 

package/src/sync/continuous-errors.ts

@@ -0,0 +1,85 @@
+import { SyncBackendConflictError } from "../backends/sync-backend.js";
+
+export type ContinuousErrorKind =
+  | "transient"
+  | "contention"
+  | "stale"
+  | "authentication"
+  | "storage"
+  | "unsafe"
+  | "model"
+  | "budget"
+  | "unknown";
+
+/** Categories are safe to persist; provider messages and causes are not. */
+export class ContinuousError extends Error {
+  constructor(
+    readonly kind: ContinuousErrorKind,
+    message: string,
+    readonly retryAfterMs?: number,
+  ) {
+    super(message);
+    this.name = "ContinuousError";
+  }
+}
+
+export function continuousFailure(error: unknown): { kind: ContinuousErrorKind; retry: boolean; delay?: number } {
+  const seen = new Set<unknown>();
+  for (let current = error; current && !seen.has(current) && seen.size < 8; ) {
+    seen.add(current);
+    if (current instanceof ContinuousError)
+      return {
+        kind: current.kind,
+        retry: ["transient", "contention", "stale", "budget"].includes(current.kind),
+        delay: current.retryAfterMs,
+      };
+    if (current instanceof SyncBackendConflictError) return { kind: "stale", retry: true };
+    if (typeof current !== "object") break;
+    const value = current as {
+      status?: unknown;
+      code?: unknown;
+      name?: unknown;
+      cause?: unknown;
+      retryAfterMs?: unknown;
+    };
+    if (value.status === 401 || value.status === 403) return { kind: "authentication", retry: false };
+    if (
+      value.status === 408 ||
+      value.status === 429 ||
+      (typeof value.status === "number" && Number.isInteger(value.status) && value.status >= 500 && value.status <= 599)
+    )
+      return { kind: "transient", retry: true, delay: boundedRetryDelay(value.retryAfterMs) };
+    if (value.code === "ELOCKED") return { kind: "contention", retry: true };
+    if (value.code === "ECOMPROMISED") return { kind: "stale", retry: true };
+    if (
+      value.name === "TimeoutError" ||
+      [
+        "ECONNRESET",
+        "ECONNREFUSED",
+        "ETIMEDOUT",
+        "ENETUNREACH",
+        "EHOSTUNREACH",
+        "ENOTFOUND",
+        "EAI_AGAIN",
+        "UND_ERR_CONNECT_TIMEOUT",
+        "UND_ERR_SOCKET",
+      ].includes(String(value.code))
+    )
+      return { kind: "transient", retry: true };
+    if (["EACCES", "EPERM", "ENOSPC", "EROFS", "EIO"].includes(String(value.code)))
+      return { kind: "storage", retry: false };
+    current = value.cause;
+  }
+  return { kind: "unknown", retry: false };
+}
+
+export function boundedRetryDelay(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.min(value, 300_000) : undefined;
+}
+
+export function retryAfter(response: Response): number | undefined {
+  const value = response.headers.get("retry-after");
+  if (!value) return;
+  const seconds = Number(value);
+  return boundedRetryDelay(Number.isFinite(seconds) ? seconds * 1000 : Date.parse(value) - Date.now());
+}