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

16.4 KB
Raw Blame
/**
 * Plan-item IDs — utilities for giving every `- [ ]` checkbox in PLAN.md a
 * stable slug ID so concurrent agents can claim distinct items by encoding
 * the ID in their worktree branch name (`cos/<task.id>/<planId>/<agentId>`).
 *
 * Public API:
 *   - slugify(title, takenIds)            → string  (deterministic, unique within `takenIds`)
 *   - parsePlanItems(markdown)            → PlanItem[]
 *   - assignMissingIds(markdown, extraIds)→ { content, assigned[] }
 *   - extractAllIds(markdown)             → string[]   (every `[slug]` in PLAN.md)
 *   - findInProgressIds(repoPath, ids)    → Set<string> (subset present in branch/PR names)
 *   - resetInProgressScanCache(repoPath?) → void     (evict the TTL-cached ref scan)
 *   - pickFirstAvailable(items, takenIds) → PlanItem | null
 *
 * @typedef {Object} PlanItem
 * @property {number} lineNumber   1-indexed
 * @property {string} indent       leading whitespace
 * @property {boolean} checked     true for `- [x]`
 * @property {string|null} id      slug if present, else null
 * @property {string} rest         everything after the `[id]` slot (or after `[x]/[ ]` if no id)
 * @property {boolean} needsInput  true if line carries the `<!-- NEEDS_INPUT -->` marker
 * @property {boolean} drifted     true if the immediately-preceding line starts with `> ⚠️ DRIFT:`
 */

import { execGit } from './execGit.js';
import { stripMarkdownEmphasis } from './markdownText.js';
import { kebabCase, truncateOnBoundary } from './textUtils.js';
import { spawn } from './childProcess.js';

const SLUG_MAX_LEN = 50;
const CHECKBOX_RE = /^(?<indent>\s*)-\s+\[(?<box>[ xX])\]\s+(?:\[(?<id>[a-z0-9][a-z0-9-]*)\]\s+)?(?<rest>.*)$/;
const NEEDS_INPUT_RE = /<!--\s*NEEDS_INPUT\s*-->/;
const DRIFT_LINE_RE = /^\s*>\s*⚠️\s*DRIFT:/;

/**
 * Derive a unique slug for `title`, avoiding any string in `takenIds`.
 * Deterministic for the same (title, takenIds) inputs.
 *
 * `takenIds` may be a Set or an array. It is not mutated.
 */
export function slugify(title, takenIds = new Set()) {
  const taken = takenIds instanceof Set ? takenIds : new Set(takenIds);
  const base = truncateOnBoundary(kebabCase(stripMarkdownEmphasis(title)), SLUG_MAX_LEN) || 'item';
  if (!taken.has(base)) return base;
  // Collision: append -2, -3, ... — keep the suffix inside SLUG_MAX_LEN.
  for (let n = 2; n < 10000; n++) {
    const suffix = `-${n}`;
    const trimmedBase = base.length + suffix.length > SLUG_MAX_LEN
      ? truncateOnBoundary(base, SLUG_MAX_LEN - suffix.length)
      : base;
    const candidate = `${trimmedBase}${suffix}`;
    if (!taken.has(candidate)) return candidate;
  }
  throw new Error(`slugify exhausted collision space for title: ${title}`);
}

/**
 * Parse every `- [ ]` / `- [x]` line in a PLAN.md-style markdown document.
 * Returns one PlanItem per checkbox line, in document order.
 */
export function parsePlanItems(markdown) {
  if (!markdown) return [];
  const lines = markdown.split('\n');
  const items = [];
  for (let i = 0; i < lines.length; i++) {
    const m = CHECKBOX_RE.exec(lines[i]);
    if (!m) continue;
    const { indent, box, id, rest } = m.groups;
    items.push({
      lineNumber: i + 1,
      indent: indent || '',
      checked: box.toLowerCase() === 'x',
      id: id || null,
      rest: rest || '',
      needsInput: NEEDS_INPUT_RE.test(rest || ''),
      drifted: DRIFT_LINE_RE.test(lines[i - 1] || '')
    });
  }
  return items;
}

/**
 * Return every `[slug]` ID that appears in a PLAN.md-style document.
 * Captures both checkbox-prefixed IDs (parsePlanItems) AND any `[slug]`
 * marker embedded inline in narrative copy (e.g. cross-references in
 * design-log entries left as `- [x] [slug] …` for posterity).
 */
export function extractAllIds(markdown) {
  if (!markdown) return [];
  const ids = new Set();
  for (const item of parsePlanItems(markdown)) {
    if (item.id) ids.add(item.id);
  }
  // Pick up inline `[slug]` markers not on checkbox lines (e.g. design-log
  // back-references in `## Shipped` sections or PR descriptions inlined here).
  // Length range 2–81 chars is intentionally wider than slugify()'s 50-char
  // cap so historical slugs that exceeded the modern length limit are still
  // recognized for the uniqueness check (we never want to re-issue one).
  const inlineRe = /\[([a-z0-9][a-z0-9-]{1,80})\]/g;
  let m;
  while ((m = inlineRe.exec(markdown)) !== null) {
    // Skip markdown links: `[text](url)` — only count when not immediately followed by `(`
    const after = markdown[m.index + m[0].length];
    if (after === '(') continue;
    ids.add(m[1]);
  }
  return [...ids];
}

/**
 * Assign a slug ID to every `- [ ]` / `- [x]` line that doesn't already have one.
 * Idempotent: existing IDs are preserved verbatim. `extraIds` lets the caller
 * pass IDs from sibling sources (e.g. an in-flight branch scan) into the
 * uniqueness check.
 *
 * @param {string} markdown
 * @param {string[]|Set<string>} extraIds
 * @returns {{ content: string, assigned: Array<{ id: string, title: string, lineNumber: number }> }}
 */
export function assignMissingIds(markdown, extraIds = []) {
  if (!markdown) return { content: markdown || '', assigned: [] };
  const taken = new Set([...extractAllIds(markdown), ...extraIds]);
  const lines = markdown.split('\n');
  const assigned = [];
  for (let i = 0; i < lines.length; i++) {
    const m = CHECKBOX_RE.exec(lines[i]);
    if (!m) continue;
    if (m.groups.id) continue;
    const rest = m.groups.rest || '';
    const id = slugify(rest, taken);
    taken.add(id);
    lines[i] = `${m.groups.indent || ''}- [${m.groups.box}] [${id}] ${rest}`;
    assigned.push({ id, title: rest, lineNumber: i + 1 });
  }
  return { content: lines.join('\n'), assigned };
}

/**
 * Classify why no PLAN.md item is currently dispatchable, for `plan-task`
 * gating. Returns null when an agent dispatch should proceed (an item is
 * pickable, or the state is recoverable — e.g. missing IDs that `do-replan`
 * will fix on its own pass). Returns a human-readable reason string when
 * the dispatch should be skipped entirely so the LLM isn't spun up just
 * to exit cleanly.
 *
 * Skip cases:
 *   - PLAN.md missing or empty.
 *   - No `- [ ]` items at all.
 *   - Every unchecked item is blocked on human input (`<!-- NEEDS_INPUT -->`
 *     annotation, or the preceding line starts with `> ⚠️ DRIFT:`).
 *   - Every unchecked item is either blocked on human input OR already
 *     claimed by another agent (in-flight by branch/PR scan).
 *
 * Either `planMd` or `parsedItems` must be supplied. When the caller has
 * already run `parsePlanItems(planMd)` (e.g. `applyPlanIdMetadata` does this
 * for the pick step), passing `parsedItems` here avoids a redundant parse;
 * `planMd` can then be passed as `null`.
 *
 * @param {string|null} planMd                 PLAN.md content, or null if parsedItems is supplied
 * @param {Set<string>|string[]} inFlightIds   IDs currently claimed elsewhere
 * @param {PlanItem[]|null} [parsedItems]      pre-parsed items, avoids re-parsing planMd
 * @returns {string | null}                    skip reason, or null when dispatch should proceed
 */
export function diagnoseUnpickablePlan(planMd, inFlightIds = new Set(), parsedItems = null) {
  if (!planMd && !parsedItems) return 'PLAN.md missing or empty';
  const inFlight = inFlightIds instanceof Set ? inFlightIds : new Set(inFlightIds);
  const items = parsedItems || parsePlanItems(planMd);
  const unchecked = items.filter(i => !i.checked);
  if (unchecked.length === 0) return 'PLAN.md has no unchecked items';

  const isBlockedByHuman = (i) => i.needsInput || i.drifted;
  if (unchecked.every(isBlockedByHuman)) {
    return 'all PLAN.md items are blocked on human input (NEEDS_INPUT / DRIFT)';
  }
  if (unchecked.every(i => isBlockedByHuman(i) || (i.id && inFlight.has(i.id)))) {
    return 'all PLAN.md items are claimed by other agents or blocked on human input';
  }
  return null;
}

/**
 * Pick the first `- [ ]` item that is not checked, not annotated NEEDS_INPUT,
 * not already in flight, and (if `requireId`) carries an ID.
 *
 * @param {PlanItem[]} items
 * @param {Set<string>|string[]} takenIds  IDs currently claimed by another agent
 * @param {{ requireId?: boolean }} [options]
 */
export function pickFirstAvailable(items, takenIds = new Set(), options = {}) {
  const taken = takenIds instanceof Set ? takenIds : new Set(takenIds);
  const requireId = options.requireId !== false; // default true
  for (const item of items) {
    if (item.checked) continue;
    if (item.needsInput) continue;
    if (item.drifted) continue;
    if (requireId && !item.id) continue;
    if (item.id && taken.has(item.id)) continue;
    return item;
  }
  return null;
}

/**
 * Promise-wrapped `gh pr list` — separated from execGit because `gh` is
 * not always installed on every host.
 *
 * Sentinel discipline (#3358): `[]` means "gh answered and there are no open
 * PRs"; `null` means "we could not ask" (gh missing, unauthenticated, network
 * blocked, timed out). The caller must not read the second as the first.
 *
 * @returns {Promise<string[]|null>}
 */
export function listOpenPullRequestHeadRefs(repoPath) {
  return new Promise(resolve => {
    const child = spawn('gh', ['pr', 'list', '--state', 'open', '--json', 'headRefName', '-q', '.[].headRefName'], {
      cwd: repoPath,
      shell: false
    });
    let out = '';
    let settled = false;
    // One settle path so the 15s backstop can't resolve a promise the close
    // handler already settled, and so the timer is always cleared.
    const done = (value) => { if (!settled) { settled = true; clearTimeout(timer); resolve(value); } };
    const timer = setTimeout(() => {
      // setTimeout callback boundary — a kill() throw here would be uncaught.
      try { child.kill(); } catch { /* already exited */ }
      done(null);
    }, 15000);
    child.on('error', () => done(null));
    child.stdout.on('data', chunk => { out += chunk.toString(); });
    child.on('close', code => {
      if (code !== 0) return done(null);
      done(out.split('\n').map(s => s.trim()).filter(Boolean));
    });
  });
}

/**
 * Extract the PLAN.md slug from a git ref ONLY when the ref matches one of
 * the three documented claim patterns:
 *   - `claim/<slug>`                       (human / TUI / scheduler path)
 *   - `cos/<task>/<slug>/<agent>`          (CoS sub-agent path)
 *   - `next/<slug>`                        (slashdo `/do:next` path — #8161)
 * after stripping any single leading remote prefix (e.g. `origin/`).
 *
 * The `next/<slug>` branch is created by the bundled slashdo `/do:next`
 * skill, not by PortOS's own claim-issue flow (which uses `claim/issue-<n>`
 * under `data/cos/worktrees/claim-*`) — but a claim agent can still end up
 * running `/do:next` itself, so its branch must be recognized as a live
 * claim by the same scanners, or the branch reads as an orphan and a
 * concurrent scan can re-dispatch onto the same issue mid-flight.
 *
 * Returns null for refs that don't match — e.g. `feature/foo`, `main`,
 * `release`, or `origin/HEAD`. Without this gate, the segment-walking
 * approach would falsely flag any slug literally named `main`, `fix`,
 * `feature`, `release`, `dev`, etc. as in-flight against virtually every
 * branch in the repo, which would then suppress every plan-task dispatch.
 */
export function extractSlugFromRef(ref) {
  if (typeof ref !== 'string' || !ref) return null;
  const stripped = /^[^/]+\/(claim|cos|next)\//.test(ref)
    ? ref.replace(/^[^/]+\//, '')
    : ref;
  const m1 = /^claim\/(.+)$/.exec(stripped);
  if (m1) return m1[1];
  const m2 = /^cos\/[^/]+\/([^/]+)\/[^/]+$/.exec(stripped);
  if (m2) return m2[1];
  const m3 = /^next\/(.+)$/.exec(stripped);
  if (m3) return m3[1];
  return null;
}

/**
 * How long a claim-ref scan stays reusable. The scan costs a network
 * `git fetch --prune`, a `git branch -a`, and a `gh pr list` child process, and
 * the background scheduler re-evaluates plan-task dispatch far more often than
 * claim branches actually appear (#3499). One minute is short enough that a
 * freshly pushed claim branch is seen on the next tick or two, and long enough
 * that a burst of evaluation ticks costs one scan instead of one each.
 */
export const IN_PROGRESS_SCAN_TTL_MS = 60_000;

/** repoPath → { expiresAt:number, promise:Promise<Set<string>> } */
const inProgressScanCache = new Map();

/**
 * Drop cached claim-ref scans. Call with a `repoPath` to evict one repo, or
 * with no argument to clear every entry.
 *
 * Tests MUST call this in `beforeEach` — the cache is module-level, so without
 * a reset one test's scan result leaks into the next one's assertions.
 *
 * @param {string} [repoPath]
 */
export function resetInProgressScanCache(repoPath) {
  if (typeof repoPath === 'string') inProgressScanCache.delete(repoPath);
  else inProgressScanCache.clear();
}

/**
 * The uncached scan: every claim slug currently evidenced by a git ref or an
 * open PR head ref in `repoPath`. Returns ALL slugs found, not just the ones a
 * particular caller asked about, so one scan can serve callers with different
 * `knownIds` sets.
 */
async function scanClaimedSlugs(repoPath) {
  // Best-effort fetch so remote branches are current
  await execGit(['fetch', '--prune'], repoPath).catch(() => {});

  const [branchOutput, prHeadRefs] = await Promise.all([
    execGit(
      ['branch', '-a', '--no-color', '--format=%(refname:short)'],
      repoPath,
      { ignoreExitCode: true }
    ).then(r => r.stdout || '').catch(() => ''),
    listOpenPullRequestHeadRefs(repoPath)
  ]);

  if (prHeadRefs === null) {
    console.error(`❌ plan claim scan: could not read open PRs from the forge — in-flight detection is running on git refs alone for ${repoPath}`);
  }

  const refs = [
    ...branchOutput.split('\n'),
    ...(prHeadRefs || [])
  ].map(s => s.trim()).filter(Boolean);

  const slugs = new Set();
  for (const ref of refs) {
    const slug = extractSlugFromRef(ref);
    if (slug) slugs.add(slug);
  }
  return slugs;
}

/**
 * TTL-cached wrapper around `scanClaimedSlugs`. Concurrent callers share the
 * one in-flight promise; the TTL is stamped again when it settles so a slow
 * scan doesn't immediately look stale. A rejected scan is evicted so the next
 * call retries rather than caching the failure.
 */
function claimedSlugs(repoPath, { force = false } = {}) {
  const cached = inProgressScanCache.get(repoPath);
  if (!force && cached && cached.expiresAt > Date.now()) return cached.promise;

  const entry = { expiresAt: Date.now() + IN_PROGRESS_SCAN_TTL_MS, promise: null };
  entry.promise = scanClaimedSlugs(repoPath).then(
    slugs => {
      entry.expiresAt = Date.now() + IN_PROGRESS_SCAN_TTL_MS;
      return slugs;
    },
    err => {
      if (inProgressScanCache.get(repoPath) === entry) inProgressScanCache.delete(repoPath);
      throw err;
    }
  );
  inProgressScanCache.set(repoPath, entry);
  return entry.promise;
}

/**
 * Find which of `knownIds` are currently in flight, as evidenced by an open
 * git branch (local or remote) or open PR with the slug encoded into a
 * documented claim ref pattern (`claim/<slug>` or `cos/<task>/<slug>/<agent>`).
 *
 * `repoPath` is the repository to query. Git refs (local + freshly fetched
 * `origin/*`) are the primary evidence and cover every documented claim pattern;
 * the open-PR head refs are a secondary net for a claim whose branch was pruned.
 *
 * When `gh` cannot be reached the PR net is UNAVAILABLE, not empty (#3358) — the
 * degradation is logged once so a run that later double-claims an item has a
 * visible cause, rather than the forge outage passing as "no PRs are open".
 *
 * The underlying ref scan is cached per `repoPath` for `IN_PROGRESS_SCAN_TTL_MS`
 * so back-to-back scheduler evaluation ticks reuse it instead of respawning
 * `git fetch` / `git branch` / `gh pr list` every time (#3499). What's cached is
 * the full slug set, so a caller passing a different `knownIds` still gets a
 * correct intersection. Pass `{ force: true }` to bypass the cache when a caller
 * is about to act on the result rather than merely gate on it.
 *
 * @param {string} repoPath
 * @param {string[]|Set<string>} knownIds
 * @param {{ force?: boolean }} [options]
 * @returns {Promise<Set<string>>}
 */
export async function findInProgressIds(repoPath, knownIds, options = {}) {
  const known = knownIds instanceof Set ? knownIds : new Set(knownIds);
  if (known.size === 0) return new Set();

  const claimed = await claimedSlugs(repoPath, options);

  const inFlight = new Set();
  for (const slug of claimed) {
    if (known.has(slug)) inFlight.add(slug);
  }
  return inFlight;
}