Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

10.9 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import { appWorktreeSlug, isAgentWorktreeId, isHumanClaimWorktree, worktreeAgentId, worktreeHoldExpiresAt, worktreeOwnershipReason } from './worktreeOwnership.js';

describe('worktree ownership', () => {
  const COS_ROOT = '/repo/data/cos/worktrees';

  it('permits only an inactive, unlocked CoS agent tree under the configured root', () => {
    const options = {
      roots: [{ path: COS_ROOT, requireAgentId: true }],
      activeAgentIds: new Set(),
      requireKnownLiveness: true,
    };
    expect(worktreeOwnershipReason({ ...options, path: `${COS_ROOT}/agent-dead` })).toBeNull();
    expect(worktreeOwnershipReason({ ...options, path: '/repo/elsewhere/agent-dead' })).toBe('worktree-unmanaged-location');
    expect(worktreeOwnershipReason({ ...options, path: `${COS_ROOT}/next-issue-42` })).toBe('worktree-missing-agent-id');
    expect(worktreeOwnershipReason({ ...options, path: `${COS_ROOT}/agent-live`, activeAgentIds: new Set(['agent-live']) }))
      .toBe('worktree-active-agent');
    expect(worktreeOwnershipReason({ ...options, path: `${COS_ROOT}/agent-locked`, locked: true })).toBe('worktree-locked');
  });

  it('keeps human claims unless the caller explicitly permits reclamation', () => {
    const input = { path: `${COS_ROOT}/claim-issue-42`, ageMs: 8_000, staleClaimIdleMs: 7_000 };
    expect(worktreeOwnershipReason(input)).toBe('worktree-human-claim');
    // A reaper may take an ABANDONED claim once its window lapses…
    expect(worktreeOwnershipReason({ ...input, allowStaleClaim: true })).toBeNull();
    // …and the dispatch side never treats the directory as an owner at all,
    // regardless of age (it reads the tree as a claim MARKER, not a process).
    expect(worktreeOwnershipReason({ ...input, ageMs: 1, allowLiveClaim: true })).toBeNull();
  });

  it('tests the claim LAST, so every unconditional hold outranks it', () => {
    // The ordering IS the precedence: a claim tree that is also locked / also
    // running an agent reports that hold, not 'worktree-human-claim'. Callers
    // therefore never have to re-derive "a lock beats a claim" from the slug.
    const claim = `${COS_ROOT}/claim-issue-42`;
    expect(worktreeOwnershipReason({ path: claim, locked: true })).toBe('worktree-locked');
    expect(worktreeOwnershipReason({ path: claim, activeAgentIds: new Set(['claim-issue-42']) }))
      .toBe('worktree-active-agent');
    // …and the exceptions cannot reach past them either.
    expect(worktreeOwnershipReason({
      path: claim, locked: true, allowLiveClaim: true, allowStaleClaim: true, ageMs: 8_000, staleClaimIdleMs: 7_000
    })).toBe('worktree-locked');
    // A root that demands an agent id refuses the claim basename on that ground.
    expect(worktreeOwnershipReason({ path: claim, roots: [{ path: COS_ROOT, requireAgentId: true }] }))
      .toBe('worktree-missing-agent-id');
    // …unless the caller opted into live-claim adoption, which lets a claim
    // basename through the agent-id root gate so the claim test below it (not
    // this one) decides the verdict.
    expect(worktreeOwnershipReason({
      path: claim, roots: [{ path: COS_ROOT, requireAgentId: true }], allowLiveClaim: true
    })).toBeNull();
    // A non-claim, non-agent basename still can't ride that carve-out through.
    expect(worktreeOwnershipReason({
      path: `${COS_ROOT}/next-issue-42`, roots: [{ path: COS_ROOT, requireAgentId: true }], allowLiveClaim: true
    })).toBe('worktree-missing-agent-id');
  });

  it('admits a tree outside every configured root only through an explicit idle window', () => {
    // The unmanaged-location hold is unconditional by default (#10270: a release
    // worktree deleted a minute after a live run cut it). A caller that has an
    // independent proof the tree is unwanted — the superseded reap, whose branch
    // carries a recorded verdict and a backup — may name an idle window, after
    // which the tree is judged by the remaining gates like any managed one.
    const outside = { path: '/private/tmp/portos-elsewhere', roots: [{ path: COS_ROOT, requireAgentId: false }], activeAgentIds: new Set() };
    expect(worktreeOwnershipReason(outside)).toBe('worktree-unmanaged-location');
    expect(worktreeOwnershipReason({ ...outside, unmanagedIdleMs: 3_600_000, ageMs: 60_000 })).toBe('worktree-unmanaged-location');
    expect(worktreeOwnershipReason({ ...outside, unmanagedIdleMs: 3_600_000, ageMs: 3_600_000 })).toBeNull();
    // An unknown age never counts as idle.
    for (const ageMs of [null, undefined, NaN]) {
      expect(worktreeOwnershipReason({ ...outside, unmanagedIdleMs: 3_600_000, ageMs })).toBe('worktree-unmanaged-location');
    }
    // The window only replaces the LOCATION gate; every later hold still applies.
    expect(worktreeOwnershipReason({ ...outside, unmanagedIdleMs: 3_600_000, ageMs: 7_200_000, locked: true })).toBe('worktree-locked');
    expect(worktreeOwnershipReason({
      ...outside, path: `${outside.path}/agent-live`, unmanagedIdleMs: 3_600_000, ageMs: 7_200_000, activeAgentIds: new Set(['agent-live'])
    })).toBe('worktree-active-agent');
  });

  it('fails closed when agent liveness is unknown and permits an explicitly non-agent root', () => {
    expect(worktreeOwnershipReason({
      path: `${COS_ROOT}/agent-unknown`,
      requireAgentId: true,
      requireKnownLiveness: true,
    })).toBe('worktree-agent-liveness-unknown');
    expect(worktreeOwnershipReason({
      path: '/repo/.claude/worktrees/review-fix',
      roots: [{ path: '/repo/.claude/worktrees', requireAgentId: false }],
      activeAgentIds: new Set(),
      requireKnownLiveness: true,
    })).toBeNull();
  });

  it('uses one separator-safe namespace definition', () => {
    expect(worktreeAgentId('H:/repo/data/cos/worktrees/agent-abc')).toBe('agent-abc');
    expect(worktreeAgentId('H:\\repo\\data\\cos\\worktrees\\claim-issue-42')).toBe('claim-issue-42');
    expect(isAgentWorktreeId('agent-abc')).toBe(true);
    expect(isAgentWorktreeId('next-issue-42')).toBe(false);
    expect(isHumanClaimWorktree('claim-issue-42')).toBe(true);
  });
});

describe('appWorktreeSlug', () => {
  const ID_A = '3f2a1b9c-4d5e-6f70-8a9b-0c1d2e3f4a5b';
  const ID_B = '9e8d7c6b-5a49-3827-1605-f4e3d2c1b0a9';

  // The whole point: two managed apps sharing a name must not share a worktree
  // directory, because every app's claim flow checks out into ONE shared root.
  it('separates two same-named apps, so their identical issue numbers cannot collide', () => {
    const a = appWorktreeSlug({ id: ID_A, name: 'Example App' });
    const b = appWorktreeSlug({ id: ID_B, name: 'Example App' });
    expect(a).not.toBe(b);
  });

  it('stays a safe, readable single path segment', () => {
    expect(appWorktreeSlug({ id: ID_A, name: 'Example App' })).toBe('example-app-3f2a1b9c');
    // Punctuation, unicode and a runaway name all have to survive as one segment
    // — the value is interpolated straight into a shell-quoted path.
    expect(appWorktreeSlug({ id: ID_A, name: 'My App (v2)/prod' })).toMatch(/^[a-z0-9-]+$/);
    expect(appWorktreeSlug({ id: ID_A, name: 'x'.repeat(200) }).length).toBeLessThanOrEqual(33);
    // Bounded on a word boundary, never mid-word — the name is what a human reads
    // in `git worktree list` when judging whether a tree is safe to reap.
    expect(appWorktreeSlug({ id: ID_A, name: 'Example Application Framework' })).toBe('example-application-3f2a1b9c');
    // A name that slugifies to nothing must not leave a leading separator.
    expect(appWorktreeSlug({ id: ID_A, name: '???' })).toBe('3f2a1b9c');
  });

  // Never empty: an empty segment would collapse `claim-${slug}-issue-10` back to
  // a colliding `claim--issue-10` shared by every app missing a record field.
  it('always yields a non-empty segment', () => {
    expect(appWorktreeSlug({})).toBe('app');
    expect(appWorktreeSlug(undefined)).toBe('app');
    expect(appWorktreeSlug({ name: 'Example App' })).toBe('example-app');
  });
});

describe('worktreeHoldExpiresAt', () => {
  const COS_ROOT = '/repo/data/cos/worktrees';
  const NOW = Date.parse('2026-01-10T00:00:00.000Z');
  const claim = (over = {}) => worktreeHoldExpiresAt({
    path: `${COS_ROOT}/claim-issue-42`, allowStaleClaim: true, ageMs: 2_000, staleClaimIdleMs: 7_000, nowMs: NOW, ...over
  });

  it('dates a stale-claim hold to the moment its window lapses', () => {
    expect(claim()).toBe(new Date(NOW + 5_000).toISOString());
  });

  it('gives no expiry to a claim tree that is ALSO locked', () => {
    // The lock outlives the window, and the gate now says so structurally: a
    // locked claim tree reports 'worktree-locked', never the claim slug, so
    // there is no window here to date.
    expect(claim({ locked: true })).toBeNull();
  });

  it('gives no expiry to a claim tree whose agent is still live', () => {
    expect(worktreeHoldExpiresAt({
      path: `${COS_ROOT}/claim-issue-42`, allowStaleClaim: true, ageMs: 2_000, staleClaimIdleMs: 7_000,
      activeAgentIds: new Set(['claim-issue-42']), nowMs: NOW
    })).toBeNull();
  });

  it('gives no expiry when the caller has not opted into stale-claim reclamation', () => {
    // Without allowStaleClaim the window never lapses for this caller, so there
    // is no deadline to report.
    expect(claim({ allowStaleClaim: false })).toBeNull();
  });

  it('gives no expiry once the window has already lapsed, or when age is unknown', () => {
    expect(claim({ ageMs: 9_000 })).toBeNull();
    expect(claim({ ageMs: 7_000 })).toBeNull();
    for (const ageMs of [null, undefined, NaN, 'old']) expect(claim({ ageMs })).toBeNull();
    expect(claim({ staleClaimIdleMs: undefined })).toBeNull();
  });

  it('dates an unmanaged-location hold to the end of the caller\'s idle window', () => {
    const outside = {
      path: '/private/tmp/portos-elsewhere', roots: [{ path: COS_ROOT, requireAgentId: false }],
      activeAgentIds: new Set(), unmanagedIdleMs: 3_600_000, ageMs: 600_000, nowMs: NOW
    };
    expect(worktreeHoldExpiresAt(outside)).toBe(new Date(NOW + 3_000_000).toISOString());
    // No window from this caller, or no measured age: nothing to date.
    expect(worktreeHoldExpiresAt({ ...outside, unmanagedIdleMs: undefined })).toBeNull();
    for (const ageMs of [null, undefined, NaN]) expect(worktreeHoldExpiresAt({ ...outside, ageMs })).toBeNull();
    // A lock outlives the window and the gate reports it first, so no date.
    expect(worktreeHoldExpiresAt({ ...outside, locked: true })).toBeNull();
  });

  it('gives no expiry to holds that are not the stale-claim window', () => {
    expect(worktreeHoldExpiresAt({ path: `${COS_ROOT}/agent-live`, activeAgentIds: new Set(['agent-live']), ageMs: 2_000, staleClaimIdleMs: 7_000 })).toBeNull();
    expect(worktreeHoldExpiresAt({ path: null })).toBeNull();
    // A tree nothing holds at all has no expiry either — there is no wait.
    expect(worktreeHoldExpiresAt({ path: `${COS_ROOT}/agent-dead`, activeAgentIds: new Set(), ageMs: 2_000, staleClaimIdleMs: 7_000 })).toBeNull();
  });
});