Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

99.0 KB
Raw Blame
import mongoose from 'mongoose';
import { logger, createModels } from '..';
import { MongoMemoryServer } from 'mongodb-memory-server';
import {
  SystemRoles,
  ResourceType,
  AccessRoleIds,
  PrincipalType,
  PermissionBits,
  SKILL_BODY_MAX_LENGTH,
} from 'librechat-data-provider';
import {
  partitionIssues,
  validateSkillName,
  validateSkillDescription,
  validateSkillFrontmatter,
  getCanonicalSkillFrontmatterKey,
  normalizeSkillFrontmatterKeys,
  validateAlwaysApply,
  validateRelativePath,
  inferSkillFileCategory,
  filterExistingSkillIds,
  deriveStructuredFrontmatterFields,
} from './skill';
import { createSkillLifecycleMethods } from './skillLifecycle';
import { createAclEntryMethods } from './aclEntry';
import { createMethods } from './index';

logger.silent = true;

type LeanUser = {
  _id: mongoose.Types.ObjectId;
  name?: string;
  email: string;
  role?: string;
};

let Skill: mongoose.Model<unknown>;
let SkillFile: mongoose.Model<unknown>;
let AclEntry: mongoose.Model<unknown>;
let AccessRole: mongoose.Model<unknown>;
let User: mongoose.Model<unknown>;
let methods: ReturnType<typeof createMethods>;
let aclMethods: ReturnType<typeof createAclEntryMethods>;
let owner: LeanUser;
let other: LeanUser;

let mongoServer: MongoMemoryServer;

beforeAll(async () => {
  mongoServer = await MongoMemoryServer.create();
  await mongoose.connect(mongoServer.getUri());

  createModels(mongoose);
  Skill = mongoose.models.Skill;
  SkillFile = mongoose.models.SkillFile;
  AclEntry = mongoose.models.AclEntry;
  AccessRole = mongoose.models.AccessRole;
  User = mongoose.models.User;

  methods = createMethods(mongoose, {
    removeAllPermissions: async ({ resourceType, resourceId }) => {
      await AclEntry.deleteMany({ resourceType, resourceId });
    },
  });
  aclMethods = createAclEntryMethods(mongoose);

  await AccessRole.create({
    accessRoleId: AccessRoleIds.SKILL_OWNER,
    name: 'Owner',
    description: 'Full control over skills',
    resourceType: ResourceType.SKILL,
    permBits:
      PermissionBits.VIEW | PermissionBits.EDIT | PermissionBits.DELETE | PermissionBits.SHARE,
  });
  await AccessRole.create({
    accessRoleId: AccessRoleIds.SKILL_EDITOR,
    name: 'Editor',
    description: 'Can view and edit skills',
    resourceType: ResourceType.SKILL,
    permBits: PermissionBits.VIEW | PermissionBits.EDIT,
  });
  await AccessRole.create({
    accessRoleId: AccessRoleIds.SKILL_VIEWER,
    name: 'Viewer',
    description: 'Can view skills',
    resourceType: ResourceType.SKILL,
    permBits: PermissionBits.VIEW,
  });

  owner = (
    await User.create({
      name: 'Skill Owner',
      email: '[email protected]',
      role: SystemRoles.USER,
    })
  ).toObject() as unknown as LeanUser;
  other = (
    await User.create({
      name: 'Other User',
      email: '[email protected]',
      role: SystemRoles.USER,
    })
  ).toObject() as unknown as LeanUser;
});

afterAll(async () => {
  await mongoose.disconnect();
  await mongoServer.stop();
});

afterEach(async () => {
  await Skill.deleteMany({});
  await SkillFile.deleteMany({});
  await mongoose.models.SkillUploadIntent.deleteMany({});
  await AclEntry.deleteMany({});
  await mongoose.models.Agent.deleteMany({});
});

function makeAgentDoc(skillIds: string[], overrides: Record<string, unknown> = {}) {
  return {
    id: `agent_${new mongoose.Types.ObjectId().toString()}`,
    name: 'Allowlist Agent',
    provider: 'openai',
    model: 'gpt-4',
    author: owner._id,
    skills: skillIds,
    skills_enabled: true,
    ...overrides,
  };
}

async function grantOwner(resourceId: mongoose.Types.ObjectId | string) {
  const role = (await AccessRole.findOne({ accessRoleId: AccessRoleIds.SKILL_OWNER }).lean()) as {
    _id: mongoose.Types.ObjectId;
    permBits: number;
  } | null;
  if (!role) throw new Error('SKILL_OWNER role not seeded');
  return aclMethods.grantPermission(
    PrincipalType.USER,
    owner._id,
    ResourceType.SKILL,
    resourceId,
    role.permBits,
    owner._id,
    undefined,
    role._id,
  );
}

function makeSkillInput(overrides: Record<string, unknown> = {}) {
  return {
    name: 'demo-skill',
    description: 'A small demo skill used in tests.',
    body: '# Demo\n\nBody content',
    frontmatter: { name: 'demo-skill', description: 'A small demo skill used in tests.' },
    author: owner._id,
    authorName: owner.name ?? 'Skill Owner',
    ...overrides,
  };
}

describe('Skill schema indexes', () => {
  it('supports GitHub sync source metadata lookups', () => {
    const indexSpecs = Skill.schema.indexes().map(([fields]) => fields);

    expect(indexSpecs).toContainEqual({
      source: 1,
      'sourceMetadata.upstreamId': 1,
      tenantId: 1,
    });
    expect(indexSpecs).toContainEqual({
      source: 1,
      'sourceMetadata.sourceId': 1,
      tenantId: 1,
    });
  });
});

describe('skill validation helpers', () => {
  it('rejects names starting with reserved brand prefixes', () => {
    expect(validateSkillName('anthropic-helper').some((i) => i.code === 'RESERVED_PREFIX')).toBe(
      true,
    );
    expect(validateSkillName('claude-helper').some((i) => i.code === 'RESERVED_PREFIX')).toBe(true);
  });

  it('allows names that merely contain reserved words as substrings', () => {
    expect(validateSkillName('research-anthropic-helper')).toEqual([]);
    expect(validateSkillName('about-claude')).toEqual([]);
  });

  it('rejects reserved CLI command names', () => {
    for (const word of ['help', 'clear', 'compact', 'model', 'exit', 'quit', 'settings']) {
      expect(validateSkillName(word).some((i) => i.code === 'RESERVED_WORD')).toBe(true);
    }
  });

  it('rejects non-kebab-case names', () => {
    expect(validateSkillName('My Skill').some((i) => i.code === 'INVALID_FORMAT')).toBe(true);
    expect(validateSkillName('UPPER').some((i) => i.code === 'INVALID_FORMAT')).toBe(true);
  });

  it('rejects names longer than 64 chars', () => {
    const long = 'a'.repeat(65);
    expect(validateSkillName(long).some((i) => i.code === 'TOO_LONG')).toBe(true);
  });

  it('accepts valid kebab-case names', () => {
    expect(validateSkillName('my-skill-1')).toEqual([]);
  });

  it('requires description', () => {
    expect(validateSkillDescription('').some((i) => i.code === 'REQUIRED')).toBe(true);
    expect(validateSkillDescription('   ').some((i) => i.code === 'REQUIRED')).toBe(true);
  });

  it('rejects description over 1024 chars', () => {
    expect(validateSkillDescription('x'.repeat(1025)).some((i) => i.code === 'TOO_LONG')).toBe(
      true,
    );
  });

  it('emits a warning (not an error) for short descriptions', () => {
    const issues = validateSkillDescription('too short');
    const warnings = issues.filter((i) => i.severity === 'warning' && i.code === 'TOO_SHORT');
    const errors = issues.filter((i) => i.severity !== 'warning');
    expect(warnings.length).toBe(1);
    expect(errors.length).toBe(0);
  });

  it('does not warn for descriptions at or above the threshold', () => {
    expect(
      validateSkillDescription('This description is comfortably over the threshold length.'),
    ).toEqual([]);
  });

  it('rejects path traversal', () => {
    expect(validateRelativePath('../evil').some((i) => i.code === 'TRAVERSAL')).toBe(true);
    expect(validateRelativePath('scripts/../../etc').some((i) => i.code === 'TRAVERSAL')).toBe(
      true,
    );
  });

  it('rejects absolute paths', () => {
    expect(validateRelativePath('/abs/path').some((i) => i.code === 'ABSOLUTE_PATH')).toBe(true);
  });

  it('rejects SKILL.md explicitly', () => {
    expect(validateRelativePath('SKILL.md').some((i) => i.code === 'RESERVED')).toBe(true);
  });

  it('accepts well-formed relative paths', () => {
    expect(validateRelativePath('scripts/parse.sh')).toEqual([]);
    expect(validateRelativePath('references/schema.md')).toEqual([]);
  });

  it('infers category from top-level prefix', () => {
    expect(inferSkillFileCategory('scripts/parse.sh')).toBe('script');
    expect(inferSkillFileCategory('references/notes.md')).toBe('reference');
    expect(inferSkillFileCategory('assets/image.png')).toBe('asset');
    expect(inferSkillFileCategory('readme.txt')).toBe('other');
  });

  describe('validateSkillFrontmatter', () => {
    it('canonicalizes recognized keys without rewriting unknown keys', () => {
      expect(getCanonicalSkillFrontmatterKey('Allowed-Tools')).toBe('allowed-tools');
      expect(getCanonicalSkillFrontmatterKey('ALWAYSAPPLY')).toBe('alwaysApply');
      expect(getCanonicalSkillFrontmatterKey('customConfig')).toBeUndefined();
      expect(
        normalizeSkillFrontmatterKeys({
          'Allowed-Tools': ['execute_code'],
          customConfig: { mode: 'strict' },
        }),
      ).toEqual({
        frontmatter: {
          'allowed-tools': ['execute_code'],
          customConfig: { mode: 'strict' },
        },
      });
    });

    it('rejects case-colliding recognized keys', () => {
      const frontmatter = {
        'allowed-tools': ['read_file'],
        'Allowed-Tools': ['execute_code'],
      };

      expect(normalizeSkillFrontmatterKeys(frontmatter)).toEqual({
        error:
          'Recognized frontmatter keys "allowed-tools" and "Allowed-Tools" both resolve to "allowed-tools"',
      });
      expect(validateSkillFrontmatter(frontmatter)).toEqual([
        expect.objectContaining({ field: 'frontmatter', code: 'DUPLICATE_KEY' }),
      ]);
    });

    it('accepts an undefined or empty frontmatter', () => {
      expect(validateSkillFrontmatter(undefined)).toEqual([]);
      expect(validateSkillFrontmatter(null)).toEqual([]);
      expect(validateSkillFrontmatter({})).toEqual([]);
    });

    it('rejects non-object frontmatter', () => {
      expect(validateSkillFrontmatter('not an object').some((i) => i.code === 'INVALID_TYPE')).toBe(
        true,
      );
      expect(validateSkillFrontmatter([]).some((i) => i.code === 'INVALID_TYPE')).toBe(true);
    });

    it('warns about unknown keys instead of rejecting them', () => {
      const issues = validateSkillFrontmatter({ 'not-a-real-key': 'value' });
      expect(issues).toEqual([
        expect.objectContaining({
          field: 'frontmatter.not-a-real-key',
          code: 'UNKNOWN_KEY',
          severity: 'warning',
        }),
      ]);
      expect(partitionIssues(issues).errors).toEqual([]);
    });

    it('still bounds the value of an unknown key', () => {
      /* The key is tolerated, the payload is not: an unrecognized key is
         persisted, so it stays inside the same limits as every other key. */
      const deep = { a: { b: { c: { d: { e: { f: 'too deep' } } } } } };
      const issues = validateSkillFrontmatter({ 'not-a-real-key': deep });

      expect(issues.some((i) => i.code === 'UNKNOWN_KEY' && i.severity === 'warning')).toBe(true);
      expect(
        partitionIssues(issues).errors.some(
          (i) => i.code === 'INVALID_SHAPE' && i.field === 'frontmatter.not-a-real-key',
        ),
      ).toBe(true);
    });

    it('rejects non-plain object values under unknown keys', () => {
      const issues = validateSkillFrontmatter({ created: new Date('2026-08-11T00:00:00.000Z') });

      expect(issues.some((i) => i.code === 'UNKNOWN_KEY' && i.severity === 'warning')).toBe(true);
      expect(
        partitionIssues(issues).errors.some(
          (i) => i.code === 'INVALID_SHAPE' && i.field === 'frontmatter.created',
        ),
      ).toBe(true);
    });

    it('rejects NUL characters in unknown key names before persistence', () => {
      const issues = validateSkillFrontmatter({ ['custom\u0000key']: 'value' });

      expect(partitionIssues(issues).errors).toEqual([
        expect.objectContaining({
          field: 'frontmatter',
          code: 'INVALID_KEY',
        }),
      ]);
      expect(issues.some((i) => i.code === 'UNKNOWN_KEY')).toBe(false);
    });

    it('rejects object property names that Mongoose cannot persist at any depth', () => {
      for (const key of ['__proto__', 'constructor', 'prototype']) {
        const topLevel = validateSkillFrontmatter(Object.fromEntries([[key, 'value']]));
        const nested = validateSkillFrontmatter({
          metadata: Object.fromEntries([[key, 'value']]),
        });

        expect(partitionIssues(topLevel).errors).toEqual([
          expect.objectContaining({ field: 'frontmatter', code: 'INVALID_KEY' }),
        ]);
        expect(partitionIssues(nested).errors).toEqual([
          expect.objectContaining({ field: 'frontmatter.metadata', code: 'INVALID_KEY' }),
        ]);
      }
    });

    it('accepts the references key in every shape real SKILL.md files use', () => {
      expect(validateSkillFrontmatter({ references: ['workers', 'pages', 'd1'] })).toEqual([]);
      expect(validateSkillFrontmatter({ references: 'references/api.md' })).toEqual([]);
      expect(
        validateSkillFrontmatter({
          references: [{ path: 'references/api.md', description: 'API surface' }],
        }),
      ).toEqual([]);
      expect(
        validateSkillFrontmatter({ references: { workers: 'references/workers.md' } }),
      ).toEqual([]);
    });

    it('rejects a references value with excessive nesting', () => {
      const deep = { a: { b: { c: { d: { e: { f: 'too deep' } } } } } };
      expect(
        validateSkillFrontmatter({ references: deep }).some(
          (i) => i.code === 'INVALID_SHAPE' && i.field === 'frontmatter.references',
        ),
      ).toBe(true);
    });

    it('accepts known keys with correct types', () => {
      expect(
        validateSkillFrontmatter({
          name: 'demo-skill',
          description: 'A demo skill',
          'when-to-use': 'When the user needs a demo.',
          'allowed-tools': ['read', 'write'],
          'user-invocable': true,
          effort: 5,
          version: '1.0.0',
          license: 'MIT',
          compatibility: 'Requires GitHub MCP to access the repository content.',
          hooks: { 'pre-run': 'echo hi' },
          metadata: { owner: 'data-team' },
        }),
      ).toEqual([]);
    });

    it('accepts the spec-defined compatibility field as a string', () => {
      expect(
        validateSkillFrontmatter({
          compatibility: 'Designed for Claude Code (or similar products)',
        }),
      ).toEqual([]);
    });

    it('rejects a non-string compatibility field', () => {
      expect(
        validateSkillFrontmatter({ compatibility: ['a', 'b'] }).some(
          (i) => i.code === 'INVALID_TYPE',
        ),
      ).toBe(true);
    });

    it('rejects known keys with wrong types', () => {
      expect(
        validateSkillFrontmatter({ 'user-invocable': 'yes' }).some(
          (i) => i.code === 'INVALID_TYPE',
        ),
      ).toBe(true);
      expect(
        validateSkillFrontmatter({ 'allowed-tools': [1, 2, 3] }).some(
          (i) => i.code === 'INVALID_TYPE',
        ),
      ).toBe(true);
    });

    it('rejects hooks object with excessive nesting', () => {
      const deep = { a: { b: { c: { d: { e: { f: 'too deep' } } } } } };
      expect(
        validateSkillFrontmatter({ hooks: deep }).some((i) => i.code === 'INVALID_SHAPE'),
      ).toBe(true);
    });

    it('accepts always-apply as a boolean', () => {
      expect(validateSkillFrontmatter({ 'always-apply': true })).toEqual([]);
      expect(validateSkillFrontmatter({ 'always-apply': false })).toEqual([]);
      expect(validateSkillFrontmatter({ alwaysApply: true })).toEqual([]);
      expect(validateSkillFrontmatter({ alwaysApply: false })).toEqual([]);
    });

    it('rejects always-apply with non-boolean values', () => {
      expect(
        validateSkillFrontmatter({ 'always-apply': 'yes' }).some(
          (i) => i.code === 'INVALID_TYPE' && i.field === 'frontmatter.always-apply',
        ),
      ).toBe(true);
      expect(
        validateSkillFrontmatter({ 'always-apply': 1 }).some((i) => i.code === 'INVALID_TYPE'),
      ).toBe(true);
      expect(
        validateSkillFrontmatter({ alwaysApply: 'yes' }).some(
          (i) => i.code === 'INVALID_TYPE' && i.field === 'frontmatter.alwaysApply',
        ),
      ).toBe(true);
    });
  });

  describe('validateAlwaysApply', () => {
    it('accepts undefined and booleans (undefined = no change)', () => {
      expect(validateAlwaysApply(undefined)).toEqual([]);
      expect(validateAlwaysApply(true)).toEqual([]);
      expect(validateAlwaysApply(false)).toEqual([]);
    });

    it('rejects null (PATCH forwards any non-undefined value to $set, and null in a boolean column is an ambiguous state)', () => {
      expect(validateAlwaysApply(null).some((i) => i.code === 'INVALID_TYPE')).toBe(true);
    });

    it('rejects string payloads (defends against loosely-typed clients)', () => {
      expect(validateAlwaysApply('true').some((i) => i.code === 'INVALID_TYPE')).toBe(true);
      expect(validateAlwaysApply('false').some((i) => i.code === 'INVALID_TYPE')).toBe(true);
    });

    it('rejects numeric / object / array payloads', () => {
      expect(validateAlwaysApply(1).some((i) => i.code === 'INVALID_TYPE')).toBe(true);
      expect(validateAlwaysApply({}).some((i) => i.code === 'INVALID_TYPE')).toBe(true);
      expect(validateAlwaysApply([]).some((i) => i.code === 'INVALID_TYPE')).toBe(true);
    });
  });

  describe('deriveStructuredFrontmatterFields', () => {
    it('returns empty object for missing or non-object frontmatter', () => {
      expect(deriveStructuredFrontmatterFields(undefined)).toEqual({});
      expect(deriveStructuredFrontmatterFields(null as unknown as Record<string, unknown>)).toEqual(
        {},
      );
    });

    it('extracts disable-model-invocation only when explicitly boolean', () => {
      expect(deriveStructuredFrontmatterFields({ 'disable-model-invocation': true })).toEqual({
        disableModelInvocation: true,
      });
      expect(deriveStructuredFrontmatterFields({ 'disable-model-invocation': false })).toEqual({
        disableModelInvocation: false,
      });
      /* Non-boolean values are silently ignored — the validator already
         rejects them upstream with INVALID_TYPE, so deriving here would
         double-fire the failure. */
      expect(deriveStructuredFrontmatterFields({ 'disable-model-invocation': 'yes' })).toEqual({});
    });

    it('extracts user-invocable only when explicitly boolean', () => {
      expect(deriveStructuredFrontmatterFields({ 'user-invocable': true })).toEqual({
        userInvocable: true,
      });
      expect(deriveStructuredFrontmatterFields({ 'user-invocable': false })).toEqual({
        userInvocable: false,
      });
      /* Field absent → no override; downstream uses schema default of true. */
      expect(deriveStructuredFrontmatterFields({})).toEqual({});
    });

    it('normalizes a string allowed-tools to a one-element array', () => {
      expect(deriveStructuredFrontmatterFields({ 'allowed-tools': 'web_search' })).toEqual({
        allowedTools: ['web_search'],
      });
      /* Empty string → not extracted; an explicit empty array is the
         author's way to say "no extras". */
      expect(deriveStructuredFrontmatterFields({ 'allowed-tools': '' })).toEqual({});
      expect(deriveStructuredFrontmatterFields({ 'Allowed-Tools': 'execute_code' })).toEqual({
        allowedTools: ['execute_code'],
      });
    });

    it('passes through array allowed-tools, dropping non-string entries', () => {
      expect(
        deriveStructuredFrontmatterFields({
          'allowed-tools': ['execute_code', 'read_file', '', 42 as unknown as string, null],
        }),
      ).toEqual({ allowedTools: ['execute_code', 'read_file'] });
      expect(deriveStructuredFrontmatterFields({ 'allowed-tools': [] })).toEqual({
        allowedTools: [],
      });
    });

    it('combines all three fields when present together', () => {
      expect(
        deriveStructuredFrontmatterFields({
          'disable-model-invocation': true,
          'user-invocable': false,
          'allowed-tools': ['execute_code'],
        }),
      ).toEqual({
        disableModelInvocation: true,
        userInvocable: false,
        allowedTools: ['execute_code'],
      });
    });
  });
});

describe('Skill CRUD methods', () => {
  it('rejects an oversized body before scanning its frontmatter on create', async () => {
    const body = `---\nalways-apply: a${' '.repeat(SKILL_BODY_MAX_LENGTH)}b\n---`;

    await expect(methods.createSkill(makeSkillInput({ body }))).rejects.toMatchObject({
      code: 'SKILL_VALIDATION_FAILED',
      issues: [expect.objectContaining({ field: 'body', code: 'TOO_LONG' })],
    });
  });

  it('rejects an oversized body before scanning its frontmatter on update', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    const body = `---\nalways-apply: a${' '.repeat(SKILL_BODY_MAX_LENGTH)}b\n---`;

    await expect(
      methods.updateSkill({
        id: skill._id.toString(),
        expectedVersion: 1,
        update: { body },
      }),
    ).rejects.toMatchObject({
      code: 'SKILL_VALIDATION_FAILED',
      issues: [expect.objectContaining({ field: 'body', code: 'TOO_LONG' })],
    });
  });

  it('creates a skill with version 1 and default fileCount 0', async () => {
    const { skill, warnings } = await methods.createSkill(makeSkillInput());
    expect(skill.name).toBe('demo-skill');
    expect(skill.version).toBe(1);
    expect(skill.fileCount).toBe(0);
    expect(skill.source).toBe('inline');
    expect(skill.author.toString()).toBe(owner._id.toString());
    expect(warnings).toEqual([]);
  });

  it('emits a too-short warning when the description is under 20 chars', async () => {
    const { skill, warnings } = await methods.createSkill(
      makeSkillInput({ name: 'short-desc-skill', description: 'Too short.' }),
    );
    expect(skill._id).toBeDefined();
    expect(warnings).toEqual([
      expect.objectContaining({
        field: 'description',
        code: 'TOO_SHORT',
        severity: 'warning',
      }),
    ]);
  });

  it('creates the skill and warns when frontmatter carries an unknown key', async () => {
    /* One unrecognized key in one SKILL.md must not fail the skill: the GitHub
       sync runner marks the whole source failed on a validation error, so a
       stray key used to block every other skill in the repository. */
    const { skill, warnings } = await methods.createSkill(
      makeSkillInput({
        name: 'unknown-key-frontmatter',
        frontmatter: { name: 'unknown-key-frontmatter', 'bogus-key': 'nope' },
      }),
    );
    expect(skill._id).toBeDefined();
    expect(skill.frontmatter).toMatchObject({ 'bogus-key': 'nope' });
    expect(warnings).toEqual([
      expect.objectContaining({
        field: 'frontmatter.bogus-key',
        code: 'UNKNOWN_KEY',
        severity: 'warning',
      }),
    ]);
  });

  it('canonicalizes recognized frontmatter variants before persistence and derivation', async () => {
    const { skill, warnings } = await methods.createSkill(
      makeSkillInput({
        name: 'case-variant-frontmatter',
        frontmatter: {
          name: 'case-variant-frontmatter',
          'Allowed-Tools': ['execute_code'],
          'User-Invocable': false,
        },
      }),
    );

    expect(skill.frontmatter).toMatchObject({
      'allowed-tools': ['execute_code'],
      'user-invocable': false,
    });
    expect(skill.frontmatter).not.toHaveProperty('Allowed-Tools');
    expect(skill.allowedTools).toEqual(['execute_code']);
    expect(skill.userInvocable).toBe(false);
    expect(warnings).toEqual([]);
  });

  it('rejects case-colliding recognized frontmatter keys', async () => {
    await expect(
      methods.createSkill(
        makeSkillInput({
          name: 'case-collision-frontmatter',
          frontmatter: {
            'allowed-tools': ['read_file'],
            'Allowed-Tools': ['execute_code'],
          },
        }),
      ),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
  });

  it('creates a skill whose frontmatter carries a references list', async () => {
    const { skill, warnings } = await methods.createSkill(
      makeSkillInput({
        name: 'references-frontmatter',
        frontmatter: {
          name: 'references-frontmatter',
          description: 'A small demo skill used in tests.',
          references: ['workers', 'pages', 'd1'],
        },
      }),
    );
    expect(skill.frontmatter).toMatchObject({ references: ['workers', 'pages', 'd1'] });
    expect(warnings).toEqual([]);
  });

  it('still rejects malformed frontmatter', async () => {
    await expect(
      methods.createSkill(
        makeSkillInput({
          name: 'malformed-frontmatter',
          frontmatter: { 'user-invocable': 'yes' },
        }),
      ),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
    await expect(
      methods.createSkill(
        makeSkillInput({
          name: 'non-object-frontmatter',
          frontmatter: 'not an object',
        }),
      ),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
    await expect(
      methods.createSkill(
        makeSkillInput({
          name: 'deep-hooks-frontmatter',
          frontmatter: { hooks: { a: { b: { c: { d: { e: { f: 'too deep' } } } } } } },
        }),
      ),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
  });

  it('rejects names that start with reserved brand prefixes', async () => {
    await expect(
      methods.createSkill(makeSkillInput({ name: 'anthropic-helper' })),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
    await expect(
      methods.createSkill(makeSkillInput({ name: 'claude-helper' })),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
  });

  it('allows names that merely contain the reserved words as substrings', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'research-anthropic-helper' }),
    );
    expect(skill.name).toBe('research-anthropic-helper');
  });

  it('rejects reserved CLI command names', async () => {
    await expect(methods.createSkill(makeSkillInput({ name: 'help' }))).rejects.toMatchObject({
      code: 'SKILL_VALIDATION_FAILED',
    });
    await expect(methods.createSkill(makeSkillInput({ name: 'settings' }))).rejects.toMatchObject({
      code: 'SKILL_VALIDATION_FAILED',
    });
  });

  it('enforces name uniqueness per author', async () => {
    await methods.createSkill(makeSkillInput());
    await expect(methods.createSkill(makeSkillInput())).rejects.toBeDefined();
  });

  it.each(['abcdef0123456789abcdef01', 'ABCDEF0123456789ABCDEF01'])(
    'accepts hex string author %s and stores it as an ObjectId',
    async (hexAuthor) => {
      const { skill } = await methods.createSkill(
        makeSkillInput({ name: 'hex-author-skill', author: hexAuthor }),
      );
      expect(skill.author).toBeInstanceOf(mongoose.Types.ObjectId);
      expect(skill.author.toHexString()).toBe(hexAuthor.toLowerCase());
    },
  );

  it.each(['', 'not-an-id', 'a'.repeat(23), 'a'.repeat(25), 'g'.repeat(24)])(
    'rejects malformed string author %p with a validation error before querying',
    async (author) => {
      const findOne = jest.spyOn(Skill, 'findOne');

      await expect(methods.createSkill(makeSkillInput({ author }))).rejects.toMatchObject({
        message: 'Skill validation failed',
        code: 'SKILL_VALIDATION_FAILED',
        issues: [{ field: 'author', code: 'INVALID_FORMAT' }],
      });
      expect(findOne).not.toHaveBeenCalled();
    },
  );

  it('enforces name uniqueness per author across ObjectId and string forms', async () => {
    const hexAuthor = new mongoose.Types.ObjectId().toHexString();
    await methods.createSkill(
      makeSkillInput({ name: 'mixed-author-form-skill', author: hexAuthor }),
    );
    await expect(
      methods.createSkill(
        makeSkillInput({
          name: 'mixed-author-form-skill',
          author: new mongoose.Types.ObjectId(hexAuthor),
        }),
      ),
    ).rejects.toBeDefined();
  });

  it('throws with validation issues on bad input', async () => {
    await expect(methods.createSkill(makeSkillInput({ name: 'BAD NAME' }))).rejects.toMatchObject({
      code: 'SKILL_VALIDATION_FAILED',
    });
  });

  it('optimistic concurrency — stale version returns conflict with current state', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    const id = skill._id.toString();
    const first = await methods.updateSkill({
      id,
      expectedVersion: 1,
      update: { description: 'First update description (long enough).' },
    });
    expect(first.status).toBe('updated');
    if (first.status === 'updated') {
      expect(first.skill.version).toBe(2);
    }

    const stale = await methods.updateSkill({
      id,
      expectedVersion: 1,
      update: { description: 'Second update description (long enough).' },
    });
    expect(stale.status).toBe('conflict');
    if (stale.status === 'conflict') {
      expect(stale.current.version).toBe(2);
      expect(stale.current.description).toBe('First update description (long enough).');
    }
  });

  it('does not expose a deleting Skill as the current version after a missed update', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    await mongoose.models.Skill.updateOne({ _id: skill._id }, { $set: { deletingAt: new Date() } });

    await expect(
      methods.updateSkill({
        id: skill._id.toString(),
        expectedVersion: skill.version,
        update: { description: 'Updated description (long enough).' },
      }),
    ).resolves.toEqual({ status: 'not_found' });
  });

  it('queues blob cleanup before finalizing ACL and file rows', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    await grantOwner(skill._id);
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/parse.sh',
      file_id: 'file-123',
      filename: 'parse.sh',
      filepath: '/tmp/parse.sh',
      source: 'local',
      mimeType: 'text/x-shellscript',
      bytes: 42,
      author: owner._id,
    });

    expect(await AclEntry.countDocuments({ resourceId: skill._id })).toBe(1);
    expect(await SkillFile.countDocuments({ skillId: skill._id })).toBe(1);

    const res = await methods.deleteSkill(skill._id.toString());
    expect(res.cleanupComplete).toBe(false);
    expect(await AclEntry.countDocuments({ resourceId: skill._id })).toBe(1);
    expect(await SkillFile.countDocuments({ skillId: skill._id })).toBe(1);
    expect((await methods.finalizeSkillDeletion(skill._id.toString())).cleanupComplete).toBe(false);
    await methods.deleteSkillFileAfterBlob(skill._id.toString(), 'file-123');
    expect((await methods.finalizeSkillDeletion(skill._id.toString())).cleanupComplete).toBe(true);
    expect(await AclEntry.countDocuments({ resourceId: skill._id })).toBe(0);
    expect(await SkillFile.countDocuments({ skillId: skill._id })).toBe(0);
  });

  it('filterExistingSkillIds matches uppercase-hex candidates and returns canonical ids', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'case-skill' }));
    const canonical = skill._id.toString();

    const filtered = await filterExistingSkillIds(mongoose, [canonical.toUpperCase()]);
    expect(filtered).toEqual([canonical]);
  });

  it('does not admit a Skill already fenced for deletion into a new agent allowlist', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'deleting-allowlist' }));
    await Skill.updateOne({ _id: skill._id }, { $set: { deletingAt: new Date() } });
    expect(await filterExistingSkillIds(mongoose, [skill._id.toString()])).toEqual([]);
  });

  it('deleteSkill retains its retry journal instead of removing file rows', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'flaky-files' }));
    const Agent = mongoose.models.Agent;
    const agent = await Agent.create(makeAgentDoc([skill._id.toString()]));

    const first = await methods.deleteSkill(skill._id.toString());
    expect(first).toMatchObject({ cleanupComplete: false, failedCleanupSteps: ['skill_files'] });
    const retry = await methods.deleteSkill(skill._id.toString());
    expect(retry).toMatchObject({ cleanupComplete: false, failedCleanupSteps: ['skill_files'] });
    expect(await Skill.countDocuments({ _id: skill._id })).toBe(1);
    expect(await mongoose.models.SkillDeletion.countDocuments({ skillId: skill._id })).toBe(1);

    const agentAfter = (await Agent.findById(agent._id).lean()) as {
      skills?: string[];
      skills_enabled?: boolean;
    } | null;
    expect(agentAfter?.skills).toEqual([skill._id.toString()]);
    expect(agentAfter?.skills_enabled).toBe(true);
  });

  it('deleteSkill disables skills when the deleted id was the entire allowlist', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'only-skill' }));
    const Agent = mongoose.models.Agent;
    const agent = await Agent.create(makeAgentDoc([skill._id.toString()]));

    const res = await methods.deleteSkill(skill._id.toString().toUpperCase());
    expect(res.cleanupComplete).toBe(false);
    expect((await methods.finalizeSkillDeletion(skill._id.toString())).cleanupComplete).toBe(true);

    const agentAfter = (await Agent.findById(agent._id).lean()) as {
      skills?: string[];
      skills_enabled?: boolean;
    } | null;
    expect(agentAfter?.skills).toEqual([]);
    expect(agentAfter?.skills_enabled).toBe(false);
  });

  it('deleteSkill keeps skills enabled when the entire allowlist is deleted from an all-scoped agent', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'all-scoped-only-skill' }));
    const Agent = mongoose.models.Agent;
    const agent = await Agent.create(makeAgentDoc([skill._id.toString()], { skills_scope: 'all' }));

    const res = await methods.deleteSkill(skill._id.toString());
    expect(res.cleanupComplete).toBe(false);
    expect((await methods.finalizeSkillDeletion(skill._id.toString())).cleanupComplete).toBe(true);

    const agentAfter = (await Agent.findById(agent._id).lean()) as {
      skills?: string[];
      skills_enabled?: boolean;
      skills_scope?: string;
    } | null;
    expect(agentAfter?.skills).toEqual([]);
    expect(agentAfter?.skills_enabled).toBe(true);
    expect(agentAfter?.skills_scope).toBe('all');
  });

  it('deleteSkill keeps skills enabled when the entire allowlist is deleted from a selected-scoped agent', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'selected-scoped-only-skill' }),
    );
    const Agent = mongoose.models.Agent;
    const agent = await Agent.create(
      makeAgentDoc([skill._id.toString()], { skills_scope: 'selected' }),
    );

    const res = await methods.deleteSkill(skill._id.toString());
    expect(res.cleanupComplete).toBe(false);
    expect((await methods.finalizeSkillDeletion(skill._id.toString())).cleanupComplete).toBe(true);

    const agentAfter = (await Agent.findById(agent._id).lean()) as {
      skills?: string[];
      skills_enabled?: boolean;
      skills_scope?: string;
    } | null;
    expect(agentAfter?.skills).toEqual([]);
    expect(agentAfter?.skills_enabled).toBe(true);
    expect(agentAfter?.skills_scope).toBe('selected');
  });

  it('deleteSkill disables skills when the entire allowlist is deleted from a none-scoped agent', async () => {
    /** `skills_enabled: true` with `skills_scope: none` is a shape the API
     *  accepts. It renders as Off, and `skillDeps` reads the master flag on
     *  its own as permission to expose the authoring tools, so cleanup has to
     *  clear it rather than treat the explicit scope as an opt-out. */
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'none-scoped-only-skill' }));
    const Agent = mongoose.models.Agent;
    const agent = await Agent.create(
      makeAgentDoc([skill._id.toString()], { skills_scope: 'none' }),
    );

    const res = await methods.deleteSkill(skill._id.toString());
    expect(res.cleanupComplete).toBe(false);
    expect((await methods.finalizeSkillDeletion(skill._id.toString())).cleanupComplete).toBe(true);

    const agentAfter = (await Agent.findById(agent._id).lean()) as {
      skills?: string[];
      skills_enabled?: boolean;
      skills_scope?: string;
    } | null;
    expect(agentAfter?.skills).toEqual([]);
    expect(agentAfter?.skills_enabled).toBe(false);
    expect(agentAfter?.skills_scope).toBe('none');
  });

  it('deleteSkill prunes the deleted id from agent skill allowlists', async () => {
    const { skill: doomed } = await methods.createSkill(makeSkillInput({ name: 'doomed-skill' }));
    const { skill: kept } = await methods.createSkill(makeSkillInput({ name: 'kept-skill' }));
    const Agent = mongoose.models.Agent;
    const scoped = await Agent.create(makeAgentDoc([doomed._id.toString(), kept._id.toString()]));
    const untouched = await Agent.create(
      makeAgentDoc([kept._id.toString()], { name: 'Untouched Agent' }),
    );

    const res = await methods.deleteSkill(doomed._id.toString());
    expect(res.cleanupComplete).toBe(false);
    expect((await methods.finalizeSkillDeletion(doomed._id.toString())).cleanupComplete).toBe(true);

    const scopedAfter = (await Agent.findById(scoped._id).lean()) as {
      skills?: string[];
      skills_enabled?: boolean;
    } | null;
    expect(scopedAfter?.skills).toEqual([kept._id.toString()]);
    expect(scopedAfter?.skills_enabled).toBe(true);

    const untouchedAfter = (await Agent.findById(untouched._id).lean()) as {
      skills?: string[];
    } | null;
    expect(untouchedAfter?.skills).toEqual([kept._id.toString()]);
  });

  it('findSkillBySourceIdentity searches only the requested tenant bucket', async () => {
    const upstreamId = 'librechat-skills:skills/research';
    const sourceMetadata = {
      provider: 'github',
      sourceId: 'librechat-skills',
      upstreamId,
    };
    const author = new mongoose.Types.ObjectId();
    const tenantSkill = await Skill.create({
      name: 'research',
      description: 'A tenant-scoped GitHub skill mirror.',
      body: 'tenant body',
      author,
      authorName: 'GitHub Sync',
      tenantId: 'tenant-a',
      source: 'github',
      sourceMetadata,
    });
    const ambientSkill = await Skill.create({
      name: 'research',
      description: 'An ambient GitHub skill mirror.',
      body: 'ambient body',
      author,
      authorName: 'GitHub Sync',
      source: 'github',
      sourceMetadata,
    });

    const ambientResult = await methods.findSkillBySourceIdentity({
      source: 'github',
      upstreamId,
    });
    const tenantResult = await methods.findSkillBySourceIdentity({
      source: 'github',
      upstreamId,
      tenantId: 'tenant-a',
    });

    expect(ambientResult?._id.toString()).toBe(ambientSkill._id.toString());
    expect(tenantResult?._id.toString()).toBe(tenantSkill._id.toString());
  });

  it('listSkillsByAccess returns only accessible skills and paginates by cursor', async () => {
    const ids: mongoose.Types.ObjectId[] = [];
    for (let i = 0; i < 3; i++) {
      const { skill } = await methods.createSkill(
        makeSkillInput({
          name: `demo-skill-${i}`,
          description: `A demo skill used to test pagination (${i}).`,
        }),
      );
      ids.push(skill._id);
      await new Promise((r) => setTimeout(r, 5));
    }

    const page1 = await methods.listSkillsByAccess({ accessibleIds: ids, limit: 2 });
    expect(page1.skills.length).toBe(2);
    expect(page1.has_more).toBe(true);
    expect(page1.after).not.toBeNull();

    const page2 = await methods.listSkillsByAccess({
      accessibleIds: ids,
      limit: 2,
      cursor: page1.after,
    });
    expect(page2.skills.length).toBe(1);
    expect(page2.has_more).toBe(false);
  });

  it('persists disableModelInvocation / userInvocable / allowedTools derived from frontmatter', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'frontmatter-derived',
        frontmatter: {
          name: 'frontmatter-derived',
          description: 'A demo skill used in tests.',
          'disable-model-invocation': true,
          'user-invocable': false,
          'allowed-tools': ['execute_code', 'read_file'],
        },
      }),
    );
    expect(skill.disableModelInvocation).toBe(true);
    expect(skill.userInvocable).toBe(false);
    expect(skill.allowedTools).toEqual(['execute_code', 'read_file']);

    /* Re-fetch via getSkillById to confirm the columns survive the round-trip
       (proving they're persisted, not just echoed in the create response). */
    const reloaded = await methods.getSkillById(skill._id);
    expect(reloaded?.disableModelInvocation).toBe(true);
    expect(reloaded?.userInvocable).toBe(false);
    expect(reloaded?.allowedTools).toEqual(['execute_code', 'read_file']);
  });

  it('defaults disableModelInvocation=false / userInvocable=true / allowedTools=undefined when frontmatter omits them', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'defaults' }));
    expect(skill.disableModelInvocation).toBe(false);
    expect(skill.userInvocable).toBe(true);
    expect(skill.allowedTools).toBeUndefined();
  });

  it('updateSkill re-derives the structured columns when frontmatter changes', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'mutating',
        frontmatter: {
          name: 'mutating',
          description: 'A demo skill used in tests.',
          'disable-model-invocation': true,
          'user-invocable': false,
          'allowed-tools': ['execute_code'],
        },
      }),
    );
    expect(skill.disableModelInvocation).toBe(true);

    const updated = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: 1,
      update: {
        frontmatter: {
          name: 'mutating',
          description: 'A demo skill used in tests.',
          /* Drops disable-model-invocation, allowed-tools; flips user-invocable. */
          'user-invocable': true,
        },
      },
    });
    expect(updated.status).toBe('updated');
    if (updated.status !== 'updated') return;
    /* Fields the new frontmatter omits are `$unset` so a re-fetch returns
       undefined. Functionally equivalent to the schema default for all three:
       runtime catalog filter checks `disableModelInvocation === true` (so
       undefined passes through), `resolveManualSkills` checks
       `userInvocable === false` (undefined passes through), and the tool-
       union helper treats undefined `allowedTools` as "no extras". */
    expect(updated.skill.disableModelInvocation).toBeUndefined();
    expect(updated.skill.userInvocable).toBe(true);
    expect(updated.skill.allowedTools).toBeUndefined();
  });

  it('backfills legacy skills from frontmatter when columns are unset (getSkillByName)', async () => {
    /* Simulate a pre-Phase-6 skill: it has `user-invocable` /
       `disable-model-invocation` / `allowed-tools` set in frontmatter
       but the structured columns were never populated (no migration). */
    const legacy = await Skill.create({
      name: 'legacy-skill',
      description: 'A legacy skill from before Phase 6.',
      body: 'body',
      frontmatter: {
        name: 'legacy-skill',
        description: 'A legacy skill from before Phase 6.',
        'disable-model-invocation': true,
        'user-invocable': false,
        'allowed-tools': ['execute_code'],
      },
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      version: 1,
      source: 'inline',
      fileCount: 0,
    });
    /* Strip the columns to simulate pre-Phase-6 state — `Skill.create`
       above would have run the new derive helper, so we explicitly unset
       to recreate the legacy shape. */
    await Skill.collection.updateOne(
      { _id: legacy._id },
      { $unset: { disableModelInvocation: '', userInvocable: '', allowedTools: '' } },
    );

    const fetched = await methods.getSkillByName('legacy-skill', [
      legacy._id as mongoose.Types.ObjectId,
    ]);
    /* Backfill must populate the columns from frontmatter so runtime
       gates fire correctly without a write migration. */
    expect(fetched?.disableModelInvocation).toBe(true);
    expect(fetched?.userInvocable).toBe(false);
    expect(fetched?.allowedTools).toEqual(['execute_code']);
  });

  it('getAuthorSkillByName resolves only the matching author and tenant', async () => {
    const sharedName = 'author-owned-lookup';
    const ownerSkill = await Skill.create({
      name: sharedName,
      description: 'Owner tenant skill.',
      body: 'owner body',
      frontmatter: {},
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      tenantId: 'tenant-a',
      version: 1,
      source: 'inline',
      fileCount: 0,
    });
    await Skill.create({
      name: sharedName,
      description: 'Other author skill.',
      body: 'other body',
      frontmatter: {},
      author: other._id,
      authorName: other.name ?? 'Other',
      tenantId: 'tenant-a',
      version: 1,
      source: 'inline',
      fileCount: 0,
    });
    await Skill.create({
      name: sharedName,
      description: 'Owner different tenant skill.',
      body: 'tenant b body',
      frontmatter: {},
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      tenantId: 'tenant-b',
      version: 1,
      source: 'inline',
      fileCount: 0,
    });

    const fetched = await methods.getAuthorSkillByName({
      name: sharedName,
      author: owner._id,
      tenantId: 'tenant-a',
    });

    expect(fetched?._id.toString()).toBe(ownerSkill._id.toString());
    expect(fetched?.body).toBe('owner body');
  });

  it('preferModelInvocable picks the model-invocable doc on same-name collision (does NOT filter on userInvocable)', async () => {
    /* Same-name collision scenario the model paths must handle: an older
       user-invocable variant and a newer model-only variant
       (`userInvocable: false`) — both are model-invocable. The model
       path uses preferModelInvocable, which deliberately does NOT
       filter on userInvocable; otherwise the older doc would shadow the
       cataloged model-only doc the model targeted. */
    const olderUserInvocable = await Skill.create({
      name: 'model-collision',
      description: 'Older user-invocable variant of the colliding name.',
      body: 'user-invocable body',
      frontmatter: {},
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      version: 1,
      source: 'inline',
      fileCount: 0,
      userInvocable: true,
    });
    const newerModelOnly = await Skill.create({
      name: 'model-collision',
      description: 'Newer model-only variant of the colliding name.',
      body: 'model-only body',
      frontmatter: {},
      author: other._id,
      authorName: other.name ?? 'Other',
      version: 1,
      source: 'inline',
      fileCount: 0,
      userInvocable: false,
    });
    /* Set updatedAt explicitly so the "older / newer" assertion is
       deterministic across CI runners — relying on wall-clock spacing
       between two `Skill.create` calls would race on a fast machine. */
    await Skill.collection.updateOne(
      { _id: olderUserInvocable._id },
      { $set: { updatedAt: new Date(Date.now() - 1000) } },
    );

    const accessibleIds = [
      olderUserInvocable._id as mongoose.Types.ObjectId,
      newerModelOnly._id as mongoose.Types.ObjectId,
    ];

    /* preferModelInvocable: both are model-invocable (neither has
       disableModelInvocation: true), so newest wins → model-only doc. */
    const modelLookup = await methods.getSkillByName('model-collision', accessibleIds, {
      preferModelInvocable: true,
    });
    expect(modelLookup?._id.toString()).toBe(newerModelOnly._id.toString());
  });

  it('preferUserInvocable picks the user-invocable doc on same-name collision (does NOT filter on disableModelInvocation)', async () => {
    /* Manual path scenario: older user-invocable variant + newer
       model-only variant. The popover surfaced the older doc; the
       resolver must look it up with preferUserInvocable so the
       newer model-only doc doesn't shadow the user's selection. */
    const olderUserInvocable = await Skill.create({
      name: 'user-collision',
      description: 'Older user-invocable variant.',
      body: 'user-invocable body',
      frontmatter: {},
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      version: 1,
      source: 'inline',
      fileCount: 0,
      userInvocable: true,
    });
    const newerModelOnly = await Skill.create({
      name: 'user-collision',
      description: 'Newer model-only variant.',
      body: 'model-only body',
      frontmatter: {},
      author: other._id,
      authorName: other.name ?? 'Other',
      version: 1,
      source: 'inline',
      fileCount: 0,
      userInvocable: false,
    });
    /* Deterministic ordering — see the model-collision test above. */
    await Skill.collection.updateOne(
      { _id: olderUserInvocable._id },
      { $set: { updatedAt: new Date(Date.now() - 1000) } },
    );

    const accessibleIds = [
      olderUserInvocable._id as mongoose.Types.ObjectId,
      newerModelOnly._id as mongoose.Types.ObjectId,
    ];

    /* Default behavior: newest wins → model-only doc returned. */
    const defaultLookup = await methods.getSkillByName('user-collision', accessibleIds);
    expect(defaultLookup?._id.toString()).toBe(newerModelOnly._id.toString());

    /* preferUserInvocable: user-invocable doc wins → older doc returned.
       Disabled-model status is irrelevant here. */
    const preferred = await methods.getSkillByName('user-collision', accessibleIds, {
      preferUserInvocable: true,
    });
    expect(preferred?._id.toString()).toBe(olderUserInvocable._id.toString());
  });

  it('preferUserInvocable still returns disabled docs (manual prime of disabled is supported)', async () => {
    /* Manual path with a disabled-but-user-invocable skill: the user
       can still pick it from the popover; resolveManualSkills uses
       preferUserInvocable, which doesn't filter on
       disableModelInvocation. */
    const disabled = await Skill.create({
      name: 'disabled-user-invocable',
      description: 'User-invocable but model-disabled.',
      body: 'body',
      frontmatter: {},
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      version: 1,
      source: 'inline',
      fileCount: 0,
      userInvocable: true,
      disableModelInvocation: true,
    });

    const result = await methods.getSkillByName(
      'disabled-user-invocable',
      [disabled._id as mongoose.Types.ObjectId],
      { preferUserInvocable: true },
    );
    expect(result?._id.toString()).toBe(disabled._id.toString());
    expect(result?.disableModelInvocation).toBe(true);
  });

  it('preferred lookups fall back to the newest match when no preferred doc exists', async () => {
    /* Sole-disabled name: only a disable-model-invocation doc exists.
       preferModelInvocable must still return it so handleSkillToolCall
       can fire the explicit-rejection error path. */
    const disabledOnly = await Skill.create({
      name: 'sole-disabled-fallback',
      description: 'Only a model-disabled variant of this name exists.',
      body: 'disabled body',
      frontmatter: {},
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      version: 1,
      source: 'inline',
      fileCount: 0,
      disableModelInvocation: true,
    });

    const result = await methods.getSkillByName(
      'sole-disabled-fallback',
      [disabledOnly._id as mongoose.Types.ObjectId],
      { preferModelInvocable: true },
    );
    expect(result?._id.toString()).toBe(disabledOnly._id.toString());
    expect(result?.disableModelInvocation).toBe(true);
  });

  it('does not overwrite explicit columns with frontmatter values (column wins)', async () => {
    /* If both column and frontmatter are set (e.g. an admin edited the
       column directly via the API but the frontmatter still says
       otherwise), the column is authoritative — backfill only fills
       undefined fields. */
    const skill = await Skill.create({
      name: 'column-wins',
      description: 'A demo skill used in tests.',
      body: 'body',
      frontmatter: {
        name: 'column-wins',
        description: 'A demo skill used in tests.',
        'disable-model-invocation': true,
        'user-invocable': false,
      },
      author: owner._id,
      authorName: owner.name ?? 'Skill Owner',
      version: 1,
      source: 'inline',
      fileCount: 0,
      disableModelInvocation: false,
      userInvocable: true,
    });

    const fetched = await methods.getSkillByName('column-wins', [
      skill._id as mongoose.Types.ObjectId,
    ]);
    expect(fetched?.disableModelInvocation).toBe(false);
    expect(fetched?.userInvocable).toBe(true);
  });

  it('listSkillsByAccess returns disableModelInvocation / userInvocable / allowedTools on summary rows', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'list-summary',
        frontmatter: {
          name: 'list-summary',
          description: 'A demo skill used in tests.',
          'disable-model-invocation': true,
          'user-invocable': false,
          'allowed-tools': ['web_search'],
        },
      }),
    );
    const result = await methods.listSkillsByAccess({
      accessibleIds: [skill._id],
      limit: 10,
    });
    expect(result.skills.length).toBe(1);
    /* These are the fields injectSkillCatalog filters on; if they're
       missing from the projection, the catalog can't enforce
       disableModelInvocation. */
    expect(result.skills[0].disableModelInvocation).toBe(true);
    expect(result.skills[0].userInvocable).toBe(false);
    expect(result.skills[0].allowedTools).toEqual(['web_search']);
  });

  it('listSkillsByAccess filters by category and search', async () => {
    const { skill: a } = await methods.createSkill(
      makeSkillInput({ name: 'alpha-skill', category: 'tools' }),
    );
    await methods.createSkill(
      makeSkillInput({
        name: 'beta-skill',
        category: 'other',
        description: 'A beta description that is long enough.',
      }),
    );
    const ids = await Skill.find().distinct('_id');

    const byCat = await methods.listSkillsByAccess({
      accessibleIds: ids as unknown as mongoose.Types.ObjectId[],
      limit: 10,
      category: 'tools',
    });
    expect(byCat.skills.length).toBe(1);
    expect(byCat.skills[0].name).toBe(a.name);

    const bySearch = await methods.listSkillsByAccess({
      accessibleIds: ids as unknown as mongoose.Types.ObjectId[],
      limit: 10,
      search: 'beta',
    });
    expect(bySearch.skills.length).toBe(1);
    expect(bySearch.skills[0].name).toBe('beta-skill');
  });

  it('listAlwaysApplySkills returns only alwaysApply:true rows within accessibleIds', async () => {
    const { skill: a } = await methods.createSkill(
      makeSkillInput({ name: 'always-a', alwaysApply: true }),
    );
    const { skill: b } = await methods.createSkill(
      makeSkillInput({ name: 'always-b', alwaysApply: true }),
    );
    const { skill: c } = await methods.createSkill(
      makeSkillInput({ name: 'not-always-c' /* alwaysApply defaults false */ }),
    );
    const ids = [a._id, b._id, c._id];
    const result = await methods.listAlwaysApplySkills({
      accessibleIds: ids as unknown as mongoose.Types.ObjectId[],
      limit: 10,
    });
    const names = result.skills.map((s) => s.name).sort();
    expect(names).toEqual(['always-a', 'always-b']);
    expect(result.skills.map((skill) => skill.version)).toEqual([1, 1]);
  });

  it('listAlwaysApplySkills excludes rows outside accessibleIds', async () => {
    const { skill: mine } = await methods.createSkill(
      makeSkillInput({ name: 'mine-always', alwaysApply: true }),
    );
    await methods.createSkill(makeSkillInput({ name: 'other-always', alwaysApply: true }));
    const result = await methods.listAlwaysApplySkills({
      accessibleIds: [mine._id] as unknown as mongoose.Types.ObjectId[],
      limit: 10,
    });
    expect(result.skills.map((s) => s.name)).toEqual(['mine-always']);
  });

  it('listAlwaysApplySkills respects the limit and reports has_more for pagination', async () => {
    const created = [];
    for (let i = 0; i < 3; i++) {
      const { skill } = await methods.createSkill(
        makeSkillInput({ name: `always-${i}`, alwaysApply: true }),
      );
      created.push(skill);
    }
    const result = await methods.listAlwaysApplySkills({
      accessibleIds: created.map((s) => s._id) as unknown as mongoose.Types.ObjectId[],
      limit: 2,
    });
    expect(result.skills).toHaveLength(2);
    expect(result.has_more).toBe(true);
    expect(result.after).not.toBeNull();
  });

  it('listAlwaysApplySkills paginates via cursor to return subsequent rows without duplicates', async () => {
    const created = [];
    for (let i = 0; i < 5; i++) {
      const { skill } = await methods.createSkill(
        makeSkillInput({ name: `paged-${i}`, alwaysApply: true }),
      );
      created.push(skill);
    }
    const ids = created.map((s) => s._id) as unknown as mongoose.Types.ObjectId[];
    const first = await methods.listAlwaysApplySkills({ accessibleIds: ids, limit: 2 });
    expect(first.skills).toHaveLength(2);
    expect(first.has_more).toBe(true);
    const second = await methods.listAlwaysApplySkills({
      accessibleIds: ids,
      limit: 2,
      cursor: first.after,
    });
    expect(second.skills).toHaveLength(2);
    const third = await methods.listAlwaysApplySkills({
      accessibleIds: ids,
      limit: 2,
      cursor: second.after,
    });
    expect(third.has_more).toBe(false);
    expect(third.after).toBeNull();
    const seenIds = [...first.skills, ...second.skills, ...third.skills].map((s) =>
      s._id.toString(),
    );
    expect(new Set(seenIds).size).toBe(5);
  });

  it('createSkill persists alwaysApply first-class column', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'flagged', alwaysApply: true }),
    );
    expect(skill.alwaysApply).toBe(true);

    const { skill: defaulted } = await methods.createSkill(makeSkillInput({ name: 'defaulted' }));
    expect(defaulted.alwaysApply).toBe(false);
  });

  it('createSkill rejects a non-boolean top-level alwaysApply', async () => {
    await expect(
      methods.createSkill(
        makeSkillInput({ name: 'bad-always', alwaysApply: 'false' as unknown as boolean }),
      ),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
  });

  it('updateSkill rejects a non-boolean top-level alwaysApply', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'type-guard' }));
    await expect(
      methods.updateSkill({
        id: skill._id.toString(),
        expectedVersion: skill.version,
        update: { alwaysApply: 'true' as unknown as boolean },
      }),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
  });

  it('updateSkill rejects explicit null for alwaysApply (cannot persist ambiguous state)', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'null-guard', alwaysApply: true }),
    );
    await expect(
      methods.updateSkill({
        id: skill._id.toString(),
        expectedVersion: skill.version,
        update: { alwaysApply: null as unknown as boolean },
      }),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
  });

  it('createSkill derives alwaysApply from frontmatter when the top-level flag is absent', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'frontmatter-on',
        frontmatter: {
          name: 'frontmatter-on',
          description: 'A small demo skill used in tests.',
          'always-apply': true,
        },
      }),
    );
    expect(skill.alwaysApply).toBe(true);
  });

  it('createSkill derives alwaysApply from the camel-case frontmatter alias', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'frontmatter-alias-on',
        frontmatter: {
          name: 'frontmatter-alias-on',
          description: 'A small demo skill used in tests.',
          alwaysApply: true,
        },
      }),
    );
    expect(skill.alwaysApply).toBe(true);
  });

  it('createSkill lets always-apply win when both frontmatter spellings are present', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'frontmatter-canonical-wins',
        frontmatter: {
          name: 'frontmatter-canonical-wins',
          description: 'A small demo skill used in tests.',
          'always-apply': false,
          alwaysApply: true,
        },
      }),
    );
    expect(skill.alwaysApply).toBe(false);
  });

  it('createSkill prefers explicit top-level alwaysApply over frontmatter', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'explicit-wins',
        alwaysApply: false,
        frontmatter: {
          name: 'explicit-wins',
          description: 'A small demo skill used in tests.',
          'always-apply': true,
        },
      }),
    );
    expect(skill.alwaysApply).toBe(false);
  });

  it('updateSkill syncs alwaysApply column from a frontmatter-only update', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'sync-test' }));
    expect(skill.alwaysApply).toBe(false);
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: {
        frontmatter: {
          name: 'sync-test',
          description: 'A small demo skill used in tests.',
          'always-apply': true,
        },
      },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill syncs alwaysApply column from the camel-case frontmatter alias', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'sync-alias-test' }));
    expect(skill.alwaysApply).toBe(false);
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: {
        frontmatter: {
          name: 'sync-alias-test',
          description: 'A small demo skill used in tests.',
          alwaysApply: true,
        },
      },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill keeps alwaysApply column untouched when the frontmatter update omits always-apply', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'no-flip', alwaysApply: true }),
    );
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: {
        frontmatter: { name: 'no-flip', description: 'Updated desc without touching the flag.' },
      },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill top-level alwaysApply wins over a frontmatter flag in the same update', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'explicit-update-wins' }));
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: {
        alwaysApply: false,
        frontmatter: {
          name: 'explicit-update-wins',
          description: 'A small demo skill used in tests.',
          'always-apply': true,
        },
      },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(false);
    }
  });

  it('updateSkill derives alwaysApply from a body edit that flips `always-apply:` inline', async () => {
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'body-flip', alwaysApply: true }),
    );
    const newBody = `---\nname: body-flip\ndescription: still a demo skill.\nalways-apply: false\n---\n\n# Edited body`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: { body: newBody },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(false);
      expect(result.skill.body).toBe(newBody);
    }
  });

  it('updateSkill derives alwaysApply=true from a body edit that adds `always-apply: true` inline', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'body-enable' }));
    expect(skill.alwaysApply).toBe(false);
    const newBody = `---\nname: body-enable\ndescription: now opting in.\nalways-apply: true\n---\n\n# Body`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: { body: newBody },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill derives alwaysApply=true from a body edit that adds `alwaysApply: true` inline', async () => {
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'body-enable-alias' }));
    expect(skill.alwaysApply).toBe(false);
    const newBody = `---\nname: body-enable-alias\ndescription: now opting in.\nalwaysApply: true\n---\n\n# Body`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: { body: newBody },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill flips alwaysApply to false when the body removes the `always-apply:` line', async () => {
    /* Regression for the “durable mismatch” case: a previously-
       always-apply skill whose SKILL.md body no longer declares the
       flag must stop auto-priming. Without this, the column would
       stick at `true` and the UI pin badge would persist even though
       the file itself no longer opts in. */
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'body-remove', alwaysApply: true }),
    );
    const bodyWithoutKey = `---\nname: body-remove\ndescription: opting out by removing the line.\n---\n\n# Body`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: { body: bodyWithoutKey },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(false);
      expect(result.skill.body).toBe(bodyWithoutKey);
    }
  });

  it('updateSkill flips alwaysApply to false when the body update carries no frontmatter block at all', async () => {
    /* An author rewriting SKILL.md without any YAML frontmatter is an
       implicit opt-out — there is no declaration anywhere, so the
       column should reflect that. */
    const { skill } = await methods.createSkill(
      makeSkillInput({ name: 'body-strip-fm', alwaysApply: true }),
    );
    const plainBody = `# Just the body now — no frontmatter.`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: { body: plainBody },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(false);
    }
  });

  it('updateSkill explicit alwaysApply still wins when body would otherwise flip it to false', async () => {
    /* Higher-precedence sources still override: an API caller sending
       both `alwaysApply: true` and a body without the key keeps the
       column `true`, because explicit top-level is the authoritative
       source for programmatic callers. */
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'explicit-trumps-body' }));
    const bodyWithoutKey = `---\nname: explicit-trumps-body\ndescription: frontmatter block without the flag.\n---\n\n# Body`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: { alwaysApply: true, body: bodyWithoutKey },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill accepts a body typo when an explicit top-level alwaysApply overrides it', async () => {
    /* Validation respects the same precedence as derivation: a caller
       sending `alwaysApply: true` alongside a body whose frontmatter
       carries a typo (`always-apply: tru`) should NOT be rejected —
       the body value is never consulted. Rejecting would be
       user-hostile for programmatic callers that legitimately own the
       explicit field. */
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'typo-overridden' }));
    const bodyWithTypo = `---\nname: typo-overridden\ndescription: body has a broken flag.\nalways-apply: tru\n---\n\n# Body`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: { alwaysApply: true, body: bodyWithTypo },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill accepts a body typo when a structured frontmatter override carries a valid boolean', async () => {
    /* Same precedence rule for the frontmatter-bag layer: a caller
       that sends a structured `frontmatter['always-apply']: true`
       plus a body with a typo is overriding the body at derivation
       time, so the body typo should not reject the update. */
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'fm-overrides-body' }));
    const bodyWithTypo = `---\nname: fm-overrides-body\ndescription: broken body flag.\nalways-apply: yes\n---\n\n# Body`;
    const result = await methods.updateSkill({
      id: skill._id.toString(),
      expectedVersion: skill.version,
      update: {
        frontmatter: {
          name: 'fm-overrides-body',
          description: 'A small demo skill used in tests.',
          'always-apply': true,
        },
        body: bodyWithTypo,
      },
    });
    expect(result.status).toBe('updated');
    if (result.status === 'updated') {
      expect(result.skill.alwaysApply).toBe(true);
    }
  });

  it('updateSkill still rejects a body typo when no higher-precedence source is provided', async () => {
    /* Body-inline validation must still fire when nothing else is
       carrying the value — otherwise a body PATCH with `tru` would
       silently drop the typo + keep the old column value. */
    const { skill } = await methods.createSkill(makeSkillInput({ name: 'typo-body-only' }));
    const bodyWithTypo = `---\nname: typo-body-only\ndescription: nothing else carries the flag.\nalways-apply: tru\n---\n\n# Body`;
    await expect(
      methods.updateSkill({
        id: skill._id.toString(),
        expectedVersion: skill.version,
        update: { body: bodyWithTypo },
      }),
    ).rejects.toMatchObject({ code: 'SKILL_VALIDATION_FAILED' });
  });

  it('createSkill accepts a body typo when an explicit top-level alwaysApply overrides it', async () => {
    /* Same precedence-aware validation on the create path: explicit
       top-level `alwaysApply` short-circuits body-inline validation. */
    const bodyWithTypo = `---\nname: create-typo-overridden\ndescription: broken body flag.\nalways-apply: tru\n---\n\n# Body`;
    const { skill } = await methods.createSkill(
      makeSkillInput({
        name: 'create-typo-overridden',
        alwaysApply: false,
        body: bodyWithTypo,
      }),
    );
    expect(skill.alwaysApply).toBe(false);
  });
});

describe('SkillFile methods', () => {
  it('allows exactly one conditional writer and rejects a stale or deleted revision', async () => {
    await mongoose.models.SkillUploadIntent.init();
    const { skill } = await methods.createSkill(makeSkillInput());
    const input = {
      skillId: skill._id,
      relativePath: 'references/race.md',
      file_id: 'original',
      filename: 'race.md',
      filepath: '/tmp/original',
      source: 'local',
      mimeType: 'text/markdown',
      bytes: 10,
      author: owner._id,
    };
    await methods.upsertSkillFile(input);
    const results = await Promise.allSettled(
      ['a', 'b'].map((revision) =>
        methods.upsertSkillFile({ ...input, expectedFileId: 'original', file_id: revision }),
      ),
    );
    expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
    expect(results.find((result) => result.status === 'rejected')).toMatchObject({
      reason: { code: 'SKILL_FILE_CONFLICT' },
    });
    const current = await methods.getSkillFileByPath(skill._id, input.relativePath);
    expect(['a', 'b']).toContain(current?.file_id);
    expect(
      await mongoose.models.SkillUploadIntent.findOne({ fileId: 'original' }).lean(),
    ).toMatchObject({
      state: 'committed',
      storageKey: '/tmp/original',
      cleanupRequestedAt: expect.any(Date),
    });
    expect(
      (await createSkillLifecycleMethods(mongoose).listAbandonedSkillUploadIntents()).filter(
        (intent) => intent.fileId === 'original',
      ),
    ).toHaveLength(1);
    expect(await methods.getSkillById(skill._id)).toMatchObject({ version: 3, fileCount: 1 });

    // An unconditional authoring/agent write also invalidates a captured editor revision.
    await methods.upsertSkillFile({ ...input, file_id: 'agent' });
    await expect(
      methods.upsertSkillFile({
        ...input,
        expectedFileId: current!.file_id,
        file_id: 'stale-editor',
      }),
    ).rejects.toMatchObject({ code: 'SKILL_FILE_CONFLICT' });
    await methods.deleteSkillFile(skill._id, input.relativePath);
    await expect(
      methods.upsertSkillFile({
        ...input,
        expectedFileId: 'agent',
        file_id: 'resurrected',
      }),
    ).rejects.toMatchObject({ code: 'SKILL_FILE_CONFLICT' });
    expect(await methods.getSkillFileByPath(skill._id, input.relativePath)).toBeNull();
  });

  it('keeps a queued blob safe when replacement CAS fails, then retries it after replacement', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    const input = {
      skillId: skill._id,
      relativePath: 'references/queued.md',
      file_id: 'legacy-original',
      filename: 'queued.md',
      filepath: '/tmp/legacy-original',
      source: 'local',
      mimeType: 'text/markdown',
      bytes: 10,
      author: owner._id,
    };
    await methods.upsertSkillFile(input);
    const spy = jest.spyOn(SkillFile, 'findOneAndUpdate').mockImplementationOnce(
      () =>
        ({
          lean: async () => {
            throw new Error('CAS unavailable');
          },
        }) as never,
    );
    try {
      await expect(
        methods.upsertSkillFile({
          ...input,
          expectedFileId: input.file_id,
          file_id: 'replacement',
        }),
      ).rejects.toThrow('CAS unavailable');
    } finally {
      spy.mockRestore();
    }
    const lifecycle = createSkillLifecycleMethods(mongoose);
    expect(await lifecycle.skillFileExistsForIntent(skill._id.toString(), input.file_id)).toBe(
      true,
    );
    const queued = await lifecycle.listAbandonedSkillUploadIntents();
    expect(queued).toEqual([expect.objectContaining({ fileId: input.file_id })]);
    const ownerId = 'cleanup-worker';
    expect(await lifecycle.claimAbandonedSkillUploadIntent(input.file_id, ownerId, 120_000)).toBe(
      true,
    );
    await expect(
      methods.upsertSkillFile({
        ...input,
        expectedFileId: input.file_id,
        file_id: 'held-replacement',
        cleanupHoldOwner: 'sync-hold',
      }),
    ).rejects.toMatchObject({ code: 'SKILL_FILE_CONFLICT' });
    expect((await methods.getSkillFileByPath(skill._id, input.relativePath))?.file_id).toBe(
      input.file_id,
    );
    expect(
      await lifecycle.scheduleAbandonedSkillUploadIntentRecheck(input.file_id, ownerId, 3_600_000),
    ).toBe(true);
    await lifecycle.releaseAbandonedSkillUploadIntentClaim(input.file_id, ownerId);
    expect(await lifecycle.listAbandonedSkillUploadIntents()).toHaveLength(0);
    await methods.upsertSkillFile({
      ...input,
      expectedFileId: input.file_id,
      file_id: 'replacement',
    });
    expect(await lifecycle.skillFileExistsForIntent(skill._id.toString(), input.file_id)).toBe(
      false,
    );
    expect(await lifecycle.listAbandonedSkillUploadIntents()).toEqual([
      expect.objectContaining({ fileId: input.file_id }),
    ]);
    expect(
      await mongoose.models.SkillUploadIntent.findOne({ fileId: input.file_id }).lean(),
    ).toMatchObject({
      storageKey: input.filepath,
      cleanupRequestedAt: expect.any(Date),
    });
    await lifecycle.beginSkillDeletion(skill._id.toString());
    await lifecycle.beginSkillDeletion(skill._id.toString());
    expect(await mongoose.models.SkillUploadIntent.countDocuments({ skillId: skill._id })).toBe(2);
    expect(
      await mongoose.models.SkillUploadIntent.findOne({ fileId: input.file_id }).lean(),
    ).toMatchObject({
      cleanupRequestedAt: expect.any(Date),
    });
  });

  it('records the storage key rather than a legacy URL for replacement cleanup', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    const input = {
      skillId: skill._id,
      relativePath: 'references/legacy-cloud.md',
      file_id: 'legacy-cloud-original',
      filename: 'legacy-cloud.md',
      filepath: 'https://stale.example.invalid/legacy-cloud.md',
      storageKey: 'eu-west-1/skills/legacy-cloud-original.md',
      storageRegion: 'eu-west-1',
      source: 's3',
      mimeType: 'text/markdown',
      bytes: 10,
      author: owner._id,
    };
    await methods.upsertSkillFile(input);
    await methods.upsertSkillFile({
      ...input,
      file_id: 'legacy-cloud-replacement',
      filepath: 'https://current.example.invalid/legacy-cloud.md',
      storageKey: 'eu-west-1/skills/legacy-cloud-replacement.md',
    });
    expect(
      await mongoose.models.SkillUploadIntent.findOne({ fileId: input.file_id }).lean(),
    ).toMatchObject({ storageKey: input.storageKey });
  });

  it('rejects moving a blob while reusing its file id', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    const input = {
      skillId: skill._id,
      relativePath: 'references/stable.md',
      file_id: 'stable-id',
      filename: 'stable.md',
      filepath: '/tmp/stable-id',
      source: 'local',
      mimeType: 'text/markdown',
      bytes: 10,
      author: owner._id,
    };
    await methods.upsertSkillFile(input);
    await expect(
      methods.upsertSkillFile({ ...input, filepath: '/tmp/other-object' }),
    ).rejects.toMatchObject({
      code: 'SKILL_FILE_CONFLICT',
    });
    expect(await methods.getSkillFileByPath(skill._id, input.relativePath)).toMatchObject({
      file_id: 'stable-id',
      filepath: '/tmp/stable-id',
    });
    expect(await mongoose.models.SkillUploadIntent.countDocuments({ fileId: 'stable-id' })).toBe(0);
  });

  it('creates only absent skill files and leaves the winner intact when creation races', async () => {
    await SkillFile.init();
    const { skill } = await methods.createSkill(makeSkillInput());
    const original = {
      skillId: skill._id,
      relativePath: 'references/new.md',
      file_id: 'browser',
      filename: 'new.md',
      filepath: '/tmp/browser',
      source: 'local',
      mimeType: 'text/markdown',
      bytes: 7,
      author: owner._id,
    };
    await methods.upsertSkillFile(original);
    await expect(
      methods.upsertSkillFile({ ...original, createOnly: true, file_id: 'late-agent' }),
    ).rejects.toMatchObject({ code: 'SKILL_FILE_CONFLICT' });
    expect(await methods.getSkillFileByPath(skill._id, original.relativePath)).toMatchObject({
      file_id: 'browser',
      filepath: '/tmp/browser',
    });
    expect(await methods.getSkillById(skill._id)).toMatchObject({ version: 2, fileCount: 1 });

    const results = await Promise.allSettled(
      ['first', 'second'].map((id) =>
        methods.upsertSkillFile({
          ...original,
          relativePath: 'references/concurrent.md',
          filename: 'concurrent.md',
          filepath: `/tmp/${id}`,
          file_id: id,
          createOnly: true,
        }),
      ),
    );
    expect(results.filter((result) => result.status === 'fulfilled')).toHaveLength(1);
    expect(results.find((result) => result.status === 'rejected')).toMatchObject({
      reason: { code: 'SKILL_FILE_CONFLICT' },
    });
    expect(['first', 'second']).toContain(
      (await methods.getSkillFileByPath(skill._id, 'references/concurrent.md'))?.file_id,
    );
    expect(await methods.getSkillById(skill._id)).toMatchObject({ version: 3, fileCount: 2 });
  });

  it('does not let a delayed read cache old bytes on a replaced file', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    const input = {
      skillId: skill._id,
      relativePath: 'references/cache.md',
      file_id: 'before',
      filename: 'cache.md',
      filepath: '/tmp/before',
      source: 'local',
      mimeType: 'text/markdown',
      bytes: 10,
      author: owner._id,
    };
    await methods.upsertSkillFile(input);
    await methods.upsertSkillFile({ ...input, expectedFileId: 'before', file_id: 'after' });
    await methods.updateSkillFileContent(
      skill._id,
      input.relativePath,
      {
        content: 'stale read',
        isBinary: false,
      },
      'before',
    );
    expect(await methods.getSkillFileByPath(skill._id, input.relativePath)).not.toHaveProperty(
      'content',
    );
    await methods.updateSkillFileContent(
      skill._id,
      input.relativePath,
      {
        content: 'new bytes',
        isBinary: false,
      },
      'after',
    );
    expect(await methods.getSkillFileByPath(skill._id, input.relativePath)).toMatchObject({
      file_id: 'after',
      content: 'new bytes',
    });
  });

  it('upsertSkillFile bumps parent skill version and updates fileCount', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    expect(skill.version).toBe(1);
    expect(skill.fileCount).toBe(0);

    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/parse.sh',
      file_id: 'file-abc',
      filename: 'parse.sh',
      filepath: '/tmp/parse.sh',
      source: 'local',
      mimeType: 'text/plain',
      bytes: 10,
      author: owner._id,
    });

    const updated = await methods.getSkillById(skill._id);
    expect(updated?.version).toBe(2);
    expect(updated?.fileCount).toBe(1);
  });

  it('upsertSkillFile replaces an existing row and bumps version again', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/parse.sh',
      file_id: 'file-1',
      filename: 'parse.sh',
      filepath: '/tmp/v1',
      source: 'local',
      mimeType: 'text/plain',
      bytes: 10,
      author: owner._id,
    });
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/parse.sh',
      file_id: 'file-2',
      filename: 'parse.sh',
      filepath: '/tmp/v2',
      source: 'local',
      mimeType: 'text/plain',
      bytes: 20,
      author: owner._id,
    });
    const after = await methods.getSkillById(skill._id);
    expect(after?.fileCount).toBe(1);
    expect(after?.version).toBe(3);
    const files = await methods.listSkillFiles(skill._id);
    expect(files.length).toBe(1);
    expect(files[0].file_id).toBe('file-2');
  });

  it('upsertSkillFile persists storage metadata', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/parse.sh',
      file_id: 'file-1',
      filename: 'parse.sh',
      filepath: '/tmp/v1',
      storageKey: 'r/us-east-2/uploads/user123/parse.sh',
      storageRegion: 'us-east-2',
      source: 's3',
      mimeType: 'text/plain',
      bytes: 10,
      author: owner._id,
    });

    const files = await methods.listSkillFiles(skill._id);
    expect(files[0].storageKey).toBe('r/us-east-2/uploads/user123/parse.sh');
    expect(files[0].storageRegion).toBe('us-east-2');
  });

  it('throws an explicit error when the upsert returns no saved file row', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    const missingUpsert = {
      lean: jest.fn().mockResolvedValue({
        value: null,
        lastErrorObject: { updatedExisting: false },
      }),
    } as unknown as ReturnType<typeof SkillFile.findOneAndUpdate>;
    const findOneAndUpdateSpy = jest
      .spyOn(SkillFile, 'findOneAndUpdate')
      .mockReturnValueOnce(missingUpsert);
    const bumpSpy = jest.spyOn(Skill, 'findByIdAndUpdate');

    try {
      await expect(
        methods.upsertSkillFile({
          skillId: skill._id,
          relativePath: 'scripts/parse.sh',
          file_id: 'file-1',
          filename: 'parse.sh',
          filepath: '/tmp/v1',
          source: 'local',
          mimeType: 'text/plain',
          bytes: 10,
          author: owner._id,
        }),
      ).rejects.toMatchObject({ code: 'SKILL_FILE_UPSERT_NOT_FOUND' });
      expect(bumpSpy).not.toHaveBeenCalled();
    } finally {
      findOneAndUpdateSpy.mockRestore();
      bumpSpy.mockRestore();
    }
  });

  it('clears all code environment refs when a skill file is upserted (replacement)', async () => {
    /* A re-upload of a skill file replaces the row's contents — but the
     * cached `codeEnvRef` refers to the OLD bytes living in codeapi.
     * Leaving it populated would make the next prime resolve a stale
     * pointer. The upsert MUST $unset codeEnvRef. */
    const { skill } = await methods.createSkill(makeSkillInput());
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/parse.sh',
      file_id: 'file-1',
      filename: 'parse.sh',
      filepath: '/tmp/v1',
      source: 'local',
      mimeType: 'text/plain',
      bytes: 10,
      author: owner._id,
    });

    const entityId = skill._id.toString();
    await methods.updateSkillFileCodeEnvIds([
      {
        skillId: skill._id,
        relativePath: 'scripts/parse.sh',
        codeEnvRef: {
          kind: 'skill',
          id: entityId,
          storage_session_id: 'sess-old',
          file_id: 'file-old',
          version: 1,
        },
      },
    ]);

    /* Sanity: ref is persisted before the replacement. */
    const before = await methods.listSkillFiles(skill._id);
    expect(before[0].codeEnvRef).toMatchObject({
      kind: 'skill',
      storage_session_id: 'sess-old',
      file_id: 'file-old',
      version: 1,
    });

    /* Replace the row with new bytes. */
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/parse.sh',
      file_id: 'file-2',
      filename: 'parse.sh',
      filepath: '/tmp/v2',
      source: 'local',
      mimeType: 'text/plain',
      bytes: 20,
      author: owner._id,
    });

    const after = await methods.listSkillFiles(skill._id);
    expect(after).toHaveLength(1);
    expect(after[0].file_id).toBe('file-2');
    expect(after[0].codeEnvRef).toBeUndefined();
    expect(after[0].codeEnvRefs).toBeUndefined();
  });

  it('deleteSkillFile recounts and bumps version', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/a.sh',
      file_id: 'f1',
      filename: 'a.sh',
      filepath: '/a',
      source: 'local',
      mimeType: 'text/plain',
      bytes: 1,
      author: owner._id,
    });
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'scripts/b.sh',
      file_id: 'f2',
      filename: 'b.sh',
      filepath: '/b',
      source: 'local',
      mimeType: 'text/plain',
      bytes: 1,
      author: owner._id,
    });
    const res = await methods.deleteSkillFile(skill._id, 'scripts/a.sh');
    expect(res.deleted).toBe(true);
    const after = await methods.getSkillById(skill._id);
    expect(after?.fileCount).toBe(1);
    expect(after?.version).toBe(4);
  });

  it('deleteSkillFile preserves a concurrently replaced file when its revision changed', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    await methods.upsertSkillFile({
      skillId: skill._id,
      relativePath: 'references/guide.md',
      file_id: 'current-revision',
      filename: 'guide.md',
      filepath: '/guide',
      source: 'local',
      mimeType: 'text/markdown',
      bytes: 1,
      author: owner._id,
    });

    await expect(
      methods.deleteSkillFile(skill._id, 'references/guide.md', 'stale-revision'),
    ).resolves.toEqual({ deleted: false });
    expect(await methods.getSkillFileByPath(skill._id, 'references/guide.md')).toMatchObject({
      file_id: 'current-revision',
    });
    expect(await methods.getSkillById(skill._id)).toMatchObject({ fileCount: 1, version: 2 });
  });

  it('rejects invalid paths via upsertSkillFile', async () => {
    const { skill } = await methods.createSkill(makeSkillInput());
    await expect(
      methods.upsertSkillFile({
        skillId: skill._id,
        relativePath: '../evil',
        file_id: 'f1',
        filename: 'evil',
        filepath: '/x',
        source: 'local',
        mimeType: 'text/plain',
        bytes: 1,
        author: owner._id,
      }),
    ).rejects.toMatchObject({ code: 'SKILL_FILE_VALIDATION_FAILED' });
  });

  describe('updateSkillFileCodeEnvIds (skill-bundle cache pointer)', () => {
    /**
     * The returned `{matchedCount, modifiedCount}` shape is the diagnostic
     * contract `primeSkillFiles` relies on — a silently-dropped write
     * turns every subsequent prime into a fresh codeapi upload (N×M
     * egress per chat load). Pinning the contract here so the caller
     * can warn-log on partial writes instead of failing closed.
     */
    it('persists codeEnvRef and reports matched/modified counts', async () => {
      const { skill } = await methods.createSkill(makeSkillInput());
      await methods.upsertSkillFile({
        skillId: skill._id,
        relativePath: 'scripts/a.sh',
        file_id: 'f1',
        filename: 'a.sh',
        filepath: '/a',
        source: 'local',
        mimeType: 'text/plain',
        bytes: 1,
        author: owner._id,
      });

      const entityId = skill._id.toString();
      const result = await methods.updateSkillFileCodeEnvIds([
        {
          skillId: skill._id,
          relativePath: 'scripts/a.sh',
          codeEnvRef: {
            kind: 'skill',
            id: entityId,
            storage_session_id: 'session-1',
            file_id: 'file-1',
            version: 1,
          },
        },
      ]);

      expect(result.matchedCount).toBe(1);
      expect(result.modifiedCount).toBe(1);

      const files = await methods.listSkillFiles(skill._id);
      expect(files[0].codeEnvRef).toMatchObject({
        kind: 'skill',
        id: entityId,
        storage_session_id: 'session-1',
        file_id: 'file-1',
        version: 1,
      });
      expect(files[0].codeEnvRefs?.default).toMatchObject({
        kind: 'skill',
        id: entityId,
        storage_session_id: 'session-1',
        file_id: 'file-1',
        version: 1,
      });
    });

    it('retains pointers for both execution profiles', async () => {
      const { skill } = await methods.createSkill(makeSkillInput());
      await methods.upsertSkillFile({
        skillId: skill._id,
        relativePath: 'scripts/a.sh',
        file_id: 'f1',
        filename: 'a.sh',
        filepath: '/a',
        source: 'local',
        mimeType: 'text/plain',
        bytes: 1,
        author: owner._id,
      });
      const base = {
        kind: 'skill' as const,
        id: skill._id.toString(),
        version: 1,
      };

      await methods.updateSkillFileCodeEnvIds([
        {
          skillId: skill._id,
          relativePath: 'scripts/a.sh',
          codeEnvRef: {
            ...base,
            storage_session_id: 'default-session',
            file_id: 'default-file',
            executionProfile: 'default',
          },
        },
        {
          skillId: skill._id,
          relativePath: 'scripts/a.sh',
          codeEnvRef: {
            ...base,
            storage_session_id: 'stateful-session',
            file_id: 'stateful-file',
            executionProfile: 'stateful',
          },
        },
      ]);

      const [file] = await methods.listSkillFiles(skill._id);
      expect(file.codeEnvRefs?.default?.file_id).toBe('default-file');
      expect(file.codeEnvRefs?.stateful?.file_id).toBe('stateful-file');
    });

    it('persists deployment-specific route keys and their reference metadata', async () => {
      const { skill } = await methods.createSkill(makeSkillInput());
      await methods.upsertSkillFile({
        skillId: skill._id,
        relativePath: 'scripts/a.sh',
        file_id: 'f1',
        filename: 'a.sh',
        filepath: '/a',
        source: 'local',
        mimeType: 'text/plain',
        bytes: 1,
        author: owner._id,
      });
      const executionRouteKey = 'stateful:0123456789abcdef0123456789abcdef';

      await methods.updateSkillFileCodeEnvIds([
        {
          skillId: skill._id,
          relativePath: 'scripts/a.sh',
          codeEnvRef: {
            kind: 'skill',
            id: skill._id.toString(),
            version: 1,
            storage_session_id: 'route-session',
            file_id: 'route-file',
            executionProfile: 'stateful',
            executionRouteKey,
          },
        },
      ]);

      const [file] = await methods.listSkillFiles(skill._id);
      expect(file.codeEnvRefs?.[executionRouteKey]).toMatchObject({
        file_id: 'route-file',
        executionProfile: 'stateful',
        executionRouteKey,
      });
    });

    it('reports modifiedCount=0 when no SkillFile rows match the (skillId, relativePath) filter', async () => {
      const { skill } = await methods.createSkill(makeSkillInput());
      const result = await methods.updateSkillFileCodeEnvIds([
        {
          skillId: skill._id,
          relativePath: 'does/not/exist.sh',
          codeEnvRef: {
            kind: 'skill',
            id: 'x',
            storage_session_id: 'sid',
            file_id: 'fid',
            version: 1,
          },
        },
      ]);
      expect(result.modifiedCount).toBe(0);
      expect(result.matchedCount).toBe(0);
    });

    it('returns zero counts when called with an empty update list', async () => {
      const result = await methods.updateSkillFileCodeEnvIds([]);
      expect(result).toEqual({ matchedCount: 0, modifiedCount: 0 });
    });
  });
});

describe('deleteUserSkills', () => {
  it('removes sole-owned skills only', async () => {
    const { skill: mine } = await methods.createSkill(makeSkillInput({ name: 'mine' }));
    await grantOwner(mine._id);

    // Create a second skill owned by someone else
    const shared = await Skill.create({
      name: 'shared',
      description: 'shared skill',
      body: '',
      frontmatter: {},
      category: '',
      author: other._id,
      authorName: other.name ?? 'Other',
      version: 1,
      source: 'inline',
      fileCount: 0,
    });
    const sharedId = (shared.toObject() as { _id: mongoose.Types.ObjectId })._id;
    // Owner user has viewer access to shared — so it's NOT sole-owned
    const viewerRole = (await AccessRole.findOne({
      accessRoleId: AccessRoleIds.SKILL_VIEWER,
    }).lean()) as { _id: mongoose.Types.ObjectId; permBits: number } | null;
    await aclMethods.grantPermission(
      PrincipalType.USER,
      owner._id,
      ResourceType.SKILL,
      sharedId,
      viewerRole!.permBits,
      other._id,
      undefined,
      viewerRole!._id,
    );
    // And other is owner of the shared skill
    const ownerRole = (await AccessRole.findOne({
      accessRoleId: AccessRoleIds.SKILL_OWNER,
    }).lean()) as { _id: mongoose.Types.ObjectId; permBits: number } | null;
    await aclMethods.grantPermission(
      PrincipalType.USER,
      other._id,
      ResourceType.SKILL,
      sharedId,
      ownerRole!.permBits,
      other._id,
      undefined,
      ownerRole!._id,
    );

    const deleted = await methods.deleteUserSkills(owner._id as mongoose.Types.ObjectId);
    expect(deleted).toBe(1);
    // Account deletion queues storage-aware cleanup; it must not remove the
    // Skill row before its blobs have been reconciled.
    expect(await Skill.countDocuments()).toBe(2);
    expect(await Skill.countDocuments({ deletingAt: { $exists: true } })).toBe(1);
    expect(await Skill.countDocuments({ deletionNeedsJournal: true })).toBe(1);
    expect(((await Skill.findById(mine._id).lean()) as { name: string } | null)?.name).toBe(
      `__deleted__${mine._id}`,
    );
    expect(await Skill.countDocuments({ _id: sharedId })).toBe(1);
    const { skill: replacement } = await methods.createSkill(makeSkillInput({ name: 'mine' }));
    expect(replacement._id.toString()).not.toBe(mine._id.toString());
    expect(await mongoose.models.SkillDeletion.countDocuments({ skillId: mine._id })).toBe(0);
    await createSkillLifecycleMethods(mongoose).discoverUnjournaledDeletions();
    expect(await mongoose.models.SkillDeletion.countDocuments({ skillId: mine._id })).toBe(1);
    expect(await Skill.countDocuments({ deletionNeedsJournal: true })).toBe(0);
  });

  it('defers allowlist pruning until storage-aware deletion finishes', async () => {
    const { skill: mine } = await methods.createSkill(makeSkillInput({ name: 'mine' }));
    await grantOwner(mine._id);
    const Agent = mongoose.models.Agent;
    const agent = await Agent.create(makeAgentDoc([mine._id.toString()]));

    const deleted = await methods.deleteUserSkills(owner._id as mongoose.Types.ObjectId);
    expect(deleted).toBe(1);

    const agentAfter = (await Agent.findById(agent._id).lean()) as {
      skills?: string[];
      skills_enabled?: boolean;
    } | null;
    expect(agentAfter?.skills).toEqual([mine._id.toString()]);
    expect(agentAfter?.skills_enabled).toBe(true);
  });

  it('retains the durable retry anchor when account-deletion allowlist cleanup fails', async () => {
    const { skill: mine } = await methods.createSkill(makeSkillInput({ name: 'mine' }));
    await grantOwner(mine._id);
    const Agent = mongoose.models.Agent;
    const agent = await Agent.create(makeAgentDoc([mine._id.toString(), 'keep-me']));

    expect(await methods.deleteUserSkills(owner._id as mongoose.Types.ObjectId)).toBe(1);
    expect(await Skill.findById(mine._id).lean()).toMatchObject({
      deletionNeedsJournal: true,
    });
    // Account erasure removes principal ACLs before the background reconciler runs.
    await AclEntry.deleteMany({ principalId: owner._id });
    const lifecycle = createSkillLifecycleMethods(mongoose);
    await lifecycle.discoverUnjournaledDeletions();

    const failure = jest
      .spyOn(Agent, 'updateMany')
      .mockRejectedValueOnce(new Error('transient outage'));
    try {
      expect(await methods.finalizeSkillDeletion(mine._id.toString())).toMatchObject({
        cleanupComplete: false,
        failedCleanupSteps: ['agent_allowlists'],
      });
    } finally {
      failure.mockRestore();
    }
    expect(await Skill.findById(mine._id).lean()).not.toBeNull();
    expect(await lifecycle.getSkillDeletion(mine._id.toString())).not.toBeNull();

    expect(await methods.finalizeSkillDeletion(mine._id.toString())).toMatchObject({
      cleanupComplete: true,
    });
    expect(await Skill.findById(mine._id).lean()).toBeNull();
    const agentAfter = (await Agent.findById(agent._id).lean()) as { skills?: string[] } | null;
    expect(agentAfter?.skills).toEqual(['keep-me']);
  });
});