Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

29.5 KB
Raw Blame
import { type ChildProcess, spawn } from 'node:child_process';
import {
  chmodSync,
  cpSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readdirSync,
  readFileSync,
  renameSync,
  rmSync,
  utimesSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { basename, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterEach, describe, expect, test, vi } from 'vitest';
import { okVitestBase } from '../../../test-support/vitest.base.ts';
import { BUNDLE_IDS, BUNDLE_SKILL_NAME } from '../src/skill-bundles.ts';
import {
  __testing,
  buildAgentPluginArtifact,
  buildPackSkills,
  buildSkillBundles,
  defaultPaths,
  type SkillBundlePaths,
} from './build-skill-bundles.ts';

const { keepDisplacedTree, peerPublished, sweepRuns } = __testing;

const PUBLISH_CYCLES = 6;
const CONCURRENT_WRITERS = 4;
const SUITE_TEST_TIMEOUT_MS = okVitestBase.test.testTimeout;
const HANG_GUARD_MS = SUITE_TEST_TIMEOUT_MS - 5_000;
const WRITER_BARRIER_BOUND_MS = HANG_GUARD_MS;
const WRITER_PUBLISH_ROUNDS = 3;
const COMPOSER_PATH = fileURLToPath(new URL('./build-skill-bundles.ts', import.meta.url));
const STAGING_ROOT_PREFIX = '.ok-skill-publish-';
const STALE_STAGING_MTIME = new Date('2001-01-01T00:00:00Z');
const PERMISSION_BITS_UNENFORCED = process.platform === 'win32' || process.getuid?.() === 0;

const cleanup: string[] = [];
const children = new Map<ChildProcess, Promise<Error | undefined>>();

function observeClose(child: ChildProcess): Promise<Error | undefined> {
  let error: Error | undefined;
  child.on('error', (cause) => {
    error = cause;
  });
  const closed = new Promise<Error | undefined>((resolve) => {
    child.once('close', () => {
      children.delete(child);
      resolve(error);
    });
  });
  children.set(child, closed);
  return closed;
}

afterEach(async () => {
  const roots = cleanup.splice(0);
  const pending = [...children];
  for (const [child] of pending) {
    if (child.exitCode === null && child.signalCode === null) child.kill();
  }
  await Promise.all(pending.map(([, closed]) => closed));
  while (roots.length > 0) {
    const path = roots.pop();
    if (path) rmSync(path, { recursive: true, force: true });
  }
});

const OBSERVER_STATES = ['ROOT_ABSENT', 'STRADDLE', 'WALK_ERROR', 'COMPLETE', 'PARTIAL'] as const;
type ObserverState = (typeof OBSERVER_STATES)[number];

function listFiles(root: string): string[] {
  const out: string[] = [];
  const walk = (prefix: string): void => {
    for (const entry of readdirSync(prefix === '' ? root : join(root, prefix), {
      withFileTypes: true,
    })) {
      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
      if (entry.isDirectory()) walk(rel);
      else if (entry.isFile()) out.push(rel);
    }
  };
  walk('');
  return out.sort();
}

function listFilesIfPresent(root: string): string[] {
  return existsSync(root) ? listFiles(root) : [];
}

function composedSkillsTreeExpectedFiles(sourceSkills: string): string[] {
  const packsDir = join(sourceSkills, 'packs');
  return [
    ...BUNDLE_IDS.flatMap((bundle) =>
      listFiles(join(sourceSkills, bundle)).map((file) => `${bundle}/${file}`),
    ),
    ...readdirSync(packsDir, { withFileTypes: true })
      .filter((entry) => entry.isDirectory())
      .flatMap((entry) =>
        listFiles(join(packsDir, entry.name)).map((file) => `packs/${entry.name}/${file}`),
      ),
  ].sort();
}

function agentPluginExpectedFiles(sourceSkills: string): string[] {
  return [
    ...BUNDLE_IDS.flatMap((bundle) =>
      listFiles(join(sourceSkills, bundle)).map(
        (file) => `skills/${BUNDLE_SKILL_NAME[bundle]}/${file}`,
      ),
    ),
    'plugin.json',
  ].sort();
}

interface ObserverWitness {
  readonly state: ObserverState;
  readonly expectedFiles: number;
  readonly observedFiles: number | null;
  readonly missingCount: number | null;
  readonly missingSample: string[];
}

interface ObserverTarget {
  readonly label: string;
  readonly hist: Partial<Record<ObserverState, number>>;
  readonly witness: ObserverWitness | null;
}

interface ObserverResult {
  readonly exitReason: string;
  readonly targets: ObserverTarget[];
}

function parseObserverResult(raw: string): ObserverResult {
  const parsed = JSON.parse(raw) as ObserverResult;
  const known = new Set<string>(OBSERVER_STATES);
  for (const target of parsed.targets) {
    for (const state of Object.keys(target.hist)) {
      if (!known.has(state)) {
        throw new Error(
          `observer reported state '${state}' for ${target.label}, which is not one of ${[...known].join(', ')}`,
        );
      }
    }
  }
  return parsed;
}

const OBSERVER_SOURCE = `
import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';

const spec = JSON.parse(readFileSync(process.argv[2], 'utf-8'));
const STATE = ${JSON.stringify(Object.fromEntries(OBSERVER_STATES.map((state) => [state, state])))};

function walk(root, prefix, out) {
  const dir = prefix === '' ? root : join(root, prefix);
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const rel = prefix === '' ? entry.name : prefix + '/' + entry.name;
    if (entry.isDirectory()) walk(root, rel, out);
    else if (entry.isFile()) out.push(rel);
  }
}

const targets = spec.targets.map((t) => ({
  label: t.label,
  path: t.path,
  expect: t.expect,
  hist: {},
  witness: null,
}));

function classify(target) {
  let before;
  try {
    before = statSync(target.path).ino;
  } catch {
    return { state: STATE.ROOT_ABSENT };
  }
  const found = [];
  let torn = false;
  try {
    walk(target.path, '', found);
  } catch {
    torn = true;
  }
  let after = -1;
  try {
    after = statSync(target.path).ino;
  } catch {
    after = -1;
  }
  if (after !== before) return { state: STATE.STRADDLE };
  if (torn) return { state: STATE.WALK_ERROR };
  const seen = new Set(found);
  const missing = target.expect.filter((f) => !seen.has(f));
  if (missing.length === 0) return { state: STATE.COMPLETE };
  return { state: STATE.PARTIAL, missing, observedFiles: found.length };
}

function sweep() {
  for (const target of targets) {
    const result = classify(target);
    target.hist[result.state] = (target.hist[result.state] || 0) + 1;
    if (
      target.witness === null &&
      (result.state === STATE.PARTIAL || result.state === STATE.WALK_ERROR)
    ) {
      target.witness = {
        state: result.state,
        expectedFiles: target.expect.length,
        observedFiles: result.observedFiles ?? null,
        missingCount: result.missing ? result.missing.length : null,
        missingSample: result.missing ? result.missing.slice(0, 8) : [],
      };
    }
  }
}

sweep();
for (const target of targets) {
  target.hist = {};
  target.witness = null;
}
process.stdout.write('ready\\n');

let exitReason = 'liveness-bound';
const bound = Date.now() + spec.livenessBoundMs;
while (Date.now() < bound) {
  sweep();
  if (existsSync(spec.sentinelPath)) {
    exitReason = 'sentinel';
    break;
  }
}

writeFileSync(
  spec.resultPath,
  JSON.stringify({
    exitReason,
    targets: targets.map((t) => ({ label: t.label, hist: t.hist, witness: t.witness })),
  }),
  'utf-8',
);
`;

const WRITER_SOURCE = `
import { existsSync, readFileSync } from 'node:fs';
import { pathToFileURL } from 'node:url';

const spec = JSON.parse(readFileSync(process.argv[2], 'utf-8'));
const composer = await import(pathToFileURL(spec.composerPath).href);
const paths = { skillsDir: spec.skillsDir, distDir: spec.distDir };

process.stdout.write('armed\\n');
const barrierBound = Date.now() + spec.barrierBoundMs;
while (!existsSync(spec.startPath) && Date.now() < barrierBound) {
  await new Promise((resolve) => setTimeout(resolve, 1));
}

for (let round = 0; round < spec.rounds; round += 1) {
  composer.buildSkillBundles(paths);
  composer.buildPackSkills(paths);
  composer.buildAgentPluginArtifact(paths);
}
process.stdout.write('composed\\n');
`;

type WriterOutcome =
  | { readonly writer: number; readonly outcome: 'composed' }
  | {
      readonly writer: number;
      readonly outcome: 'failed' | 'hang-guard';
      readonly exitCode: number | null;
      readonly signal: NodeJS.Signals | null;
      readonly stdout: string;
      readonly stderr: string;
      readonly error: Error | undefined;
    };

type DestinationState = 'absent' | 'empty' | 'occupied';

function plantStagingTree(root: string): string {
  mkdirSync(join(root, 'project'), { recursive: true });
  writeFileSync(join(root, 'project', 'SKILL.md'), 'scratch from an earlier run', 'utf-8');
  return root;
}

function backdate(path: string): void {
  for (const entry of readdirSync(path, { withFileTypes: true })) {
    const child = join(path, entry.name);
    if (entry.isDirectory()) backdate(child);
    else utimesSync(child, STALE_STAGING_MTIME, STALE_STAGING_MTIME);
  }
  utimesSync(path, STALE_STAGING_MTIME, STALE_STAGING_MTIME);
}

function captureConsole(channel: 'warn' | 'error', run: () => void): string[] {
  const lines: string[] = [];
  const spy = vi.spyOn(console, channel).mockImplementation((...args: unknown[]) => {
    lines.push(args.map(String).join(' '));
  });
  try {
    run();
  } finally {
    spy.mockRestore();
  }
  return lines;
}

function errnoFailure(code: string): NodeJS.ErrnoException {
  return Object.assign(new Error(`rename failed with ${code}`), { code });
}

function makeDestination(root: string, state: DestinationState): string {
  const dest = join(root, `destination-${state}`);
  if (state === 'absent') return dest;
  mkdirSync(dest, { recursive: true });
  if (state === 'occupied') writeFileSync(join(dest, 'SKILL.md'), 'a peer published me', 'utf-8');
  return dest;
}

describe('the lost-publish-race arbiter', () => {
  test.each([
    {
      arm: 'a destination-occupied errno is a peer publish even once the destination is gone again',
      state: 'absent',
      failure: errnoFailure('ENOTEMPTY'),
      expected: true,
    },
    {
      arm: 'an occupied destination is a peer publish when the errno does not say so, the only arm Windows rename leaves',
      state: 'occupied',
      failure: errnoFailure('EPERM'),
      expected: true,
    },
    {
      arm: 'an absent destination under a non-occupancy errno is this run failing, not a peer publishing',
      state: 'absent',
      failure: errnoFailure('EPERM'),
      expected: false,
    },
    {
      arm: 'an empty destination under a non-occupancy errno is not a peer publish, since rename would have taken it',
      state: 'empty',
      failure: errnoFailure('EPERM'),
      expected: false,
    },
    {
      arm: 'a thrown value carrying no code still answers from the destination it can observe',
      state: 'occupied',
      failure: null,
      expected: true,
    },
    {
      arm: 'a thrown value carrying no code answers false when nothing occupies the destination',
      state: 'absent',
      failure: undefined,
      expected: false,
    },
  ] as ReadonlyArray<{
    arm: string;
    state: DestinationState;
    failure: unknown;
    expected: boolean;
  }>)('$arm', ({ state, failure, expected }) => {
    const root = mkdtempSync(join(tmpdir(), 'ok-skill-peer-arbiter-'));
    cleanup.push(root);

    expect(peerPublished(makeDestination(root, state), failure)).toBe(expected);
  });

  test('the error this platform really raises for an occupied destination is read as a peer publish', () => {
    const root = mkdtempSync(join(tmpdir(), 'ok-skill-peer-arbiter-real-'));
    cleanup.push(root);
    const staged = join(root, 'staged');
    mkdirSync(staged, { recursive: true });
    writeFileSync(join(staged, 'SKILL.md'), 'this run', 'utf-8');
    const dest = makeDestination(root, 'occupied');

    let failure: unknown;
    try {
      renameSync(staged, dest);
    } catch (err) {
      failure = err;
    }

    expect(
      failure,
      'renaming onto an occupied destination has to fail, or the lost race this arbiter decides never arises',
    ).toBeDefined();
    expect(peerPublished(dest, failure)).toBe(true);
  });
});

describe('skill-bundle publish atomicity', () => {
  test(
    'no concurrent reader observes a published bundle directory incomplete',
    async ({ signal }) => {
      const root = mkdtempSync(join(tmpdir(), 'ok-skill-atomic-publish-'));
      cleanup.push(root);
      const sourceSkills = defaultPaths().skillsDir;
      const paths: SkillBundlePaths = {
        skillsDir: sourceSkills,
        distDir: join(root, 'dist', 'assets', 'skills'),
      };

      const packTargets = readdirSync(join(sourceSkills, 'packs'), { withFileTypes: true })
        .filter((entry) => entry.isDirectory())
        .map((entry) => ({
          name: entry.name,
          files: listFiles(join(sourceSkills, 'packs', entry.name)),
        }))
        .sort((a, b) => b.files.length - a.files.length || a.name.localeCompare(b.name))
        .slice(0, 1)
        .map((pack) => ({
          label: `dist/assets/skills/packs/${pack.name}`,
          path: join(paths.distDir, 'packs', pack.name),
          expect: pack.files,
        }));

      const targets = [
        {
          label: 'dist/assets/skills/project',
          path: join(paths.distDir, 'project'),
          expect: listFiles(join(sourceSkills, 'project')),
        },
        ...packTargets,
        {
          label: 'dist/assets/agent-plugin',
          path: join(paths.distDir, '..', 'agent-plugin'),
          expect: agentPluginExpectedFiles(sourceSkills),
        },
      ];

      buildSkillBundles(paths);
      buildPackSkills(paths);
      buildAgentPluginArtifact(paths);

      const observerPath = join(root, 'observer.mjs');
      const specPath = join(root, 'observer-spec.json');
      const sentinelPath = join(root, 'writer-finished');
      const resultPath = join(root, 'observer-result.json');
      writeFileSync(observerPath, OBSERVER_SOURCE, 'utf-8');
      writeFileSync(
        specPath,
        JSON.stringify({
          targets,
          sentinelPath,
          resultPath,
          livenessBoundMs: HANG_GUARD_MS,
        }),
        'utf-8',
      );

      const observer = spawn(process.execPath, [observerPath, specPath], {
        stdio: ['ignore', 'pipe', 'pipe'],
      });
      const closed = observeClose(observer);
      let observerStderr = '';
      observer.stderr.setEncoding('utf-8');
      observer.stderr.on('data', (chunk: string) => {
        observerStderr += chunk;
      });

      try {
        await new Promise<void>((resolve, reject) => {
          let stdout = '';
          observer.stdout.setEncoding('utf-8');
          observer.stdout.on('data', (chunk: string) => {
            stdout += chunk;
            if (stdout.includes('ready')) resolve();
          });
          void closed.then((error) => {
            reject(
              new Error(
                `observer closed before signalling ready: exit=${observer.exitCode}, signal=${observer.signalCode}, stdout=${stdout}, stderr=${observerStderr}`,
                { cause: error },
              ),
            );
          });
        });

        signal.throwIfAborted();
        for (let cycle = 0; cycle < PUBLISH_CYCLES; cycle += 1) {
          buildSkillBundles(paths);
          buildPackSkills(paths);
          buildAgentPluginArtifact(paths);
        }
        writeFileSync(sentinelPath, '', 'utf-8');
        const error = await closed;
        if (error) throw error;
      } finally {
        if (observer.exitCode === null && observer.signalCode === null) observer.kill();
        await closed;
      }
      signal.throwIfAborted();

      expect(existsSync(resultPath), `observer wrote no result. stderr: ${observerStderr}`).toBe(
        true,
      );
      const result = parseObserverResult(readFileSync(resultPath, 'utf-8'));

      expect(
        result.exitReason,
        'the observer must still be sampling when the publisher finishes, or it proves nothing',
      ).toBe('sentinel');

      expect(
        result.targets
          .filter((target) => (target.hist.COMPLETE ?? 0) > 0)
          .map((target) => target.label),
      ).toEqual(targets.map((target) => target.label));

      const violations = result.targets
        .filter((target) => (target.hist.PARTIAL ?? 0) > 0 || (target.hist.WALK_ERROR ?? 0) > 0)
        .map((target) => ({
          label: target.label,
          partialSamples: target.hist.PARTIAL ?? 0,
          walkErrorSamples: target.hist.WALK_ERROR ?? 0,
          firstWitness: target.witness,
        }));
      expect(
        violations,
        'PARTIAL and WALK_ERROR are the violations. ROOT_ABSENT (the rename window, in which the destination does not exist at all) and STRADDLE (a publish landed mid-walk) are measured and deliberately tolerated: a reader in either window sees no tree rather than a half-populated one.',
      ).toEqual([]);

      for (const target of targets) {
        expect(
          listFilesIfPresent(target.path),
          `${target.label} must hold a complete tree once publishing has finished`,
        ).toEqual(target.expect);
      }
    },
    SUITE_TEST_TIMEOUT_MS,
  );

  test(
    'concurrent composer processes all succeed and leave one complete published tree',
    async ({ signal }) => {
      const root = mkdtempSync(join(tmpdir(), 'ok-skill-writer-race-'));
      cleanup.push(root);
      const sourceSkills = defaultPaths().skillsDir;
      const distDir = join(root, 'dist', 'assets', 'skills');
      const writerPath = join(root, 'writer.mjs');
      const specPath = join(root, 'writer-spec.json');
      writeFileSync(writerPath, WRITER_SOURCE, 'utf-8');
      const startPath = join(root, 'writers-start');
      writeFileSync(
        specPath,
        JSON.stringify({
          composerPath: COMPOSER_PATH,
          skillsDir: sourceSkills,
          distDir,
          startPath,
          barrierBoundMs: WRITER_BARRIER_BOUND_MS,
          rounds: WRITER_PUBLISH_ROUNDS,
        }),
        'utf-8',
      );

      const writers = Array.from({ length: CONCURRENT_WRITERS }, () => {
        const writer = spawn(process.execPath, ['--conditions=development', writerPath, specPath], {
          stdio: ['ignore', 'pipe', 'pipe'],
        });
        return { writer, closed: observeClose(writer) };
      });
      let hangGuardFired = false;
      const deadline = setTimeout(() => {
        hangGuardFired = true;
        for (const { writer } of writers) {
          if (writer.exitCode === null && writer.signalCode === null) writer.kill();
        }
      }, HANG_GUARD_MS);

      let outcomes: WriterOutcome[];
      try {
        const armed: Array<Promise<void>> = [];
        const settled = writers.map(({ writer, closed }, index) => {
          let stdout = '';
          let stderr = '';
          writer.stdout.setEncoding('utf-8');
          writer.stderr.setEncoding('utf-8');
          armed.push(
            new Promise<void>((resolve) => {
              writer.stdout.on('data', (chunk: string) => {
                stdout += chunk;
                if (stdout.includes('armed')) resolve();
              });
              void closed.then(() => resolve());
            }),
          );
          writer.stderr.on('data', (chunk: string) => {
            stderr += chunk;
          });
          return closed.then((error): WriterOutcome => {
            if (!hangGuardFired && !error && writer.exitCode === 0 && stdout.includes('composed')) {
              return { writer: index, outcome: 'composed' };
            }
            return {
              writer: index,
              outcome: hangGuardFired ? 'hang-guard' : 'failed',
              exitCode: writer.exitCode,
              signal: writer.signalCode,
              stdout,
              stderr,
              error,
            };
          });
        });
        await Promise.all(armed);
        signal.throwIfAborted();
        writeFileSync(startPath, '', 'utf-8');
        outcomes = await Promise.all(settled);
      } finally {
        clearTimeout(deadline);
        for (const { writer } of writers) {
          if (writer.exitCode === null && writer.signalCode === null) writer.kill();
        }
        await Promise.all(writers.map(({ closed }) => closed));
      }
      signal.throwIfAborted();

      expect
        .soft(
          hangGuardFired,
          'the hang guard preempted the writers, so this run measured machine speed rather than the publish race',
        )
        .toBe(false);
      expect(outcomes).toEqual(
        Array.from({ length: CONCURRENT_WRITERS }, (_unused, writer) => ({
          writer,
          outcome: 'composed',
        })),
      );

      expect(listFiles(distDir)).toEqual(composedSkillsTreeExpectedFiles(sourceSkills));
      expect(listFiles(join(distDir, '..', 'agent-plugin'))).toEqual(
        agentPluginExpectedFiles(sourceSkills),
      );
    },
    SUITE_TEST_TIMEOUT_MS,
  );

  test.each([
    {
      window: 'a peer has unlinked the composed bundle directory',
      perturb: (distDir: string): void =>
        rmSync(join(distDir, 'discovery'), { recursive: true, force: true }),
    },
    {
      window: 'a peer has left the composed bundle directory half-populated',
      perturb: (distDir: string): void =>
        rmSync(join(distDir, 'project', 'references'), { recursive: true, force: true }),
    },
  ])('the agent-plugin artifact is complete when $window', ({ perturb }) => {
    const root = mkdtempSync(join(tmpdir(), 'ok-skill-peer-window-'));
    cleanup.push(root);
    const sourceSkills = defaultPaths().skillsDir;
    const paths: SkillBundlePaths = {
      skillsDir: sourceSkills,
      distDir: join(root, 'dist', 'assets', 'skills'),
    };
    const outRoot = join(paths.distDir, '..', 'agent-plugin');

    buildSkillBundles(paths);
    perturb(paths.distDir);

    expect(() => buildAgentPluginArtifact(paths)).not.toThrow();
    expect(listFiles(outRoot)).toEqual(agentPluginExpectedFiles(sourceSkills));
  });

  test('the next build reclaims scratch an interrupted run abandoned and spares scratch still in use', () => {
    const root = mkdtempSync(join(tmpdir(), 'ok-skill-stale-staging-'));
    cleanup.push(root);
    const paths: SkillBundlePaths = {
      skillsDir: defaultPaths().skillsDir,
      distDir: join(root, 'dist', 'assets', 'skills'),
    };

    const abandonedRoot = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));
    const abandonedHolder = plantStagingTree(mkdtempSync(`${abandonedRoot}-superseded-`));
    backdate(abandonedRoot);
    backdate(abandonedHolder);

    const workingRoot = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));
    backdate(workingRoot);
    writeFileSync(join(workingRoot, 'project', 'SKILL.md'), 'a peer is still composing', 'utf-8');

    const liveRoot = mkdtempSync(join(root, STAGING_ROOT_PREFIX));

    buildSkillBundles(paths);

    expect(
      readdirSync(root)
        .filter((name) => name.startsWith(STAGING_ROOT_PREFIX))
        .sort(),
      "an interrupted run runs no finally, so its staging root and displaced-tree holder outlive it and the next build has to reclaim both; a peer whose only recent write is deep inside its root is still working, so its root is not the next build's to take",
    ).toEqual([basename(liveRoot), basename(workingRoot)].sort());
  });

  test('the displaced tree a stranded publish keeps survives the next build that sweeps beside it', () => {
    const root = mkdtempSync(join(tmpdir(), 'ok-skill-kept-tree-'));
    cleanup.push(root);
    const paths: SkillBundlePaths = {
      skillsDir: defaultPaths().skillsDir,
      distDir: join(root, 'dist', 'assets', 'skills'),
    };

    const stagingRoot = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));
    const holder = plantStagingTree(mkdtempSync(`${stagingRoot}-superseded-`));

    const outcome = keepDisplacedTree(holder);
    expect(outcome.kept, 'the tree was moved into the class the sweep spares').toBe(true);
    const kept = outcome.root;
    expect(existsSync(holder), 'the holder is moved, not copied').toBe(false);
    expect(listFiles(kept), 'the displaced tree moves with it').toEqual(['project/SKILL.md']);

    backdate(kept);
    backdate(stagingRoot);

    const sweepsBefore = sweepRuns();
    const warnings = captureConsole('warn', () => {
      buildSkillBundles(paths);
      buildPackSkills(paths);
      buildAgentPluginArtifact(paths);
    });

    expect(
      sweepRuns() - sweepsBefore,
      'all three composer functions open a staging root beside this dist, and the sweep is the expensive part, so it runs once for the build rather than once per function',
    ).toBe(1);
    expect(
      warnings.filter((line) => line.includes(kept)),
      'the sweep enumerates this directory on every run, so it is where a kept tree can still be found by an operator who did not see the build that made it — once for the build, not once per composer function that sweeps',
    ).toHaveLength(1);
    expect(
      listFilesIfPresent(kept),
      "the stranded publish's error names a path inside this tree as the only copy of what it displaced, so no later build may reclaim it however old it looks",
    ).toEqual(['project/SKILL.md']);
    expect(
      existsSync(stagingRoot),
      'the staging root beside it carries no such promise and is still reclaimed',
    ).toBe(false);
  });

  test.skipIf(PERMISSION_BITS_UNENFORCED)(
    'a candidate the sweep cannot finish walking is left alone rather than removed',
    () => {
      const root = mkdtempSync(join(tmpdir(), 'ok-skill-sealed-staging-'));
      cleanup.push(root);
      const paths: SkillBundlePaths = {
        skillsDir: defaultPaths().skillsDir,
        distDir: join(root, 'dist', 'assets', 'skills'),
      };

      const unreadable = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));
      const abandoned = plantStagingTree(mkdtempSync(join(root, STAGING_ROOT_PREFIX)));
      backdate(unreadable);
      backdate(abandoned);
      const sealed = join(unreadable, 'project');
      chmodSync(sealed, 0o000);

      try {
        expect(
          () => readdirSync(sealed),
          'the walk has to really fail for this to be the case under test, which it will not when the suite runs as root',
        ).toThrow();

        const warnings = captureConsole('warn', () => buildSkillBundles(paths));

        expect(existsSync(abandoned), 'the sweep ran').toBe(false);
        expect(
          existsSync(unreadable),
          "a candidate whose age the sweep could not establish is not the sweep's to take",
        ).toBe(true);
        const named = warnings.filter((line) => line.includes(unreadable));
        expect(
          named,
          "and the candidate it declined is nameable from this build's own output",
        ).toHaveLength(1);
        expect(
          named[0],
          'as a decline, not as a removal that was attempted and failed, which is what reading an inspection failure as an age produces',
        ).not.toContain('could not remove');
      } finally {
        chmodSync(sealed, 0o755);
      }
    },
  );

  test.skipIf(PERMISSION_BITS_UNENFORCED)(
    'a staging parent the sweep cannot list at all is reported rather than passed over in silence',
    () => {
      const root = mkdtempSync(join(tmpdir(), 'ok-skill-unlistable-parent-'));
      cleanup.push(root);
      const paths: SkillBundlePaths = {
        skillsDir: defaultPaths().skillsDir,
        distDir: join(root, 'dist', 'assets', 'skills'),
      };

      chmodSync(root, 0o300);
      let warnings: string[] = [];
      let sweepsDuringBuild = 0;
      try {
        expect(
          () => readdirSync(root),
          'the listing has to really fail for this to be the case under test, which it will not when the suite runs as root',
        ).toThrow();

        const sweepsBefore = sweepRuns();
        warnings = captureConsole('warn', () => {
          buildSkillBundles(paths);
          buildPackSkills(paths);
          buildAgentPluginArtifact(paths);
        });
        sweepsDuringBuild = sweepRuns() - sweepsBefore;
      } finally {
        chmodSync(root, 0o700);
      }

      expect(
        sweepsDuringBuild,
        "a sweep that could not list the parent has reclaimed nothing, so it does not spend the build's one attempt: each composer function tries again",
      ).toBe(3);
      expect(
        warnings.filter((line) => line.includes(root)),
        'a sweep that cannot run at all leaves nothing on the filesystem for an operator to find later, so the build output is the only place it can surface — once, not once per composer function',
      ).toHaveLength(1);
    },
  );

  test('a keep that cannot move the tree reports it and does not claim the tree was kept', () => {
    const root = mkdtempSync(join(tmpdir(), 'ok-skill-keep-failure-'));
    cleanup.push(root);
    const absent = join(root, `${STAGING_ROOT_PREFIX}gone-superseded-gone`);

    let outcome: { kept: boolean; root: string } | undefined;
    const errors = captureConsole('error', () => {
      outcome = keepDisplacedTree(absent);
    });

    expect(
      outcome,
      'the caller has to be able to tell a kept tree from one the keep could not move, because its message claims one of the two',
    ).toEqual({ kept: false, root: absent });
    expect(errors).toHaveLength(1);
    expect(errors[0]).toContain('[build-skill-bundles]');
    expect(errors[0]).toContain(absent);
    expect(
      errors[0],
      "reported in the same reason form this file's other recovery steps use",
    ).toContain('ENOENT');
  });

  test('a bundle whose source SKILL.md is absent still fails the build loudly', () => {
    const root = mkdtempSync(join(tmpdir(), 'ok-skill-absent-source-'));
    cleanup.push(root);
    const skillsDir = join(root, 'skills');
    const distDir = join(root, 'dist', 'assets', 'skills');
    cpSync(defaultPaths().skillsDir, skillsDir, { recursive: true });
    rmSync(join(skillsDir, 'project', 'SKILL.md'));

    expect(() => buildSkillBundles({ skillsDir, distDir })).toThrow(/SKILL\.md/);
    expect(existsSync(join(distDir, 'project'))).toBe(false);
  });
});