@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/integrations/state.ts

@@ -10,7 +10,7 @@
  */
 import { createClineIO } from "./cline-io";
 import { parseClineDocument } from "./cline-document";
-import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, type ExportModel, type ManagedContribution } from "../clients/config-export";
+import { ClientPathError, EXPORT_CLIENTS, opencodeProxyBaseUrl, droidDefaultsFromOwnedRows, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import type { ConfigFormat } from "../clients/config-export";
 import type { OcxConfig } from "../types";
 import { PARSE_FAILED, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
@@ -25,6 +25,8 @@ import {
 } from "./merge";
 import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
 import {
+  droidNormalizedContributionMatchesRecord,
+  droidNormalizedFileMatchesRecord,
   isHermesAffinityUpgrade,
   protectedContributionFingerprint,
   refreshablePathsOf,
@@ -40,7 +42,7 @@ import {
   unresolvedPathHintFor,
   type IntegrationClientId,
 } from "./registry";
-import { resolveIntegrationTarget, type IntegrationTarget } from "./target";
+import { resolveIntegrationTarget, type IneffectiveWriteReason, type IntegrationTarget } from "./target";
 import { inspectKiloCandidates } from "./kilo-candidates";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 
@@ -84,6 +86,13 @@ export interface IntegrationStatus {
    * `current` has to be able to report this beside it.
    */
   supersededBy?: string;
+  /** Why `supersededBy` is not written; present exactly when it is. */
+  supersededReason?: IneffectiveWriteReason;
+  /**
+   * `missing-store` only: the document that recreates the store. A surface that localizes the
+   * remedy needs the content to name, not the writer's English sentence.
+   */
+  missingStoreDocument?: string;
   /** Snapshot files retained for this client; -1 when they cannot be inspected. */
   snapshotCount: number;
   /** Pruning is behind, so older (possibly credential-bearing) snapshots remain. */
@@ -208,6 +217,18 @@ function recordedContribution(
   };
 }
 
+function observedContributionMatchesRecord(
+  observed: ManagedContribution,
+  record: OwnershipRecord,
+): boolean {
+  if (fingerprint(canonicalContribution(observed)) === record.blockFingerprint) return true;
+  if (
+    typeof record.semanticBlockFingerprint === "string"
+    && fingerprint(semanticContribution(observed)) === record.semanticBlockFingerprint
+  ) return true;
+  return droidNormalizedContributionMatchesRecord(observed, record);
+}
+
 /**
  * Prove that every protected field still matches what OpenCodex wrote.
  *
@@ -223,13 +244,8 @@ function recordedBlockIsOwned(
 ): boolean {
   const observed = recordedContribution(doc, record);
   if (!observed) return false;
-  if (fingerprint(canonicalContribution(observed)) === record.blockFingerprint) return true;
-
+  if (observedContributionMatchesRecord(observed, record)) return true;
   const observedSemanticFingerprint = fingerprint(semanticContribution(observed));
-  if (
-    typeof record.semanticBlockFingerprint === "string"
-    && observedSemanticFingerprint === record.semanticBlockFingerprint
-  ) return true;
 
   const desiredFingerprint = fingerprint(canonicalContribution(desired));
   if (
@@ -304,6 +320,12 @@ export function classifyIntegration(input: {
    * the wrong way.
    */
   format?: ConfigFormat;
+  /**
+   * Whether the file being classified is patched in place, which makes a
+   * sibling edit harmless. Like `format`, it belongs to the target; omitted, the
+   * client's config-file declaration answers.
+   */
+  sourcePreservingYaml?: boolean;
 }): { state: IntegrationState; reason?: StateReason } {
   if (input.fileText !== null && !input.fileIsRegular) {
     return { state: "unsafe", reason: "not-regular-file" };
@@ -405,12 +427,16 @@ export function classifyIntegration(input: {
     && !isHermesAffinityUpgrade(input.parsed, input.record, input.contribution)) {
     return { state: "conflict", reason: "foreign-edit" };
   }
-  if (!INTEGRATION_CLIENTS[clientId].sourcePreservingYaml
-    && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
+  if (!(input.sourcePreservingYaml ?? INTEGRATION_CLIENTS[clientId].sourcePreservingYaml !== undefined)
+    && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint
+    && !droidNormalizedFileMatchesRecord(input.parsed, input.record)) {
     /*
-     * The file changed since we wrote it, but every fragment we own is still
-     * byte-for-byte what we put there — a sibling edit, not tampering. Apply
-     * rewrites the WHOLE document, so for comment-capable formats (yaml,
+     * The file changed since we wrote it. Every fragment we own is still
+     * byte-for-byte what we put there, so this is a sibling edit rather than
+     * tampering. Known Droid row normalization is accepted before this branch
+     * only when removing its two client fields reproduces the recorded file.
+     * Other drift reaches this branch. Apply rewrites the WHOLE document, so
+     * for comment-capable formats (yaml,
      * json5, toml) it would drop comments the user wrote next to us: fail
      * closed there. Strict JSON cannot carry comments — a commented file
      * never reaches this branch because parsing already failed — so the only
@@ -449,6 +475,7 @@ export interface IntegrationStateInput {
   models: readonly ExportModel[];
   config: OcxConfig;
   port: number;
+  droidReasoningDefaults?: Record<string, string>;
   env?: NodeJS.ProcessEnv;
   home?: string;
   /** The whole integration state store, bound to one root. */
@@ -462,7 +489,8 @@ export function exportContextOf(input: {
   models: readonly ExportModel[];
   config: OcxConfig;
   port: number;
-}): { baseUrl: string; models: readonly ExportModel[]; config: OcxConfig } {
+  droidReasoningDefaults?: Record<string, string>;
+}): { baseUrl: string; models: readonly ExportModel[]; config: OcxConfig; droidReasoningDefaults?: Record<string, string> } {
   return {
     /*
      * Composed through the SAME helper `ocx export` uses. Interpolating the
@@ -476,9 +504,35 @@ export function exportContextOf(input: {
     baseUrl: opencodeProxyBaseUrl(input.port, input.config.hostname, input.config),
     models: input.models,
     config: input.config,
+    ...(input.droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: input.droidReasoningDefaults }),
   };
 }
 
+export function buildIntegrationContribution(
+  input: IntegrationStateInput,
+  effective: IntegrationTarget,
+  parsed: unknown,
+  record: OwnershipRecord | null,
+): ManagedContribution {
+  const context = exportContextOf(input);
+  if (input.clientId === "droid" && input.droidReasoningDefaults === undefined && record?.configPath === effective.configPath) {
+    const inherited = recordedDroidContributionMatches(parsed, record)
+      ? droidDefaultsFromOwnedRows(context, parsed, record.fragmentPaths)
+      : {};
+    if (Object.keys(inherited).length > 0) context.droidReasoningDefaults = inherited;
+  }
+  return effective.buildContribution(context);
+}
+
+function recordedDroidContributionMatches(document: unknown, record: OwnershipRecord): boolean {
+  try {
+    const observed = recordedContribution(document, record);
+    return observed !== null && observedContributionMatchesRecord(observed, record);
+  } catch {
+    return false;
+  }
+}
+
 let retriedThisProcess = false;
 
 /**
@@ -535,9 +589,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   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 context = exportContextOf(input);
-    const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home, context);
-    if (input.clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(paths.detectDir, context);
+    const paths = resolveStatePaths(input);
     installed = io.statKind(paths.detectDir) === "dir";
     if (input.clientId === "cline") io = createClineIO(io, paths.configPath, store);
     /*
@@ -608,7 +660,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
   const parsed = input.clientId === "cline"
     ? parseClineDocument(loaded.before)
     : parseConfig(loaded.before, effective.format, EXPORT_CLIENTS[input.clientId].jsonc ? { jsonc: true } : undefined);
-  const contribution = effective.buildContribution(exportContextOf(input));
+  const contribution = buildIntegrationContribution(input, effective, parsed, record);
   if (input.clientId === "droid" && input.models.length > 0 && contribution.fragments.length === 0
     && (!record || record.configPath !== configPath)) {
     return { clientId: input.clientId, state: "unsafe", installed, configPath,
@@ -623,6 +675,7 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
     configPath,
     clientId: input.clientId,
     format: effective.format,
+    sourcePreservingYaml: effective.sourcePreservingYaml !== null,
   });
   if (input.clientId === "droid" && record && (state === "current" || state === "stale")) {
     try { assertDroidRecordedSettingsUnambiguous(spec.detectDir(input.env, input.home), parsed, record); }
@@ -644,9 +697,43 @@ export function readIntegrationState(input: IntegrationStateInput): IntegrationS
      * about. A store we are writing needs no notice; the path already names it.
      */
     ...(effective.ineffective && effective.ineffective.store !== configPath
-      ? { supersededBy: effective.ineffective.store }
+      ? {
+          supersededBy: effective.ineffective.store,
+          supersededReason: effective.ineffective.why,
+          ...(effective.ineffective.emptyDocument === undefined ? {} : { missingStoreDocument: effective.ineffective.emptyDocument }),
+        }
       : {}),
     ...(record ? { appliedAt: record.appliedAt, lastOpId: record.opId } : {}),
     ...retention,
   };
 }
+
+function resolveStatePaths(input: IntegrationStateInput): { configPath: string; detectDir: string } {
+  const context = exportContextOf(input);
+  const paths = input.resolvedPaths ?? resolveIntegrationPaths(input.clientId, input.env, input.home, context);
+  if (input.clientId === "droid" && input.resolvedPaths) assertDroidPathsUnambiguous(paths.detectDir, context);
+  return paths;
+}
+
+export function readOwnedDroidReasoningDefaults(input: IntegrationStateInput): Record<string, string> {
+  if (input.clientId !== "droid") return {};
+  const store = input.store ?? createIntegrationStateStore();
+  const io = input.io ?? store.io();
+  try {
+    const paths = resolveStatePaths(input);
+    const record = store.readRecords().droid;
+    if (!record || record.clientId !== "droid" || record.configPath !== paths.configPath) return {};
+    const effective = resolveIntegrationTarget({
+      clientId: "droid", configPath: paths.configPath, io, record, env: input.env, home: input.home,
+    });
+    const loaded = loadTarget(io, effective.configPath);
+    if (!loaded.ok) return {};
+    const parsed = parseConfig(loaded.before, "json");
+    if (parsed === PARSE_FAILED) return {};
+    if (!recordedDroidContributionMatches(parsed, record)) return {};
+    return droidDefaultsFromOwnedRows(exportContextOf(input), parsed, record.fragmentPaths);
+  } catch (error) {
+    if (error instanceof ClientPathError) return {};
+    throw error;
+  }
+}

package/src/integrations/target.ts

@@ -36,6 +36,12 @@ export interface IntegrationTarget {
   readonly format: ConfigFormat;
   /** The contribution shape that file's reader understands. */
   readonly buildContribution: BuildContribution;
+  /**
+   * The one YAML leaf patched in place in that file, or null when the writer
+   * re-renders the document. A client's config file and its store have
+   * different shapes, so this belongs to the target rather than the client.
+   */
+  readonly sourcePreservingYaml: { readonly path: readonly string[] } | null;
   /**
    * Set when a write to the file above would not reach the client.
    *
@@ -60,10 +66,20 @@ export interface IneffectiveWrite {
    * with the store itself as the target: a client that bumps its schema after
    * we wrote the store leaves our block there, removable, and the file no
    * longer one we may merge into.
+   *
+   * `missing-store` — the store does not exist, but the client already manages it
+   * (DSH: a Desktop profile manifest is present). DSH renames `settings.yaml` to
+   * `settings.yaml.imported` and imports it on startup, so a config-file write would
+   * orphan our ownership record. `remedy` says how to bring the store back, and
+   * `emptyDocument` is what to create it with.
    */
-  readonly why: "owned-config-file" | "unestablished-schema";
+  readonly why: IneffectiveWriteReason;
+  readonly remedy?: string;
+  readonly emptyDocument?: string;
 }
 
+export type IneffectiveWriteReason = "owned-config-file" | "unestablished-schema" | "missing-store";
+
 function configFileTarget(
   clientId: IntegrationClientId,
   configPath: string,
@@ -74,6 +90,7 @@ function configFileTarget(
     configPath,
     format: exportSpec.format,
     buildContribution: exportSpec.buildContribution,
+    sourcePreservingYaml: INTEGRATION_CLIENTS[clientId].sourcePreservingYaml ?? null,
     ineffective,
   };
 }
@@ -87,6 +104,7 @@ function storeTarget(
     configPath,
     format: declared.format,
     buildContribution: declared.buildContribution,
+    sourcePreservingYaml: declared.sourcePreservingYaml ?? null,
     ineffective,
   };
 }
@@ -141,7 +159,12 @@ export function resolveIntegrationTarget(args: {
   if (!declared) return configFileTarget(clientId, configPath, null);
   const storePath = declared.path(args.env, args.home);
   const kind = io.statKind(storePath);
-  if (kind === "missing") return configFileTarget(clientId, configPath, null);
+  if (kind === "missing") {
+    const missing = declared.missingStore;
+    return missing?.readsStore(storePath, path => io.statKind(path)) === true
+      ? configFileTarget(clientId, configPath, { store: storePath, why: "missing-store", remedy: missing.remedy, emptyDocument: missing.emptyDocument })
+      : configFileTarget(clientId, configPath, null);
+  }
   // Only proven absence permits a legacy write. Unreadable or non-file stores
   // cannot establish what the client reads; preserve the recorded removal target.
   if (kind !== "file") {

package/src/integrations/writer.ts

@@ -18,7 +18,7 @@ import { shouldInjectApiAuthHeader } from "../codex/inject";
 import { detachedConfigSnapshot } from "../config/admitted-identity";
 import { copyPlainData } from "../lib/plain-data";
 import type { OcxConfig } from "../types";
-import { defaultIntegrationIO, loadTarget, type IntegrationIO } from "./config-io";
+import { defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
 import { inspectKiloCandidates } from "./kilo-candidates";
 import {
   fingerprint,
@@ -33,7 +33,7 @@ import {
   refreshablePathsOf,
   semanticProtectedContributionFingerprint,
 } from "./ownership-policy";
-import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, removeFragments } from "./merge";
+import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, parseSegment, removeFragments } from "./merge";
 import {
   INTEGRATION_CLIENTS,
   assertDroidPathsUnambiguous,
@@ -43,12 +43,12 @@ import {
   type IntegrationClientId,
 } from "./registry";
 import { declaredIntegrationTarget } from "./target";
-import { exportContextOf } from "./state";
+import { buildIntegrationContribution, exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
-import { observeIntegration, type IntegrationWriteInput, type RefusalReason } from "./mutation-plan";
+import { observeIntegration, restoreStoreDirectoryRefusal, type IntegrationWriteInput, type RefusalReason } from "./mutation-plan";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 import {
   patchYamlFragmentSource,
@@ -300,6 +300,8 @@ function applyOrRefreshIntegration(
     return refuse(clientId, "superseded_store", classified.state,
       target.ineffective.why === "owned-config-file"
         ? `${clientId} now reads its providers from ${readsFrom}, and opencodex still has a block in ${configPath}, which it no longer reads. Disable the ${clientId} integration to remove that block, then enable it again to write ${readsFrom}.`
+        : target.ineffective.why === "missing-store"
+          ? `${clientId} reads its providers from ${readsFrom}, which does not exist. ${clientId} renames ${configPath} away and imports it on its next start, so opencodex will not write there. ${target.ineffective.remedy ?? fallback}`
         : readsFrom === configPath
           ? `opencodex does not recognise the schema of ${readsFrom}, the file ${clientId} reads its providers from, so it will not merge into it. ${fallback}`
           : `${clientId} now reads its providers from ${readsFrom}, whose schema opencodex does not recognise, so writing ${configPath} would change nothing it loads. ${fallback}`);
@@ -383,8 +385,15 @@ function applyOrRefreshIntegration(
   let created: string[];
   let text: string;
   try {
+    // The source patcher updates this selected row in place. Keep it in the
+    // semantic merge too, even when we originally created it, and retain that
+    // provenance so disable can still remove the row when it becomes empty.
+    const sourceRoot = target.sourcePreservingYaml?.path[0];
+    const retainedRow = sourceRoot && parseSegment(sourceRoot).kind === "select" ? sourceRoot : null;
+    const priorCreated = record?.createdContainers ?? [];
+    const prunable = new Set(priorCreated.filter(path => path !== retainedRow));
     const base = classified.state === "stale" && record
-      ? removeFragments(parsed, record.fragmentPaths, new Set(record.createdContainers ?? [])).doc
+      ? removeFragments(parsed, record.fragmentPaths, prunable).doc
       : classified.state === "conflict" && record
         /*
          * A forced overwrite of a `foreign-edit` conflict drops what the previous
@@ -399,26 +408,27 @@ function applyOrRefreshIntegration(
          * them, so a later disable removes our leaves and leaves their structure
          * standing.
          */
-        ? removeFragments(parsed, record.fragmentPaths, new Set(record.createdContainers ?? [])).doc
+        ? removeFragments(parsed, record.fragmentPaths, prunable).doc
         : parsed;
     // Computed against the document as it stands BEFORE the merge: afterwards
     // every container exists and "did we create this?" is unanswerable.
     created = createdContainerPaths(base, contribution);
+    if (retainedRow && priorCreated.includes(retainedRow)) created = [...new Set([retainedRow, ...created])];
     const nextDocument = mergeContribution(base, contribution);
     if (clientId === "cline") preserveClineSelection(parsed, nextDocument);
-    if (spec.sourcePreservingYaml && before !== null) {
-      const value = sourcePreservingFragmentValue(contribution, spec.sourcePreservingYaml.path);
+    if (target.sourcePreservingYaml && before !== null) {
+      const value = sourcePreservingFragmentValue(contribution, target.sourcePreservingYaml.path);
       const patched = value === undefined
         ? null
         : patchYamlFragmentSource(
             before,
-            spec.sourcePreservingYaml.path,
+            target.sourcePreservingYaml.path,
             { kind: "upsert", value },
             nextDocument,
           );
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
-          yamlRefusalReason(before, spec.sourcePreservingYaml.path, configPath, "it was left alone"));
+          yamlRefusalReason(before, target.sourcePreservingYaml.path, configPath, "it was left alone"));
       }
       text = patched;
     } else {
@@ -565,12 +575,12 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
    * comment makes its ancestor user-owned without protecting our leaf.
    */
   const recordedCreated = record!.createdContainers ?? [];
-  const prunableCreated = spec.sourcePreservingYaml && before !== null
-    ? sourcePrunableYamlContainers(before, spec.sourcePreservingYaml.path, recordedCreated)
+  const prunableCreated = target.sourcePreservingYaml && before !== null
+    ? sourcePrunableYamlContainers(before, target.sourcePreservingYaml.path, recordedCreated)
     : recordedCreated;
   if (prunableCreated === null) {
     return refuse(clientId, "unsafe", "unsafe",
-      yamlRefusalReason(before ?? "", spec.sourcePreservingYaml!.path, configPath, "nothing was removed"));
+      yamlRefusalReason(before ?? "", target.sourcePreservingYaml!.path, configPath, "nothing was removed"));
   }
   let doc: unknown;
   let removed: boolean;
@@ -586,14 +596,14 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
   }
   let text: string;
   try {
-    if (spec.sourcePreservingYaml && before !== null) {
-      const patched = patchYamlFragmentSource(before, spec.sourcePreservingYaml.path, {
+    if (target.sourcePreservingYaml && before !== null) {
+      const patched = patchYamlFragmentSource(before, target.sourcePreservingYaml.path, {
         kind: "remove",
         createdContainers: prunableCreated,
       }, doc);
       if (patched === null) {
         return refuse(clientId, "unsafe", "unsafe",
-          yamlRefusalReason(before, spec.sourcePreservingYaml.path, configPath, "nothing was removed"));
+          yamlRefusalReason(before, target.sourcePreservingYaml.path, configPath, "nothing was removed"));
       }
       text = patched;
     } else {
@@ -651,6 +661,10 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
     return refuse(clientId, "conflict", "conflict",
       `that operation was recorded for ${configPath}, which this client no longer writes; it now resolves to ${resolvedPath}`);
   }
+  const directoryRefusal = restoreStoreDirectoryRefusal(input, configPath, io);
+  if (directoryRefusal !== null) {
+    return refuse(clientId, "unsafe", "unsafe", directoryRefusal);
+  }
   /*
    * Preview refuses this in observeRestore. Refusing here too is what keeps an
    * undo of an older candidate from replacing the record a newer candidate owns.
@@ -713,7 +727,11 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
   // exact bytes when the snapshot was taken. Re-deriving it from the file would
   // mean guessing which entries are ours, and a wrong guess deletes a user's.
   const restoredRecord = entry.priorRecord;
-  const fresh = rowTarget.buildContribution(exportContextOf(input));
+  const fresh = buildIntegrationContribution(
+    { ...input, droidReasoningDefaults: undefined }, rowTarget,
+    clientId === "droid" && restoredText !== null ? parseConfig(restoredText, "json") : undefined,
+    restoredRecord,
+  );
   /*
    * Does the restored record actually describe the restored bytes?
    *
@@ -812,6 +830,12 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
   if (!models.ok) {
     throw new UncopyableIntegrationInputError("the model roster could not be captured for this write");
   }
+  const droidReasoningDefaults = input.droidReasoningDefaults === undefined
+    ? undefined
+    : copyPlainData(input.droidReasoningDefaults);
+  if (droidReasoningDefaults !== undefined && !droidReasoningDefaults.ok) {
+    throw new UncopyableIntegrationInputError("Droid reasoning defaults could not be captured for this write");
+  }
   /*
    * One resolution for both paths. Aside derives them from the account id in
    * its manifest, so two independent calls could verify one account's install
@@ -828,7 +852,11 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
    * checked in one state and written from another, which is the substitution the fingerprint
    * exists to prevent. Copying both here gives the plan and the document one input.
    */
-  return { ...input, config, models: models.value, env, home, store, io, resolvedPaths };
+  return {
+    ...input, config, models: models.value,
+    ...(droidReasoningDefaults === undefined ? {} : { droidReasoningDefaults: droidReasoningDefaults.value }),
+    env, home, store, io, resolvedPaths,
+  };
 }
 
 function tryFreezeIntegrationInput(input: IntegrationWriteInput):
@@ -848,6 +876,57 @@ function tryFreezeIntegrationInput(input: IntegrationWriteInput):
   }
 }
 
+/**
+ * The store lock to hold beside the config file's, or null.
+ *
+ * Only for a store whose directory exists: a lock is never what creates a
+ * client's profile. A store path that cannot be resolved names nothing to lock;
+ * target resolution reports it on its own.
+ */
+function storeLockFile(frozen: FrozenIntegrationInput): string | null {
+  const declared = INTEGRATION_CLIENTS[frozen.clientId].currentStore;
+  if (!declared?.lockFile) return null;
+  let storePath: string;
+  try {
+    storePath = declared.path(frozen.env, frozen.home);
+  } catch (error) {
+    if (error instanceof ClientPathError) return null;
+    throw error;
+  }
+  return frozen.io.statKind(dirname(storePath)) === "dir" ? declared.lockFile(storePath) : null;
+}
+
+/**
+ * Hold the config file's sibling lock, then the store's. Every operation takes
+ * them in that order, so two of ours cannot deadlock, and the client's own
+ * writer only ever holds one of them.
+ */
+function withClientLocks(
+  frozen: FrozenIntegrationInput,
+  suffix: ".lock",
+  operation: () => WriteOutcome,
+  options?: CoordinatedIntegrationOptions,
+): Promise<WriteOutcome> {
+  const run = async (heldStoreLock: string | null): Promise<WriteOutcome> => {
+    const refused = await options?.revalidate?.(frozen);
+    if (refused) return refused;
+    // A profile can appear while revalidation awaits. Acquire its lock and
+    // repeat the validation before observing or mutating its document.
+    const required = storeLockFile(frozen);
+    if (required !== null && required !== heldStoreLock) {
+      return withIntegrationWriterLock(required, () => run(required), options?.lockSeams, ".lock");
+    }
+    // No await between the last store probe and the synchronous transaction.
+    return operation();
+  };
+  return withIntegrationWriterLock(frozen.resolvedPaths.configPath, () => {
+    // Decide only after the outer lock has actually been acquired.
+    const storeLock = storeLockFile(frozen);
+    return storeLock === null ? run(null)
+      : withIntegrationWriterLock(storeLock, () => run(storeLock), options?.lockSeams, ".lock");
+  }, options?.lockSeams, suffix);
+}
+
 async function coordinatedWrite(
   input: IntegrationWriteInput,
   operation: (frozen: IntegrationWriteInput) => WriteOutcome,
@@ -865,16 +944,14 @@ async function coordinatedWrite(
   // An absent client home is not created merely to acquire a sibling lock.
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
     const refused = await options?.revalidate?.(frozen);
-    return refused ?? operation(frozen);
+    if (refused) return refused;
+    if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") return operation(frozen);
   }
-  return withIntegrationWriterLock(
-    frozen.resolvedPaths.configPath,
-    async () => {
-      const refused = await options?.revalidate?.(frozen);
-      return refused ?? operation(frozen);
-    },
-    options?.lockSeams,
+  return withClientLocks(
+    frozen,
     spec.writerLock.suffix,
+    () => operation(frozen),
+    options,
   );
 }
 
@@ -927,15 +1004,10 @@ export async function restoreIntegrationCoordinated(
       `${frozen.resolvedPaths.detectDir} is missing; restore will not create the client home`,
     );
   }
-  return withIntegrationWriterLock(
-    frozen.resolvedPaths.configPath,
-    async () => {
-      // An undo is bound like any other confirmation, and this is the only place where that check
-      // happens with the lock held and before the snapshot, the write and the journal row.
-      const refused = await options?.revalidate?.(frozen);
-      return refused ?? run();
-    },
-    options?.lockSeams,
+  return withClientLocks(
+    frozen,
     spec.writerLock.suffix,
+    run,
+    options,
   );
 }

package/src/lib/gui-pair-capability.ts

@@ -65,6 +65,23 @@ export function canonicalHttpOrigin(value: unknown): string | null {
   }
 }
 
+/**
+ * Standalone pairing is only for this process's configured literal loopback origin.
+ * No CORS entry, public hub URL, wildcard bind, alias or client role can widen it.
+ * The CLI separately checks the attested runtime's actual port before requesting a grant.
+ */
+export function standaloneGuiPairingOrigin(config: {
+  runtimeRole?: string;
+  hostname?: string;
+  port: number;
+}): string | null {
+  if ((config.runtimeRole ?? "standalone") !== "standalone") return null;
+  const hostname = config.hostname ?? "127.0.0.1";
+  if (hostname !== "127.0.0.1" && hostname !== "::1") return null;
+  if (!Number.isInteger(config.port) || config.port < 1 || config.port > 65535) return null;
+  return new URL(`http://${hostname === "::1" ? "[::1]" : hostname}:${config.port}`).origin;
+}
+
 function capabilityPayload(
   nonce: string,
   method: string,