Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

36.6 KB
Raw Blame
import { execFileSync } from 'node:child_process';
import {
  chmodSync,
  mkdirSync,
  mkdtempSync,
  renameSync,
  rmSync,
  statSync,
  symlinkSync,
  utimesSync,
  writeFileSync,
} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test } from 'vitest';
import {
  type ContractSpec,
  delivered,
  deliveriesFor,
  type ForkedContractProcess,
  type ForkedWatcherProcess,
  forkWatcherProcess,
  type LoggedError,
  type ReadinessScenario,
  type Recovery,
  reportOf,
  unlinked,
  type WatcherEntry,
  type WatcherProcessReport,
} from './forked-watcher-process.test-helper.ts';

interface WatchedFile {
  watch: string[];
  target: string;
}

interface EntryCase {
  watcher: string;
  entry: WatcherEntry;
}

interface UnreadableCase extends EntryCase {
  unreadable: 'skill directory' | 'skills root' | 'directory';
}

interface RecoveryCase extends UnreadableCase {
  recovery: Recovery;
}

const ENTRIES: EntryCase[] = [
  { watcher: 'startManagedArtifactWatcher', entry: 'managed' },
  { watcher: 'startConfigFileWatcher', entry: 'config' },
  { watcher: 'startMultiPathConfigFileWatcher', entry: 'multi-config' },
];

const UNREADABLE_CASES: UnreadableCase[] = [
  { watcher: 'startManagedArtifactWatcher', entry: 'managed', unreadable: 'skill directory' },
  { watcher: 'startManagedArtifactWatcher', entry: 'managed', unreadable: 'skills root' },
  { watcher: 'startConfigFileWatcher', entry: 'config', unreadable: 'directory' },
  { watcher: 'startMultiPathConfigFileWatcher', entry: 'multi-config', unreadable: 'directory' },
];

const RECOVERY_CASES: RecoveryCase[] = UNREADABLE_CASES.flatMap((unreadableCase) =>
  (['readable', 'removed'] as const).map((recovery) => ({ ...unreadableCase, recovery })),
);

const INITIAL: Record<WatcherEntry, string> = {
  managed: 'demo skill',
  config: 'theme: light\n',
  'multi-config': '*.tmp\n',
};

const PARTIAL = 'half-writ';
const COMPLETE = 'half-written, then completed\n';
const HELD_CHANGE = 'changed while the next sample was held\n';
const READABLE_AGAIN = 'edited once readable\n';
const SAME_SIZE_REPLACEMENT = 'theme: dark!\n';
const IN_PLACE_REWRITE = 'DEMO SKILL';

function write(path: string, content: string): void {
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(path, content, 'utf-8');
}

let fixture: string;
let harness: ForkedWatcherProcess | undefined;
const madeUnreadable: string[] = [];

beforeEach(() => {
  fixture = mkdtempSync(join(tmpdir(), 'ok-polled-contract-'));
});
afterEach(async () => {
  await harness?.close();
  harness = undefined;
  for (const dir of madeUnreadable.splice(0)) chmodSync(dir, 0o755);
  rmSync(fixture, { recursive: true, force: true });
});

function skillsRoot(): string {
  return join(fixture, 'skills');
}

function leaf(...segments: string[]): string {
  return join(skillsRoot(), ...segments, 'SKILL.md');
}

function watchedFile(entry: WatcherEntry, scenario: ReadinessScenario): WatchedFile {
  const project = join(fixture, 'project');
  const file: WatchedFile =
    entry === 'managed'
      ? { watch: [skillsRoot()], target: leaf('demo') }
      : entry === 'config'
        ? {
            watch: [join(project, '.ok', 'config.yml')],
            target: join(project, '.ok', 'config.yml'),
          }
        : {
            watch: [join(project, '.okignore'), join(project, '.gitignore')],
            target: join(project, '.okignore'),
          };
  mkdirSync(dirname(file.target), { recursive: true });
  if (entry === 'multi-config') write(join(project, '.gitignore'), 'dist/\n');
  if (scenario === 'edit') write(file.target, INITIAL[entry]);
  return file;
}

async function watchFrom(
  entry: WatcherEntry,
  watch: string[],
  coarseTimestampsAt?: string,
): Promise<ForkedContractProcess> {
  const spec: ContractSpec = { mode: 'contract', entry, watch, coarseTimestampsAt };
  const run = forkWatcherProcess(spec);
  harness = run;
  await run.until(
    'the watcher to start and every baseline it registered to be taken',
    (reports) => reportOf(reports, 'settled') !== undefined,
  );
  return run;
}

function unreadableScope(
  { entry, unreadable }: UnreadableCase,
  { watch, target }: WatchedFile,
): { dir: string; failing: string[] } {
  if (entry !== 'managed') return { dir: dirname(target), failing: watch };
  if (unreadable === 'skills root') return { dir: skillsRoot(), failing: [skillsRoot(), target] };
  return { dir: dirname(target), failing: [target] };
}

function accessDenials(logged: readonly LoggedError[] = []): LoggedError[] {
  return logged.filter((entry) => entry.code === 'EACCES');
}

function asLogLines(logged: readonly LoggedError[]): string[] {
  return logged.map((entry) => `${entry.level} ${entry.code} ${entry.path}: ${entry.message}`);
}

function reportsFor(
  logged: readonly LoggedError[] | undefined,
  code: string,
  path: string,
): LoggedError[] {
  return (logged ?? []).filter((entry) => entry.code === code && entry.path === path);
}

function reportsBefore(
  reports: readonly WatcherProcessReport[],
  kind: WatcherProcessReport['kind'],
): readonly WatcherProcessReport[] {
  const at = reports.findIndex((report) => report.kind === kind);
  return at === -1 ? reports : reports.slice(0, at);
}

function failingSampleOf({ unreadable }: UnreadableCase, { target }: WatchedFile): string {
  return unreadable === 'skills root' ? skillsRoot() : target;
}

function sampledEveryPollOf({ entry }: UnreadableCase, { target }: WatchedFile): string {
  return entry === 'managed' ? skillsRoot() : target;
}

function failingOnceMore({ unreadable, recovery }: RecoveryCase, failing: string[]): string[] {
  const recreatedRootListsNothing = unreadable === 'skills root' && recovery === 'removed';
  return recreatedRootListsNothing ? [skillsRoot()] : failing;
}

describe('startManagedArtifactWatcher reports SKILL.md at a skills root and one directory down', () => {
  test('reports the root SKILL.md, a skill directory SKILL.md and one reached through a symlinked skill directory, and nothing deeper or beside them', async () => {
    const outside = join(fixture, 'outside');
    const nestedTwoDown = leaf('demo', 'nested');
    const notesBesideASkill = join(skillsRoot(), 'demo', 'NOTES.md');
    const fileAtTheRoot = join(skillsRoot(), 'README.md');
    const outsideTheLeafSet = [nestedTwoDown, notesBesideASkill, fileAtTheRoot];
    write(leaf(), 'root skill');
    write(leaf('demo'), 'demo skill');
    write(nestedTwoDown, 'nested skill');
    write(notesBesideASkill, 'notes');
    write(fileAtTheRoot, 'readme');
    write(join(outside, 'linked-skill', 'SKILL.md'), 'linked skill');
    write(join(outside, 'late-skill', 'SKILL.md'), 'late skill');
    symlinkSync(join(outside, 'linked-skill'), join(skillsRoot(), 'linked'), 'junction');
    const run = await watchFrom('managed', [skillsRoot()]);

    for (const path of outsideTheLeafSet) {
      writeFileSync(path, 'edited, never to be reported', 'utf-8');
    }
    writeFileSync(leaf(), 'root skill, edited', 'utf-8');
    writeFileSync(leaf('demo'), 'demo skill, edited', 'utf-8');
    writeFileSync(join(outside, 'linked-skill', 'SKILL.md'), 'linked skill, edited', 'utf-8');
    symlinkSync(join(outside, 'late-skill'), join(skillsRoot(), 'late'), 'junction');

    const nothingOutsideTheLeafSet = (reports: readonly WatcherProcessReport[]): void => {
      expect(
        reports.filter(
          (report) =>
            (report.kind === 'change' || report.kind === 'unlink') &&
            outsideTheLeafSet.includes(report.path),
        ),
        'the watcher reported a path other than <root>/SKILL.md or <root>/<entry>/SKILL.md',
      ).toEqual([]);
    };
    const expected: Array<[string, string]> = [
      [leaf(), 'root skill, edited'],
      [leaf('demo'), 'demo skill, edited'],
      [leaf('linked'), 'linked skill, edited'],
      [leaf('late'), 'late skill'],
    ];
    await run.until(
      'the watcher to report the root SKILL.md, the skill directory SKILL.md, the edited one behind a symlink and the one behind a symlink made after start',
      (reports) => {
        nothingOutsideTheLeafSet(reports);
        return expected.every(([path, content]) => delivered(reports, path, content));
      },
    );

    writeFileSync(leaf('demo'), 'demo skill, edited again', 'utf-8');
    await run.until(
      'a later report, after which every report the earlier changes could produce has arrived',
      (reports) => {
        nothingOutsideTheLeafSet(reports);
        return delivered(reports, leaf('demo'), 'demo skill, edited again');
      },
    );
  });
});

describe('startManagedArtifactWatcher when a skill directory stops being a readable directory', () => {
  test('reports a SKILL.md unlinked when its skill directory is replaced by a regular file, and keeps reporting the others', async () => {
    write(leaf('demo'), 'demo skill');
    write(leaf('kept'), 'kept skill');
    const run = await watchFrom('managed', [skillsRoot()]);

    rmSync(join(skillsRoot(), 'demo'), { recursive: true, force: true });
    writeFileSync(
      join(skillsRoot(), 'demo'),
      'a regular file where the skill directory was',
      'utf-8',
    );
    await run.until(`onUnlink to report ${leaf('demo')}`, (reports) => {
      expect(
        deliveriesFor(reports, leaf('demo')),
        'the watcher reported the SKILL.md under a directory turned into a file as changed, not unlinked',
      ).toEqual([]);
      return unlinked(reports, leaf('demo'));
    });

    writeFileSync(leaf('kept'), 'kept skill, edited', 'utf-8');
    await run.until('the watcher to keep reporting the other skill', (reports) =>
      delivered(reports, leaf('kept'), 'kept skill, edited'),
    );
  });

  describe.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
    'while a directory on the path is unreadable (EACCES; chmod does not bind root or Windows)',
    () => {
      test.each([{ unreadable: 'skill directory' }, { unreadable: 'skills root' }])(
        'keeps a SKILL.md, reporting it neither unlinked nor changed, while its $unreadable is briefly unreadable, then reports its next edit',
        async ({ unreadable }) => {
          write(leaf('demo'), 'demo skill');
          const dir = unreadable === 'skills root' ? skillsRoot() : join(skillsRoot(), 'demo');
          const run = await watchFrom('managed', [skillsRoot()]);

          madeUnreadable.push(dir);
          run.send({ op: 'unreadable-until-sampled', dir, leaf: leaf('demo') });
          const onlyTheEdit = (reports: readonly WatcherProcessReport[]): void => {
            expect(
              unlinked(reports, leaf('demo')),
              `onUnlink reported ${leaf('demo')} although only its ${unreadable} was unreadable: ` +
                'a sample that fails with EACCES must keep the last observation, not read as a deletion',
            ).toBe(false);
            expect(
              deliveriesFor(reports, leaf('demo')),
              'the watcher reported the untouched SKILL.md as changed after the directory was readable again',
            ).not.toContain('demo skill');
          };
          await run.until(
            `the watcher to sample ${leaf('demo')} while its ${unreadable} was unreadable, and the harness to restore it`,
            (reports) => {
              onlyTheEdit(reports);
              return reportOf(reports, 'readable-again') !== undefined;
            },
          );

          writeFileSync(leaf('demo'), 'demo skill, edited once readable again', 'utf-8');
          await run.until(
            `onChange to report the edit made once the ${unreadable} was readable again`,
            (reports) => {
              onlyTheEdit(reports);
              return delivered(reports, leaf('demo'), 'demo skill, edited once readable again');
            },
          );
        },
      );
    },
  );
});

describe('a file written in two steps is reported only once its size holds', () => {
  test.each(
    ENTRIES.flatMap((entryCase) =>
      (['create', 'edit'] as const).map((scenario) => ({ ...entryCase, scenario })),
    ),
  )(
    '$watcher never reports a $scenario half-written, and reports it once the second half lands',
    async ({ entry, scenario }) => {
      const { watch, target } = watchedFile(entry, scenario);
      const run = await watchFrom(entry, watch);

      run.send({ op: 'write-in-two-steps', path: target, partial: PARTIAL, complete: COMPLETE });
      await run.until(
        `the watcher to report ${target} with the contents of both halves, never the first half alone`,
        (reports) => {
          expect(
            deliveriesFor(reports, target),
            `the watcher reported ${target} holding only the first half of a two-step write ` +
              `(first half written at a startup timer tick: ${reportOf(reports, 'partial-written')?.atStartupTimerTick})`,
          ).not.toContain(PARTIAL);
          return delivered(reports, target, COMPLETE);
        },
      );
      expect(
        reportOf(run.reports(), 'partial-sampled'),
        'the second half is written only after the watcher has sampled the first',
      ).toBeDefined();
    },
  );
});

describe('closing a watcher', () => {
  test.each(ENTRIES)(
    '$watcher cleanup, called while the watcher samples a pending change, resolves when called twice, reports nothing once resolved, and leaves nothing that keeps the process alive',
    async ({ entry }) => {
      const { watch, target } = watchedFile(entry, 'edit');
      const run = await watchFrom(entry, watch);

      run.send({
        op: 'close-while-sampling',
        path: target,
        content: 'changed just before cleanup',
      });
      await run.until(
        `the watcher to sample the change to ${target} once and begin sampling it again, when cleanup is called`,
        (reports) => reportOf(reports, 'closing') !== undefined,
      );
      await run.until(
        'cleanup to resolve, twice',
        (reports) => reportOf(reports, 'closed') !== undefined,
      );
      await run.until(
        'the watcher process to fall idle on its own once cleanup resolved (a timer or handle the watcher left armed keeps it running)',
        (reports) => reportOf(reports, 'quiesced') !== undefined,
      );
      expect(
        reportOf(run.reports(), 'quiesced')?.eventsAfterClose,
        'the watcher called back after its cleanup resolved',
      ).toEqual([]);
      await run.until('the idle watcher process to exit', () => run.exitStatus() !== undefined);
      expect(run.exitStatus(), 'the watcher process exits by itself once idle').toEqual({
        code: 0,
        signal: null,
      });
    },
  );
});

describe.skipIf(process.platform === 'win32')(
  'a watcher never begins a sample of a path while its previous sample is in flight (the threadpool barrier is a POSIX FIFO)',
  () => {
    test.each(ENTRIES)(
      '$watcher begins no further sample of a changed file while that sample is held on the only libuv worker, then reports the change',
      async ({ entry }) => {
        const { watch, target } = watchedFile(entry, 'edit');
        const barrier = join(fixture, 'threadpool-barrier');
        execFileSync('mkfifo', [barrier]);
        const run = await watchFrom(entry, watch);

        run.send({ op: 'hold-next-sample', path: target, content: HELD_CHANGE, barrier });
        await run.until(
          `the watcher to begin sampling ${target} after it changed`,
          (reports) => reportOf(reports, 'sample-held') !== undefined,
        );
        await run.until(
          'every timer the watcher had pending while that sample was held to fire or be cleared (this over-constrains, by design, a watcher that keeps a timer pending for longer than the test budget)',
          (reports) => reportOf(reports, 'overlap-checked') !== undefined,
        );
        const checked = reportOf(run.reports(), 'overlap-checked');
        expect(
          checked?.samplesBegunWhileHeld,
          `the watcher began another sample of ${target} (or another listing of its skills root) while the previous sample was still in flight ` +
            `(${checked?.timersWaitedOut} pending timer(s) waited out): a slow filesystem would pile samples up behind the libuv threadpool the server shares`,
        ).toBe(0);

        await run.until(
          `onChange to report the change to ${target} once the held sample was released`,
          (reports) => delivered(reports, target, HELD_CHANGE),
        );
      },
    );
  },
);

describe.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
  'an error the watcher keeps silent to its callers is reported at some logger level, and not again while it persists (EACCES; chmod does not bind root or Windows)',
  () => {
    test.each(UNREADABLE_CASES)(
      '$watcher reports the EACCES of every path it cannot read while its $unreadable is unreadable, at least once, and not again in a further poll',
      async (unreadableCase) => {
        const file = watchedFile(unreadableCase.entry, 'edit');
        const { dir, failing } = unreadableScope(unreadableCase, file);
        const run = await watchFrom(unreadableCase.entry, file.watch);

        madeUnreadable.push(dir);
        run.send({ op: 'unreadable-across-polls', dir, path: file.target });
        await run.until(
          `the watcher to sample ${file.target} in polls that fail with EACCES, until a poll begun with the ${unreadableCase.unreadable} already unreadable and one more poll have both settled`,
          (reports) => {
            expect(
              unlinked(reports, file.target),
              `onUnlink reported ${file.target} although only its ${unreadableCase.unreadable} was unreadable: ` +
                'the watcher read the EACCES as a deletion instead of keeping the last observation and reporting the error',
            ).toBe(false);
            return reportOf(reports, 'error-reports') !== undefined;
          },
        );

        const errorReports = reportOf(run.reports(), 'error-reports');
        const onceEstablished = accessDenials(errorReports?.onceEstablished);
        const afterAnotherPoll = accessDenials(errorReports?.afterAnotherPoll);
        for (const path of failing) {
          expect(
            afterAnotherPoll.filter((entry) => entry.path === path),
            `the watcher never reported the EACCES of ${path} at any logger level: an error it keeps silent to its callers must be reported, not swallowed`,
          ).not.toEqual([]);
        }
        expect(
          asLogLines(afterAnotherPoll),
          'the watcher reported the EACCES again in a further poll while it persisted, instead of once per path and error code',
        ).toEqual(asLogLines(onceEstablished));
      },
    );
  },
);

describe.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
  'an error the watcher reported is reported again once the path has read as present or absent and then fails once more (EACCES; chmod does not bind root or Windows)',
  () => {
    test.each(RECOVERY_CASES)(
      '$watcher reports the EACCES of every path it cannot read in each episode when its $unreadable is unreadable, then $recovery, then unreadable once more',
      async (recoveryCase) => {
        const { unreadable, recovery } = recoveryCase;
        const file = watchedFile(recoveryCase.entry, 'edit');
        const { dir, failing } = unreadableScope(recoveryCase, file);
        const run = await watchFrom(recoveryCase.entry, file.watch);

        madeUnreadable.push(dir);
        run.send({
          op: 'unreadable-again-after-recovery',
          dir,
          failingAt: failingSampleOf(recoveryCase, file),
          sampledEveryPoll: sampledEveryPollOf(recoveryCase, file),
          recovery,
          aside: join(fixture, 'aside'),
        });
        await run.until(
          `the watcher to sample through an unreadable episode of its ${unreadable}, its recovery (${recovery}) and a second unreadable episode, each established by a poll begun with it in place`,
          (reports) => {
            expect(
              unlinked(reportsBefore(reports, 'removed'), file.target),
              `onUnlink reported ${file.target} while its ${unreadable} was only unreadable: ` +
                'the watcher read the EACCES as a deletion instead of keeping the last observation and reporting the error',
            ).toBe(false);
            return reportOf(reports, 'error-reports-across-recovery') !== undefined;
          },
        );

        const episodes = reportOf(run.reports(), 'error-reports-across-recovery');
        for (const path of failing) {
          expect(
            reportsFor(episodes?.firstEpisode, 'EACCES', path),
            `the watcher never reported the EACCES of ${path} in the first unreadable episode, at any logger level`,
          ).not.toEqual([]);
        }
        for (const path of failingOnceMore(recoveryCase, failing)) {
          expect(
            reportsFor(episodes?.afterRecovery, 'EACCES', path),
            `the watcher reported the EACCES of ${path} in the first unreadable episode but not in the one after its ${unreadable} was ${recovery}: ` +
              'a path that reads as present or absent again must have its next failure reported, or a second episode is kept silent',
          ).not.toEqual([]);
        }
      },
    );
  },
);

describe.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
  'an error the watcher keeps silent to its callers is reported once per error code, so a path that keeps failing with a new code is reported again (EACCES, then ELOOP; chmod does not bind root or Windows)',
  () => {
    test.each(UNREADABLE_CASES)(
      '$watcher reports the ELOOP of every path it cannot read once its $unreadable, unreadable until then, becomes a symlink loop, and not again while it stays one',
      async (unreadableCase) => {
        const { unreadable } = unreadableCase;
        const file = watchedFile(unreadableCase.entry, 'edit');
        const { dir, failing } = unreadableScope(unreadableCase, file);
        const failingAt = failingSampleOf(unreadableCase, file);
        const run = await watchFrom(unreadableCase.entry, file.watch);

        madeUnreadable.push(dir);
        run.send({
          op: 'error-code-changes-while-failing',
          dir,
          failingAt,
          aside: join(fixture, 'aside'),
        });
        await run.until(
          `the watcher to sample ${failingAt} in polls that fail with EACCES and then, once the ${unreadable} is a symlink loop, with ELOOP, each established by a poll begun with it in place`,
          (reports) => {
            expect(
              unlinked(reports, file.target),
              `onUnlink reported ${file.target} while its ${unreadable} was only unreadable and then a symlink loop: ` +
                'the watcher read EACCES or ELOOP as a deletion instead of keeping the last observation and reporting the error',
            ).toBe(false);
            return reportOf(reports, 'error-reports-across-code-change') !== undefined;
          },
        );

        const codes = reportOf(run.reports(), 'error-reports-across-code-change');
        for (const path of failing) {
          expect(
            reportsFor(codes?.beforeChange, 'EACCES', path),
            `the watcher never reported the EACCES of ${path} before its error code changed, at any logger level`,
          ).not.toEqual([]);
          expect(
            reportsFor(codes?.afterChange, 'ELOOP', path),
            `the watcher reported the EACCES of ${path} but not the ELOOP it failed with next: ` +
              'reports are once per path and error code, so a new code on a path that keeps failing must be reported',
          ).not.toEqual([]);
          expect(
            asLogLines(reportsFor(codes?.whileItPersists, 'ELOOP', path)),
            `the watcher reported the ELOOP of ${path} again in further polls while it persisted, instead of once per path and error code`,
          ).toEqual([]);
        }
      },
    );
  },
);

describe('startManagedArtifactWatcher when a SKILL.md or its skill directory goes away', () => {
  test('reports a SKILL.md unlinked, never changed, once a directory takes its place', async () => {
    write(leaf('demo'), 'demo skill');
    const run = await watchFrom('managed', [skillsRoot()]);

    rmSync(leaf('demo'));
    mkdirSync(leaf('demo'));
    await run.until(`onUnlink to report ${leaf('demo')}, now a directory`, (reports) => {
      expect(
        deliveriesFor(reports, leaf('demo')),
        'the watcher reported a SKILL.md that became a directory as changed: only a regular file reads as present',
      ).toEqual([]);
      return unlinked(reports, leaf('demo'));
    });
  });

  test('reports a deleted SKILL.md unlinked once, and not again while it stays deleted', async () => {
    write(leaf('demo'), 'demo skill');
    write(leaf('kept'), 'kept skill');
    const run = await watchFrom('managed', [skillsRoot()]);

    rmSync(leaf('demo'));
    await run.until(`onUnlink to report ${leaf('demo')}`, (reports) =>
      unlinked(reports, leaf('demo')),
    );
    for (const content of ['kept skill, edited once', 'kept skill, edited twice']) {
      writeFileSync(leaf('kept'), content, 'utf-8');
      await run.until(
        `a later report of ${leaf('kept')}, polls after the deletion was reported`,
        (reports) => delivered(reports, leaf('kept'), content),
      );
    }
    expect(
      run.reports().filter((report) => report.kind === 'unlink' && report.path === leaf('demo')),
      'the watcher reported the deleted SKILL.md unlinked again in later polls while it stayed deleted',
    ).toHaveLength(1);
  });

  test('reports a SKILL.md unlinked when its whole skill directory is deleted', async () => {
    write(leaf('demo'), 'demo skill');
    const run = await watchFrom('managed', [skillsRoot()]);

    rmSync(join(skillsRoot(), 'demo'), { recursive: true, force: true });
    await run.until(
      `onUnlink to report ${leaf('demo')} once its skill directory was deleted, which drops it from the listing`,
      (reports) => unlinked(reports, leaf('demo')),
    );
    expect(unlinked(run.reports(), leaf('demo'))).toBe(true);
  });
});

describe('closing a watcher between polls', () => {
  test('startConfigFileWatcher cleanup, called while no sample is in flight, leaves no poll armed to sample again', async () => {
    const { watch, target } = watchedFile('config', 'edit');
    const run = await watchFrom('config', watch);

    run.send({ op: 'close-between-polls', path: target });
    await run.until(
      'the watcher process to fall idle on its own once cleanup resolved between two polls',
      (reports) => reportOf(reports, 'idle-after-close') !== undefined,
    );
    expect(
      reportOf(run.reports(), 'idle-after-close')?.samplesAfterClose,
      `the watcher sampled ${target} again after its cleanup resolved: cleanup left its next poll armed`,
    ).toBe(0);
  });
});

describe.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
  'a watcher started while its file is unreadable (EACCES; chmod does not bind root or Windows)',
  () => {
    test.each(ENTRIES.filter(({ entry }) => entry !== 'multi-config'))(
      '$watcher resolves its start and reports an edit made once the file is readable',
      async ({ entry }) => {
        const { watch, target } = watchedFile(entry, 'edit');
        const dir = dirname(target);
        const mode = statSync(dir).mode & 0o7777;
        madeUnreadable.push(dir);
        chmodSync(dir, 0o000);
        const run = await watchFrom(entry, watch);

        chmodSync(dir, mode);
        writeFileSync(target, READABLE_AGAIN, 'utf-8');
        await run.until(
          `onChange to report the edit of ${target} made once its directory was readable, after a start that met it unreadable`,
          (reports) => delivered(reports, target, READABLE_AGAIN),
        );
        expect(delivered(run.reports(), target, READABLE_AGAIN)).toBe(true);
      },
    );
  },
);

describe('a file whose two-step write is interrupted between its halves is reported only once its size holds after the interruption', () => {
  test.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
    'startConfigFileWatcher never reports an edit half-written when a sample between the halves fails with EACCES (chmod does not bind root or Windows)',
    async () => {
      const { watch, target } = watchedFile('config', 'edit');
      const dir = dirname(target);
      madeUnreadable.push(dir);
      const run = await watchFrom('config', watch);

      run.send({
        op: 'two-step-write-across-interruption',
        path: target,
        dir,
        partial: PARTIAL,
        complete: COMPLETE,
        interruption: 'unreadable',
      });
      await run.until(
        `the watcher to report ${target} with both halves after a sample between them failed with EACCES, never the first half alone`,
        (reports) => {
          expect(
            deliveriesFor(reports, target),
            `the watcher reported ${target} holding only the first half once a sample between the halves had failed: a failed sample must drop the size it was waiting to see hold`,
          ).not.toContain(PARTIAL);
          return delivered(reports, target, COMPLETE);
        },
      );
      expect(
        reportOf(run.reports(), 'interrupted'),
        'a watcher sample between the two halves failed with EACCES',
      ).toBeDefined();
    },
  );

  test('startConfigFileWatcher never reports a creation half-written when the file is deleted and created again with its first half', async () => {
    const { watch, target } = watchedFile('config', 'create');
    const run = await watchFrom('config', watch);

    run.send({
      op: 'two-step-write-across-interruption',
      path: target,
      dir: dirname(target),
      partial: PARTIAL,
      complete: COMPLETE,
      interruption: 'removed',
    });
    await run.until(
      `the watcher to report ${target} with both halves after a sample between them found it deleted, never the first half alone`,
      (reports) => {
        expect(
          deliveriesFor(reports, target),
          `the watcher reported ${target} holding only the first half once a sample between the halves had found it absent: an absent sample must drop the size it was waiting to see hold`,
        ).not.toContain(PARTIAL);
        return delivered(reports, target, COMPLETE);
      },
    );
    expect(
      reportOf(run.reports(), 'interrupted'),
      'a watcher sample between the two halves found the file absent',
    ).toBeDefined();
  });
});

describe('a watched file replaced by one of the same size and modification time', () => {
  test('startConfigFileWatcher reports the replacement', async () => {
    const { watch, target } = watchedFile('config', 'edit');
    const { mtime } = statSync(target);
    utimesSync(target, mtime, mtime);
    const run = await watchFrom('config', watch);

    const replacement = `${target}.replacement`;
    write(replacement, SAME_SIZE_REPLACEMENT);
    utimesSync(replacement, mtime, mtime);
    expect(
      statSync(replacement, { bigint: true }).size,
      'the replacement has the size of the file it replaces',
    ).toBe(statSync(target, { bigint: true }).size);
    expect(
      statSync(replacement, { bigint: true }).mtimeNs,
      'the replacement has the modification time of the file it replaces',
    ).toBe(statSync(target, { bigint: true }).mtimeNs);
    renameSync(replacement, target);
    await run.until(
      `onChange to report the replacement of ${target}, which kept its size and modification time but not its inode or change time`,
      (reports) => delivered(reports, target, SAME_SIZE_REPLACEMENT),
    );
  });
});

describe('a watched file rewritten in place at its size inside the timestamp granule its baseline was sampled in (whole-second timestamps modelled at the stat seam)', () => {
  test('startManagedArtifactWatcher reports the rewrite, which leaves every stat field as the baseline sampled it', async () => {
    const { watch, target } = watchedFile('managed', 'edit');
    const run = await watchFrom('managed', watch, target);

    run.send({ op: 'rewrite-in-place', path: target, content: IN_PLACE_REWRITE });
    await run.until(
      `the watcher process to rewrite ${target} in place`,
      (reports) => reportOf(reports, 'rewritten-in-place') !== undefined,
    );
    expect(
      reportOf(run.reports(), 'rewritten-in-place')?.statUnchanged,
      `the rewrite of ${target} changed its device, inode, size, modification time or change time, so it does not reproduce a rewrite inside one timestamp granule`,
    ).toBe(true);
    await run.until(
      `onChange to report the in-place rewrite of ${target}, which kept its size inside the timestamp granule of the baseline sample`,
      (reports) => delivered(reports, target, IN_PLACE_REWRITE),
    );
  });
});

describe.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
  'an error the watcher reported is reported again once its directory has been a regular file (EACCES, then ENOTDIR, then EACCES; chmod does not bind root or Windows)',
  () => {
    test.each(
      UNREADABLE_CASES.filter(
        ({ entry, unreadable }) => entry !== 'multi-config' && unreadable !== 'skills root',
      ),
    )(
      '$watcher reports the EACCES of every path it cannot read in each episode when its $unreadable is unreadable, then a regular file, then unreadable once more',
      async (unreadableCase) => {
        const { unreadable } = unreadableCase;
        const file = watchedFile(unreadableCase.entry, 'edit');
        const { dir, failing } = unreadableScope(unreadableCase, file);
        const run = await watchFrom(unreadableCase.entry, file.watch);

        madeUnreadable.push(dir);
        run.send({
          op: 'unreadable-again-after-recovery',
          dir,
          failingAt: failingSampleOf(unreadableCase, file),
          sampledEveryPoll: sampledEveryPollOf(unreadableCase, file),
          recovery: 'replaced-by-file',
          aside: join(fixture, 'aside'),
        });
        await run.until(
          `the watcher to sample through an unreadable episode of its ${unreadable}, a spell as a regular file and a second unreadable episode, each established by a poll begun with it in place`,
          (reports) => {
            expect(
              unlinked(reportsBefore(reports, 'removed'), file.target),
              `onUnlink reported ${file.target} while its ${unreadable} was only unreadable: ` +
                'the watcher read the EACCES as a deletion instead of keeping the last observation and reporting the error',
            ).toBe(false);
            return reportOf(reports, 'error-reports-across-recovery') !== undefined;
          },
        );

        const episodes = reportOf(run.reports(), 'error-reports-across-recovery');
        for (const path of failing) {
          expect(
            reportsFor(episodes?.firstEpisode, 'EACCES', path),
            `the watcher never reported the EACCES of ${path} in the first unreadable episode, at any logger level`,
          ).not.toEqual([]);
          expect(
            reportsFor(episodes?.afterRecovery, 'EACCES', path),
            `the watcher reported the EACCES of ${path} before its ${unreadable} was a regular file but not after: ` +
              'a sample that fails with ENOTDIR reads as absent, so the next failure must be reported again',
          ).not.toEqual([]);
        }
      },
    );
  },
);

describe.skipIf(process.platform === 'win32' || process.geteuid?.() === 0)(
  'closing a watcher whose in-flight sample has not settled (the threadpool barrier is a POSIX FIFO; chmod does not bind root or Windows)',
  () => {
    test.each(ENTRIES)(
      '$watcher cleanup resolves while its sample of a watched file is held on the only libuv worker, and reports nothing once that sample fails',
      async ({ entry }) => {
        const { watch, target } = watchedFile(entry, 'edit');
        const dir = dirname(target);
        const barrier = join(fixture, 'threadpool-barrier');
        execFileSync('mkfifo', [barrier]);
        madeUnreadable.push(dir);
        const run = await watchFrom(entry, watch);

        run.send({ op: 'close-while-sample-held', path: target, dir, barrier });
        await run.until(
          `the watcher process to fall idle once cleanup was called while its sample of ${target} was held, and that sample then failed with EACCES`,
          (reports) => reportOf(reports, 'idle-after-held-close') !== undefined,
        );
        const idle = reportOf(run.reports(), 'idle-after-held-close');
        expect(
          idle?.resolvedWhileHeld,
          `cleanup waited on the watcher's in-flight sample of ${target}: a sample that never settles, on a stalled mount, keeps server shutdown from reaching its document flush`,
        ).toBe(true);
        expect(
          idle?.eventsAfterClose,
          'the watcher called back after its cleanup resolved',
        ).toEqual([]);
        expect(
          asLogLines(idle?.loggedAfterClose ?? []),
          'the watcher reported an error from a sample that landed after its cleanup resolved',
        ).toEqual([]);
      },
    );
  },
);