@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/grok/grpc-web.ts

@@ -5,6 +5,7 @@
 
 export interface GrpcWebTrailer {
   status: number;
+  statusValues: string[];
   statusMessage?: string;
   metadata: Record<string, string>;
 }
@@ -12,6 +13,8 @@ export interface GrpcWebTrailer {
 export interface DecodedGrpcWebResponse {
   messages: Uint8Array[];
   status: number;
+  statusValues: string[];
+  framingComplete: boolean;
   statusMessage?: string;
   trailers?: GrpcWebTrailer;
 }
@@ -51,6 +54,7 @@ export function parseGrpcWebTrailers(bytes: Uint8Array): GrpcWebTrailer {
   const text = new TextDecoder("utf-8").decode(bytes);
   const lines = text.split(/\r?\n/);
   const metadata: Record<string, string> = {};
+  const statusValues: string[] = [];
   let status = 0;
   let statusMessage: string | undefined;
 
@@ -62,6 +66,7 @@ export function parseGrpcWebTrailers(bytes: Uint8Array): GrpcWebTrailer {
     if (!key) continue;
     metadata[key] = value;
     if (key === "grpc-status") {
+      statusValues.push(value);
       const parsed = parseInt(value, 10);
       if (!Number.isNaN(parsed)) {
         status = parsed;
@@ -75,7 +80,7 @@ export function parseGrpcWebTrailers(bytes: Uint8Array): GrpcWebTrailer {
     }
   }
 
-  return { status, statusMessage, metadata };
+  return { status, statusValues, statusMessage, metadata };
 }
 
 /**
@@ -83,8 +88,11 @@ export function parseGrpcWebTrailers(bytes: Uint8Array): GrpcWebTrailer {
  */
 export function decodeGrpcWebResponse(bytes: Uint8Array): DecodedGrpcWebResponse {
   const messages: Uint8Array[] = [];
+  const statusValues: string[] = [];
   let offset = 0;
   let trailer: GrpcWebTrailer | undefined;
+  let firstTrailerPayload: Uint8Array | undefined;
+  let framingComplete = true;
 
   while (offset + HEADER_SIZE <= bytes.length) {
     const flag = bytes[offset];
@@ -99,10 +107,22 @@ export function decodeGrpcWebResponse(bytes: Uint8Array): DecodedGrpcWebResponse
 
     const payload = bytes.subarray(frameStart, frameEnd);
 
+    // Preserve legacy decoding; callers needing confirmation inspect framingComplete.
     if (flag === FRAME_DATA) {
+      if (firstTrailerPayload !== undefined) framingComplete = false;
       messages.push(payload);
     } else if (flag === FRAME_TRAILER) {
+      const firstTrailer = firstTrailerPayload;
+      if (firstTrailer === undefined) {
+        firstTrailerPayload = payload;
+      } else if (payload.length !== firstTrailer.length
+        || payload.some((byte, index) => byte !== firstTrailer[index])) {
+        framingComplete = false;
+      }
       trailer = parseGrpcWebTrailers(payload);
+      for (const value of trailer.statusValues) statusValues.push(value);
+    } else {
+      framingComplete = false;
     }
 
     offset = frameEnd;
@@ -114,6 +134,8 @@ export function decodeGrpcWebResponse(bytes: Uint8Array): DecodedGrpcWebResponse
   return {
     messages,
     status: finalStatus,
+    statusValues,
+    framingComplete: framingComplete && offset === bytes.length,
     statusMessage: finalMessage,
     trailers: trailer,
   };

package/src/grok/reset-coupon-ledger.ts

@@ -25,6 +25,8 @@ export interface GrokResetCouponOperationRecord {
   attemptedAt?: number;
   code?: string;
   settledAt?: number;
+  /** Durable status of a replayed record, so callers apply the terminal-replay predicate. */
+  status?: "attempted" | "settled" | "failed";
 }
 
 interface GrokResetCouponOperationState {
@@ -77,8 +79,15 @@ function readGrokCouponLedger(filePath: string): GrokResetCouponLedger {
           op.status = "attempted";
           delete op.code;
         }
+        // A v1 attempted record never carried a confirmed outcome.
+        if (op.status === "attempted") delete op.code;
       }
     }
+    // Only a settled or failed record carries an outcome. An open or attempted
+    // record with a code would replay an unconfirmed result as definitive.
+    for (const op of Object.values(parsed.operations)) {
+      if ((op.status === "open" || op.status === "attempted") && op.code !== undefined) throw new Error();
+    }
     return { version: 2, operations: parsed.operations };
   } catch {
     throw new Error("Grok coupon ledger is unreadable; existing records were preserved.");
@@ -163,6 +172,7 @@ export function openGrokResetCouponOperation(
           attemptedAt: existing.status === "attempted" ? existing.updatedAt : undefined,
           code: existing.code,
           settledAt: existing.updatedAt,
+          status: existing.status,
         };
       }
       return {
@@ -232,17 +242,37 @@ type GrokResetCouponPreflightResult =
   | { kind: "recorded" | "changed" }
   | { kind: "replay"; code: string; tokenId?: string; settledAt: number };
 
-const UNRESOLVED_COUPON_CODES = new Set(["redeem_failed", "attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed"]);
+/**
+ * Codes that never prove an outcome. A record carrying one is not replayed as
+ * definitive, even if a restored or hand-edited ledger stores it as settled/failed.
+ */
+const UNRESOLVED_COUPON_CODES = new Set([
+  "redeem_failed", "attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed",
+  "attempt_mark_failed", "operation_token_mismatch", "ledger_unavailable", "capacity",
+]);
+
+/**
+ * Whether a durable record is a definitive outcome this account and token may replay:
+ * settled or failed, same account, same token when both are known, and a code that
+ * does not itself mean "unconfirmed".
+ */
+export function isTerminalGrokCouponReplay(
+  record: { status?: string; accountId?: string; tokenId?: string; code?: string } | undefined,
+  accountId: string, tokenId: string | undefined,
+): boolean {
+  if (!record || record.accountId !== accountId) return false;
+  if (tokenId !== undefined && record.tokenId !== undefined && record.tokenId !== tokenId) return false;
+  return (record.status === "settled" || record.status === "failed")
+    && !!record.code && !UNRESOLVED_COUPON_CODES.has(record.code);
+}
 
 /** The durable definitive outcome for this account and token, if the operation has one. */
 function terminalReplay(
   ledger: GrokResetCouponLedger, operationId: string, accountId: string, tokenId: string | undefined,
 ): Extract<GrokResetCouponPreflightResult, { kind: "replay" }> | null {
   const existing = ledger.operations[operationId];
-  if (!existing || existing.accountId !== accountId) return null;
-  if (tokenId !== undefined && existing.tokenId !== undefined && existing.tokenId !== tokenId) return null;
-  if ((existing.status !== "settled" && existing.status !== "failed") || !existing.code || UNRESOLVED_COUPON_CODES.has(existing.code)) return null;
-  return { kind: "replay", code: existing.code, tokenId: existing.tokenId, settledAt: existing.updatedAt };
+  if (!existing || !isTerminalGrokCouponReplay(existing, accountId, tokenId)) return null;
+  return { kind: "replay", code: existing.code!, tokenId: existing.tokenId, settledAt: existing.updatedAt };
 }
 
 /** Settle a refusal or inspect its winner without releasing the mutation transaction. */
@@ -259,6 +289,46 @@ export function settleGrokResetCouponPreflightRefusal(
   });
 }
 
+export type GrokResetCouponPreOpenRefusalResult =
+  | GrokResetCouponPreflightResult
+  | { kind: "identity-mismatch" | "capacity" };
+
+/**
+ * Refuse a request that never opened its supplied operationId. Under the mutation lock
+ * an absent id is reserved as a failed record, so a later open of the same id replays
+ * the refusal and can never be claimed (within the 30-day retention window). An id
+ * that already exists is never overwritten: a definitive outcome replays, anything
+ * else reports "changed" so the caller keeps its hold.
+ */
+export function refuseGrokResetCouponBeforeOpen(
+  refusal: { operationId: string; accountId: string; tokenId?: string; code: string },
+  now = Date.now(),
+  journalPath?: string,
+): GrokResetCouponPreOpenRefusalResult {
+  return withConfigMutationLockSync(() => {
+    const filePath = journalPath ?? grokCouponJournalPath();
+    const ledger = readGrokCouponLedger(filePath);
+    const retentionCutoff = now - 30 * 24 * 60 * 60_000;
+    ledger.operations = Object.fromEntries(
+      Object.entries(ledger.operations).filter(([, op]) => op.updatedAt > retentionCutoff),
+    );
+    const existing = ledger.operations[refusal.operationId];
+    if (existing) {
+      if (existing.accountId !== refusal.accountId) return { kind: "identity-mismatch" };
+      // Same token binding as a normal replay: a different requested coupon never
+      // replays another coupon's outcome.
+      return terminalReplay(ledger, refusal.operationId, refusal.accountId, refusal.tokenId) ?? { kind: "changed" };
+    }
+    if (Object.keys(ledger.operations).length >= MAX_GROK_RESET_COUPON_OPERATION_IDS) return { kind: "capacity" };
+    ledger.operations[refusal.operationId] = {
+      accountId: refusal.accountId, ...(refusal.tokenId !== undefined ? { tokenId: refusal.tokenId } : {}),
+      status: "failed", code: refusal.code, createdAt: now, updatedAt: now,
+    };
+    writeGrokCouponLedger(filePath, ledger, now);
+    return { kind: "recorded" };
+  });
+}
+
 /**
  * After a lost claim: the definitive winner to replay, or null while the
  * operation is still unresolved. Terminal states never revert, so reading after

package/src/grok/reset-coupons.ts

@@ -231,10 +231,12 @@ function buildGrokHeaders(accessToken: string): Record<string, string> {
  * Reads available Grok reset tokens for the authenticated xAI account.
  */
 function assertConfirmedCouponStatus(decoded: ReturnType<typeof decodeGrpcWebResponse>): void {
-  const rawStatus = decoded.trailers?.metadata["grpc-status"];
+  const rawStatus = decoded.statusValues[0];
   // The shared decoder defaults a missing/malformed status to zero. Coupon
   // availability and an irreversible redemption need affirmative confirmation.
-  if (rawStatus === undefined || !/^\d+$/.test(rawStatus) || !Number.isSafeInteger(Number(rawStatus))) {
+  if (decoded.framingComplete !== true || rawStatus === undefined
+    || decoded.statusValues.some((value) => !/^\d+$/.test(value)
+      || !Number.isSafeInteger(Number(value)) || value !== rawStatus)) {
     throw new Error("Grok coupon response has no confirmed gRPC status");
   }
   const status = Number(rawStatus);

package/src/integrations/mutation-plan.ts

@@ -32,6 +32,7 @@ import {
   assertDroidRecordedSettingsUnambiguous,
   isLoopbackOnly,
   resolveIntegrationPaths,
+  type ResolvedIntegrationPaths,
   restoreOwnershipCollision,
   type IntegrationClientId,
 } from "./registry";
@@ -567,7 +568,7 @@ export function restoreStoreDirectoryRefusal(
   if (!declared?.lockFile) return null;
   let storePath: string;
   try {
-    storePath = declared.path(input.env, input.home);
+    storePath = declared.path(input.env, input.home, io);
   } catch (error) {
     if (error instanceof ClientPathError) return null;
     throw error;
@@ -602,10 +603,11 @@ export function observeRestore(
   const store = selectedOperation?.store ?? input.store ?? createIntegrationStateStore();
   let io = input.io ?? defaultIntegrationIO(store);
   const clientId = input.clientId;
-  let resolved: { configPath: string; detectDir: string };
+  let resolved: ResolvedIntegrationPaths;
   try {
     const context = exportContextOf(input);
-    resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home, context);
+    resolved = clientId === "zcode" || !input.resolvedPaths
+      ? resolveIntegrationPaths(clientId, input.env, input.home, context, io) : input.resolvedPaths;
     if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context);
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
@@ -630,7 +632,7 @@ export function observeRestore(
    * config file. The answer also carries the document shape those bytes are in.
    */
   const rowTarget = declaredIntegrationTarget({
-    clientId, configPath, resolvedConfigPath: resolved.configPath, env: input.env, home: input.home,
+    clientId, configPath, resolvedConfigPath: resolved.configPath, env: input.env, home: input.home, io,
   });
   if (rowTarget === null) {
     return {
@@ -848,7 +850,7 @@ export interface IntegrationWriteInput {
   store?: IntegrationStateStore;
   io?: IntegrationIO;
   /** Frozen once by the async coordinator; synchronous callers may omit it. */
-  resolvedPaths?: { configPath: string; detectDir: string };
+  resolvedPaths?: ResolvedIntegrationPaths;
 }
 
 /** A refusal in the planner's own vocabulary, so observation does not depend on the writer's result type. */
@@ -922,7 +924,8 @@ export function observeIntegration(
      * verify account 1 was installed and then write account 0's catalog.
      */
     const context = exportContextOf(input);
-    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home, context);
+    const resolved = clientId === "zcode" || !input.resolvedPaths
+      ? resolveIntegrationPaths(clientId, input.env, input.home, context, io) : input.resolvedPaths;
     if (clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(resolved.detectDir, context);
     detectDir = resolved.detectDir;
     if (clientId === "cline") io = createClineIO(io, resolved.configPath, store, effects.recover);
@@ -945,9 +948,12 @@ export function observeIntegration(
      * collection route.
      */
     effective = resolveIntegrationTarget({
-      clientId, configPath: recordedPath, io, record: stored, env: input.env, home: input.home,
+      clientId, configPath: recordedPath, io, record: stored, env: input.env, home: input.home, resolvedPaths: resolved,
     });
     configPath = effective.configPath;
+    if (effective.pathError && operation !== "disable") {
+      return { failed: observationFailure("unsafe", "unsafe", effective.pathError) } as const;
+    }
   } catch (error) {
     if (error instanceof ClineTransactionError) {
       return { failed: { ...observationFailure("unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;

package/src/integrations/registry.ts

@@ -12,6 +12,7 @@ import { homedir } from "node:os";
 import { assertDroidSettingsUnambiguous } from "./droid-settings";
 import { readPath } from "./merge";
 import type { OwnershipRecord } from "./ownership";
+import type { IntegrationIO } from "./config-io";
 import { dirname, join } from "node:path";
 import {
   ClientPathError,
@@ -49,6 +50,8 @@ import {
   raycastConfigPath,
   zcodeConfigPath,
   zcodeHomeDir,
+  zcodeLegacyHomeDir,
+  ZcodeSettingsPathError,
   zcodeProviderStorePath,
   buildZcodeStoreContribution,
   zcodeStoreSchemaEstablished,
@@ -75,12 +78,21 @@ import {
  */
 export type IntegrationClientId = ExportClientId;
 
+export interface ResolvedIntegrationPaths {
+  configPath: string;
+  detectDir: string;
+  /** Snapshot of a mutable store resolution from the same bootstrap read. */
+  storePath?: string;
+  /** The default config path is only a recovery hint when the active root is unknown. */
+  pathError?: string;
+}
+
 export interface IntegrationClientSpec {
   id: IntegrationClientId;
   /** The client's config file, honoring that client's own environment override. */
-  configPath: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  configPath: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string;
   /** Directory whose existence is the cheap "is it installed?" signal. */
-  detectDir: (env?: NodeJS.ProcessEnv, home?: string) => string;
+  detectDir: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string;
   /**
    * The provider store this client reads INSTEAD of `configPath`.
    *
@@ -98,7 +110,7 @@ export interface IntegrationClientSpec {
    * client, never merged into on a guess.
    */
   currentStore?: {
-    path: (env?: NodeJS.ProcessEnv, home?: string) => string;
+    path: (env?: NodeJS.ProcessEnv, home?: string, io?: Pick<IntegrationIO, "readText">) => string;
     format: ConfigFormat;
     establishes: (parsed: unknown) => boolean;
     buildContribution: BuildContribution;
@@ -139,7 +151,7 @@ export interface IntegrationClientSpec {
    * Droid uses the same seam to check competing settings against the export
    * context before status, preview, or mutation proceeds.
    */
-  resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string, exportContext?: ExportContext) => { configPath: string; detectDir: string };
+  resolvePaths?: (env?: NodeJS.ProcessEnv, home?: string, exportContext?: ExportContext, io?: Pick<IntegrationIO, "readText">) => ResolvedIntegrationPaths;
   /**
    * Where the client's config WOULD live, for a client whose real path cannot
    * be resolved yet.
@@ -183,10 +195,11 @@ export function resolveIntegrationPaths(
   env: NodeJS.ProcessEnv = process.env,
   home: string = homedir(),
   exportContext?: ExportContext,
-): { configPath: string; detectDir: string } {
+  io?: Pick<IntegrationIO, "readText">,
+): ResolvedIntegrationPaths {
   const spec = INTEGRATION_CLIENTS[clientId];
-  if (spec.resolvePaths) return spec.resolvePaths(env, home, exportContext);
-  return { configPath: spec.configPath(env, home), detectDir: spec.detectDir(env, home) };
+  if (spec.resolvePaths) return spec.resolvePaths(env, home, exportContext, io);
+  return { configPath: spec.configPath(env, home, io), detectDir: spec.detectDir(env, home, io) };
 }
 
 export function assertDroidPathsUnambiguous(root: string, exportContext?: ExportContext): void {
@@ -357,15 +370,31 @@ export const INTEGRATION_CLIENTS: Record<IntegrationClientId, IntegrationClientS
   },
   zcode: {
     id: "zcode",
-    configPath: (env = process.env, home = homedir()) => zcodeConfigPath(env, home),
-    detectDir: (env = process.env, home = homedir()) => zcodeHomeDir(env, home),
+    configPath: (env = process.env, home = homedir(), io) => zcodeConfigPath(env, home, io),
+    detectDir: (env = process.env, home = homedir(), io) => zcodeHomeDir(env, home, io),
+    resolvePaths: (env = process.env, home = homedir(), _context, io) => {
+      let root: string;
+      let pathError: string | undefined;
+      try { root = zcodeHomeDir(env, home, io); }
+      catch (error) {
+        if (!(error instanceof ZcodeSettingsPathError)) throw error;
+        root = zcodeLegacyHomeDir(env, home);
+        pathError = error.message;
+      }
+      // Passing the resolved root prevents a second bootstrap read. An explicit
+      // provider-file override outranks both the setting and ZCODE_DATA_DIR.
+      const storePath = zcodeProviderStorePath({ ...env, ZCODE_DATA_DIR: root }, home, io);
+      return { configPath: join(root, "v2", "config.json"), detectDir: root, storePath, ...(pathError ? { pathError } : {}) };
+    },
+    bindsDriftedRecord: (path, env = process.env, home = homedir()) =>
+      path === join(zcodeLegacyHomeDir(env, home), "v2", "config.json"),
     /*
      * ZCode 3.14 reads its providers from `v2/provider_config.json` and reaches
      * `v2/config.json` only through the import that seeded it. Where the new
      * file exists the import is spent, so our write is read by nobody (#5348).
      */
     currentStore: {
-      path: (env = process.env, home = homedir()) => zcodeProviderStorePath(env, home),
+      path: (env = process.env, home = homedir(), io) => zcodeProviderStorePath(env, home, io),
       format: "json",
       establishes: zcodeStoreSchemaEstablished,
       buildContribution: buildZcodeStoreContribution,
@@ -496,7 +525,7 @@ export function boundIntegrationConfigPath(input: {
   if (
     record && record.clientId === input.clientId &&
     record.configPath !== input.resolvedPath &&
-    input.statKind(record.configPath) === "file" &&
+    (input.clientId === "zcode" ? input.statKind(record.configPath) !== "missing" : input.statKind(record.configPath) === "file") &&
     INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord?.(record.configPath, input.env, input.home) === true
   ) {
     return record.configPath;
@@ -529,6 +558,11 @@ export function restoreOwnershipCollision(input: {
 }): string | null {
   const currentPath = input.currentPath;
   if (currentPath === null || currentPath === input.journaledPath) return null;
+  // A relocated ZCode store must not lose its single record to an older
+  // legacy undo, even when both journaled locations are legal for this home.
+  if (input.clientId === "zcode") {
+    return `that operation was recorded for ${input.journaledPath}, but ${currentPath} currently owns this integration`;
+  }
   const binds = INTEGRATION_CLIENTS[input.clientId].bindsDriftedRecord;
   if (!binds) return null;
   if (binds(input.journaledPath, input.env, input.home) !== true) return null;

package/src/integrations/state.ts

@@ -39,6 +39,7 @@ import {
   assertDroidPathsUnambiguous,
   assertDroidRecordedSettingsUnambiguous,
   resolveIntegrationPaths,
+  type ResolvedIntegrationPaths,
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
@@ -482,7 +483,7 @@ export interface IntegrationStateInput {
   store?: IntegrationStateStore;
   io?: IntegrationIO;
   /** Internal explicit profile target; never accepted as a caller-provided path. */
-  resolvedPaths?: { configPath: string; detectDir: string };
+  resolvedPaths?: ResolvedIntegrationPaths;
 }
 
 export function exportContextOf(input: {
@@ -592,11 +593,11 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
    */
   let installed: boolean;
   let effective: IntegrationTarget;
-  let record: OwnershipRecord | null;
+  let record: OwnershipRecord | null = null;
   try {
     // One resolution for both, so a client whose paths come from mutable state
     // cannot report one account's install beside another account's config path.
-    const paths = resolveStatePaths(input);
+    const paths = resolveStatePaths(input, io);
     installed = io.statKind(paths.detectDir) === "dir";
     if (input.clientId === "cline") io = createClineIO(io, paths.configPath, store);
     /*
@@ -611,7 +612,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
       statKind: io.statKind, env: input.env, home: input.home,
     });
     effective = resolveIntegrationTarget({
-      clientId: input.clientId, configPath: recordedPath, io, record, env: input.env, home: input.home,
+      clientId: input.clientId, configPath: recordedPath, io, record, env: input.env, home: input.home, resolvedPaths: paths,
     });
   } catch (error) {
     if (!(error instanceof ClientPathError)) throw error;
@@ -626,6 +627,10 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
      * yet. A client that can name where its config would go gets `installed:
      * false` and that location, which reads as "not installed" in the UI.
      */
+    if (input.clientId === "zcode" && record) return {
+      clientId: input.clientId, state: "unsafe", installed: false, configPath: record.configPath,
+      reason: "unresolvable-path", appliedAt: record.appliedAt, lastOpId: record.opId, ...retention,
+    };
     const hint = unresolvedPathHintFor(input.clientId, input.env, input.home);
     return {
       clientId: input.clientId,
@@ -638,6 +643,12 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   }
 
   const configPath = effective.configPath;
+  if (effective.pathError) return {
+    clientId: input.clientId, state: "unsafe", installed, configPath,
+    reason: "unresolvable-path",
+    ...(record?.configPath === configPath ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
+    ...retention,
+  };
   if (input.clientId === "kilo") {
     const candidates = inspectKiloCandidates({ io, selectedPath: configPath, env: input.env, home: input.home });
     if (candidates.kind !== "ok") return {
@@ -715,9 +726,10 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   };
 }
 
-function resolveStatePaths(input: IntegrationStateInput): { configPath: string; detectDir: string } {
+function resolveStatePaths(input: IntegrationStateInput, io: IntegrationIO): ResolvedIntegrationPaths {
   const context = exportContextOf(input);
-  const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home, context);
+  const paths = input.clientId === "zcode" || !input.resolvedPaths
+    ? resolveIntegrationPaths(input.clientId, input.env, input.home, context, io) : input.resolvedPaths;
   if (input.clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(paths.detectDir, context);
   return paths;
 }
@@ -727,7 +739,7 @@ export function readOwnedDroidReasoningDefaults(input: IntegrationStateInput): R
   const store = input.store ?? createIntegrationStateStore();
   const io = input.io ?? store.io();
   try {
-    const paths = resolveStatePaths(input);
+    const paths = resolveStatePaths(input, io);
     const record = store.readRecords().droid;
     if (!record || record.clientId !== "droid" || record.configPath !== paths.configPath) return {};
     const effective = resolveIntegrationTarget({

package/src/integrations/target.ts

@@ -23,11 +23,11 @@
  *    nesting into a file holding the user's other providers would trade a
  *    silent no-op for a silent loss.
  */
-import { EXPORT_CLIENTS, ClientPathError, type BuildContribution, type ConfigFormat } from "../clients/config-export";
+import { EXPORT_CLIENTS, ClientPathError, zcodeLegacyHomeDir, zcodeProviderStorePath, type BuildContribution, type ConfigFormat } from "../clients/config-export";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { AmbiguousSelectorError, InvalidSelectorError, readPath } from "./merge";
 import type { OwnershipRecord } from "./ownership";
-import { INTEGRATION_CLIENTS, type IntegrationClientId } from "./registry";
+import { INTEGRATION_CLIENTS, resolveIntegrationPaths, type ResolvedIntegrationPaths, type IntegrationClientId } from "./registry";
 
 export interface IntegrationTarget {
   /** The file this operation reads, writes, journals and records ownership for. */
@@ -51,6 +51,8 @@ export interface IntegrationTarget {
    * to is as effective as it ever was.
    */
   readonly ineffective: IneffectiveWrite | null;
+  /** Active root unknown; the named config is only a historical removal target. */
+  readonly pathError?: string;
 }
 
 export interface IneffectiveWrite {
@@ -153,12 +155,44 @@ export function resolveIntegrationTarget(args: {
   record: OwnershipRecord | null;
   env?: NodeJS.ProcessEnv;
   home?: string;
+  resolvedPaths?: ResolvedIntegrationPaths;
 }): IntegrationTarget {
   const { clientId, configPath, io, record } = args;
   const declared = INTEGRATION_CLIENTS[clientId].currentStore;
   if (!declared) return configFileTarget(clientId, configPath, null);
-  const storePath = declared.path(args.env, args.home);
+  const paths = clientId === "zcode"
+    ? args.resolvedPaths ?? resolveIntegrationPaths(clientId, args.env, args.home, undefined, io)
+    : undefined;
+  const storePath = paths?.storePath ?? declared.path(args.env, args.home, io);
   const kind = io.statKind(storePath);
+  const owned = record !== null && record.clientId === clientId ? record : null;
+  const historicalStore = clientId === "zcode"
+    ? zcodeProviderStorePath({ ...(args.env ?? process.env), ZCODE_DATA_DIR: zcodeLegacyHomeDir(args.env, args.home) }, args.home, io)
+    : null;
+  if (clientId === "zcode" && owned && owned.configPath !== configPath && owned.configPath !== storePath
+    && owned.configPath !== historicalStore
+    && INTEGRATION_CLIENTS[clientId].bindsDriftedRecord?.(owned.configPath, args.env, args.home) !== true
+    && io.statKind(owned.configPath) !== "missing") {
+    throw new ClientPathError(`ZCode ownership remains at ${owned.configPath}. Its location cannot be bound to the current home or selectors; restore the original selectors and disable it before enabling a different data root. Ownership and recovery evidence are retained.`);
+  }
+  // An explicit provider-file selector can establish the active target even
+  // when the bootstrap is unreadable, but absence cannot justify a legacy write.
+  if (paths?.pathError && (!(args.env ?? process.env).ZCODE_PERSONAL_PROVIDER_CONFIG_FILE?.trim() || kind !== "file")) {
+    const removal = owned?.configPath === historicalStore
+      ? storeTarget(declared, historicalStore)
+      : configFileTarget(clientId, configPath, null);
+    return { ...removal, pathError: paths.pathError };
+  }
+  if (historicalStore && owned?.configPath === historicalStore && historicalStore !== storePath
+    && recordedBlockStillPresent(io, declared.format, historicalStore, owned)) {
+    return storeTarget(declared, historicalStore, { store: storePath, why: "owned-config-file" });
+  }
+  // Relocation must not orphan a block at the default historical path, even
+  // when the relocated store has not been created yet.
+  if (clientId === "zcode" && owned?.configPath === configPath && configPath !== paths?.configPath
+    && recordedBlockStillPresent(io, EXPORT_CLIENTS[clientId].format, configPath, owned)) {
+    return configFileTarget(clientId, configPath, { store: storePath, why: "owned-config-file" });
+  }
   if (kind === "missing") {
     const missing = declared.missingStore;
     return missing?.readsStore(storePath, path => io.statKind(path)) === true
@@ -182,7 +216,6 @@ export function resolveIntegrationTarget(args: {
    * file holds it. Disable has to remove what we wrote from where we wrote it,
    * and an apply must never leave a block in one file while writing another.
    */
-  const owned = record !== null && record.clientId === clientId ? record : null;
   if (owned?.configPath === storePath && recordedBlockStillPresent(io, declared.format, storePath, owned)) {
     return storeTarget(declared, storePath, established ? null : unestablished);
   }
@@ -214,6 +247,7 @@ export function declaredIntegrationTarget(args: {
   resolvedConfigPath: string;
   env?: NodeJS.ProcessEnv;
   home?: string;
+  io?: Pick<IntegrationIO, "readText">;
 }): IntegrationTarget | null {
   const { clientId, configPath, resolvedConfigPath } = args;
   if (configPath === resolvedConfigPath) return configFileTarget(clientId, configPath, null);
@@ -222,8 +256,11 @@ export function declaredIntegrationTarget(args: {
   }
   const declared = INTEGRATION_CLIENTS[clientId].currentStore;
   if (!declared) return null;
+  if (clientId === "zcode" && configPath === zcodeProviderStorePath(
+    { ...(args.env ?? process.env), ZCODE_DATA_DIR: zcodeLegacyHomeDir(args.env, args.home) }, args.home, args.io,
+  )) return storeTarget(declared, configPath);
   try {
-    if (declared.path(args.env, args.home) !== configPath) return null;
+    if (declared.path(args.env, args.home, args.io) !== configPath) return null;
   } catch (error) {
     // A store the operator relocated with a path we cannot resolve proves
     // nothing about the row, so the row is not a legal target.

package/src/integrations/writer.ts

@@ -39,6 +39,7 @@ import {
   assertDroidPathsUnambiguous,
   isLoopbackOnly,
   resolveIntegrationPaths,
+  type ResolvedIntegrationPaths,
   restoreOwnershipCollision,
   type IntegrationClientId,
 } from "./registry";
@@ -643,8 +644,15 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   if (entry.clientId !== input.clientId) throw new Error("restore input names a different client than the operation");
 
   const clientId = entry.clientId;
-  const resolvedPath = input.resolvedPaths?.configPath
-    ?? INTEGRATION_CLIENTS[clientId].configPath(input.env, input.home);
+  let resolvedPath: string;
+  try {
+    resolvedPath = clientId === "zcode" || !input.resolvedPaths
+      ? resolveIntegrationPaths(clientId, input.env, input.home, undefined, io).configPath
+      : input.resolvedPaths.configPath;
+  } catch (error) {
+    if (!(error instanceof ClientPathError)) throw error;
+    return refuse(clientId, "unsafe", "unsafe", error.message);
+  }
   const configPath = entry.configPath;
   /*
    * Restore acts on the path the operation was journaled against. Resolving a
@@ -655,7 +663,7 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
    * shape those bytes are in, which is what the state below is measured against.
    */
   const rowTarget = declaredIntegrationTarget({
-    clientId, configPath, resolvedConfigPath: resolvedPath, env: input.env, home: input.home,
+    clientId, configPath, resolvedConfigPath: resolvedPath, env: input.env, home: input.home, io,
   });
   if (rowTarget === null) {
     return refuse(clientId, "conflict", "conflict",
@@ -814,7 +822,7 @@ type FrozenIntegrationInput = IntegrationWriteInput & {
   io: IntegrationIO;
   env: NodeJS.ProcessEnv;
   home: string;
-  resolvedPaths: { configPath: string; detectDir: string };
+  resolvedPaths: ResolvedIntegrationPaths;
 };
 
 /**
@@ -854,7 +862,7 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
    */
   const resolvedPaths = input.resolvedPaths
     ? { ...input.resolvedPaths }
-    : resolveIntegrationPaths(input.clientId, env, home, exportContextOf({ ...input, config, models: models.value }));
+    : resolveIntegrationPaths(input.clientId, env, home, exportContextOf({ ...input, config, models: models.value }), io);
   /*
    * The configuration and the roster are seams like the others, and they were the two still held
    * by reference. A coordinated write plans from this input, awaits the writer lock and a
@@ -899,7 +907,7 @@ function storeLockFile(frozen: FrozenIntegrationInput): string | null {
   if (!declared?.lockFile) return null;
   let storePath: string;
   try {
-    storePath = declared.path(frozen.env, frozen.home);
+    storePath = declared.path(frozen.env, frozen.home, frozen.io);
   } catch (error) {
     if (error instanceof ClientPathError) return null;
     throw error;