@ran-sh/dsh-crew 1.0.2 → 1.1.0

package/src/provider-layer-migration.mjs

@@ -0,0 +1,198 @@
+// Pure planning for promoting legacy Crew profile providers into the Harness
+// user settings layer. Planning never reads credentials or performs writes.
+
+import { classifyCredentialReference } from './credential-reference.mjs';
+
+const BUILTIN_PROVIDER_IDS = new Set(['deepseek-official']);
+
+function text(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function authorityKind(declaration) {
+  return text(declaration?.declaration_authority?.kind);
+}
+
+function providerId(declaration) {
+  return text(declaration?.id);
+}
+
+function safeCredentialRef(declaration) {
+  const ref = declaration?.credential_ref;
+  const kind = ref && typeof ref === 'object' && typeof ref.kind === 'string' ? ref.kind : 'env';
+  return classifyCredentialReference(ref, { kind }).value;
+}
+
+function safeProjection(declaration) {
+  return {
+    id: providerId(declaration),
+    display_name: text(declaration?.display_name) ?? providerId(declaration),
+    credential_ref: safeCredentialRef(declaration),
+  };
+}
+
+/**
+ * Build a bounded, secret-free migration plan from composition/base provider
+ * declarations to Harness user settings. The caller supplies declarations
+ * already obtained from the two authoritative stores.
+ */
+export function buildProviderLayerMigrationPlan({ declarations = [], catalogProviders = [], harnessDefault = null, routingReferences = [], tombstones = {}, recoveryTransactions = [], catalogEvidence = { ok: true, partial: false }, declarationEvidence = { ok: true }, lifecycleEvidence = { ok: true }, defaultEvidence = { ok: true } } = {}) {
+  const entries = Array.isArray(declarations) ? declarations : [];
+  const base = entries.filter((entry) => authorityKind(entry) === 'crew-profile' && providerId(entry));
+  const user = entries.filter((entry) => authorityKind(entry) === 'harness-settings' && providerId(entry));
+  const byBase = new Map(base.map((entry) => [providerId(entry), entry]));
+  const byUser = new Map(user.map((entry) => [providerId(entry), entry]));
+  const catalog = new Map((Array.isArray(catalogProviders) ? catalogProviders : [])
+    .map((entry) => [text(entry?.id), entry]).filter(([id]) => id));
+  const safeTombstones = tombstones && typeof tombstones === 'object' && !Array.isArray(tombstones) ? tombstones : {};
+  const safeRecoveryTransactions = Array.isArray(recoveryTransactions) ? recoveryTransactions : [];
+  const unresolvedRecovery = safeRecoveryTransactions.some((entry) => entry?.unresolved === true || !text(entry?.provider_id));
+  const pendingRecovery = safeRecoveryTransactions.length > 0;
+  const catalogUnavailable = catalogEvidence?.ok !== true || catalogEvidence?.partial === true;
+  const declarationUnavailable = declarationEvidence?.ok !== true;
+  const lifecycleUnavailable = lifecycleEvidence?.ok !== true;
+  const defaultUnavailable = defaultEvidence?.ok !== true;
+  const providers = [...new Set([...byBase.keys(), ...byUser.keys()])]
+    .filter((id) => !BUILTIN_PROVIDER_IDS.has(id))
+    .map((id) => {
+      const baseEntry = byBase.get(id) ?? null;
+      const userEntry = byUser.get(id) ?? null;
+      const catalogEntry = catalog.get(id) ?? null;
+      // Adapter ownership is a catalog fact, not a provider-name heuristic.
+      // An explicit true blocks the transition; missing metadata (including a
+      // missing catalog entry) also blocks a base-layer transition because
+      // reusing an unknown adapter id could hide the native Delete action.
+      const collision = catalogEntry?.adapter_owned === true;
+      const ownershipUnknown = baseEntry !== null && (catalogEntry === null || typeof catalogEntry.adapter_owned !== 'boolean');
+      const tombstoned = safeTombstones[id] === 'absent';
+      const recovery = safeRecoveryTransactions.find((entry) => text(entry?.provider_id) === id);
+      const blockedCode = lifecycleUnavailable
+        ? 'PROVIDER_LIFECYCLE_UNAVAILABLE'
+        : catalogUnavailable
+          ? 'MODEL_CATALOG_UNAVAILABLE'
+            : declarationUnavailable
+              ? 'PROVIDER_SOURCE_UNRESOLVED'
+              : defaultUnavailable
+                ? 'PROVIDER_DEFAULT_AUTHORITY_UNAVAILABLE'
+                : unresolvedRecovery
+              ? 'PROVIDER_DELETE_RECOVERY_UNRESOLVED'
+              : pendingRecovery
+                ? 'PROVIDER_DELETE_RECOVERY_PENDING'
+                : tombstoned
+                  ? 'PROVIDER_ALREADY_ABSENT'
+                  : null;
+      const ownershipCode = collision
+        ? 'HARNESS_PROVIDER_ID_COLLISION'
+        : ownershipUnknown ? 'HARNESS_PROVIDER_OWNERSHIP_UNAVAILABLE' : null;
+      const action = blockedCode ? 'blocked' : ownershipCode ? 'collision-review' : baseEntry && userEntry ? 'promote-existing-user' : baseEntry ? 'materialize-user' : 'none';
+      const currentNativeRemovable = userEntry !== null && baseEntry === null;
+      const migrationAction = action === 'promote-existing-user' || action === 'materialize-user';
+      return {
+        provider_id: id,
+        action,
+        current_native_removable: currentNativeRemovable,
+        target_native_removable: migrationAction ? true : currentNativeRemovable,
+        native_removable_after: migrationAction ? 'pending-verification' : ownershipCode || blockedCode ? 'unknown' : currentNativeRemovable,
+        requires_base_removal: baseEntry !== null,
+        target_user_layer: migrationAction || currentNativeRemovable,
+        source: { base: baseEntry ? safeProjection(baseEntry) : null, user: userEntry ? safeProjection(userEntry) : null },
+        credential_reference: safeCredentialRef(userEntry) ?? safeCredentialRef(baseEntry),
+        collision: ownershipCode ? { reason_code: ownershipCode, ...(ownershipCode === 'HARNESS_PROVIDER_ID_COLLISION' ? { requires_target_id: true } : {}) } : null,
+        ...(blockedCode ? { blocked_reason: blockedCode } : ownershipCode ? { blocked_reason: ownershipCode } : {}),
+        referenced_by: (Array.isArray(routingReferences) ? routingReferences : [])
+          .filter((ref) => ref?.provider === id).map((ref) => ({ provider: id, model: text(ref.model) })),
+        harness_default: harnessDefault?.provider === id,
+      };
+    });
+  return {
+    schema_version: 1,
+    kind: 'provider-layer-migration-plan',
+    requires_confirmation: providers.some((entry) => entry.action !== 'none'),
+    providers: providers.filter((entry) => entry.action !== 'none'),
+    blocked: providers.filter((entry) => entry.action === 'collision-review' || entry.action === 'blocked').map((entry) => ({
+      provider_id: entry.provider_id,
+      code: entry.blocked_reason ?? 'HARNESS_PROVIDER_ID_COLLISION',
+    })),
+  };
+}
+
+export function hasProviderLayerMigration(plan) {
+  return Array.isArray(plan?.providers) && plan.providers.length > 0;
+}
+
+const MIGRATION_STATES = Object.freeze(['PLANNED', 'APPLIED', 'RESTART_PENDING', 'VERIFYING', 'VERIFIED', 'FAILED']);
+
+function migrationCode(error, fallback = 'PROVIDER_MIGRATION_FAILED') {
+  const code = text(error?.code);
+  return code && /^[A-Z][A-Z0-9_]{1,63}$/u.test(code) ? code : fallback;
+}
+
+/**
+ * Execute one confirmed provider-layer transition through explicit adapters.
+ * Adapters own filesystem/CAS/restart details; this state machine never reads
+ * credentials and never runs for a GET or an unconfirmed request.
+ */
+export async function executeProviderLayerMigration(plan, hooks = {}, { confirm = false, deferRestart = false } = {}) {
+  if (confirm !== true) return { ok: false, state: 'BLOCKED', code: 'PROVIDER_MIGRATION_CONFIRM_REQUIRED', transaction_id: plan?.plan_id ?? null };
+  if (!plan?.plan_id || !text(plan.provider_id) || !['promote-existing-user', 'materialize-user'].includes(plan.action)) {
+    return { ok: false, state: 'BLOCKED', code: 'PROVIDER_MIGRATION_PLAN_INVALID', transaction_id: plan?.plan_id ?? null };
+  }
+  for (const name of ['backup', 'materialize', 'removeBase', 'rollback']) {
+    if (typeof hooks[name] !== 'function') return { ok: false, state: 'FAILED', code: 'PROVIDER_MIGRATION_HOOK_MISSING', transaction_id: plan.plan_id };
+  }
+  if (!deferRestart && (typeof hooks.restart !== 'function' || typeof hooks.verify !== 'function')) {
+    return { ok: false, state: 'FAILED', code: 'PROVIDER_MIGRATION_HOOK_MISSING', transaction_id: plan.plan_id };
+  }
+  let state = 'PLANNED';
+  const events = [{ state, at: new Date().toISOString() }];
+  let rollbackAttempted = false;
+  let rollbackError = null;
+  let verification = null;
+  try {
+    await hooks.backup(plan);
+    await hooks.materialize(plan);
+    await hooks.removeBase(plan);
+    state = 'APPLIED';
+    events.push({ state, at: new Date().toISOString() });
+    if (deferRestart) {
+      state = 'RESTART_PENDING';
+      events.push({ state, at: new Date().toISOString() });
+    } else {
+      const restarted = await hooks.restart(plan);
+      if (restarted?.ok === false) throw Object.assign(new Error('provider migration restart failed'), { code: restarted.code });
+      state = 'VERIFYING';
+      events.push({ state, at: new Date().toISOString() });
+      verification = await hooks.verify(plan);
+      if (verification?.nativeRemovable !== true || verification?.baseAbsent !== true || verification?.userPresent !== true) {
+        throw Object.assign(new Error('provider migration verification incomplete'), { code: 'PROVIDER_MIGRATION_VERIFY_FAILED' });
+      }
+      state = 'VERIFIED';
+      events.push({ state, at: new Date().toISOString() });
+    }
+  } catch (error) {
+    rollbackAttempted = true;
+    try { await hooks.rollback(plan); }
+    catch (rollbackErrorValue) { rollbackError = migrationCode(rollbackErrorValue, 'PROVIDER_MIGRATION_ROLLBACK_FAILED'); }
+    state = 'FAILED';
+    events.push({ state, at: new Date().toISOString() });
+    return {
+      ok: false,
+      state,
+      code: migrationCode(error),
+      transaction_id: plan.plan_id,
+      provider_id: plan.provider_id,
+      rollback_attempted: rollbackAttempted,
+      ...(rollbackError ? { rollback_error: rollbackError } : {}),
+      events,
+    };
+  }
+  return {
+    ok: state === 'VERIFIED' || state === 'RESTART_PENDING',
+    state,
+    transaction_id: plan.plan_id,
+    provider_id: plan.provider_id,
+    restart_required: true,
+    ...(verification ? { verification } : {}),
+    events,
+  };
+}

package/src/provider-lifecycle-state.mjs

@@ -2,6 +2,8 @@
 // Tombstones prevent an explicitly removed managed route from being re-seeded;
 // transactions retain only bounded audit metadata needed for recovery.
 
+import { classifyCredentialReference } from './credential-reference.mjs';
+
 const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const REVISION_PATTERN = /^[a-f0-9]{64}$/;
 const STATES = new Set([
@@ -28,7 +30,8 @@ function normalizedCredentialRefs(value) {
     const kind = typeof ref.kind === 'string' && ref.kind.trim() ? ref.kind.trim() : null;
     const name = typeof ref.name_or_handle === 'string' && ref.name_or_handle.trim() ? ref.name_or_handle.trim() : null;
     const ownership = typeof ref.ownership === 'string' && ref.ownership.trim() ? ref.ownership.trim() : null;
-    return kind && name && ownership ? { kind, name_or_handle: name, ownership } : null;
+    const safeName = classifyCredentialReference(name, { kind }).value;
+    return kind && safeName && ownership ? { kind, name_or_handle: safeName, ownership } : null;
   }).filter(Boolean).slice(0, 32);
   return refs;
 }

package/src/provider-profile-store.mjs

@@ -5,6 +5,7 @@
 // bounded, revision-checked text edits while preserving unrelated patch items.
 
 import { createHash } from 'node:crypto';
+import { classifyCredentialReference } from './credential-reference.mjs';
 
 const PROVIDER_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
@@ -98,12 +99,12 @@ function scalarField(lines, entry, field) {
     if (!match) continue;
     const value = match[1].trim();
     if (!value) return null;
-    return value.replace(/^(?:"([\\s\\S]*)"|'([\\s\\S]*)')$/, '$1$2');
+    return value.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/u, '$1$2');
   }
   return null;
 }
 
-const SENSITIVE_CREDENTIAL_FIELD = /(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password|authorization|credential|private[_-]?key|client[_-]?secret|cookie|bearer|webhook)/iu;
+const SENSITIVE_CREDENTIAL_FIELD = /(?:api[_-]?key|access[_-]?token|refresh[_-]?token|(?:^|[_-])token(?:$|[_-])|secret|password|authorization|credential|private[_-]?key|client[_-]?secret|cookie|bearer|webhook)/iu;
 const REFERENCE_FIELD_SUFFIX = /(?:env|ref|name|handle|id|file|path)$/iu;
 
 function isInlineCredentialLine(line) {
@@ -132,7 +133,8 @@ export function readProviderDeclarations(source, { file = 'profile.yml' } = {})
   if (!parsed.ok) return { ok: false, code: parsed.code };
   const declarations = parsed.entries.map((entry) => {
     const displayName = scalarField(parsed.lines, entry, 'displayName');
-    const credentialRef = scalarField(parsed.lines, entry, 'apiKeyEnv');
+    const rawCredentialRef = scalarField(parsed.lines, entry, 'apiKeyEnv');
+    const credential = classifyCredentialReference(rawCredentialRef, { kind: 'env' });
     return {
       id: entry.id,
       display_name: displayName ?? entry.id,
@@ -140,12 +142,199 @@ export function readProviderDeclarations(source, { file = 'profile.yml' } = {})
       ownership: 'crew-managed-profile',
       file,
       declaration_authority: { kind: 'crew-profile', locator: `llm-pi-ai.config.providers.${entry.id}` },
-      ...(credentialRef ? { credential_ref: credentialRef } : {}),
+      ...(credential.value ? { credential_ref: credential.value } : {}),
+      ...(credential.redacted ? { credential_status: 'present-redacted' } : {}),
     };
   });
   return { ok: true, declarations };
 }
 
+function unquoteScalar(value) {
+  return typeof value === 'string'
+    ? value.trim().replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/u, '$1$2')
+    : null;
+}
+
+function providerModels(lines, entry) {
+  const modelsLine = lines.findIndex((line, index) => index >= entry.start && index < entry.end && /^\s+models:\s*$/u.test(line));
+  if (modelsLine < 0) return [];
+  const modelsIndent = (lines[modelsLine].match(/^\s*/u) ?? [''])[0].length;
+  const models = [];
+  const seenModelIds = new Set();
+  for (let index = modelsLine + 1; index < entry.end; index += 1) {
+    const line = lines[index];
+    if (!nonBlank(line)) continue;
+    const indent = indentOf(line);
+    if (indent <= modelsIndent) break;
+    const match = line.match(/^\s*-\s+id:\s*(.*?)\s*$/u);
+    if (!match) continue;
+    const id = unquoteScalar(match[1]);
+    if (!id || id.length > 256 || /[\r\n]/u.test(id) || seenModelIds.has(id)) return null;
+    seenModelIds.add(id);
+    const modelIndent = indentOf(line);
+    const model = { id };
+    const seenFields = new Set(['id']);
+    for (let child = index + 1; child < entry.end; child += 1) {
+      const childLine = lines[child];
+      if (!nonBlank(childLine)) continue;
+      const childIndent = indentOf(childLine);
+      if (childIndent <= modelsIndent || /^\s*-\s+id:\s*/u.test(childLine)) break;
+      if (childIndent !== modelIndent + 2) continue;
+      const fieldMatch = childLine.match(/^\s+([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/u);
+      if (!fieldMatch) return null;
+      const [, field, rawValue] = fieldMatch;
+      if (seenFields.has(field) || !['name', 'contextWindow', 'maxTokens', 'input', 'reasoningEfforts', 'compat'].includes(field)) return null;
+      seenFields.add(field);
+      if (field === 'name') {
+        const value = unquoteScalar(rawValue);
+        if (!value || value.length > 256 || /[\r\n]/u.test(value)) return null;
+        model.name = value;
+      } else if (field === 'contextWindow' || field === 'maxTokens') {
+        const value = Number(unquoteScalar(rawValue));
+        if (!Number.isSafeInteger(value) || value <= 0) return null;
+        model[field === 'contextWindow' ? 'context_window' : 'max_tokens'] = value;
+      } else if (field === 'input') {
+        const value = unquoteScalar(rawValue);
+        if (!/^\[[^\]\r\n]*\]$/u.test(value ?? '')) return null;
+        const modalities = value.slice(1, -1).split(',').map((item) => item.trim()).filter(Boolean);
+        if (modalities.some((item) => !['text', 'image'].includes(item))) return null;
+        model.input = [...new Set(modalities)];
+      } else if (field === 'reasoningEfforts') {
+        const efforts = {};
+        for (let nested = child + 1; nested < entry.end; nested += 1) {
+          const nestedLine = lines[nested];
+          if (!nonBlank(nestedLine)) continue;
+          const nestedIndent = indentOf(nestedLine);
+          if (nestedIndent <= childIndent) break;
+          if (nestedIndent !== childIndent + 2) return null;
+          const effortMatch = nestedLine.match(/^\s+([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/u);
+          if (!effortMatch || Object.hasOwn(efforts, effortMatch[1])) return null;
+          const effortValue = unquoteScalar(effortMatch[2]);
+          if (effortValue !== null && effortValue !== 'null' && effortValue !== '~' && (effortValue.length > 256 || /[\r\n]/u.test(effortValue))) return null;
+          efforts[effortMatch[1]] = effortValue === null || effortValue === 'null' || effortValue === '~' ? null : effortValue;
+        }
+        model.reasoning_efforts = efforts;
+      } else if (field === 'compat') {
+        if (rawValue.trim() !== '{}') return null;
+        model.compat = {};
+      }
+    }
+    models.push(model);
+  }
+  return models.slice(0, 256);
+}
+
+/**
+ * Return the bounded, non-secret fields needed to materialize one profile
+ * provider in Harness settings. This is read-only and intentionally separate
+ * from readProviderDeclarations so existing provenance consumers stay stable.
+ */
+export function readProviderMaterialization(source, { providerId, file = 'profile.yml' } = {}) {
+  const parsed = parseProviderMap(source);
+  if (!parsed.ok) return { ok: false, code: parsed.code };
+  const entry = parsed.entries.find((candidate) => candidate.id === providerId);
+  if (!entry) return { ok: false, code: 'PROVIDER_NOT_FOUND' };
+  const providerIndent = indentOf(parsed.lines[entry.start]);
+  const directScalarField = (field) => {
+    const pattern = new RegExp(`^\\s{${providerIndent + 2}}${field}:\\s*(.*?)\\s*$`);
+    for (const line of parsed.lines.slice(entry.start, entry.end)) {
+      const match = line.match(pattern);
+      if (match) return unquoteScalar(match[1]);
+    }
+    return null;
+  };
+  const credentialRef = directScalarField('apiKeyEnv');
+  const credential = classifyCredentialReference(credentialRef, { kind: 'env' });
+  if (credential.redacted) return { ok: false, code: 'PROVIDER_CREDENTIAL_REFERENCE_UNSAFE' };
+  const readBounded = (field, max = 2048) => {
+    const value = directScalarField(field);
+    return value && value.length <= max && !/[\r\n]/u.test(value) ? value : null;
+  };
+  const knownFields = new Set(['displayName', 'apiKeyEnv', 'api', 'baseURL', 'models']);
+  const directFields = parsed.lines.slice(entry.start + 1, entry.end)
+    .filter((line) => nonBlank(line) && indentOf(line) === providerIndent + 2)
+    .map((line) => line.match(/^\s+([A-Za-z][A-Za-z0-9_-]*):/u)?.[1])
+    .filter(Boolean);
+  const unknownFields = directFields.filter((field) => !knownFields.has(field));
+  if (unknownFields.length > 0 || new Set(directFields).size !== directFields.length) return { ok: false, code: 'PROVIDER_MATERIALIZATION_UNSUPPORTED_FIELDS' };
+  const baseUrl = readBounded('baseURL');
+  if (baseUrl) {
+    try {
+      const parsedUrl = new URL(baseUrl);
+      if (!['http:', 'https:'].includes(parsedUrl.protocol) || parsedUrl.username || parsedUrl.password || parsedUrl.search || parsedUrl.hash || /[?#]/u.test(baseUrl) || !parsedUrl.hostname) {
+        return { ok: false, code: 'PROVIDER_BASE_URL_UNSAFE' };
+      }
+    } catch { return { ok: false, code: 'PROVIDER_BASE_URL_UNSAFE' }; }
+  }
+  const api = readBounded('api', 128);
+  if (api && !/^[A-Za-z][A-Za-z0-9._-]{0,127}$/u.test(api) || /^(?:sk|pk|rk|token|secret)[_-]/iu.test(api ?? '')) return { ok: false, code: 'PROVIDER_API_SCHEMA_UNSUPPORTED' };
+  const provider = {
+    id: entry.id,
+    display_name: readBounded('displayName', 256) ?? entry.id,
+    ...(credential.value ? { credential_ref: credential.value } : {}),
+    ...(api ? { api } : {}),
+    ...(baseUrl ? { base_url: baseUrl } : {}),
+    models: providerModels(parsed.lines, entry),
+    source_file: file,
+  };
+  if (provider.models === null) return { ok: false, code: 'PROVIDER_MODEL_SCHEMA_UNSUPPORTED' };
+  return { ok: true, provider };
+}
+
+function yamlScalar(value, max = 2048) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\r\n]/u.test(value)) return null;
+  return JSON.stringify(value.trim());
+}
+
+/** Re-add one safe provider projection during an explicit migration rollback. */
+export function addProviderDeclaration(source, { provider, expectedRevision } = {}) {
+  const currentRevision = typeof source === 'string' ? sha256(source) : null;
+  if (expectedRevision !== undefined && expectedRevision !== currentRevision) return { ok: false, code: 'PROVIDER_PROFILE_CHANGED', revision: currentRevision };
+  if (!provider || typeof provider !== 'object' || Array.isArray(provider) || !PROVIDER_ID.test(provider.id ?? '')) return { ok: false, code: 'PROVIDER_MATERIALIZATION_INVALID', revision: currentRevision };
+  const parsed = parseProviderMap(source);
+  if (!parsed.ok) return { ok: false, code: parsed.code, revision: currentRevision };
+  if (parsed.entries.some((entry) => entry.id === provider.id)) return { ok: false, code: 'PROVIDER_PROFILE_PROVIDER_EXISTS', revision: currentRevision };
+  const displayName = yamlScalar(provider.display_name ?? provider.id, 256);
+  if (!displayName) return { ok: false, code: 'PROVIDER_MATERIALIZATION_INVALID', revision: currentRevision };
+  const providerIndent = indentOf(parsed.lines[parsed.providersLine]) + 2;
+  const fieldIndent = providerIndent + 2;
+  const lines = [`${' '.repeat(providerIndent)}${provider.id}:`, `${' '.repeat(fieldIndent)}displayName: ${displayName}`];
+  const api = yamlScalar(provider.api, 128);
+  const baseUrl = yamlScalar(provider.base_url, 2048);
+  const credential = provider.credential_ref ? classifyCredentialReference(provider.credential_ref, { kind: 'env' }).value : null;
+  if (provider.credential_ref && !credential) return { ok: false, code: 'PROVIDER_CREDENTIAL_REFERENCE_UNSAFE', revision: currentRevision };
+  if (api) lines.push(`${' '.repeat(fieldIndent)}api: ${api}`);
+  if (baseUrl) lines.push(`${' '.repeat(fieldIndent)}baseURL: ${baseUrl}`);
+  if (credential) lines.push(`${' '.repeat(fieldIndent)}apiKeyEnv: ${credential}`);
+  const models = Array.isArray(provider.models) ? provider.models.filter((model) => model && typeof model.id === 'string' && model.id.trim() && model.id.length <= 256).slice(0, 256) : [];
+  if (models.length > 0) {
+    lines.push(`${' '.repeat(fieldIndent)}models:`);
+    for (const model of models) {
+      const id = yamlScalar(model.id, 256);
+      if (!id) continue;
+      lines.push(`${' '.repeat(fieldIndent + 2)}- id: ${id}`);
+      const name = yamlScalar(model.name, 256);
+      if (name) lines.push(`${' '.repeat(fieldIndent + 4)}name: ${name}`);
+      if (Number.isSafeInteger(model.context_window) && model.context_window > 0) lines.push(`${' '.repeat(fieldIndent + 4)}contextWindow: ${model.context_window}`);
+      if (Number.isSafeInteger(model.max_tokens) && model.max_tokens > 0) lines.push(`${' '.repeat(fieldIndent + 4)}maxTokens: ${model.max_tokens}`);
+      if (Array.isArray(model.input) && model.input.every((value) => value === 'text' || value === 'image')) lines.push(`${' '.repeat(fieldIndent + 4)}input: [${[...new Set(model.input)].join(', ')}]`);
+      if (model.reasoning_efforts && typeof model.reasoning_efforts === 'object' && !Array.isArray(model.reasoning_efforts)) {
+        lines.push(`${' '.repeat(fieldIndent + 4)}reasoningEfforts:`);
+        for (const [key, value] of Object.entries(model.reasoning_efforts)) if (/^[A-Za-z][A-Za-z0-9_-]*$/u.test(key) && (value === null || yamlScalar(value, 256))) lines.push(`${' '.repeat(fieldIndent + 6)}${key}: ${value === null ? 'null' : yamlScalar(value, 256)}`);
+      }
+      if (model.compat && typeof model.compat === 'object' && !Array.isArray(model.compat) && Object.keys(model.compat).length === 0) lines.push(`${' '.repeat(fieldIndent + 4)}compat: {}`);
+    }
+  }
+  const nextLines = [...parsed.lines];
+  if (/^\s+providers:\s*\{\s*\}\s*$/u.test(nextLines[parsed.providersLine])) {
+    nextLines[parsed.providersLine] = `${' '.repeat(indentOf(nextLines[parsed.providersLine]))}providers:`;
+  }
+  nextLines.splice(parsed.blockEnd, 0, ...lines);
+  const newline = source.includes('\r\n') ? '\r\n' : '\n';
+  const text = nextLines.join(newline);
+  return { ok: true, text, added: provider.id, revision: sha256(text) };
+}
+
 /**
  * Remove provider declarations from a known profile patch after an optional
  * content-revision check. The returned text is safe to write atomically by the

package/src/provider-settings-store.mjs

@@ -3,6 +3,8 @@
 // credential values are never deserialized or returned.
 
 import { createHash } from 'node:crypto';
+import { classifyCredentialReference } from './credential-reference.mjs';
+import { readProviderMaterialization } from './provider-profile-store.mjs';
 
 const PROVIDER_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
 
@@ -16,7 +18,7 @@ function scalarField(lines, entry, field) {
     if (!match) continue;
     const value = match[1].trim();
     if (!value) return null;
-    return value.replace(/^(?:"([\\s\\S]*)"|'([\\s\\S]*)')$/u, '$1$2');
+    return value.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/u, '$1$2');
   }
   return null;
 }
@@ -78,7 +80,7 @@ function parseProviderMap(source) {
   return { ok: true, lines, llmStart, blockEnd, providersLine, providersBlockEnd, entries };
 }
 
-const SENSITIVE_CREDENTIAL_FIELD = /(?:api[_-]?key|access[_-]?token|refresh[_-]?token|token|secret|password|authorization|credential|private[_-]?key|client[_-]?secret|cookie|bearer|webhook)/iu;
+const SENSITIVE_CREDENTIAL_FIELD = /(?:api[_-]?key|access[_-]?token|refresh[_-]?token|(?:^|[_-])token(?:$|[_-])|secret|password|authorization|credential|private[_-]?key|client[_-]?secret|cookie|bearer|webhook)/iu;
 const REFERENCE_FIELD_SUFFIX = /(?:env|ref|name|handle|id|file|path)$/iu;
 
 function isInlineCredentialLine(line) {
@@ -114,26 +116,100 @@ export function readProviderSettingsDeclarations(source, { file = 'harness/setti
   return {
     ok: true,
     declarations: parsed.entries.map((entry) => {
-      const credentialRef = scalarField(parsed.lines, entry, 'apiKeyEnv');
+      const rawCredentialRef = scalarField(parsed.lines, entry, 'apiKeyEnv');
+      const credential = classifyCredentialReference(rawCredentialRef, { kind: 'env' });
       return {
         id: entry.id,
         display_name: scalarField(parsed.lines, entry, 'displayName') ?? entry.id,
-        origin: 'profile-managed',
-        ownership: 'crew-managed-profile',
+        // settings.yaml is the Harness user layer. Crew profile/base
+        // declarations are reported separately by provider-profile-store.
+        origin: 'dynamic',
+        ownership: 'dynamic-user',
         file,
         declaration_authority: { kind: 'harness-settings', locator: `llm-pi-ai.providers.${entry.id}` },
-        ...(credentialRef ? { credential_ref: { kind: 'env', name_or_handle: credentialRef, ownership: 'unknown' } } : {}),
+        ...(credential.value ? { credential_ref: { kind: 'env', name_or_handle: credential.value, ownership: 'unknown' } } : {}),
+        ...(credential.redacted ? { credential_status: 'present-redacted' } : {}),
       };
     }),
   };
 }
 
+/** Return the same bounded provider projection as the profile parser, adapted
+ * to the Harness settings indentation. This is used only for rollback CAS and
+ * never exposes credential values. */
+export function readProviderSettingsMaterialization(source, { providerId, file = 'harness/settings.yaml' } = {}) {
+  const parsed = parseProviderMap(source);
+  if (!parsed.ok) return { ok: false, code: parsed.code };
+  const entry = parsed.entries.find((candidate) => candidate.id === providerId);
+  if (!entry) return { ok: false, code: 'PROVIDER_NOT_FOUND' };
+  const block = parsed.lines.slice(entry.start, entry.end).map((line) => `  ${line}`);
+  const synthetic = ['- id: llm-pi-ai', '  config:', '    providers:', ...block, ''].join('\n');
+  const result = readProviderMaterialization(synthetic, { providerId, file });
+  return result.ok ? { ...result, provider: { ...result.provider, source_file: file } } : result;
+}
+
 export function readHarnessDefault(source) {
   const parsed = parseDefaultModel(source);
   if (!parsed.ok) return { ok: false, code: parsed.code };
   return { ok: true, provider: parsed.provider, model: parsed.model, locator: 'agent-default-model' };
 }
 
+function yamlScalar(value, max = 2048) {
+  if (typeof value !== 'string' || !value.trim() || value.length > max || /[\r\n]/u.test(value)) return null;
+  return JSON.stringify(value.trim());
+}
+
+/**
+ * Add one already-sanitized provider projection to the Harness user layer.
+ * The operation is pure and revision-bound; callers perform the atomic write.
+ */
+export function addProviderSettings(source, { provider, expectedRevision } = {}) {
+  const currentRevision = typeof source === 'string' ? sha256(source) : null;
+  if (expectedRevision !== undefined && expectedRevision !== currentRevision) return { ok: false, code: 'PROVIDER_SETTINGS_CHANGED', revision: currentRevision };
+  if (!provider || typeof provider !== 'object' || Array.isArray(provider) || typeof provider.id !== 'string' || !PROVIDER_ID.test(provider.id)) {
+    return { ok: false, code: 'PROVIDER_MATERIALIZATION_INVALID', revision: currentRevision };
+  }
+  const parsed = parseProviderMap(source);
+  if (!parsed.ok) return { ok: false, code: parsed.code, revision: currentRevision };
+  if (parsed.entries.some((entry) => entry.id === provider.id)) return { ok: false, code: 'PROVIDER_SETTINGS_PROVIDER_EXISTS', revision: currentRevision };
+  const displayName = yamlScalar(provider.display_name ?? provider.id, 256);
+  if (!displayName) return { ok: false, code: 'PROVIDER_MATERIALIZATION_INVALID', revision: currentRevision };
+  const lines = [`    ${provider.id}:`, `      displayName: ${displayName}`];
+  const api = yamlScalar(provider.api, 128);
+  const baseUrl = yamlScalar(provider.base_url, 2048);
+  const credential = provider.credential_ref ? classifyCredentialReference(provider.credential_ref, { kind: 'env' }).value : null;
+  if (provider.credential_ref && !credential) return { ok: false, code: 'PROVIDER_CREDENTIAL_REFERENCE_UNSAFE', revision: currentRevision };
+  if (api) lines.push(`      api: ${api}`);
+  if (baseUrl) lines.push(`      baseURL: ${baseUrl}`);
+  if (credential) lines.push(`      apiKeyEnv: ${credential}`);
+  const models = Array.isArray(provider.models) ? provider.models.filter((model) => model && typeof model.id === 'string' && model.id.trim() && model.id.length <= 256).slice(0, 256) : [];
+  if (models.length > 0) {
+    lines.push('      models:');
+    for (const model of models) {
+      const id = yamlScalar(model.id, 256);
+      if (!id) continue;
+      lines.push(`        - id: ${id}`);
+      const name = yamlScalar(model.name, 256);
+      if (name) lines.push(`          name: ${name}`);
+      if (Number.isSafeInteger(model.context_window) && model.context_window > 0) lines.push(`          contextWindow: ${model.context_window}`);
+      if (Number.isSafeInteger(model.max_tokens) && model.max_tokens > 0) lines.push(`          maxTokens: ${model.max_tokens}`);
+      if (Array.isArray(model.input) && model.input.every((value) => value === 'text' || value === 'image')) lines.push(`          input: [${[...new Set(model.input)].join(', ')}]`);
+      if (model.reasoning_efforts && typeof model.reasoning_efforts === 'object' && !Array.isArray(model.reasoning_efforts)) {
+        lines.push('          reasoningEfforts:');
+        for (const [key, value] of Object.entries(model.reasoning_efforts)) if (/^[A-Za-z][A-Za-z0-9_-]*$/u.test(key) && (value === null || yamlScalar(value, 256))) lines.push(`            ${key}: ${value === null ? 'null' : yamlScalar(value, 256)}`);
+      }
+      if (model.compat && typeof model.compat === 'object' && !Array.isArray(model.compat) && Object.keys(model.compat).length === 0) lines.push('          compat: {}');
+    }
+  }
+  const nextLines = [...parsed.lines];
+  const insertAt = parsed.blockEnd;
+  if (/^ {2}providers:\s*\{\s*\}\s*$/u.test(nextLines[parsed.providersLine])) nextLines[parsed.providersLine] = '  providers:';
+  nextLines.splice(insertAt, 0, ...lines);
+  const newline = source.includes('\r\n') ? '\r\n' : '\n';
+  const text = nextLines.join(newline);
+  return { ok: true, text, added: provider.id, revision: sha256(text) };
+}
+
 export function replaceHarnessDefault(source, { provider, model, expectedRevision } = {}) {
   const currentRevision = typeof source === 'string' ? sha256(source) : null;
   if (expectedRevision !== undefined && expectedRevision !== currentRevision) return { ok: false, code: 'PROVIDER_SETTINGS_CHANGED', revision: currentRevision };

package/src/provider-store-lock.mjs

@@ -0,0 +1,67 @@
+// Persistent token-fenced lock shared by every lifecycle operation that can
+// mutate the Harness profile/settings stores. A stale lock is reclaimed only
+// while a serialized claim is held; malformed metadata fails closed.
+
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, resolve as resolvePath } from 'node:path';
+
+function safeToken(value) { return typeof value === 'string' && /^[A-Za-z0-9-]{16,128}$/u.test(value); }
+function readOwner(file) {
+  try {
+    const owner = JSON.parse(readFileSync(file, 'utf8'));
+    if (!owner || typeof owner !== 'object' || Array.isArray(owner) || !Number.isInteger(owner.pid) || owner.pid <= 0 || !safeToken(owner.token)) return { ok: false, malformed: true };
+    return { ok: true, owner };
+  } catch { return { ok: false, malformed: true }; }
+}
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (error) { return error?.code === 'EPERM'; }
+}
+
+export async function acquireProviderStoreLock(file) {
+  if (typeof file !== 'string' || !file.trim()) throw Object.assign(new Error('provider store lock path is required'), { code: 'PROVIDER_STORE_LOCK_UNAVAILABLE' });
+  const lockFile = resolvePath(file);
+  mkdirSync(dirname(lockFile), { recursive: true });
+  const claimFile = `${lockFile}.claim`;
+  const token = randomUUID();
+  let claimed = false;
+  try {
+    try { mkdirSync(claimFile); claimed = true; }
+    catch (error) { throw Object.assign(new Error('provider store lock is busy'), { code: error?.code === 'EEXIST' ? 'PROVIDER_STORE_LOCK_BUSY' : 'PROVIDER_STORE_LOCK_UNAVAILABLE' }); }
+    while (true) {
+      try {
+        writeFileSync(lockFile, JSON.stringify({ pid: process.pid, token, created_at: new Date().toISOString() }) + '\n', { flag: 'wx' });
+        return {
+          ok: true,
+          token,
+          release: async () => {
+            const current = readOwner(lockFile);
+            if (current.ok && current.owner.token === token) rmSync(lockFile, { force: true });
+          },
+        };
+      } catch (error) {
+        if (error?.code !== 'EEXIST') throw Object.assign(new Error('provider store lock is unavailable'), { code: 'PROVIDER_STORE_LOCK_UNAVAILABLE' });
+        const current = readOwner(lockFile);
+        if (!current.ok) throw Object.assign(new Error('provider store lock metadata is invalid'), { code: 'PROVIDER_STORE_LOCK_BUSY' });
+        if (processAlive(current.owner.pid)) throw Object.assign(new Error('provider store lock is busy'), { code: 'PROVIDER_STORE_LOCK_BUSY' });
+        rmSync(lockFile, { force: true });
+      }
+    }
+  } finally { if (claimed) rmSync(claimFile, { recursive: true, force: true }); }
+}
+
+export async function recoverProviderStoreLock(file, { confirm = false } = {}) {
+  if (confirm !== true) return { ok: false, code: 'PROVIDER_STORE_LOCK_CONFIRM_REQUIRED' };
+  if (typeof file !== 'string' || !file.trim()) return { ok: false, code: 'PROVIDER_STORE_LOCK_UNAVAILABLE' };
+  const lockFile = resolvePath(file);
+  const claimFile = `${lockFile}.claim`;
+  try { mkdirSync(dirname(lockFile), { recursive: true }); mkdirSync(claimFile); }
+  catch (error) { return { ok: false, code: error?.code === 'EEXIST' ? 'PROVIDER_STORE_LOCK_BUSY' : 'PROVIDER_STORE_LOCK_UNAVAILABLE' }; }
+  try {
+    if (!existsSync(lockFile)) return { ok: true, recovered: false };
+    const current = readOwner(lockFile);
+    if (current.ok && processAlive(current.owner.pid)) return { ok: false, code: 'PROVIDER_STORE_LOCK_BUSY' };
+    rmSync(lockFile, { force: true });
+    return { ok: true, recovered: true };
+  } finally { rmSync(claimFile, { recursive: true, force: true }); }
+}