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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* 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;
}