agentcache 0.4.2 → 0.5.0-beta.2

package/dist/cli.js

@@ -1,366 +1,2609 @@
 #!/usr/bin/env node
+import {
+  DEFAULT_READ_BUDGET,
+  PORTABLE_CLI_ADAPTER_ID,
+  SESSION_SCHEMA_VERSION,
+  SessionOperationError,
+  SessionService,
+  SqliteSessionRepository,
+  createId,
+  listAdapters,
+  redactPortableText,
+  resolveWorkspace,
+  serializePublicResumeCapsule,
+  validateReadBudget
+} from "./chunk-YY7QXBG5.js";
+import {
+  loadOrCreateDeviceId
+} from "./chunk-XRJ6QW6N.js";
+import {
+  configureMcpRegistrationEntrypoint,
+  inspectLegacyClaudeHookPresence,
+  isMcpServerRegistered
+} from "./chunk-YKG6CDGT.js";
+import "./chunk-RXGW4Q3G.js";
+import {
+  getSessionDbPath
+} from "./chunk-R5I6WWSD.js";
 
 // src/cli.ts
+import { Command as Command3 } from "commander";
+import {
+  closeSync as closeSync2,
+  constants as fsConstants,
+  fstatSync as fstatSync2,
+  lstatSync as lstatFileSync,
+  openSync as openSync2,
+  readFileSync as readPackageFileSync,
+  readSync as readSync2
+} from "fs";
+import { fileURLToPath } from "url";
+
+// src/commands/adapter.ts
 import { Command } from "commander";
-var program = new Command();
-program.name("agentcache").description("Engineering Knowledge Compiler \u2014 universal, zero-config").version("0.3.1");
-program.command("setup").description("Detect IDEs and register AgentCache (runs automatically on install)").action(async () => {
-  const { runSetup } = await import("./setup-CVG35TUZ.js");
-  await runSetup();
-});
-program.command("serve").description("Start AgentCache MCP server (spawned by IDEs automatically)").action(async () => {
-  const { startMcpServer } = await import("./mcp.js");
-  await startMcpServer();
+async function startMcpForAdapter(adapterId, dependencies = {}) {
+  const adapters = dependencies.adapters ?? listAdapters();
+  const adapter = requireAdapter(
+    new Map(adapters.map((candidate) => [candidate.id, candidate])),
+    adapterId
+  );
+  const loadDeviceId = dependencies.loadDeviceId ?? (await import("./device-id-RV7RO5RB.js")).loadOrCreateDeviceId;
+  const startServer = dependencies.startServer ?? (await import("./mcp.js")).startMcpServer;
+  await startServer({ adapterId: adapter.id, deviceId: loadDeviceId() });
+}
+function createAdapterCommand(dependencies = {}) {
+  const adapters = dependencies.adapters ?? listAdapters();
+  const write = dependencies.write ?? ((value) => process.stdout.write(value));
+  const byId = new Map(adapters.map((adapter) => [adapter.id, adapter]));
+  const command = new Command("adapter").description("Inspect and configure agent adapters");
+  command.command("list").description("List supported agent adapters").option("--json", "Print machine-readable JSON").action((options) => {
+    const result = {
+      adapters: adapters.map((adapter) => {
+        const descriptor = adapter.descriptor();
+        return {
+          id: descriptor.id,
+          displayName: publicDiagnostic(descriptor.displayName),
+          capabilities: publicCapabilities(descriptor.capabilities)
+        };
+      })
+    };
+    if (options.json) return writeJson(write, result);
+    for (const adapter of result.adapters) {
+      write(`${terminalText(adapter.id)}	${terminalText(adapter.displayName)}
+`);
+    }
+  });
+  command.command("doctor <adapter-id>").description("Probe an adapter and report capability evidence").option("--json", "Print machine-readable JSON").action(async (adapterId, options) => {
+    const adapter = requireAdapter(byId, adapterId);
+    const probe = await adapter.probe();
+    const result = {
+      adapterId: adapter.id,
+      available: probe.available,
+      checkedAt: publicDiagnostic(probe.checkedAt),
+      ...probe.clientVersion === void 0 ? {} : { clientVersion: publicDiagnostic(probe.clientVersion) },
+      ...probe.sourceFormatVersion === void 0 ? {} : { sourceFormatVersion: publicDiagnostic(probe.sourceFormatVersion) },
+      diagnostics: probe.diagnostics.slice(0, 50).map(publicDiagnostic),
+      capabilities: publicCapabilities(probe.capabilities)
+    };
+    if (options.json) return writeJson(write, result);
+    write(
+      `${publicDiagnostic(adapter.descriptor().displayName)}: ${probe.available ? "available" : "unavailable"}
+`
+    );
+    for (const [name, capability] of Object.entries(result.capabilities)) {
+      const evidence = capability.evidence ?? capability.reason ?? "No evidence reported";
+      write(
+        `  ${terminalText(name)}: ${terminalText(capability.level)} (${terminalText(capability.mode)}) \u2014 ${terminalText(evidence)}
+`
+      );
+    }
+    for (const diagnostic of result.diagnostics) {
+      write(`  diagnostic: ${terminalText(diagnostic)}
+`);
+    }
+  });
+  command.command("register <adapter-id>").description("Register AgentCache with one adapter").action(async (adapterId) => {
+    const adapter = requireAdapter(byId, adapterId);
+    const result = await adapter.register();
+    const state = result.registered ? "registered" : "not registered";
+    write(
+      `${publicDiagnostic(adapter.descriptor().displayName)}: ${state}${result.reason ? ` \u2014 ${publicDiagnostic(result.reason)}` : ""}
+`
+    );
+  });
+  command.command("unregister <adapter-id>").description("Remove AgentCache registration from one adapter").action(async (adapterId) => {
+    const adapter = requireAdapter(byId, adapterId);
+    const result = await adapter.unregister();
+    const state = result.registered ? "still registered" : "unregistered";
+    write(
+      `${publicDiagnostic(adapter.descriptor().displayName)}: ${state}${result.reason ? ` \u2014 ${publicDiagnostic(result.reason)}` : ""}
+`
+    );
+  });
+  return command;
+}
+function registerAdapterCommands(program2, dependencies = {}) {
+  program2.addCommand(createAdapterCommand(dependencies));
+}
+function requireAdapter(adapters, adapterId) {
+  const adapter = adapters.get(adapterId);
+  if (!adapter) {
+    throw new SessionOperationError(
+      "invalid_input",
+      `Unknown adapter: ${adapterId}`,
+      ["setup", "cancel"]
+    );
+  }
+  return adapter;
+}
+function publicCapabilities(capabilities) {
+  return {
+    registration: publicCapability(capabilities.registration),
+    history: publicCapability(capabilities.history),
+    nativeResume: publicCapability(capabilities.nativeResume),
+    append: publicCapability(capabilities.append),
+    checkpoint: publicCapability(capabilities.checkpoint),
+    fork: publicCapability(capabilities.fork),
+    launch: publicCapability(capabilities.launch)
+  };
+}
+function publicCapability(capability) {
+  return {
+    level: capability.level,
+    mode: capability.mode,
+    ...capability.reason === void 0 ? {} : { reason: publicDiagnostic(capability.reason) },
+    ...capability.evidence === void 0 ? {} : { evidence: publicDiagnostic(capability.evidence) },
+    ...capability.verifiedAt === void 0 ? {} : { verifiedAt: publicDiagnostic(capability.verifiedAt) }
+  };
+}
+function writeJson(write, value) {
+  write(`${JSON.stringify(value)}
+`);
+}
+function terminalText(value) {
+  return value.replace(
+    /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g,
+    "\uFFFD"
+  );
+}
+function publicDiagnostic(value) {
+  const boundedSource = value.slice(0, 4096);
+  return terminalText(redactPortableText(terminalText(boundedSource))).slice(0, 1024);
+}
+
+// src/commands/session.ts
+import { randomUUID } from "crypto";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync
+} from "fs";
+import { basename } from "path";
+import { createInterface } from "readline/promises";
+import { TextDecoder } from "util";
+import { Command as Command2, CommanderError } from "commander";
+
+// src/session/ingestion.ts
+import { createHash } from "crypto";
+import { isAbsolute } from "path";
+var SESSION_TITLE_MAX_CHARS = 120;
+var METADATA_KEY_MAX_CHARS = 256;
+var METADATA_STRING_MAX_CHARS = 4096;
+var OPERATION_ERROR_CODES = /* @__PURE__ */ new Set([
+  "not_found",
+  "adapter_unavailable",
+  "unsupported_version",
+  "malformed_source",
+  "workspace_mismatch",
+  "head_changed",
+  "handoff_expired",
+  "handoff_consumed",
+  "wrong_destination",
+  "lease_conflict",
+  "invalid_token",
+  "out_of_sync",
+  "invalid_input"
+]);
+var OPERATION_ALTERNATIVES = /* @__PURE__ */ new Set([
+  "refresh",
+  "fork",
+  "cancel",
+  "wait",
+  "retry",
+  "setup",
+  "diagnose"
+]);
+async function discoverSessions(binding, adapters, budget) {
+  const validatedBudget = validateReadBudget(budget);
+  const uniqueAdapters = /* @__PURE__ */ new Map();
+  for (const adapter of adapters) {
+    if (!uniqueAdapters.has(adapter.id)) uniqueAdapters.set(adapter.id, adapter);
+  }
+  const diagnostics = [];
+  const candidates = /* @__PURE__ */ new Map();
+  const ambiguousIdentities = /* @__PURE__ */ new Set();
+  for (const adapter of uniqueAdapters.values()) {
+    const descriptor = adapter.descriptor();
+    if (descriptor.capabilities.history.level === "unsupported" || !adapter.discover) {
+      diagnostics.push({
+        adapterId: adapter.id,
+        code: "history_unsupported",
+        message: safeErrorMessage(descriptor.capabilities.history.reason ?? `${descriptor.displayName} does not support local history discovery`)
+      });
+      continue;
+    }
+    let discovered;
+    try {
+      discovered = await adapter.discover({
+        workspaceRoot: binding.rootPath,
+        budget: validatedBudget
+      });
+    } catch (error) {
+      diagnostics.push({
+        adapterId: adapter.id,
+        code: "discovery_failed",
+        message: safeErrorMessage(error)
+      });
+      continue;
+    }
+    for (const candidate of discovered) {
+      const reference = candidate?.reference;
+      if (!reference || reference.adapterId !== adapter.id || !nonEmpty(reference.nativeSessionId) || !nonEmpty(reference.locator)) {
+        diagnostics.push({
+          adapterId: adapter.id,
+          code: "invalid_reference",
+          message: "Adapter discovery returned an invalid or mismatched native session reference"
+        });
+        continue;
+      }
+      const evidence = workspaceEvidence(candidate);
+      if (evidence.status === "verified" && (evidence.root !== binding.rootPath || reference.workspaceRoot !== evidence.root)) {
+        diagnostics.push({
+          adapterId: adapter.id,
+          code: "workspace_unverified",
+          message: "Native session workspace could not be verified for the active root"
+        });
+        continue;
+      }
+      let boundCandidate;
+      try {
+        boundCandidate = evidence.status === "verified" ? sanitizeDiscoveredSession(candidate, evidence) : unassignedDiscoveryChoice(candidate, evidence);
+      } catch (error) {
+        diagnostics.push({
+          adapterId: adapter.id,
+          code: "invalid_reference",
+          message: safeErrorMessage(error)
+        });
+        continue;
+      }
+      if (evidence.status !== "verified") {
+        diagnostics.push({
+          adapterId: adapter.id,
+          code: "workspace_unverified",
+          message: "Native session is unassigned and requires an explicit attach target"
+        });
+      }
+      const identity = nativeIdentity(adapter.id, reference.nativeSessionId);
+      if (ambiguousIdentities.has(identity)) continue;
+      const existing = candidates.get(identity);
+      if (existing && existing.reference.locator !== boundCandidate.reference.locator) {
+        candidates.delete(identity);
+        ambiguousIdentities.add(identity);
+        diagnostics.push({
+          adapterId: adapter.id,
+          code: "ambiguous_reference",
+          message: "Native session ID was discovered at multiple source locations"
+        });
+      } else if (!existing || compareDiscovery(boundCandidate, existing) < 0) {
+        candidates.set(identity, boundCandidate);
+      }
+    }
+  }
+  const sessions = [...candidates.values()].sort(compareDiscovery);
+  return {
+    binding,
+    searchedAdapters: [...uniqueAdapters.keys()],
+    sessions,
+    diagnostics: diagnostics.map((diagnostic) => ({
+      ...diagnostic,
+      message: safeErrorMessage(diagnostic.message)
+    }))
+  };
+}
+var SessionIngestionService = class {
+  #repository;
+  #adapters;
+  #binding;
+  #deviceId;
+  #rootScopeId;
+  #budget;
+  #now;
+  #pendingByNativeIdentity = /* @__PURE__ */ new Map();
+  constructor(options) {
+    if (!nonEmpty(options.deviceId)) {
+      throw invalidInput("Device ID must be non-empty");
+    }
+    const adapters = /* @__PURE__ */ new Map();
+    for (const adapter of options.adapters) {
+      if (adapters.has(adapter.id)) {
+        throw invalidInput(`Adapter ${adapter.id} was registered more than once`);
+      }
+      adapters.set(adapter.id, adapter);
+    }
+    this.#repository = options.repository;
+    this.#adapters = adapters;
+    this.#binding = options.binding;
+    this.#deviceId = options.deviceId;
+    this.#rootScopeId = rootScopeId(options.binding, options.deviceId);
+    this.#budget = { ...validateReadBudget(options.budget) };
+    this.#now = options.now ?? Date.now;
+  }
+  discoverSessions(budget = this.#budget) {
+    return discoverSessions(this.#binding, [...this.#adapters.values()], budget);
+  }
+  /**
+   * Imports a native transcript or explicitly attaches it to a selected
+   * portable session. Supplying a target is the only way to join timelines.
+   */
+  ingestNativeSession(input, target, mode = target ? "attach" : "import") {
+    const native = normalizeNativeInput(input);
+    const key = nativeIdentity(native.reference.adapterId, native.reference.nativeSessionId);
+    const previous = this.#pendingByNativeIdentity.get(key);
+    const operation = (previous ? previous.catch(() => void 0) : Promise.resolve()).then(() => this.#ingestNativeSession(native, target, mode)).catch((error) => {
+      throw ingestionOperationFailure(error);
+    });
+    this.#pendingByNativeIdentity.set(key, operation);
+    void operation.finally(() => {
+      if (this.#pendingByNativeIdentity.get(key) === operation) {
+        this.#pendingByNativeIdentity.delete(key);
+      }
+    }).catch(() => void 0);
+    return operation;
+  }
+  /** Refreshes a leg from the exact source locator persisted at import time. */
+  async refreshClientLeg(legId) {
+    const leg = this.#repository.getLeg(legId);
+    if (!leg) {
+      throw new SessionOperationError("not_found", `Client leg ${legId} was not found`, ["refresh"]);
+    }
+    if (!leg.nativeSessionId) {
+      throw invalidInput("A client leg without a native session ID cannot be refreshed");
+    }
+    const session = this.#repository.getSession(leg.sessionId);
+    if (!session) {
+      throw new SessionOperationError(
+        "not_found",
+        `Portable session ${leg.sessionId} was not found`,
+        ["diagnose"]
+      );
+    }
+    this.#assertSessionWorkspace(session, leg);
+    const adapter = this.#getAdapter(leg.adapterId);
+    const sourceLocator = stringMetadata(leg.metadata, "sourceLocator");
+    let reference;
+    if (sourceLocator) {
+      reference = {
+        adapterId: leg.adapterId,
+        nativeSessionId: leg.nativeSessionId,
+        locator: sourceLocator,
+        workspaceRoot: this.#binding.rootPath
+      };
+    } else if (adapter.resolveNativeReference) {
+      try {
+        reference = await adapter.resolveNativeReference({
+          nativeSessionId: leg.nativeSessionId,
+          workspaceRoot: this.#binding.rootPath
+        });
+      } catch (error) {
+        if (error instanceof SessionOperationError) throw sanitizedOperationError(error);
+        throw initialSourceFailure("validate", adapter.id, error);
+      }
+    }
+    if (!reference) {
+      throw new SessionOperationError(
+        "not_found",
+        `The native source for client leg ${legId} could not be resolved`,
+        ["diagnose", "cancel"]
+      );
+    }
+    const sourceStartedAt = timestampMetadata(leg.metadata, "sourceStartedAt");
+    const sourceActivityAt2 = timestampMetadata(leg.metadata, "sourceActivityAt") ?? normalizeStoredTimestamp(leg.startedAt, "Stored leg start timestamp");
+    const ingestionMode = stringMetadata(leg.metadata, "ingestionMode");
+    if (ingestionMode !== "import" && ingestionMode !== "attach") {
+      throw new SessionOperationError(
+        "out_of_sync",
+        "Client leg is missing trusted ingestion provenance",
+        ["diagnose", "cancel"]
+      );
+    }
+    const target = ingestionMode === "attach" ? {
+      sessionId: leg.sessionId,
+      resumedFromCheckpointId: leg.resumedFromCheckpointId
+    } : void 0;
+    return this.ingestNativeSession({
+      reference,
+      ...stringMetadata(leg.metadata, "sourceTitle") ? { title: stringMetadata(leg.metadata, "sourceTitle") } : {},
+      ...sourceStartedAt !== void 0 ? { startedAt: sourceStartedAt } : {},
+      updatedAt: sourceActivityAt2,
+      ...leg.clientVersion ? { clientVersion: leg.clientVersion } : {},
+      ...leg.model ? { model: leg.model } : {},
+      ...stringMetadata(leg.metadata, "gitBranch") ? { gitBranch: stringMetadata(leg.metadata, "gitBranch") } : {},
+      ...stringMetadata(leg.metadata, "gitCommit") ? { gitCommit: stringMetadata(leg.metadata, "gitCommit") } : {}
+    }, target, ingestionMode);
+  }
+  async #ingestNativeSession(native, target, mode) {
+    this.#validateMode(target, mode);
+    native = normalizeNativeTimestamps(native);
+    this.#assertNativeWorkspaceEvidence(native, mode);
+    const adapter = this.#getAdapter(native.reference.adapterId);
+    if (adapter.descriptor().capabilities.history.level === "unsupported" || !adapter.readSnapshot) {
+      throw new SessionOperationError(
+        "adapter_unavailable",
+        `${adapter.descriptor().displayName} does not support native history reads`,
+        ["diagnose", "cancel"]
+      );
+    }
+    let reference;
+    try {
+      reference = await this.#resolveReference(adapter, native.reference, mode === "attach");
+    } catch (error) {
+      if (error instanceof SessionOperationError) throw sanitizedOperationError(error);
+      throw initialSourceFailure("validate", adapter.id, error);
+    }
+    native = { ...native, reference };
+    const existingLeg = this.#repository.findLeg(
+      this.#deviceId,
+      reference.adapterId,
+      reference.nativeSessionId
+    );
+    if (mode === "import" && !existingLeg && native.workspaceEvidence?.status !== "verified") {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "A new native import requires verified workspace provenance",
+        ["diagnose", "cancel"]
+      );
+    }
+    if (existingLeg) {
+      const existingLocator = stringMetadata(existingLeg.metadata, "sourceLocator");
+      if (existingLocator && existingLocator !== reference.locator) {
+        const durableCursor = this.#repository.findSourceCursor(
+          this.#deviceId,
+          reference.adapterId,
+          existingLocator
+        );
+        const message = "Native session ID was reused at a different source locator; refusing to merge timelines";
+        if (durableCursor) this.#markCursor(durableCursor, "out-of-sync", message);
+        throw new SessionOperationError(
+          "out_of_sync",
+          message,
+          ["diagnose", "cancel"],
+          { adapterId: reference.adapterId, nativeSessionId: reference.nativeSessionId }
+        );
+      }
+      if (target && existingLeg.sessionId !== target.sessionId) {
+        throw invalidInput(
+          "A native session already belongs to another portable session and cannot be merged"
+        );
+      }
+      const session2 = this.#repository.getSession(existingLeg.sessionId);
+      if (!session2) {
+        throw new SessionOperationError(
+          "not_found",
+          `Portable session ${existingLeg.sessionId} was not found`,
+          ["diagnose"]
+        );
+      }
+      this.#assertSessionWorkspace(session2, existingLeg);
+      this.#assertExistingClaim(existingLeg, target, mode);
+    }
+    const targetSession = !existingLeg && target ? this.#resolveTarget(target) : null;
+    const session = existingLeg ? this.#repository.getSession(existingLeg.sessionId) : targetSession;
+    const existingCursor = existingLeg ? this.#repository.findSourceCursor(
+      this.#deviceId,
+      reference.adapterId,
+      reference.locator
+    ) : null;
+    if (existingCursor && existingCursor.legId !== existingLeg?.legId) {
+      throw new SessionOperationError(
+        "out_of_sync",
+        "The native source locator belongs to a different client leg",
+        ["diagnose", "cancel"]
+      );
+    }
+    let snapshot;
+    try {
+      snapshot = await this.#readSnapshot(adapter, reference, existingCursor);
+      this.#assertSnapshotReference(snapshot, reference);
+      this.#assertSnapshotWorkspaceEvidence(snapshot, mode);
+    } catch (error) {
+      if (!existingCursor) {
+        if (error instanceof SessionOperationError) throw sanitizedOperationError(error);
+        throw initialSourceFailure("read", adapter.id, error);
+      }
+      const message = safeErrorMessage(error);
+      this.#markCursor(existingCursor, "out-of-sync", message);
+      throw new SessionOperationError(
+        "out_of_sync",
+        `Native transcript could not continue from its durable cursor: ${message}`,
+        ["retry", "diagnose"],
+        { adapterId: adapter.id, nativeSessionId: native.reference.nativeSessionId }
+      );
+    }
+    if (existingCursor && existingCursor.sourceFingerprint !== snapshot.sourceFingerprint) {
+      const message = "Native transcript identity changed; the previous cursor was retained";
+      this.#markCursor(existingCursor, "out-of-sync", message);
+      throw new SessionOperationError(
+        "out_of_sync",
+        "Native transcript was truncated or replaced; refusing to merge it into the existing timeline",
+        ["diagnose", "cancel"],
+        { adapterId: adapter.id, nativeSessionId: native.reference.nativeSessionId }
+      );
+    }
+    const now = normalizeClockTimestamp(this.#now());
+    const parseState = parseStateFor(snapshot);
+    const derivedTitle = sessionTitle(native, snapshot);
+    let events;
+    try {
+      events = snapshot.events.map(normalizeEvent);
+    } catch (error) {
+      if (existingCursor) this.#markCursor(existingCursor, "out-of-sync", safeErrorMessage(error));
+      throw error;
+    }
+    const activityAt = sourceActivityAt(native, events, now);
+    const startedAt = native.startedAt ?? firstEventAt(events) ?? activityAt;
+    const proposedSession = session ? null : {
+      sessionId: createId("ses", startedAt),
+      workspaceId: this.#binding.status === "bound" ? this.#binding.workspaceId : null,
+      title: derivedTitle.title,
+      status: "active",
+      createdAt: startedAt,
+      updatedAt: activityAt,
+      headEventId: null,
+      headSequence: 0,
+      headCheckpointId: null,
+      metadata: {
+        ...initialSessionMetadata(native, activityAt, parseState, derivedTitle.source),
+        rootScopeId: this.#rootScopeId
+      },
+      schemaVersion: SESSION_SCHEMA_VERSION
+    };
+    const sessionId = existingLeg?.sessionId ?? targetSession?.sessionId ?? proposedSession.sessionId;
+    const baseLegMetadata = existingLeg?.metadata ?? initialLegMetadata(native, activityAt, parseState);
+    const proposedLeg = existingLeg ?? {
+      legId: createId("leg", startedAt),
+      sessionId,
+      deviceId: this.#deviceId,
+      adapterId: reference.adapterId,
+      nativeSessionId: reference.nativeSessionId,
+      clientVersion: portableScalar(native.clientVersion),
+      model: portableScalar(native.model),
+      workspaceLocationId: this.#binding.status === "bound" ? this.#binding.locationId : null,
+      resumedFromCheckpointId: target?.resumedFromCheckpointId ?? null,
+      state: "attached",
+      startedAt,
+      endedAt: null,
+      metadata: {
+        ...baseLegMetadata,
+        rootScopeId: this.#rootScopeId,
+        ingestionMode: mode,
+        attachedSessionId: mode === "attach" ? sessionId : null,
+        attachedCheckpointId: mode === "attach" ? target?.resumedFromCheckpointId ?? null : null
+      },
+      schemaVersion: SESSION_SCHEMA_VERSION
+    };
+    const cursorStatus = cursorStatusFor(snapshot);
+    const nextCursor = {
+      sourceId: existingCursor?.sourceId ?? createId("src", now),
+      legId: proposedLeg.legId,
+      deviceId: this.#deviceId,
+      adapterId: native.reference.adapterId,
+      locator: native.reference.locator,
+      sourceFingerprint: snapshot.sourceFingerprint,
+      cursorKind: snapshot.nextCursor.kind,
+      cursorValue: snapshot.nextCursor.value,
+      lastSourceEventId: snapshot.nextCursor.lastSourceEventId ?? existingCursor?.lastSourceEventId ?? null,
+      parserVersion: snapshot.parserVersion,
+      lastSeenAt: monotonicSeenAt(existingCursor, now),
+      status: cursorStatus,
+      lastError: cursorError(snapshot),
+      schemaVersion: SESSION_SCHEMA_VERSION
+    };
+    const baseSessionMetadata = session?.metadata ?? proposedSession.metadata;
+    const sessionMetadata = {
+      ...mergeSessionMetadata(
+        baseSessionMetadata,
+        native,
+        activityAt,
+        parseState,
+        session?.headSequence ?? 0,
+        snapshot,
+        !session
+      ),
+      rootScopeId: this.#rootScopeId
+    };
+    const legMetadata = {
+      ...mergeLegMetadata(baseLegMetadata, native, activityAt, parseState, 0, snapshot),
+      rootScopeId: this.#rootScopeId,
+      ingestionMode: mode,
+      attachedSessionId: mode === "attach" ? sessionId : null,
+      attachedCheckpointId: mode === "attach" ? target?.resumedFromCheckpointId ?? null : null
+    };
+    let persisted;
+    try {
+      persisted = this.#repository.ingestTranscriptPage({
+        mode,
+        proposedSession,
+        proposedLeg,
+        targetSessionId: target?.sessionId ?? null,
+        rootScopeId: this.#rootScopeId,
+        events,
+        expectedHeadSequence: session?.headSequence ?? 0,
+        expectedCursor: existingCursor,
+        nextCursor,
+        titleCandidate: derivedTitle,
+        sessionMetadata,
+        legMetadata,
+        updatedAt: Math.max(activityAt, now)
+      });
+    } catch (error) {
+      if (existingCursor && !isHeadChanged(error)) {
+        this.#markCursor(existingCursor, "out-of-sync", safeErrorMessage(error));
+      }
+      throw error;
+    }
+    return {
+      session: persisted.session,
+      leg: persisted.leg,
+      cursor: persisted.cursor,
+      inserted: persisted.inserted,
+      createdSession: persisted.createdSession,
+      attached: mode === "attach",
+      truncated: snapshot.truncated,
+      diagnostics: sanitizeDiagnostics(snapshot.diagnostics)
+    };
+  }
+  async #readSnapshot(adapter, reference, cursor) {
+    return adapter.readSnapshot({
+      reference,
+      budget: this.#budget,
+      ...cursor ? {
+        cursor: {
+          kind: cursor.cursorKind,
+          value: cursor.cursorValue,
+          ...cursor.lastSourceEventId ? { lastSourceEventId: cursor.lastSourceEventId } : {}
+        }
+      } : {}
+    });
+  }
+  async #resolveReference(adapter, reference, allowBindingAuthority) {
+    if (reference.adapterId !== adapter.id || !nonEmpty(reference.nativeSessionId) || !nonEmpty(reference.locator)) {
+      throw invalidInput("Native session reference is incomplete or belongs to another adapter");
+    }
+    if (reference.workspaceRoot && reference.workspaceRoot !== this.#binding.rootPath) {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "Native session reference belongs to another workspace root",
+        ["cancel"]
+      );
+    }
+    if (!reference.workspaceRoot && !allowBindingAuthority) {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "Native session reference has no verified workspace provenance",
+        ["diagnose", "cancel"]
+      );
+    }
+    if (!adapter.resolveNativeReference) {
+      return {
+        ...reference,
+        workspaceRoot: reference.workspaceRoot ?? this.#binding.rootPath
+      };
+    }
+    const resolved = await adapter.resolveNativeReference({
+      nativeSessionId: reference.nativeSessionId,
+      locator: reference.locator,
+      workspaceRoot: this.#binding.rootPath
+    });
+    if (!resolved || resolved.adapterId !== adapter.id || resolved.nativeSessionId !== reference.nativeSessionId || resolved.locator !== reference.locator) {
+      throw new SessionOperationError(
+        "malformed_source",
+        "Adapter could not validate the native session reference inside its read-only roots",
+        ["diagnose", "cancel"]
+      );
+    }
+    if (resolved.workspaceRoot && resolved.workspaceRoot !== this.#binding.rootPath) {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "Resolved native session belongs to another workspace root",
+        ["cancel"]
+      );
+    }
+    return {
+      ...resolved,
+      workspaceRoot: resolved.workspaceRoot ?? reference.workspaceRoot ?? this.#binding.rootPath
+    };
+  }
+  #validateMode(target, mode) {
+    if (mode !== "import" && mode !== "attach") {
+      throw invalidInput(`Unsupported ingestion mode: ${String(mode)}`);
+    }
+    if (mode === "attach" && !target) {
+      throw invalidInput("Attach mode requires an explicitly selected portable session");
+    }
+    if (mode === "import" && target) {
+      throw invalidInput("Import mode cannot silently attach to a portable session");
+    }
+  }
+  #assertNativeWorkspaceEvidence(native, mode) {
+    const evidence = native.workspaceEvidence;
+    if (!evidence) return;
+    if (evidence.status === "verified" && (evidence.root !== this.#binding.rootPath || native.reference.workspaceRoot !== evidence.root)) {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "Native session workspace evidence does not match the active root",
+        ["cancel"]
+      );
+    }
+    if (mode === "import" && evidence.status !== "verified") {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "Native session workspace provenance is not verified for import",
+        ["diagnose", "cancel"]
+      );
+    }
+  }
+  #resolveTarget(target) {
+    if (!nonEmpty(target.sessionId)) throw invalidInput("Target session ID must be non-empty");
+    if (this.#binding.status !== "bound") {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "An ambiguous workspace cannot attach a native leg to an existing session",
+        ["cancel"]
+      );
+    }
+    const session = this.#repository.getSession(target.sessionId);
+    if (!session) {
+      throw new SessionOperationError(
+        "not_found",
+        `Portable session ${target.sessionId} was not found`,
+        ["cancel"]
+      );
+    }
+    this.#assertSessionWorkspace(session);
+    const checkpointId = target.resumedFromCheckpointId ?? null;
+    if (checkpointId !== null) {
+      const checkpoint = this.#repository.getCheckpoint(checkpointId);
+      if (!checkpoint || checkpoint.sessionId !== session.sessionId) {
+        throw invalidInput("Attach checkpoint does not belong to the selected portable session");
+      }
+    }
+    return session;
+  }
+  #assertSessionWorkspace(session, leg) {
+    const expectedWorkspaceId = this.#binding.status === "bound" ? this.#binding.workspaceId : null;
+    const persistedSessionScope = stringMetadata(session.metadata, "rootScopeId");
+    const sessionScopeMismatch = this.#binding.status === "unassigned" ? persistedSessionScope !== this.#rootScopeId : persistedSessionScope !== void 0 && persistedSessionScope !== this.#rootScopeId;
+    const legScopeMismatch = leg !== void 0 && stringMetadata(leg.metadata, "rootScopeId") !== this.#rootScopeId;
+    if (session.workspaceId !== expectedWorkspaceId || sessionScopeMismatch || legScopeMismatch) {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "Portable session does not belong to the active workspace binding",
+        ["cancel"],
+        {
+          expectedWorkspaceId,
+          actualWorkspaceId: session.workspaceId
+        }
+      );
+    }
+  }
+  #assertExistingClaim(leg, target, mode) {
+    const persistedMode = stringMetadata(leg.metadata, "ingestionMode");
+    if (persistedMode !== mode) {
+      throw invalidInput("Native leg ingestion mode does not match its persisted provenance");
+    }
+    if (mode === "import") {
+      if (target || leg.resumedFromCheckpointId !== null) {
+        throw invalidInput("Imported native leg cannot be reclassified or attached");
+      }
+      return;
+    }
+    const expectedCheckpointId = target?.resumedFromCheckpointId ?? null;
+    const metadataSessionId = stringMetadata(leg.metadata, "attachedSessionId");
+    const rawMetadataCheckpointId = leg.metadata.attachedCheckpointId;
+    const metadataCheckpointId = rawMetadataCheckpointId === null ? null : typeof rawMetadataCheckpointId === "string" ? rawMetadataCheckpointId : void 0;
+    if (!target || target.sessionId !== leg.sessionId || leg.resumedFromCheckpointId !== expectedCheckpointId || metadataSessionId !== leg.sessionId || metadataCheckpointId !== expectedCheckpointId) {
+      throw invalidInput("Explicit attach target does not match persisted resume provenance");
+    }
+  }
+  #assertSnapshotReference(snapshot, reference) {
+    if (snapshot.reference.adapterId !== reference.adapterId || snapshot.reference.nativeSessionId !== reference.nativeSessionId || snapshot.reference.locator !== reference.locator) {
+      throw new SessionOperationError(
+        "malformed_source",
+        "Adapter snapshot substituted a different native session reference",
+        ["diagnose", "cancel"]
+      );
+    }
+    if (!nonEmpty(snapshot.sourceFingerprint) || Buffer.byteLength(snapshot.sourceFingerprint, "utf8") > 512 || /[\0-\x1f\x7f]/u.test(snapshot.sourceFingerprint)) {
+      throw new SessionOperationError(
+        "malformed_source",
+        "Adapter snapshot did not provide a valid bounded source fingerprint",
+        ["diagnose", "cancel"]
+      );
+    }
+  }
+  #assertSnapshotWorkspaceEvidence(snapshot, mode) {
+    const evidence = normalizedWorkspaceEvidence(snapshot.workspaceEvidence);
+    if (evidence.status === "verified") {
+      if (evidence.root !== this.#binding.rootPath || snapshot.reference.workspaceRoot !== evidence.root) {
+        throw new SessionOperationError(
+          "workspace_mismatch",
+          "Snapshot workspace evidence does not match the active root",
+          ["cancel"]
+        );
+      }
+      return;
+    }
+    if (snapshot.reference.workspaceRoot !== void 0 || mode === "import") {
+      throw new SessionOperationError(
+        "workspace_mismatch",
+        "Snapshot workspace provenance is not verified for import",
+        ["diagnose", "cancel"]
+      );
+    }
+  }
+  #getAdapter(adapterId) {
+    const adapter = this.#adapters.get(adapterId);
+    if (!adapter) {
+      throw new SessionOperationError(
+        "adapter_unavailable",
+        `Adapter ${adapterId} is not registered in this ingestion service`,
+        ["setup", "cancel"]
+      );
+    }
+    return adapter;
+  }
+  #markCursor(cursor, status, message) {
+    try {
+      this.#repository.markIngestionSourceStatus({
+        expectedCursor: cursor,
+        rootScopeId: this.#rootScopeId,
+        status,
+        lastError: redactPortableText(message).slice(0, 2e3),
+        lastSeenAt: monotonicSeenAt(cursor, normalizeClockTimestamp(this.#now()))
+      });
+    } catch (error) {
+      if (isHeadChanged(error)) throw error;
+    }
+  }
+};
+function normalizeNativeInput(input) {
+  if ("reference" in input) return { ...input, reference: { ...input.reference } };
+  return { reference: { ...input } };
+}
+function normalizeNativeTimestamps(native) {
+  return {
+    ...native,
+    ...native.startedAt === void 0 ? {} : { startedAt: normalizeSourceTimestamp(native.startedAt, "Native session start timestamp") },
+    ...native.updatedAt === void 0 ? {} : { updatedAt: normalizeSourceTimestamp(native.updatedAt, "Native session activity timestamp") }
+  };
+}
+function nativeIdentity(adapterId, nativeSessionId) {
+  return `${adapterId}\0${nativeSessionId}`;
+}
+function compareDiscovery(left, right) {
+  return right.updatedAt - left.updatedAt || left.reference.adapterId.localeCompare(right.reference.adapterId) || left.reference.nativeSessionId.localeCompare(right.reference.nativeSessionId) || left.reference.locator.localeCompare(right.reference.locator);
+}
+function workspaceEvidence(candidate) {
+  return normalizedWorkspaceEvidence(candidate.workspaceEvidence);
+}
+function normalizedWorkspaceEvidence(evidence) {
+  const candidate = evidence;
+  if (candidate?.status === "verified" && validWorkspaceRoot(candidate.root) && ["claude.cwd", "codex.session_meta.cwd", "continue.workspaceDirectory"].includes(String(candidate.source))) {
+    return {
+      status: "verified",
+      root: candidate.root,
+      source: candidate.source
+    };
+  }
+  if (candidate?.status === "hint" && ["claude.path-key", "cursor.path-key"].includes(String(candidate.source))) {
+    return {
+      status: "hint",
+      source: candidate.source
+    };
+  }
+  return { status: "unknown", source: "none" };
+}
+function sanitizeDiscoveredSession(candidate, evidence) {
+  const metadata = redactJson(candidate.metadata ?? {});
+  const startedAt = candidate.startedAt === void 0 ? void 0 : normalizeSourceTimestamp(candidate.startedAt, "Native session start timestamp");
+  return {
+    reference: {
+      adapterId: candidate.reference.adapterId,
+      nativeSessionId: candidate.reference.nativeSessionId,
+      locator: candidate.reference.locator,
+      workspaceRoot: evidence.root
+    },
+    workspaceEvidence: evidence,
+    ...normalizeTitle(candidate.title) ? { title: normalizeTitle(candidate.title) } : {},
+    ...startedAt === void 0 ? {} : { startedAt },
+    updatedAt: normalizeSourceTimestamp(
+      candidate.updatedAt,
+      "Native session activity timestamp"
+    ),
+    ...portableScalar(candidate.clientVersion) ? { clientVersion: portableScalar(candidate.clientVersion) } : {},
+    ...portableScalar(candidate.model) ? { model: portableScalar(candidate.model) } : {},
+    ...portableScalar(candidate.gitBranch) ? { gitBranch: portableScalar(candidate.gitBranch) } : {},
+    ...portableScalar(candidate.gitCommit) ? { gitCommit: portableScalar(candidate.gitCommit) } : {},
+    metadata: metadata.value
+  };
+}
+function unassignedDiscoveryChoice(candidate, evidence) {
+  return {
+    reference: {
+      adapterId: candidate.reference.adapterId,
+      nativeSessionId: candidate.reference.nativeSessionId,
+      locator: candidate.reference.locator
+    },
+    workspaceEvidence: evidence,
+    updatedAt: normalizeSourceTimestamp(
+      candidate.updatedAt,
+      "Native session activity timestamp"
+    )
+  };
+}
+function validWorkspaceRoot(value) {
+  return typeof value === "string" && value.length > 0 && Buffer.byteLength(value, "utf8") <= 4096 && !/[\0-\x1f\x7f]/u.test(value) && isAbsolute(value);
+}
+function normalizeEvent(event) {
+  assertEventAuthority(event);
+  const text = event.textContent === void 0 ? void 0 : redactPortableText(event.textContent);
+  const payload = redactJson(event.payload ?? {});
+  const textWasRedacted = text !== event.textContent;
+  return {
+    sourceEventId: event.sourceEventId,
+    ...event.sourceSequence !== void 0 ? { sourceSequence: event.sourceSequence } : {},
+    kind: event.kind,
+    ...event.role !== void 0 ? { role: event.role } : {},
+    occurredAt: normalizeSourceTimestamp(event.occurredAt, "Event timestamp"),
+    ...text !== void 0 ? { textContent: text } : {},
+    payload: payload.value,
+    redactionState: textWasRedacted || payload.redacted ? "redacted" : "none"
+  };
+}
+function assertEventAuthority(event) {
+  if (!nonEmpty(event.sourceEventId)) {
+    throw new SessionOperationError(
+      "malformed_source",
+      "Adapter emitted an event without a stable source ID",
+      ["diagnose"]
+    );
+  }
+  if (event.kind === "message.user" && event.role !== "user") {
+    throw new SessionOperationError(
+      "malformed_source",
+      "Adapter emitted a user message without verified user provenance",
+      ["diagnose"]
+    );
+  }
+  if (event.kind === "message.assistant" && event.role !== "assistant") {
+    throw new SessionOperationError(
+      "malformed_source",
+      "Adapter emitted an assistant message with inconsistent provenance",
+      ["diagnose"]
+    );
+  }
+}
+function redactJson(value, seen = /* @__PURE__ */ new Set(), depth = 0) {
+  if (value === null || typeof value === "boolean") return { value, redacted: false };
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? { value, redacted: false } : { value: String(value), redacted: true };
+  }
+  if (typeof value === "string") {
+    const redacted = boundedPortableText(value, METADATA_STRING_MAX_CHARS);
+    return { value: redacted, redacted: redacted !== value };
+  }
+  if (typeof value !== "object") {
+    const stringified = boundedPortableText(String(value), METADATA_STRING_MAX_CHARS);
+    return { value: stringified, redacted: true };
+  }
+  if (seen.has(value)) return { value: "[REDACTED CIRCULAR VALUE]", redacted: true };
+  if (depth >= 12) return { value: "[TRUNCATED NESTED VALUE]", redacted: true };
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      let changed2 = false;
+      const result2 = value.slice(0, 1e3).map((item) => {
+        const nested = redactJson(item, seen, depth + 1);
+        changed2 ||= nested.redacted;
+        return nested.value;
+      });
+      return { value: result2, redacted: changed2 || value.length > result2.length };
+    }
+    let changed = false;
+    const result = {};
+    for (const [key, item] of Object.entries(value).slice(0, 1e3)) {
+      const portableKey = boundedPortableText(key, METADATA_KEY_MAX_CHARS) || "[REDACTED KEY]";
+      if (Object.prototype.hasOwnProperty.call(result, portableKey)) {
+        changed = true;
+        continue;
+      }
+      if (sensitiveKey(key)) {
+        result[portableKey] = "[REDACTED]";
+        changed = true;
+        continue;
+      }
+      const nested = redactJson(item, seen, depth + 1);
+      result[portableKey] = nested.value;
+      changed ||= portableKey !== key || nested.redacted;
+    }
+    return {
+      value: result,
+      redacted: changed || Object.keys(value).length > Object.keys(result).length
+    };
+  } finally {
+    seen.delete(value);
+  }
+}
+function sensitiveKey(key) {
+  return /(?:authorization|cookie|api[-_]?key|api[-_]?token|access[-_]?key|secret|token|password|passwd|private[-_]?key)/i.test(
+    key
+  );
+}
+function sessionTitle(native, snapshot) {
+  const nativeTitle = normalizeTitle(native.title);
+  if (nativeTitle) return { title: nativeTitle, source: "native" };
+  const firstUserMessage = snapshot.events.find(
+    (event) => event.kind === "message.user" && event.role === "user" && nonEmpty(event.textContent)
+  )?.textContent;
+  const userTitle = normalizeTitle(firstUserMessage);
+  return userTitle ? { title: userTitle, source: "user" } : { title: `Untitled ${native.reference.adapterId} session`, source: "fallback" };
+}
+function normalizeTitle(value) {
+  if (!value) return null;
+  const redacted = redactPortableText(value).replace(/\s+/gu, " ").trim();
+  if (!redacted) return null;
+  return [...redacted].slice(0, SESSION_TITLE_MAX_CHARS).join("");
+}
+function portableScalar(value) {
+  if (!value) return null;
+  const portable = redactPortableText(value).trim();
+  return portable ? [...portable].slice(0, 512).join("") : null;
+}
+function boundedPortableText(value, maxChars) {
+  return [...redactPortableText(value)].slice(0, maxChars).join("");
+}
+function sourceActivityAt(native, events, fallback) {
+  const timestamps = [native.updatedAt, ...events.map((event) => event.occurredAt)].filter((value) => value !== void 0);
+  return timestamps.length > 0 ? Math.max(...timestamps) : fallback;
+}
+function firstEventAt(events) {
+  return events.map((event) => event.occurredAt).sort((left, right) => left - right)[0];
+}
+function normalizeSourceTimestamp(value, name) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+    throw new SessionOperationError(
+      "malformed_source",
+      `${name} must be a finite non-negative safe millisecond value`,
+      ["diagnose", "cancel"]
+    );
+  }
+  return Math.floor(value);
+}
+function normalizeClockTimestamp(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > Number.MAX_SAFE_INTEGER) {
+    throw invalidInput("Ingestion clock must return a finite non-negative safe millisecond value");
+  }
+  return Math.floor(value);
+}
+function cursorStatusFor(snapshot) {
+  if (snapshot.diagnostics.some((diagnostic) => /unsupported/i.test(diagnostic.code))) {
+    return "unsupported";
+  }
+  if (snapshot.diagnostics.some(
+    (diagnostic) => diagnostic.level === "error" || /^malformed(?:_|$)/i.test(diagnostic.code)
+  )) {
+    return "malformed";
+  }
+  return "active";
+}
+function parseStateFor(snapshot) {
+  const status = cursorStatusFor(snapshot);
+  if (status !== "active") return status;
+  if (snapshot.truncated || snapshot.diagnostics.some((diagnostic) => diagnostic.code === "incomplete_record")) {
+    return "partial";
+  }
+  return "complete";
+}
+function cursorError(snapshot) {
+  const material = snapshot.diagnostics.filter(
+    (diagnostic) => diagnostic.level === "error" || /^malformed(?:_|$)/i.test(diagnostic.code) || /unsupported/i.test(diagnostic.code)
+  );
+  if (material.length === 0) return null;
+  return redactPortableText(
+    material.map((diagnostic) => `[${diagnostic.code}] ${diagnostic.message}`).join("; ")
+  ).slice(0, 2e3);
+}
+function sanitizeDiagnostics(diagnostics) {
+  return diagnostics.slice(0, 1e3).map((diagnostic) => {
+    const candidate = diagnostic;
+    const code = typeof candidate?.code === "string" ? boundedPortableText(candidate.code, 128) : "invalid_diagnostic";
+    const message = typeof candidate?.message === "string" ? boundedPortableText(candidate.message, 2e3) : "Adapter returned an invalid diagnostic";
+    const sanitized = {
+      level: candidate?.level === "error" ? "error" : "warning",
+      code: code || "invalid_diagnostic",
+      message
+    };
+    if (typeof candidate?.sourceSequence === "number" && Number.isSafeInteger(candidate.sourceSequence) && candidate.sourceSequence >= 0) {
+      sanitized.sourceSequence = candidate.sourceSequence;
+    }
+    return sanitized;
+  });
+}
+function initialSessionMetadata(native, activityAt, parseState, titleSource) {
+  return {
+    ...mergeSessionMetadata(
+      {},
+      native,
+      activityAt,
+      parseState,
+      0,
+      null,
+      true
+    ),
+    titleSource
+  };
+}
+function mergeSessionMetadata(existing, native, activityAt, parseState, eventCount, snapshot, preserveOrigin) {
+  const metadata = {
+    ...existing,
+    lastSourceAdapter: native.reference.adapterId,
+    lastSourceNativeSessionId: native.reference.nativeSessionId,
+    sourceActivityAt: Math.max(
+      timestampMetadata(existing, "sourceActivityAt") ?? 0,
+      activityAt
+    ),
+    eventCount,
+    parseState,
+    provenance: "imported-history",
+    ...native.gitBranch ? { gitBranch: portableScalar(native.gitBranch) } : {},
+    ...native.gitCommit ? { gitCommit: portableScalar(native.gitCommit) } : {},
+    ...snapshot ? { sourceTruncated: snapshot.truncated } : {}
+  };
+  if (preserveOrigin || !("sourceAdapter" in existing)) {
+    metadata.sourceAdapter = native.reference.adapterId;
+    metadata.sourceNativeSessionId = native.reference.nativeSessionId;
+  }
+  return metadata;
+}
+function initialLegMetadata(native, activityAt, parseState) {
+  const adapterMetadata = redactJson(native.metadata ?? {});
+  return {
+    sourceAdapter: native.reference.adapterId,
+    sourceNativeSessionId: native.reference.nativeSessionId,
+    sourceLocator: native.reference.locator,
+    sourceTitle: normalizeTitle(native.title),
+    sourceStartedAt: native.startedAt ?? null,
+    sourceActivityAt: activityAt,
+    gitBranch: portableScalar(native.gitBranch),
+    gitCommit: portableScalar(native.gitCommit),
+    eventCount: 0,
+    parseState,
+    provenance: "imported-history",
+    adapterMetadata: adapterMetadata.value
+  };
+}
+function mergeLegMetadata(existing, native, activityAt, parseState, inserted, snapshot) {
+  const previousCount = numberMetadata(existing, "eventCount") ?? 0;
+  const diagnostics = redactJson(sanitizeDiagnostics(snapshot.diagnostics));
+  return {
+    ...existing,
+    sourceAdapter: native.reference.adapterId,
+    sourceNativeSessionId: native.reference.nativeSessionId,
+    sourceLocator: native.reference.locator,
+    sourceTitle: normalizeTitle(native.title),
+    sourceStartedAt: native.startedAt ?? timestampMetadata(existing, "sourceStartedAt") ?? null,
+    sourceActivityAt: Math.max(
+      timestampMetadata(existing, "sourceActivityAt") ?? 0,
+      activityAt
+    ),
+    gitBranch: native.gitBranch ? portableScalar(native.gitBranch) : existing.gitBranch ?? null,
+    gitCommit: native.gitCommit ? portableScalar(native.gitCommit) : existing.gitCommit ?? null,
+    eventCount: previousCount + inserted,
+    parseState,
+    sourceTruncated: snapshot.truncated,
+    parseDiagnostics: diagnostics.value,
+    provenance: "imported-history"
+  };
+}
+function monotonicSeenAt(cursor, now) {
+  if (!cursor) return now;
+  const previous = normalizeStoredTimestamp(cursor.lastSeenAt, "Stored cursor timestamp");
+  if (previous === Number.MAX_SAFE_INTEGER) {
+    throw new SessionOperationError(
+      "out_of_sync",
+      "Stored cursor timestamp cannot advance safely",
+      ["diagnose", "cancel"]
+    );
+  }
+  return Math.max(now, previous + 1);
+}
+function stringMetadata(metadata, key) {
+  const value = metadata[key];
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function numberMetadata(metadata, key) {
+  const value = metadata[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function timestampMetadata(metadata, key) {
+  const value = metadata[key];
+  return value === void 0 || value === null ? void 0 : normalizeStoredTimestamp(value, `Stored ${key} timestamp`);
+}
+function normalizeStoredTimestamp(value, name) {
+  try {
+    return normalizeSourceTimestamp(value, name);
+  } catch {
+    throw new SessionOperationError(
+      "out_of_sync",
+      `${name} is invalid`,
+      ["diagnose", "cancel"]
+    );
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function safeErrorMessage(error) {
+  return boundedPortableText(errorMessage(error), 2e3);
+}
+function initialSourceFailure(operation, adapterId, error) {
+  return new SessionOperationError(
+    "malformed_source",
+    `Adapter ${adapterId} could not ${operation} the selected native transcript: ${safeErrorMessage(error)}`,
+    ["retry", "diagnose", "cancel"],
+    { adapterId }
+  );
+}
+function sanitizedOperationError(error) {
+  const code = typeof error.code === "string" && OPERATION_ERROR_CODES.has(error.code) ? error.code : "invalid_input";
+  const alternatives = [];
+  if (Array.isArray(error.alternatives)) {
+    for (const alternative of error.alternatives) {
+      if (typeof alternative === "string" && OPERATION_ALTERNATIVES.has(alternative) && !alternatives.includes(alternative)) {
+        alternatives.push(alternative);
+      }
+    }
+  }
+  const redactedDetails = redactJson(error.details).value;
+  const details = redactedDetails !== null && typeof redactedDetails === "object" && !Array.isArray(redactedDetails) ? redactedDetails : {};
+  return new SessionOperationError(
+    code,
+    safeErrorMessage(error),
+    alternatives,
+    details
+  );
+}
+function ingestionOperationFailure(error) {
+  if (error instanceof SessionOperationError) return sanitizedOperationError(error);
+  return new SessionOperationError(
+    "invalid_input",
+    `Native session ingestion failed: ${safeErrorMessage(error)}`,
+    ["retry", "diagnose", "cancel"]
+  );
+}
+function isHeadChanged(error) {
+  return error instanceof SessionOperationError && error.code === "head_changed";
+}
+function rootScopeId(binding, deviceId) {
+  if (binding.status === "bound") return binding.workspaceId;
+  return `urs_${createHash("sha256").update(deviceId).update("\0").update(binding.rootPath).digest("hex")}`;
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function invalidInput(message) {
+  return new SessionOperationError("invalid_input", message, ["cancel"]);
+}
+
+// src/commands/session.ts
+var MAX_TEXT_CHARS = 16e3;
+var MAX_FILE_CHARS = 64e3;
+var MAX_QUERY_CHARS = 256;
+var MAX_LIMIT = 100;
+var FATAL_UTF8_DECODER = new TextDecoder("utf-8", {
+  fatal: true,
+  ignoreBOM: false
 });
-program.command("compile-session").description("Stop hook: queue transcript for compilation").action(async () => {
+var EVENT_KINDS = /* @__PURE__ */ new Set([
+  "message.user",
+  "message.assistant",
+  "tool.call",
+  "tool.result",
+  "checkpoint",
+  "correction",
+  "tombstone"
+]);
+var SESSION_STATES = /* @__PURE__ */ new Set([
+  "active",
+  "checkpointed",
+  "closed",
+  "archived"
+]);
+var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
+  "not_found",
+  "adapter_unavailable",
+  "unsupported_version",
+  "malformed_source",
+  "workspace_mismatch",
+  "head_changed",
+  "handoff_expired",
+  "handoff_consumed",
+  "wrong_destination",
+  "lease_conflict",
+  "invalid_token",
+  "out_of_sync",
+  "invalid_input"
+]);
+function createSessionCommand(dependencies = {}) {
+  const deps = resolveDependencies(dependencies);
+  const command = new Command2("session").description("Manage portable cross-agent sessions");
+  command.command("list").description("Discover and list portable sessions for the current workspace").option("--adapter <id>", "Filter by source adapter").option("--status <status>", "Filter by session state").option("--json", "Print machine-readable JSON").action(async (options) => {
+    const adapterId = options.adapter === void 0 ? void 0 : requireAdapter2(deps, options.adapter, "adapter");
+    const status = options.status === void 0 ? void 0 : sessionState(options.status);
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const discovery = await context.discover();
+      const sessions = context.service.listSessions({
+        ...adapterId === void 0 ? {} : { adapterId },
+        ...status === void 0 ? {} : { status }
+      });
+      const result = {
+        diagnostics: publicDiagnostics(discovery.diagnostics),
+        discovery: publicDiscovery(discovery),
+        sessions: sessions.map((item) => publicSessionItem(item, context.project))
+      };
+      if (options.json) return writeJson2(deps.write, result);
+      writeDiscoveryDiagnostics(deps.write, discovery);
+      writeSessionList(deps.write, result.sessions, false, sessions);
+    });
+  });
+  command.command("inspect <session-id>").description("Inspect a portable session").option("--json", "Print machine-readable JSON").action(async (sessionId, options) => {
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const diagnostics = context.workspaceDiagnostics ?? [];
+      if (!options.json) writeDiagnostics(deps.write, diagnostics);
+      const inspection = context.service.inspectSession(identifier(sessionId, "Session ID"));
+      const result = {
+        ...publicInspection(inspection, context.project),
+        diagnostics: publicDiagnostics(diagnostics)
+      };
+      if (options.json) return writeJson2(deps.write, result);
+      writeInspection(deps.write, result, inspection, context.workspacePath);
+    });
+  });
+  command.command("resume [session-id]").description("Prepare an explicit handoff to another adapter").requiredOption("--to <adapter>", "Destination adapter").option("--checkpoint <id>", "Resume from a specific checkpoint").option("--fork", "Fork instead of continuing the selected session").option("--confirm-active-source", "Confirm takeover from an active source").option("--exclude-event <event-id...>", "Exclude selected event IDs from this capsule").option("--json", "Print machine-readable JSON without prompting").action(async (sessionId, options) => {
+    const destinationAdapterId = requireAdapter2(deps, options.to, "destination adapter");
+    if (!sessionId && (options.json || !deps.isTTY)) {
+      throw invalidInput2(
+        "Pass a session ID or run this command in an interactive terminal"
+      );
+    }
+    if (!options.json && !deps.isTTY) {
+      throw invalidInput2("Interactive confirmation requires a terminal; use --json for scripts");
+    }
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const discovery = await context.discover();
+      if (!options.json) writeDiscoveryDiagnostics(deps.write, discovery);
+      let selected;
+      if (sessionId) {
+        selected = {
+          sessionId: identifier(sessionId, "Session ID"),
+          mode: options.fork ? "fork" : "continue",
+          confirmActiveSource: options.confirmActiveSource === true
+        };
+      } else {
+        selected = await pickSession(context, deps, discovery);
+        if (selected === null) return;
+        if (!selected) {
+          deps.write("Resume cancelled.\n");
+          return;
+        }
+      }
+      const inspection = context.service.inspectSession(selected.sessionId);
+      const prepareInput = {
+        sessionId: inspection.session.sessionId,
+        ...options.checkpoint === void 0 ? {} : { checkpointId: identifier(options.checkpoint, "Checkpoint ID") },
+        destinationAdapterId,
+        mode: selected.mode,
+        expectedHeadSequence: inspection.session.headSequence,
+        ...selected.confirmActiveSource ? { confirmActiveSource: true } : {},
+        ...options.excludeEvent === void 0 ? {} : { excludeEventIds: eventExclusionIds(options.excludeEvent) }
+      };
+      const prepared = await context.service.prepareResume(prepareInput);
+      await finishPreparedResume(
+        context,
+        deps,
+        prepareInput,
+        prepared,
+        options.json === true,
+        discovery.diagnostics
+      );
+    });
+  });
+  command.command("append <session-id>").description("Append one human-authorized portable event").requiredOption("--kind <kind>", "Event kind").option("--text <text>", "Event text").option("--stdin", "Read event text from stdin").option("--json", "Print machine-readable JSON").action(async (sessionId, options) => {
+    if (options.text !== void 0 === (options.stdin === true)) {
+      throw invalidInput2("Choose exactly one of --text or --stdin");
+    }
+    const kind = eventKind(options.kind);
+    const text = portableText(
+      options.stdin ? await deps.readStdin() : options.text,
+      "Event text"
+    );
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const diagnostics = context.workspaceDiagnostics ?? [];
+      if (!options.json) writeDiagnostics(deps.write, diagnostics);
+      const inspection = context.service.inspectSession(identifier(sessionId, "Session ID"));
+      const appended = context.service.appendSessionEventOnce({
+        sessionId: inspection.session.sessionId,
+        idempotencyKey: idempotencyKey("append", deps.now()),
+        expectedHeadSequence: inspection.session.headSequence,
+        kind,
+        text
+      });
+      const result = {
+        inserted: appended.inserted,
+        headEventId: appended.headEventId,
+        headSequence: appended.headSequence,
+        events: appended.events.map(publicEvent),
+        diagnostics: publicDiagnostics(diagnostics)
+      };
+      if (options.json) return writeJson2(deps.write, result);
+      deps.write(`Appended ${appended.inserted} event(s); head is ${appended.headSequence}.
+`);
+    });
+  });
+  command.command("checkpoint <session-id>").description("Create one human-authorized portable checkpoint").option("--summary <text>", "Checkpoint summary").option("--summary-file <path>", "Read summary text from a file").option("--state-file <path>", "Read checkpoint JSON from a file").option("--json", "Print machine-readable JSON").action(async (sessionId, options) => {
+    const selectedInputs = [options.summary, options.summaryFile, options.stateFile].filter((value) => value !== void 0).length;
+    if (selectedInputs > 1) {
+      throw invalidInput2("Choose only one of --summary, --summary-file, or --state-file");
+    }
+    const checkpointInput = checkpointOptions(options, deps.readFile);
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const diagnostics = context.workspaceDiagnostics ?? [];
+      if (!options.json) writeDiagnostics(deps.write, diagnostics);
+      const inspection = context.service.inspectSession(identifier(sessionId, "Session ID"));
+      const created = context.service.checkpointSessionOnce({
+        sessionId: inspection.session.sessionId,
+        idempotencyKey: idempotencyKey("checkpoint", deps.now()),
+        expectedHeadSequence: inspection.session.headSequence,
+        ...checkpointInput
+      });
+      const result = {
+        ...publicCheckpoint(created),
+        diagnostics: publicDiagnostics(diagnostics)
+      };
+      if (options.json) return writeJson2(deps.write, result);
+      deps.write(`Checkpoint ${result.checkpointId} created at sequence ${result.throughSequence}.
+`);
+    });
+  });
+  command.command("fork <session-id>").description("Prepare a fork handoff from a checkpoint").requiredOption("--from <checkpoint-id|latest>", "Fork checkpoint").requiredOption("--to <adapter>", "Destination adapter").option("--title <title>", "Reserved title for the destination fork").option("--exclude-event <event-id...>", "Exclude selected event IDs from this capsule").option("--json", "Print machine-readable JSON").action(async (sessionId, options) => {
+    const destinationAdapterId = requireAdapter2(deps, options.to, "destination adapter");
+    if (!options.json && !deps.isTTY) {
+      throw invalidInput2("Interactive confirmation requires a terminal; use --json for scripts");
+    }
+    const forkTitle = options.title === void 0 ? void 0 : portableText(options.title, "Fork title");
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const diagnostics = context.workspaceDiagnostics ?? [];
+      if (!options.json) writeDiagnostics(deps.write, diagnostics);
+      const inspection = context.service.inspectSession(identifier(sessionId, "Session ID"));
+      const checkpointId = options.from === "latest" ? inspection.session.headCheckpointId ?? void 0 : identifier(options.from, "Checkpoint ID");
+      const prepareInput = {
+        sessionId: inspection.session.sessionId,
+        ...checkpointId === void 0 ? {} : { checkpointId },
+        destinationAdapterId,
+        mode: "fork",
+        expectedHeadSequence: inspection.session.headSequence,
+        ...forkTitle === void 0 ? {} : { forkTitle },
+        ...options.excludeEvent === void 0 ? {} : { excludeEventIds: eventExclusionIds(options.excludeEvent) }
+      };
+      const prepared = await context.service.prepareResume(prepareInput);
+      await finishPreparedResume(
+        context,
+        deps,
+        prepareInput,
+        prepared,
+        options.json === true,
+        diagnostics
+      );
+    });
+  });
+  command.command("history <session-id>").description("Read a bounded page of portable session history").option("--before <cursor>", "Opaque history cursor").option("--limit <number>", "Events per page", "50").option("--json", "Print machine-readable JSON").action(async (sessionId, options) => {
+    const limit = boundedInteger(options.limit, 1, MAX_LIMIT, "History limit");
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const diagnostics = context.workspaceDiagnostics ?? [];
+      if (!options.json) writeDiagnostics(deps.write, diagnostics);
+      const page = context.service.getSessionHistory({
+        sessionId: identifier(sessionId, "Session ID"),
+        limit,
+        ...options.before === void 0 ? {} : { beforeCursor: identifier(options.before, "History cursor") }
+      });
+      const result = {
+        events: page.events.map(publicEvent),
+        beforeCursor: page.beforeCursor,
+        diagnostics: publicDiagnostics(diagnostics)
+      };
+      if (options.json) return writeJson2(deps.write, result);
+      for (const event of result.events) {
+        deps.write(`${event.sequence}	${terminalText2(event.kind)}	${terminalText2(event.text ?? "")}
+`);
+      }
+      if (result.beforeCursor) deps.write(`Older events: ${terminalText2(result.beforeCursor)}
+`);
+    });
+  });
+  return command;
+}
+function createHandoffCommand(dependencies = {}) {
+  const deps = resolveDependencies(dependencies);
+  const command = new Command2("handoff").description("Inspect and cancel prepared handoffs");
+  command.command("list").description("List pending handoffs for the current workspace").option("--json", "Print machine-readable JSON").action(async (options) => {
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const diagnostics = context.workspaceDiagnostics ?? [];
+      if (!options.json) writeDiagnostics(deps.write, diagnostics);
+      const result = {
+        handoffs: context.service.listPendingHandoffs().map((handoff) => ({
+          handoffId: handoff.handoffId,
+          sessionId: handoff.sessionId,
+          checkpointId: handoff.checkpointId,
+          targetAdapterId: handoff.targetAdapterId,
+          mode: handoff.mode,
+          createdAt: handoff.createdAt,
+          expiresAt: handoff.expiresAt
+        })),
+        diagnostics: publicDiagnostics(diagnostics)
+      };
+      if (options.json) return writeJson2(deps.write, result);
+      for (const handoff of result.handoffs) {
+        deps.write(
+          `${terminalText2(handoff.handoffId)}	${terminalText2(handoff.mode)}	${terminalText2(handoff.targetAdapterId)}	${terminalText2(handoff.sessionId)}
+`
+        );
+      }
+    });
+  });
+  command.command("cancel <handoff-id>").description("Cancel a pending handoff").option("--json", "Print machine-readable JSON").action(async (handoffId, options) => {
+    await withContext(deps, PORTABLE_CLI_ADAPTER_ID, async (context) => {
+      const diagnostics = context.workspaceDiagnostics ?? [];
+      if (!options.json) writeDiagnostics(deps.write, diagnostics);
+      const id = identifier(handoffId, "Handoff ID");
+      const cancelled = context.service.cancelHandoff(id);
+      const result = {
+        handoffId: id,
+        cancelled,
+        diagnostics: publicDiagnostics(diagnostics)
+      };
+      if (options.json) return writeJson2(deps.write, result);
+      deps.write(`Handoff ${terminalText2(id)} cancelled.
+`);
+    });
+  });
+  return command;
+}
+function registerSessionCommands(program2, dependencies = {}) {
+  program2.addCommand(createSessionCommand(dependencies));
+  program2.addCommand(createHandoffCommand(dependencies));
+}
+async function createDefaultContext(clientAdapterId = PORTABLE_CLI_ADAPTER_ID) {
+  const adapters = listAdapters();
+  if (clientAdapterId !== PORTABLE_CLI_ADAPTER_ID && !adapters.some((adapter) => adapter.id === clientAdapterId)) {
+    throw invalidInput2(`Unknown destination adapter: ${clientAdapterId}`);
+  }
+  const deviceId = loadOrCreateDeviceId();
+  const repository = new SqliteSessionRepository(getSessionDbPath());
+  try {
+    const binding = resolveWorkspace(process.cwd(), deviceId, repository);
+    const workspaceDiagnostics = binding.gitIdentityMismatch ? [{
+      adapterId: clientAdapterId,
+      code: "git_identity_mismatch",
+      message: "Git identity changed at this workspace path; verify the open repository before resuming"
+    }] : [];
+    const ingestion = new SessionIngestionService({
+      repository,
+      adapters,
+      binding,
+      deviceId,
+      budget: DEFAULT_READ_BUDGET
+    });
+    const service = new SessionService({
+      repository,
+      binding,
+      deviceId,
+      clientAdapterId,
+      adapters,
+      authority: "human",
+      ingestion
+    });
+    return {
+      service,
+      project: basename(binding.rootPath),
+      workspacePath: binding.rootPath,
+      workspaceDiagnostics,
+      async discover() {
+        const discovered = await ingestion.discoverSessions();
+        let imported = 0;
+        const diagnostics = [
+          ...workspaceDiagnostics,
+          ...discovered.diagnostics.map((diagnostic) => ({ ...diagnostic }))
+        ];
+        for (const candidate of discovered.sessions) {
+          if (candidate.workspaceEvidence.status !== "verified") continue;
+          try {
+            await ingestion.ingestNativeSession(candidate);
+            imported += 1;
+          } catch {
+            diagnostics.push({
+              adapterId: candidate.reference.adapterId,
+              code: "import_failed",
+              message: "A verified native session could not be imported"
+            });
+          }
+        }
+        return {
+          searchedAdapters: [...discovered.searchedAdapters],
+          imported,
+          diagnostics
+        };
+      },
+      close: () => repository.close()
+    };
+  } catch (error) {
+    repository.close();
+    throw error;
+  }
+}
+function resolveDependencies(dependencies) {
+  return {
+    createContext: dependencies.createContext ?? createDefaultContext,
+    adapterIds: dependencies.adapters ?? listAdapters().map((adapter) => adapter.id),
+    write: dependencies.write ?? ((value) => process.stdout.write(value)),
+    isTTY: dependencies.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    ...dependencies.prompt === void 0 ? {} : { prompt: dependencies.prompt },
+    createPrompt: dependencies.createPrompt ?? readlinePrompt,
+    readStdin: dependencies.readStdin ?? (() => readBoundedStdin(MAX_TEXT_CHARS)),
+    readFile: dependencies.readFile ?? readBoundedInputFile,
+    now: dependencies.now ?? Date.now
+  };
+}
+async function withContext(dependencies, clientAdapterId, operation) {
+  const context = await dependencies.createContext(clientAdapterId);
+  try {
+    return await operation(context);
+  } finally {
+    context.close();
+  }
+}
+async function pickSession(context, dependencies, discovery) {
+  const ownedPrompt = dependencies.prompt ? void 0 : readlinePrompt();
+  const prompt = dependencies.prompt ?? ownedPrompt;
   try {
-    const { handleStop } = await import("./stop-WGGRX6TQ.js");
-    let payload;
+    const sessions = context.service.listSessions();
+    if (sessions.length === 0) {
+      dependencies.write("No portable sessions found for this workspace.\n");
+      dependencies.write(
+        `Searched adapters: ${terminalText2(discovery.searchedAdapters.join(", "))}
+`
+      );
+      dependencies.write(
+        "Diagnose an integration with: agentcache adapter doctor <adapter-id>\n"
+      );
+      return null;
+    }
+    while (true) {
+      const query = bounded(
+        (await prompt.ask("Search sessions (or type cancel): ")).trim(),
+        MAX_QUERY_CHARS,
+        "Search query"
+      );
+      if (query.toLowerCase() === "cancel") return void 0;
+      const matches = sessions.filter((item) => matchesQuery(item, context.project, query));
+      if (matches.length === 0) {
+        dependencies.write("No matching sessions. Search again or type cancel.\n");
+        continue;
+      }
+      writeSessionList(
+        dependencies.write,
+        matches.map((item) => publicSessionItem(item, context.project)),
+        true,
+        matches
+      );
+      const selection = (await prompt.ask("Select a session number, search, or cancel: ")).trim();
+      if (selection.toLowerCase() === "cancel") return void 0;
+      if (selection.toLowerCase() === "search") continue;
+      const index = Number(selection);
+      if (!Number.isSafeInteger(index) || index < 1 || index > matches.length) {
+        dependencies.write("Invalid selection; no session was selected.\n");
+        continue;
+      }
+      const inspection = context.service.inspectSession(matches[index - 1].session.sessionId);
+      writeInspection(
+        dependencies.write,
+        publicInspection(inspection, context.project),
+        inspection,
+        context.workspacePath
+      );
+      while (true) {
+        const action = (await prompt.ask("Choose continue, fork, back, or cancel: ")).trim().toLowerCase();
+        if (action === "cancel") return void 0;
+        if (action === "back") break;
+        if (action === "fork") {
+          return { sessionId: inspection.session.sessionId, mode: "fork", confirmActiveSource: false };
+        }
+        if (action === "continue") {
+          if (inspection.activeWriter) {
+            const confirmation = (await prompt.ask(
+              "The source is active. Type continue to confirm takeover, or cancel: "
+            )).trim().toLowerCase();
+            if (confirmation !== "continue") return void 0;
+          }
+          return {
+            sessionId: inspection.session.sessionId,
+            mode: "continue",
+            confirmActiveSource: inspection.activeWriter !== null
+          };
+        }
+        dependencies.write("Invalid action; nothing was selected.\n");
+      }
+    }
+  } finally {
+    ownedPrompt?.close?.();
+  }
+}
+function readlinePrompt() {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  return {
+    ask: (message) => readline.question(message),
+    close: () => readline.close()
+  };
+}
+function matchesQuery(item, project, query) {
+  if (!query) return true;
+  const needle = query.toLowerCase();
+  return [
+    item.session.sessionId,
+    item.session.title,
+    item.session.status,
+    project,
+    ...item.legs.map((leg) => leg.adapterId)
+  ].some((value) => value.toLowerCase().includes(needle));
+}
+function publicDiscovery(discovery) {
+  return {
+    searchedAdapters: [...discovery.searchedAdapters],
+    imported: discovery.imported,
+    diagnostics: publicDiagnostics(discovery.diagnostics)
+  };
+}
+function publicDiagnostics(diagnostics) {
+  return diagnostics.map((diagnostic) => ({
+    adapterId: diagnostic.adapterId,
+    code: bounded(diagnostic.code, 128, "Diagnostic code"),
+    message: bounded(diagnostic.message, 1024, "Diagnostic message")
+  }));
+}
+function publicSessionItem(item, project) {
+  return {
+    sessionId: item.session.sessionId,
+    sourceAdapters: [...new Set(item.legs.map((leg) => leg.adapterId))],
+    project,
+    title: item.session.title,
+    lastActivity: item.session.updatedAt,
+    state: item.session.status,
+    headSequence: item.session.headSequence,
+    headCheckpointId: item.session.headCheckpointId,
+    fork: item.fork === null ? null : {
+      parentSessionId: item.fork.parentSessionId,
+      forkedFromCheckpointId: item.fork.forkedFromCheckpointId,
+      forkedFromEventId: item.fork.forkedFromEventId,
+      createdAt: item.fork.createdAt
+    },
+    activeWriter: item.activeWriter === null ? null : {
+      legId: item.activeWriter.legId,
+      generation: item.activeWriter.generation,
+      expiresAt: item.activeWriter.expiresAt
+    }
+  };
+}
+function publicInspection(inspection, project) {
+  return {
+    ...publicSessionItem(inspection, project),
+    eventCount: inspection.eventCount,
+    checkpoints: inspection.checkpoints.map(publicCheckpoint),
+    forks: inspection.forks.map((fork) => ({
+      forkSessionId: fork.forkSessionId,
+      parentSessionId: fork.parentSessionId,
+      forkedFromCheckpointId: fork.forkedFromCheckpointId,
+      forkedFromEventId: fork.forkedFromEventId,
+      reason: fork.reason,
+      createdAt: fork.createdAt
+    }))
+  };
+}
+function publicCheckpoint(checkpoint) {
+  return {
+    checkpointId: checkpoint.checkpointId,
+    sessionId: checkpoint.sessionId,
+    throughEventId: checkpoint.throughEventId,
+    throughSequence: checkpoint.throughSequence,
+    summary: checkpoint.summaryText,
+    state: {
+      objective: checkpoint.state.objective,
+      completedWork: [...checkpoint.state.completedWork],
+      openWork: [...checkpoint.state.openWork],
+      blockers: [...checkpoint.state.blockers],
+      explicitConstraints: [...checkpoint.state.explicitConstraints],
+      decisions: [...checkpoint.state.decisions],
+      rejectedApproaches: [...checkpoint.state.rejectedApproaches],
+      nextStep: checkpoint.state.nextStep
+    },
+    workspaceState: {
+      gitBranch: checkpoint.workspaceState.gitBranch,
+      gitCommit: checkpoint.workspaceState.gitCommit,
+      repositoryRelativePaths: [...checkpoint.workspaceState.repositoryRelativePaths]
+    },
+    createdAt: checkpoint.createdAt
+  };
+}
+function publicEvent(event) {
+  return {
+    eventId: event.eventId,
+    sequence: event.timelineSequence,
+    kind: event.kind,
+    role: event.role,
+    occurredAt: event.occurredAt,
+    text: event.textContent,
+    redactionState: event.redactionState
+  };
+}
+function publicPreparedResume(prepared) {
+  return {
+    handoffId: prepared.handoffId,
+    sessionId: prepared.sessionId,
+    checkpointId: prepared.checkpointId,
+    targetAdapterId: prepared.targetAdapterId,
+    mode: prepared.mode,
+    createdAt: prepared.createdAt,
+    expiresAt: prepared.expiresAt,
+    token: prepared.token,
+    ...prepared.forkTitle === null ? {} : { forkTitle: prepared.forkTitle },
+    warnings: [...prepared.warnings],
+    capsule: serializePublicResumeCapsule(prepared.capsule)
+  };
+}
+async function finishPreparedResume(context, dependencies, prepareInput, initial, json, diagnostics) {
+  if (json) {
     try {
-      let data = "";
-      for await (const chunk of process.stdin) {
-        data += chunk;
+      writeJson2(dependencies.write, {
+        ...publicPreparedResume(initial),
+        diagnostics: publicDiagnostics(diagnostics)
+      });
+      return;
+    } catch (error) {
+      cancelPreparedAfterFailure(context, initial.handoffId);
+      throw error;
+    }
+  }
+  let pending = initial;
+  let ownedPrompt;
+  const exclusions = new Set(prepareInput.excludeEventIds ?? []);
+  try {
+    ownedPrompt = dependencies.prompt ? void 0 : dependencies.createPrompt();
+    const prompt = dependencies.prompt ?? ownedPrompt;
+    while (pending) {
+      writeResumeCapsulePreview(dependencies.write, pending.capsule);
+      const action = (await prompt.ask("Choose confirm, exclude, or cancel: ")).trim().toLowerCase();
+      if (action === "confirm") {
+        writePreparedResume(dependencies.write, publicPreparedResume(pending));
+        pending = null;
+        return;
+      }
+      if (action === "cancel") {
+        context.service.cancelHandoff(pending.handoffId);
+        pending = null;
+        dependencies.write("Resume cancelled.\n");
+        return;
+      }
+      if (action !== "exclude") {
+        dependencies.write("Invalid action; choose confirm, exclude, or cancel.\n");
+        continue;
       }
-      if (data.trim()) {
-        payload = JSON.parse(data);
+      if (pending.capsule.recentEvents.length === 0) {
+        dependencies.write("There are no capsule events available to exclude.\n");
+        continue;
       }
+      const selection = (await prompt.ask(
+        "Exclude event numbers (comma-separated), or type cancel: "
+      )).trim();
+      if (selection.toLowerCase() === "cancel") {
+        context.service.cancelHandoff(pending.handoffId);
+        pending = null;
+        dependencies.write("Resume cancelled.\n");
+        return;
+      }
+      const selectedEventIds = selectedPreviewEventIds(selection, pending.capsule);
+      for (const eventId of selectedEventIds) exclusions.add(eventId);
+      const checkpointId = pending.checkpointId;
+      context.service.cancelHandoff(pending.handoffId);
+      pending = null;
+      pending = await context.service.prepareResume({
+        ...prepareInput,
+        checkpointId,
+        excludeEventIds: [...exclusions]
+      });
+    }
+  } catch (error) {
+    if (pending) cancelPreparedAfterFailure(context, pending.handoffId);
+    throw error;
+  } finally {
+    try {
+      ownedPrompt?.close?.();
     } catch {
     }
-    await handleStop(payload);
-  } catch (err) {
-    process.stderr.write(`agentcache compile-session: ${err.message}
+  }
+}
+function writeResumeCapsulePreview(write, capsule) {
+  const publicCapsule = serializePublicResumeCapsule(capsule);
+  write("Resume capsule preview (exact portable context sent to the destination):\n");
+  write("--- BEGIN RESUME CAPSULE ---\n");
+  write(`${terminalSafeJson(publicCapsule, 2)}
 `);
+  write("--- END RESUME CAPSULE ---\n");
+  if (publicCapsule.recentEvents.length > 0) {
+    write("Event selections:\n");
+    publicCapsule.recentEvents.forEach((event, index) => {
+      write(
+        `  ${index + 1}. ${terminalText2(event.eventId)} (${terminalText2(event.kind)}, sequence ${event.sequence})
+`
+      );
+    });
   }
-});
-program.command("discover").description("SessionStart hook: discover uncompiled transcripts").action(async () => {
+}
+function terminalSafeJson(value, space) {
+  return JSON.stringify(value, null, space).replace(
+    /[\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g,
+    (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`
+  );
+}
+function selectedPreviewEventIds(selection, capsule) {
+  const events = serializePublicResumeCapsule(capsule).recentEvents;
+  const tokens = selection.split(/[\s,]+/).filter(Boolean);
+  if (tokens.length === 0 || tokens.length > 50) {
+    throw invalidInput2("Select between 1 and 50 capsule event numbers");
+  }
+  const indexes = tokens.map((value) => Number(value));
+  if (indexes.some(
+    (index) => !Number.isSafeInteger(index) || index < 1 || index > events.length
+  ) || new Set(indexes).size !== indexes.length) {
+    throw invalidInput2("Capsule event selections must be unique displayed numbers");
+  }
+  return indexes.map((index) => events[index - 1].eventId);
+}
+function eventExclusionIds(values) {
+  if (values.length === 0 || values.length > 50) {
+    throw invalidInput2("Choose between 1 and 50 --exclude-event values");
+  }
+  const ids = values.map((value) => identifier(value, "Excluded event ID"));
+  if (new Set(ids).size !== ids.length) {
+    throw invalidInput2("Excluded event IDs must be unique");
+  }
+  return ids;
+}
+function cancelPreparedAfterFailure(context, handoffId) {
   try {
-    const { handleSessionStart } = await import("./session-start-DGMGEAJU.js");
-    await handleSessionStart();
-  } catch (err) {
-    process.stderr.write(`agentcache discover: ${err.message}
+    context.service.cancelHandoff(handoffId);
+  } catch {
+    throw invalidInput2("Prepared handoff could not be cancelled safely");
+  }
+}
+function writeSessionList(write, sessions, numbered = false, sourceItems) {
+  if (sessions.length === 0) {
+    write("No portable sessions found for this workspace.\n");
+    return;
+  }
+  sessions.forEach((session, index) => {
+    const prefix = numbered ? `${index + 1}. ` : "";
+    const fork = session.fork ? `fork of ${session.fork.parentSessionId}` : "not a fork";
+    const branch = sourceItems?.[index] ? sessionMetadataText(sourceItems[index], "gitBranch") : null;
+    write(`${prefix}${terminalText2(session.title)} [${terminalText2(session.sessionId)}]
+`);
+    write(`   Source: ${terminalText2(session.sourceAdapters.join(", ") || "portable")}
+`);
+    write(`   Project: ${terminalText2(session.project)}
 `);
+    if (branch) write(`   Branch: ${portableTerminalText(branch)}
+`);
+    write(`   Last activity: ${new Date(session.lastActivity).toISOString()}
+`);
+    write(`   State: ${terminalText2(session.state)}; ${terminalText2(fork)}
+`);
+  });
+}
+function writeInspection(write, inspection, source, workspacePath) {
+  writeSessionList(write, [inspection]);
+  const checkpoint = currentCheckpoint(source);
+  const branch = checkpoint?.workspaceState.gitBranch ?? sessionMetadataText(source, "gitBranch");
+  const commit = checkpoint?.workspaceState.gitCommit ?? sessionMetadataText(source, "gitCommit");
+  write(`   Workspace: ${workspacePath ? terminalText2(workspacePath) : "unavailable"}
+`);
+  write(
+    `   Objective: ${checkpoint ? portableTerminalText(checkpoint.state.objective) : "unavailable (no checkpoint)"}
+`
+  );
+  write(`   Git branch: ${branch ? portableTerminalText(branch) : "unknown"}
+`);
+  write(`   Git commit: ${commit ? portableTerminalText(commit) : "unknown"}
+`);
+  write(`   Events: ${inspection.eventCount}
+`);
+  if (checkpoint) {
+    write(`   Checkpoint: ${portableTerminalText(checkpoint.summaryText)}
+`);
+    write(
+      `   Approx. portable-context baseline: ~${approximateCheckpointContextChars(checkpoint)} characters of checkpoint-state JSON; the final resume capsule is larger
+`
+    );
+  } else {
+    write("   Approx. portable context: unavailable (no checkpoint)\n");
   }
-});
-program.command("enforce").description("PreToolUse hook: policy enforcement").action(async () => {
-  let data = "";
-  for await (const chunk of process.stdin) {
-    data += chunk;
+  if (inspection.activeWriter) {
+    write(`   Active writer until: ${new Date(inspection.activeWriter.expiresAt).toISOString()}
+`);
   }
-  try {
-    const { handlePreToolUse } = await import("./pre-tool-use-A4AJHZOJ.js");
-    const input = JSON.parse(data);
-    const result = handlePreToolUse(input);
-    process.stdout.write(JSON.stringify(result));
-  } catch (err) {
-    process.stderr.write(`agentcache enforce: ${err.message}
+}
+function currentCheckpoint(inspection) {
+  const headCheckpointId = inspection.session.headCheckpointId;
+  if (headCheckpointId) {
+    const head = inspection.checkpoints.find(
+      (checkpoint) => checkpoint.checkpointId === headCheckpointId
+    );
+    if (head) return head;
+  }
+  return inspection.checkpoints.reduce((latest, checkpoint) => {
+    if (!latest || checkpoint.throughSequence > latest.throughSequence) return checkpoint;
+    if (checkpoint.throughSequence === latest.throughSequence && checkpoint.createdAt > latest.createdAt) return checkpoint;
+    return latest;
+  }, null);
+}
+function sessionMetadataText(item, key) {
+  const legs = [...item.legs].sort((left, right) => {
+    const activityDifference = legActivityAt(right) - legActivityAt(left);
+    return activityDifference === 0 ? right.startedAt - left.startedAt : activityDifference;
+  });
+  for (const leg of legs) {
+    const value = storedMetadataText(leg.metadata[key]);
+    if (value) return value;
+  }
+  return storedMetadataText(item.session.metadata[key]);
+}
+function legActivityAt(leg) {
+  const sourceActivityAt2 = leg.metadata.sourceActivityAt;
+  return typeof sourceActivityAt2 === "number" && Number.isSafeInteger(sourceActivityAt2) ? sourceActivityAt2 : leg.startedAt;
+}
+function storedMetadataText(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed.slice(0, MAX_TEXT_CHARS) : null;
+}
+function approximateCheckpointContextChars(checkpoint) {
+  const safe = (value) => redactPortableText(value);
+  return JSON.stringify({
+    goal: safe(checkpoint.state.objective),
+    explicitConstraints: checkpoint.state.explicitConstraints.map(safe),
+    completedWork: checkpoint.state.completedWork.map(safe),
+    openWork: checkpoint.state.openWork.map(safe),
+    blockers: checkpoint.state.blockers.map(safe),
+    decisions: checkpoint.state.decisions.map(safe),
+    rejectedApproaches: checkpoint.state.rejectedApproaches.map(safe),
+    nextStep: checkpoint.state.nextStep === null ? null : safe(checkpoint.state.nextStep),
+    workspaceState: {
+      gitBranch: checkpoint.workspaceState.gitBranch === null ? null : safe(checkpoint.workspaceState.gitBranch),
+      gitCommit: checkpoint.workspaceState.gitCommit === null ? null : safe(checkpoint.workspaceState.gitCommit),
+      repositoryRelativePaths: checkpoint.workspaceState.repositoryRelativePaths.map(safe)
+    }
+  }).length;
+}
+function portableTerminalText(value) {
+  return terminalText2(redactPortableText(value));
+}
+function writePreparedResume(write, prepared) {
+  write(
+    `Handoff ${terminalText2(prepared.handoffId)} prepared for ${terminalText2(prepared.targetAdapterId)}.
+`
+  );
+  write(
+    `Use this one-time token in the destination session_resume tool: ${terminalText2(prepared.token)}
+`
+  );
+  if (prepared.forkTitle) {
+    write(`Fork title: ${terminalText2(prepared.forkTitle)}
 `);
-    process.stdout.write("{}");
   }
-});
-program.command("review").description("Review quarantined observations \u2014 approve or reject before they're injected").option("--approve-all", "Approve all pending items").option("--reject-all", "Reject (archive) all pending items").action(async (opts) => {
-  const { getDbPath, isInitialized, findProjectRoot, getProjectId } = await import("./paths-5LZRKNYY.js");
-  if (!isInitialized()) {
-    console.log("AgentCache not initialized. Run: agentcache setup");
-    return;
+  write(`Expires: ${new Date(prepared.expiresAt).toISOString()}
+`);
+}
+function writeDiscoveryDiagnostics(write, discovery) {
+  writeDiagnostics(write, discovery.diagnostics);
+}
+function writeDiagnostics(write, diagnostics) {
+  for (const diagnostic of diagnostics) {
+    write(
+      `Discovery ${terminalText2(diagnostic.adapterId)}/${terminalText2(diagnostic.code)}: ${terminalText2(diagnostic.message)}
+`
+    );
   }
-  const { SqliteKnowledgeRepository } = await import("./sqlite-NM2BVHUY.js");
-  const repo = new SqliteKnowledgeRepository(getDbPath());
-  const project = getProjectId(findProjectRoot());
-  const items = repo.getQuarantinedItems(project);
-  if (items.length === 0) {
-    console.log("No quarantined items. All observations are either approved or auto-promoted.");
-    repo.close();
-    return;
+}
+function checkpointOptions(options, readFile) {
+  if (options.summary !== void 0) {
+    return { summaryText: portableText(options.summary, "Checkpoint summary") };
+  }
+  if (options.summaryFile !== void 0) {
+    return {
+      summaryText: portableText(
+        boundedFile(readFile(identifier(options.summaryFile, "Summary file"))),
+        "Checkpoint summary"
+      )
+    };
+  }
+  if (options.stateFile === void 0) return {};
+  const parsed = parseCheckpointJson(
+    boundedFile(readFile(identifier(options.stateFile, "State file")))
+  );
+  return parsed;
+}
+function parseCheckpointJson(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw invalidInput2("Checkpoint JSON is malformed");
+  }
+  if (!isObject(parsed)) throw invalidInput2("Checkpoint JSON must be an object");
+  assertOnlyKeys(parsed, ["throughEventId", "summaryText", "state", "workspaceState"]);
+  const result = {};
+  if (parsed.throughEventId !== void 0) {
+    result.throughEventId = identifier(parsed.throughEventId, "Through event ID");
+  }
+  if (parsed.summaryText !== void 0) {
+    result.summaryText = portableText(parsed.summaryText, "Checkpoint summary");
+  }
+  if (parsed.state !== void 0) result.state = checkpointState(parsed.state);
+  if (parsed.workspaceState !== void 0) {
+    result.workspaceState = checkpointWorkspaceState(parsed.workspaceState);
+  }
+  return result;
+}
+function checkpointState(value) {
+  if (!isObject(value)) throw invalidInput2("Checkpoint state must be an object");
+  const keys = [
+    "objective",
+    "completedWork",
+    "openWork",
+    "blockers",
+    "explicitConstraints",
+    "decisions",
+    "rejectedApproaches",
+    "nextStep"
+  ];
+  assertOnlyKeys(value, keys);
+  return {
+    objective: portableText(value.objective, "Checkpoint objective"),
+    completedWork: stringArray(value.completedWork, "Completed work"),
+    openWork: stringArray(value.openWork, "Open work"),
+    blockers: stringArray(value.blockers, "Blockers"),
+    explicitConstraints: stringArray(value.explicitConstraints, "Explicit constraints"),
+    decisions: stringArray(value.decisions, "Decisions"),
+    rejectedApproaches: stringArray(value.rejectedApproaches, "Rejected approaches"),
+    nextStep: value.nextStep === null ? null : portableText(value.nextStep, "Next step")
+  };
+}
+function checkpointWorkspaceState(value) {
+  if (!isObject(value)) throw invalidInput2("Checkpoint workspace state must be an object");
+  assertOnlyKeys(value, ["gitBranch", "gitCommit", "repositoryRelativePaths"]);
+  return {
+    ...value.gitBranch === void 0 ? {} : { gitBranch: nullableText(value.gitBranch, "Git branch") },
+    ...value.gitCommit === void 0 ? {} : { gitCommit: nullableText(value.gitCommit, "Git commit") },
+    ...value.repositoryRelativePaths === void 0 ? {} : { repositoryRelativePaths: stringArray(value.repositoryRelativePaths, "Repository paths") }
+  };
+}
+function stringArray(value, name) {
+  if (!Array.isArray(value) || value.length > 100) {
+    throw invalidInput2(`${name} must be an array with at most 100 items`);
   }
-  if (opts.approveAll) {
-    for (const item of items) {
-      repo.promoteItem(item.id);
+  return value.map((item) => portableText(item, name));
+}
+function nullableText(value, name) {
+  return value === null ? null : portableText(value, name);
+}
+function assertOnlyKeys(value, allowed) {
+  const allowedKeys = new Set(allowed);
+  const unexpected = Object.keys(value).find((key) => !allowedKeys.has(key));
+  if (unexpected) throw invalidInput2(`Unexpected checkpoint JSON field: ${unexpected}`);
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireAdapter2(dependencies, value, label) {
+  const adapterId = identifier(value, label);
+  if (!dependencies.adapterIds.includes(adapterId)) {
+    throw invalidInput2(`Unknown ${label}: ${adapterId}`);
+  }
+  return adapterId;
+}
+function eventKind(value) {
+  if (!EVENT_KINDS.has(value)) throw invalidInput2(`Unsupported event kind: ${value}`);
+  return value;
+}
+function sessionState(value) {
+  if (!SESSION_STATES.has(value)) throw invalidInput2(`Unsupported session status: ${value}`);
+  return value;
+}
+function identifier(value, name) {
+  if (typeof value !== "string" || value.trim().length === 0 || value.length > 1024) {
+    throw invalidInput2(`${name} must be a non-empty bounded string`);
+  }
+  return value.trim();
+}
+function portableText(value, name) {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_TEXT_CHARS) {
+    throw invalidInput2(`${name} must contain between 1 and ${MAX_TEXT_CHARS} characters`);
+  }
+  return value;
+}
+function bounded(value, max, name) {
+  if (value.length > max) throw invalidInput2(`${name} exceeds ${max} characters`);
+  return value;
+}
+function boundedFile(value) {
+  if (value.length > MAX_FILE_CHARS) throw invalidInput2("Input file is too large");
+  return value;
+}
+function boundedInteger(value, minimum, maximum, name) {
+  if (!/^\d+$/.test(value)) throw invalidInput2(`${name} must be an integer`);
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < minimum || number > maximum) {
+    throw invalidInput2(`${name} must be between ${minimum} and ${maximum}`);
+  }
+  return number;
+}
+function idempotencyKey(operation, now) {
+  return `cli:${operation}:${now}:${randomUUID()}`;
+}
+async function readBoundedStdin(maxChars, input = process.stdin) {
+  let value = "";
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+  try {
+    for await (const chunk of input) {
+      value += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+      if (value.length > maxChars) {
+        throw invalidInput2(`Standard input exceeds ${maxChars} characters`);
+      }
     }
-    console.log(`Approved ${items.length} items. They will now be injected into future sessions.`);
-    repo.close();
-    return;
+    value += decoder.decode();
+  } catch (error) {
+    if (error instanceof SessionOperationError) throw error;
+    throw invalidInput2("Standard input contains malformed UTF-8");
+  }
+  if (value.length > maxChars) throw invalidInput2(`Standard input exceeds ${maxChars} characters`);
+  return value;
+}
+function readBoundedInputFile(path, options = {}) {
+  let initialStat;
+  try {
+    initialStat = lstatSync(path);
+  } catch {
+    throw invalidInput2("Input file could not be read");
   }
-  if (opts.rejectAll) {
-    for (const item of items) {
-      repo.updateKnowledgeItem(item.id, { status: "archived", updatedAt: Date.now() });
+  if (initialStat.isSymbolicLink() || !initialStat.isFile()) {
+    throw invalidInput2("Input path must be a regular non-symbolic file");
+  }
+  if (initialStat.size > MAX_FILE_CHARS) throw invalidInput2("Input file is too large");
+  const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+  const nonBlocking = "O_NONBLOCK" in constants ? constants.O_NONBLOCK : 0;
+  const openFile = options.openFile ?? ((filePath, flags) => openSync(filePath, flags));
+  let descriptor;
+  try {
+    descriptor = openFile(path, constants.O_RDONLY | noFollow | nonBlocking);
+  } catch {
+    throw invalidInput2("Input file could not be read");
+  }
+  try {
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || stat.dev !== initialStat.dev || stat.ino !== initialStat.ino) {
+      throw invalidInput2("Input file changed before it could be read safely");
     }
-    console.log(`Rejected ${items.length} items. They will not be injected.`);
-    repo.close();
-    return;
+    if (stat.size > MAX_FILE_CHARS) throw invalidInput2("Input file is too large");
+    const buffer = Buffer.alloc(MAX_FILE_CHARS + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const count = readSync(
+        descriptor,
+        buffer,
+        bytesRead,
+        buffer.length - bytesRead,
+        null
+      );
+      if (count === 0) break;
+      bytesRead += count;
+    }
+    if (bytesRead > MAX_FILE_CHARS) throw invalidInput2("Input file is too large");
+    const completedStat = fstatSync(descriptor);
+    if (completedStat.dev !== stat.dev || completedStat.ino !== stat.ino || completedStat.size !== stat.size || completedStat.mtimeMs !== stat.mtimeMs || completedStat.ctimeMs !== stat.ctimeMs) {
+      throw invalidInput2("Input file changed while it was being read");
+    }
+    try {
+      return FATAL_UTF8_DECODER.decode(buffer.subarray(0, bytesRead));
+    } catch {
+      throw invalidInput2("Input file contains malformed UTF-8");
+    }
+  } catch (error) {
+    if (error instanceof SessionOperationError) throw error;
+    throw invalidInput2("Input file could not be read");
+  } finally {
+    try {
+      closeSync(descriptor);
+    } catch {
+    }
+  }
+}
+function invalidInput2(message) {
+  return new SessionOperationError("invalid_input", message, ["cancel"]);
+}
+function formatCliError(error, json) {
+  const operationError = error instanceof SessionOperationError ? error : void 0;
+  const rawMessage = error instanceof Error ? error.message : "Command failed";
+  const message = publicErrorText(rawMessage);
+  const code = operationError && PUBLIC_ERROR_CODES.has(operationError.code) ? operationError.code : "command_failed";
+  if (json) {
+    return `${JSON.stringify({
+      error: {
+        code,
+        message,
+        alternatives: operationError ? operationError.alternatives.slice(0, 16).filter(isPublicAlternative) : []
+      }
+    })}
+`;
   }
-  console.log(`${items.length} quarantined observation(s):
+  return `agentcache: ${message}
+`;
+}
+function publicErrorText(value) {
+  const boundedSource = value.slice(0, 4096);
+  return terminalText2(redactPortableText(terminalText2(boundedSource))).slice(0, 1024);
+}
+async function runCliProgram(program2, argv, output = {}) {
+  const writeOut = output.writeOut ?? ((value) => process.stdout.write(value));
+  const writeError = output.writeError ?? ((value) => process.stderr.write(value));
+  configureCommander(program2, writeOut);
+  try {
+    await program2.parseAsync([...argv]);
+    return 0;
+  } catch (error) {
+    if (error instanceof CommanderError && (error.code === "commander.helpDisplayed" || error.code === "commander.version")) {
+      return 0;
+    }
+    const publicError = error instanceof CommanderError ? invalidInput2(error.message) : error;
+    writeError(formatCliError(publicError, argv.includes("--json")));
+    return error instanceof CommanderError && error.exitCode > 0 ? error.exitCode : 1;
+  }
+}
+function configureCommander(program2, writeOut) {
+  program2.configureOutput({ writeOut, writeErr: () => {
+  } });
+  program2.exitOverride();
+  for (const child of program2.commands) configureCommander(child, writeOut);
+}
+function isPublicAlternative(value) {
+  return ["refresh", "fork", "cancel", "wait", "retry", "setup", "diagnose"].includes(value);
+}
+function writeJson2(write, value) {
+  write(`${terminalSafeJson(value)}
 `);
-  for (const item of items) {
-    const age = Math.round((Date.now() - item.createdAt) / (1e3 * 60 * 60));
-    console.log(`  [${item.id}] (${item.type}/${item.scope}) ${age}h ago`);
-    console.log(`    ${item.content.slice(0, 120)}`);
-    console.log("");
-  }
-  console.log("Actions:");
-  console.log("  agentcache review --approve-all    Approve all and inject into sessions");
-  console.log("  agentcache review --reject-all     Archive all (won't be injected)");
-  console.log("  agentcache promote <id>            Approve a specific item");
-  repo.close();
-});
-program.command("promote <id>").description("Promote a specific quarantined item to approved (USER authority)").action(async (id) => {
-  const { getDbPath, isInitialized } = await import("./paths-5LZRKNYY.js");
-  if (!isInitialized()) {
-    console.log("AgentCache not initialized. Run: agentcache setup");
-    return;
+}
+function terminalText2(value) {
+  return value.replace(
+    /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/g,
+    "\uFFFD"
+  );
+}
+
+// src/cli.ts
+configureMcpRegistrationEntrypoint(fileURLToPath(import.meta.url));
+var PKG_VERSION = JSON.parse(
+  readPackageFileSync(new URL("../package.json", import.meta.url), "utf8")
+).version;
+var program = new Command3();
+var MAX_DOCTOR_MESSAGE_CHARS = 512;
+var SQLITE_FILE_HEADER_BYTES = 100;
+var SQLITE_MAGIC = Buffer.from("SQLite format 3\0", "binary");
+function publicDoctorMessage(message) {
+  const terminalSafe = message.replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ");
+  return [...redactPortableText(terminalSafe).replace(/\s+/gu, " ").trim()].slice(0, MAX_DOCTOR_MESSAGE_CHARS).join("");
+}
+function hasStructurallyValidSqliteHeader(header, fileSize) {
+  if (header.length !== SQLITE_FILE_HEADER_BYTES) return false;
+  if (!header.subarray(0, SQLITE_MAGIC.length).equals(SQLITE_MAGIC)) return false;
+  const encodedPageSize = header.readUInt16BE(16);
+  const pageSize = encodedPageSize === 1 ? 65536 : encodedPageSize;
+  const validPageSize = pageSize >= 512 && pageSize <= 65536 && (pageSize & pageSize - 1) === 0;
+  if (!validPageSize || fileSize < pageSize || fileSize % pageSize !== 0) return false;
+  const writeVersion = header[18];
+  const readVersion = header[19];
+  const usablePageBytes = pageSize - header[20];
+  if (writeVersion !== 1 && writeVersion !== 2 || readVersion !== 1 && readVersion !== 2 || usablePageBytes < 480 || header[21] !== 64 || header[22] !== 32 || header[23] !== 32) {
+    return false;
   }
-  const { SqliteKnowledgeRepository } = await import("./sqlite-NM2BVHUY.js");
-  const repo = new SqliteKnowledgeRepository(getDbPath());
-  const item = repo.getKnowledgeItem(id);
-  if (!item) {
-    console.log(`Item not found: ${id}`);
-    repo.close();
-    return;
+  const physicalPageCount = fileSize / pageSize;
+  const declaredPageCount = header.readUInt32BE(28);
+  const schemaFormat = header.readUInt32BE(44);
+  const textEncoding = header.readUInt32BE(56);
+  if (declaredPageCount === 0 || declaredPageCount > physicalPageCount || schemaFormat < 1 || schemaFormat > 4 || textEncoding < 1 || textEncoding > 3 || header.readUInt32BE(96) === 0) {
+    return false;
   }
-  repo.promoteItem(id);
-  console.log(`Promoted: ${item.content.slice(0, 80)}`);
-  repo.close();
-});
-program.command("add-rule <content>").description("Add an enforced policy rule (human-only, blocks tool calls that violate it)").option("--global", "Apply to all projects (default: current project only)").action(async (content, opts) => {
-  const { getDbPath, isInitialized, findProjectRoot, getProjectId } = await import("./paths-5LZRKNYY.js");
-  const { randomUUID } = await import("crypto");
-  if (!isInitialized()) {
-    console.log("AgentCache not initialized. Run: agentcache setup");
-    return;
+  return header.subarray(72, 92).every((byte) => byte === 0);
+}
+function probeSessionDatabase(path) {
+  const openFlags = fsConstants.O_RDONLY | (typeof fsConstants.O_NONBLOCK === "number" ? fsConstants.O_NONBLOCK : 0) | (typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0);
+  let descriptor;
+  try {
+    descriptor = openSync2(path, openFlags);
+    const opened = fstatSync2(descriptor);
+    if (!opened.isFile()) return "unsafe";
+    const pathAtOpen = lstatFileSync(path);
+    if (pathAtOpen.isSymbolicLink() || !pathAtOpen.isFile() || opened.dev !== pathAtOpen.dev || opened.ino !== pathAtOpen.ino) {
+      return "unsafe";
+    }
+    const header = Buffer.alloc(SQLITE_FILE_HEADER_BYTES);
+    let length = 0;
+    while (length < header.length) {
+      const read = readSync2(descriptor, header, length, header.length - length, length);
+      if (read === 0) break;
+      length += read;
+    }
+    const completed = fstatSync2(descriptor);
+    const finalPath = lstatFileSync(path);
+    if (!completed.isFile() || completed.dev !== opened.dev || completed.ino !== opened.ino || completed.size !== opened.size || completed.mtimeMs !== opened.mtimeMs || completed.ctimeMs !== opened.ctimeMs || finalPath.isSymbolicLink() || !finalPath.isFile() || finalPath.dev !== opened.dev || finalPath.ino !== opened.ino) {
+      return "unsafe";
+    }
+    return length === SQLITE_FILE_HEADER_BYTES && hasStructurallyValidSqliteHeader(header, opened.size) ? "detected" : "unsafe";
+  } catch (cause) {
+    if (cause?.code !== "ENOENT") return "unsafe";
+    try {
+      lstatFileSync(path);
+      return "unsafe";
+    } catch (pathCause) {
+      return pathCause?.code === "ENOENT" ? "missing" : "unsafe";
+    }
+  } finally {
+    if (descriptor !== void 0) {
+      try {
+        closeSync2(descriptor);
+      } catch {
+      }
+    }
   }
-  const { SqliteKnowledgeRepository } = await import("./sqlite-NM2BVHUY.js");
-  const { computeCanonicalHash } = await import("./3-canonicalizer-HIN2F7SZ.js");
-  const repo = new SqliteKnowledgeRepository(getDbPath());
-  const project = getProjectId(findProjectRoot());
-  const scope = opts.global ? "global" : "project";
-  repo.saveKnowledgeItem({
-    id: `ki_${randomUUID().slice(0, 8)}`,
-    canonicalHash: computeCanonicalHash(content),
-    type: "rule",
-    title: content.slice(0, 80),
-    content,
-    confidence: "high",
-    observationCount: 1,
-    authority: "USER",
-    status: "active",
-    enforce: true,
-    project,
-    scope,
-    createdAt: Date.now(),
-    updatedAt: Date.now(),
-    lastSeenAt: Date.now(),
-    metadata: { source: "cli" }
-  });
-  console.log(`Enforced rule added (${scope}): ${content}`);
-  repo.close();
+}
+program.name("agentcache").description("Same-machine cross-agent session continuity with explicit user-selected handoffs").version(PKG_VERSION);
+program.command("setup").description("Detect IDEs and register AgentCache").action(async () => {
+  const { runSetup } = await import("./setup-7JJPW3VG.js");
+  await runSetup();
+});
+program.command("serve").description("Start AgentCache MCP server (spawned by IDEs automatically)").requiredOption("--adapter <id>", "Trusted adapter identity for this MCP process").action(async (options) => {
+  await startMcpForAdapter(options.adapter);
 });
 program.command("doctor").description("Diagnose AgentCache installation and report problems").action(async () => {
-  const { existsSync, readFileSync } = await import("fs");
+  const { existsSync, lstatSync: lstatSync2 } = await import("fs");
   const { join } = await import("path");
   const { homedir } = await import("os");
-  const { spawnSync } = await import("child_process");
-  const { getDataDir, getDbPath, isInitialized } = await import("./paths-5LZRKNYY.js");
+  const { getDataDir, getSessionDbPath: getSessionDbPath2 } = await import("./paths-NTZ2357O.js");
   let ok = 0;
   let warn = 0;
   let fail = 0;
   function pass(msg) {
-    console.log(`  \u2713 ${msg}`);
+    console.log(`  \u2713 ${publicDoctorMessage(msg)}`);
     ok++;
   }
   function warning(msg) {
-    console.log(`  \u26A0 ${msg}`);
+    console.log(`  \u26A0 ${publicDoctorMessage(msg)}`);
     warn++;
   }
   function error(msg) {
-    console.log(`  \u2717 ${msg}`);
+    console.log(`  \u2717 ${publicDoctorMessage(msg)}`);
     fail++;
   }
+  function info(msg) {
+    console.log(`  \xB7 ${publicDoctorMessage(msg)}`);
+  }
   console.log("AgentCache Doctor\n");
   console.log("Storage:");
   const dataDir = getDataDir();
-  if (existsSync(dataDir)) {
-    pass(`Data directory exists: ${dataDir}`);
-  } else {
-    error(`Data directory missing: ${dataDir}`);
+  let dataDirectoryState = "unsafe";
+  try {
+    const metadata = lstatSync2(dataDir);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+      error("Session data directory is not a safe local directory");
+    } else {
+      dataDirectoryState = "available";
+      pass("Session data directory available");
+    }
+  } catch (cause) {
+    if (cause?.code === "ENOENT") {
+      dataDirectoryState = "missing";
+      info("Session data directory not initialized");
+    } else {
+      error("Session data directory could not be checked safely");
+    }
   }
-  const dbPath = getDbPath();
-  if (existsSync(dbPath)) {
-    try {
-      const { SqliteKnowledgeRepository } = await import("./sqlite-NM2BVHUY.js");
-      const repo = new SqliteKnowledgeRepository(dbPath);
-      repo.close();
-      pass(`Database accessible: ${dbPath}`);
-    } catch (err) {
-      if (err.message?.includes("NODE_MODULE_VERSION") || err.message?.includes("was compiled against")) {
-        error(`Native module ABI mismatch \u2014 run: npm rebuild better-sqlite3 -g`);
-      } else {
-        error(`Database broken: ${err.message}`);
-      }
+  const sessionDbPath = getSessionDbPath2();
+  if (dataDirectoryState === "available") {
+    const databaseProbe = probeSessionDatabase(sessionDbPath);
+    if (databaseProbe === "detected") {
+      info("Session database file detected; full validation occurs on session operations");
+    } else if (databaseProbe === "unsafe") {
+      error("Session database could not be opened safely");
+    } else {
+      info("Session database not initialized \u2014 will initialize on first session operation");
     }
-  } else if (isInitialized()) {
-    warning("Database file missing but data directory exists");
+  } else if (dataDirectoryState === "missing") {
+    info("Session database not initialized \u2014 will initialize on first session operation");
   } else {
-    warning("Not initialized yet \u2014 run: agentcache setup");
+    info("Session database not checked because the data directory is unsafe");
   }
   console.log("\nIDE registrations:");
-  const { detectInstalledIdes } = await import("./ide-detector-5TRCR4F5.js");
+  const { detectInstalledIdes } = await import("./ide-detector-ETGAVVXO.js");
   const ides = detectInstalledIdes();
   for (const ide of ides) {
     if (!ide.detected) continue;
-    if (ide.mcpConfigFormat === "claude-settings") {
-      const claudeJson = join(homedir(), ".claude.json");
-      if (existsSync(claudeJson)) {
-        try {
-          const config = JSON.parse(readFileSync(claudeJson, "utf-8"));
-          if (config.mcpServers?.agentcache) {
-            pass("Claude Code: registered");
-          } else {
-            warning("Claude Code: detected but not registered");
-          }
-        } catch {
-          warning("Claude Code: config unreadable");
-        }
-      } else {
-        warning("Claude Code: detected but not registered");
-      }
-      const settingsPath = join(homedir(), ".claude", "settings.json");
-      if (existsSync(settingsPath)) {
-        try {
-          const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-          const perms = settings.permissions?.allow || [];
-          if (perms.some((p) => p.includes("agentcache"))) {
-            pass("Claude Code permissions: auto-approved");
-          } else {
-            warning("Claude Code permissions: not in allow list");
-          }
-          if (settings.hooks?.Stop?.some((h) => JSON.stringify(h).includes("agentcache"))) {
-            pass("Claude Code hooks: registered");
-          } else {
-            warning("Claude Code hooks: not registered");
-          }
-        } catch {
-          warning("Claude Code settings: unreadable");
-        }
-      }
-    } else if (ide.mcpConfigFormat === "codex-toml") {
-      if (existsSync(ide.mcpConfigPath)) {
-        try {
-          const content = readFileSync(ide.mcpConfigPath, "utf-8");
-          if (content.includes("[mcp_servers.agentcache]")) {
-            pass(`${ide.name}: registered`);
-          } else {
-            warning(`${ide.name}: detected but not registered`);
-          }
-        } catch {
-          warning(`${ide.name}: config unreadable`);
-        }
-      } else {
-        warning(`${ide.name}: detected but not registered`);
+    if (isMcpServerRegistered(ide)) pass(`${ide.name}: registered`);
+    else warning(`${ide.name}: detected but not registered`);
+  }
+  const claudeSettingsPath = join(homedir(), ".claude", "settings.json");
+  if (existsSync(claudeSettingsPath)) {
+    try {
+      const settings = JSON.parse(readBoundedInputFile(claudeSettingsPath));
+      const permissions = Array.isArray(settings.permissions?.allow) ? settings.permissions.allow : [];
+      if (permissions.some(
+        (permission) => typeof permission === "string" && permission.startsWith("mcp__agentcache__")
+      )) {
+        warning("Claude Code legacy blanket approvals detected \u2014 run `agentcache setup` to remove");
       }
-    } else {
-      if (existsSync(ide.mcpConfigPath)) {
-        try {
-          const config = JSON.parse(readFileSync(ide.mcpConfigPath, "utf-8"));
-          if (config.mcpServers?.agentcache) {
-            pass(`${ide.name}: registered`);
-          } else {
-            warning(`${ide.name}: detected but not registered`);
-          }
-        } catch {
-          warning(`${ide.name}: config unreadable`);
-        }
-      } else {
-        warning(`${ide.name}: detected but not registered`);
+      const legacyHookPresence = inspectLegacyClaudeHookPresence(settings);
+      if (legacyHookPresence === "present") {
+        warning("Claude Code legacy automatic hooks detected \u2014 run `agentcache setup` to remove");
+      } else if (legacyHookPresence === "unknown") {
+        warning("Claude Code hook configuration is ambiguous; no hooks were changed");
       }
+    } catch {
+      warning("Claude Code settings unreadable; legacy automation state could not be checked");
     }
   }
   const notDetected = ides.filter((i) => !i.detected).map((i) => i.name);
   if (notDetected.length > 0) {
     console.log(`  \xB7 Not detected: ${notDetected.join(", ")}`);
   }
-  console.log("\nTranscript sources:");
-  const { findAllClaudeTranscripts, findAllCursorTranscripts, findAllContinueTranscripts, findAllCodexTranscripts, findAllRooCodeTranscripts } = await import("./transcript-JWSGSDSF.js");
-  const sources = [
-    { name: "Claude Code", fn: findAllClaudeTranscripts },
-    { name: "Cursor", fn: findAllCursorTranscripts },
-    { name: "Continue", fn: findAllContinueTranscripts },
-    { name: "Codex", fn: findAllCodexTranscripts },
-    { name: "Roo Code", fn: findAllRooCodeTranscripts }
-  ];
-  let totalTranscripts = 0;
-  for (const src of sources) {
-    const count = src.fn().length;
-    totalTranscripts += count;
-    if (count > 0) pass(`${src.name}: ${count} transcripts`);
-  }
-  if (totalTranscripts === 0) {
-    warning("No transcripts found from any IDE");
-  }
-  console.log("\nLLM backends (for compile-all):");
-  const backends = ["claude", "codex", "gemini", "copilot", "aider", "goose"];
-  const found = [];
-  for (const cmd of backends) {
-    try {
-      if (spawnSync("which", [cmd], { encoding: "utf-8", timeout: 3e3 }).status === 0) {
-        found.push(cmd);
-      }
-    } catch {
-    }
-  }
-  if (process.env.ANTHROPIC_API_KEY) found.push("Anthropic API (env)");
-  if (process.env.OPENAI_API_KEY) found.push("OpenAI API (env)");
-  if (found.length > 0) {
-    pass(`Available: ${found.join(", ")}`);
-  } else {
-    warning("No LLM backend found \u2014 compile-all won't work");
-  }
   console.log("\nRuntime:");
   const nodeVersion = process.version;
   const major = parseInt(nodeVersion.slice(1));
-  if (major >= 20) {
+  if (major >= 22) {
     pass(`Node ${nodeVersion}`);
   } else {
-    error(`Node ${nodeVersion} \u2014 requires >=20.12.0`);
+    error(`Node ${nodeVersion} \u2014 requires >=22`);
   }
   console.log(`
 ${ok} passed, ${warn} warnings, ${fail} errors`);
   if (fail > 0) process.exit(1);
 });
-program.command("compile-all").description("Batch-compile all unprocessed transcripts using an available LLM CLI").action(async () => {
-  const { runCompileAll } = await import("./compile-all-PTWTZVP5.js");
-  await runCompileAll();
-});
-program.command("status").description("Show AgentCache knowledge stats").action(async () => {
-  const { getDbPath, isInitialized, findProjectRoot, getProjectId, getProjectDisplayName } = await import("./paths-5LZRKNYY.js");
-  if (!isInitialized()) {
-    console.log("AgentCache not initialized. Run: agentcache setup");
-    return;
-  }
-  const { SqliteKnowledgeRepository } = await import("./sqlite-NM2BVHUY.js");
-  const repo = new SqliteKnowledgeRepository(getDbPath());
-  const projectRoot = findProjectRoot();
-  const project = getProjectId(projectRoot);
-  const displayName = getProjectDisplayName(projectRoot);
-  const items = repo.getKnowledgeForContext(project);
-  const rules = items.filter((i) => i.type === "rule");
-  const lessons = items.filter((i) => i.type === "lesson");
-  const decisions = items.filter((i) => i.type === "decision");
-  const context = items.filter((i) => i.type === "context");
-  const globalItems = items.filter((i) => i.scope === "global");
-  const projectItems = items.filter((i) => i.scope === "project");
-  const pending = repo.getPendingCount();
-  console.log(`AgentCache \u2014 ${displayName} (${project})`);
-  console.log(`  ${items.length} items (${globalItems.length} global, ${projectItems.length} project)`);
-  console.log(`  ${rules.length} rules | ${lessons.length} lessons | ${decisions.length} decisions | ${context.length} context`);
-  if (pending > 0) console.log(`  ${pending} sessions pending compilation`);
-  const allProjects = repo.getProjectStats();
-  if (allProjects.length > 1) {
-    console.log("");
-    console.log("All projects:");
-    for (const p of allProjects) {
-      const marker = p.project === project ? " \u2190 current" : "";
-      console.log(`  ${p.project}: ${p.count} items${marker}`);
-    }
-  }
-  repo.close();
-});
-program.parse();
+registerSessionCommands(program);
+registerAdapterCommands(program);
+var exitCode = await runCliProgram(program, process.argv);
+if (exitCode !== 0) process.exitCode = exitCode;