flurdy/agent-skills / skills/next
next
VerifiedRank ready beads across validated workspace stores or one local store. List read-only, or claim one selected bead, show its details, and continue into its work.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 50.3 KB |
| pi/index.ts | script | 2.5 KB |
| pi/lease-selection.ts | script | 16.9 KB |
| references/dolt-recovery.md | markdown | 7.7 KB |
| references/source-scope.md | markdown | 12.5 KB |
| scripts/bd-showexecutable | script | 1.1 KB |
| scripts/collect.pyexecutable | script | 25.5 KB |
| scripts/next-bdexecutable | script | 16.5 KB |
| scripts/next-selectexecutable | script | 21.3 KB |
| tests/lease-extension.test.mjs | script | 7.4 KB |
| tests/lease-kernel.test.mjs | script | 3.7 KB |
| tests/lease-selection.test.mjs | script | 20.1 KB |
| tests/test_defer_dates.py | script | 6.8 KB |
| tests/test_dolt_recovery_contract.py | script | 3.3 KB |
| tests/test_machine_routing.py | script | 10.1 KB |
| tests/test_next_bd.py | script | 43.8 KB |
| tests/test_next_select.py | script | 36.2 KB |
| tests/test_ownership_contract.py | script | 2.8 KB |
| tests/test_read_deadlines.py | script | 8.2 KB |
| tests/test_related.py | script | 11.4 KB |
| tests/test_source_scope.py | script | 10.1 KB |
| tests/workspace_fixture.py | script | 10.8 KB |
pi/lease-selection.ts
View on GitHubimport { spawn, execFile } from 'node:child_process';
import { access } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { promisify } from 'node:util';
const collector = fileURLToPath(new URL('../scripts/next-bd', import.meta.url));
const runFile = promisify(execFile);
const MAX_ROOTS = 32;
const COVERAGE = 'Advisory cooperating local Pi occupancy in this process runtime namespace only; not a reservation, source authority, or proof that other harnesses/machines are idle. Completeness is declared, not inferred.';
export function collectCandidates(cwd, signal, timeoutMs = 60000) {
return new Promise((resolve, reject) => {
if (signal?.aborted) { reject(new Error('Selection collection aborted')); return; }
const grouped = process.platform !== 'win32';
const child = spawn(collector, ['--safe-json'], {
cwd, detached: grouped, stdio: ['ignore', 'pipe', 'pipe'],
});
let output = '';
let bytes = 0;
let failure;
let settled = false;
const kill = () => {
if (!child.pid) return;
try { grouped ? process.kill(-child.pid, 'SIGKILL') : child.kill('SIGKILL'); } catch {}
};
const stop = reason => { failure ??= new Error(reason); kill(); };
const abort = () => stop('Selection collection aborted');
const timer = setTimeout(() => stop('Selection collection timed out'), timeoutMs);
signal?.addEventListener('abort', abort, { once: true });
const finish = error => {
if (settled) return;
settled = true;
kill();
clearTimeout(timer);
signal?.removeEventListener('abort', abort);
if (failure || error) reject(failure ?? error);
else {
try { resolve(JSON.parse(output)); } catch { reject(new Error('Invalid selection JSON')); }
}
};
child.stdout.setEncoding('utf8');
child.stdout.on('data', chunk => {
bytes += Buffer.byteLength(chunk);
if (bytes > 2 * 1024 * 1024) stop('Selection output exceeds 2 MiB; narrow the workspace');
else if (!failure) output += chunk;
});
child.stderr.resume();
child.once('error', () => finish(new Error('Selection collector unavailable')));
child.once('close', code => finish(code === 0 ? undefined : new Error('Selection collector failed')));
if (signal?.aborted) abort();
});
}
function validatePacket(packet) {
if (!packet || packet.version !== 1 || !Array.isArray(packet.candidates) || packet.candidates.length > 1000 ||
!Array.isArray(packet.in_progress) || !Array.isArray(packet.diagnostics)) throw new Error('Invalid or oversized selection packet');
for (const row of [...packet.candidates, ...packet.in_progress]) {
if (!row || typeof row !== 'object' || [row.labels ?? [], row.services ?? []].some(values =>
!Array.isArray(values) || values.some(label => typeof label !== 'string'))) throw new Error('Invalid tracker labels');
}
if (packet.candidates.some(row => typeof row.id !== 'string' || typeof row.selector !== 'string' ||
(row.machine_eligibility !== undefined && row.machine_eligibility.eligible !== true) ||
!row.source_scope || !['declared', 'partial', 'unknown', 'invalid', 'unavailable'].includes(row.source_scope.state) ||
!Array.isArray(row.source_scope.roots) || row.source_scope.roots.length > MAX_ROOTS ||
row.source_scope.roots.some(root => typeof root !== 'string' || !root.startsWith('/')) ||
!Array.isArray(row.service_roots ?? []) || (row.service_roots ?? []).length > MAX_ROOTS ||
(row.service_roots ?? []).some(root => typeof root !== 'string' || !root.startsWith('/')) ||
(row.service_roots !== undefined && row.service_roots.length !== (row.services ?? []).length) ||
(['declared', 'partial'].includes(row.source_scope.state) && row.source_scope.roots.length === 0))) {
throw new Error('Invalid source-scope packet');
}
if (new Set(packet.candidates.map(row => row.selector)).size !== packet.candidates.length) throw new Error('Duplicate candidate selectors');
const other = packet.other_machines ?? [];
if (!Array.isArray(other) || other.length > 1000 || other.some(row =>
!row || typeof row.selector !== 'string' || typeof row.id !== 'string' ||
!Array.isArray(row.labels ?? []) || (row.labels ?? []).some(label => typeof label !== 'string') ||
row.machine_eligibility?.eligible !== false || typeof row.machine_eligibility.reason !== 'string')) {
throw new Error('Invalid other-machine packet');
}
if (new Set([...packet.candidates, ...other].map(row => row.selector)).size !== packet.candidates.length + other.length) {
throw new Error('Duplicate machine candidate selectors');
}
if (packet.machine !== undefined && (!packet.machine ||
!(packet.machine.id === null || typeof packet.machine.id === 'string') ||
!['ok', 'missing', 'invalid', 'conflict'].includes(packet.machine.state) ||
typeof packet.machine.source !== 'string' || typeof packet.machine.reason !== 'string')) {
throw new Error('Invalid machine identity packet');
}
const stores = packet.unavailable_stores ?? [];
if (!Array.isArray(stores) || stores.some(store => !store || typeof store.repository !== 'string' ||
typeof store.reason !== 'string' || !(store.hint == null || typeof store.hint === 'string'))) {
throw new Error('Invalid unavailable-store packet');
}
}
export async function classifyCandidates(packet, observer, signal) {
validatePacket(packet);
const declared = [...new Set(packet.candidates.flatMap(row => row.source_scope.roots))];
const labelRoots = [...new Set(packet.candidates.flatMap(row => row.service_roots ?? []))]
.filter(root => !declared.includes(root));
const capacity = declared.length > MAX_ROOTS ? 0 : MAX_ROOTS - declared.length;
const roots = [...declared, ...labelRoots.slice(0, capacity)];
const skippedLabels = labelRoots.length - Math.min(labelRoots.length, capacity);
let observations;
let reason = 'no in-process Pi observer';
if (declared.length > MAX_ROOTS) reason = 'more than 32 unique roots; recheck a single qualified selector';
else if (typeof observer === 'function' && roots.length > 0) {
const deadline = AbortSignal.timeout(4000);
const bounded = signal ? AbortSignal.any([signal, deadline]) : deadline;
let onAbort;
try {
bounded.throwIfAborted();
const cancelled = new Promise((_, reject) => {
onAbort = () => reject(new Error('Observation cancelled'));
bounded.addEventListener('abort', onAbort, { once: true });
});
observations = await Promise.race([observer(roots, { timeoutMs: 2000, signal: bounded }), cancelled]);
if (bounded.aborted) throw new Error('Observation cancelled');
if (!Array.isArray(observations) || observations.length !== roots.length) throw new Error('Invalid observation count');
observations = observations.map((row, index) => {
if (row && ['free', 'held'].includes(row.kind) && row.root === roots[index]) return row;
return { kind: 'unavailable', reason: row?.kind === 'unavailable' ? 'observer unavailable' : 'invalid observation or declared path is not an exact canonical Git root' };
});
} catch {
reason = 'observer failed, cancelled or returned malformed results';
observations = undefined;
} finally {
if (onAbort) bounded.removeEventListener('abort', onAbort);
}
}
const byRoot = new Map(roots.map((root, index) => [root, observations?.[index] ?? { kind: 'unavailable', reason }]));
const result = {
machine: packet.machine, other_machines: packet.other_machines ?? [],
version: 1, workspace: packet.workspace, observedAt: new Date().toISOString(), coverage: COVERAGE,
eligible: [], occupied: [], unknown: [], unavailable: [], tracker_conflicts: [],
in_progress: packet.in_progress, blocked: packet.blocked ?? [], deferred: packet.deferred ?? [],
unavailable_stores: packet.unavailable_stores ?? [],
diagnostics: skippedLabels && typeof observer === 'function'
? [...packet.diagnostics, `${skippedLabels} service-label root${skippedLabels === 1 ? '' : 's'} not observed (32-root limit)`]
: packet.diagnostics,
};
for (const [position, candidate] of packet.candidates.entries()) {
const scope = candidate.source_scope;
const occupancy = scope.roots.map(root => ({ root, ...byRoot.get(root) }));
const labelOccupancy = (candidate.service_roots ?? [])
.map((root, index) => ({ root, kind: 'held', service: candidate.services?.[index] ?? root }))
.filter(item => byRoot.get(item.root)?.kind === 'held');
const overlaps = packet.in_progress
.filter(row => (row.repository ?? 'local') === (candidate.repository ?? 'local'))
.map(row => ({ id: row.id, services: (row.services ?? []).filter(service => (candidate.services ?? []).includes(service)) }))
.filter(row => row.services.length > 0);
const conflicts = overlaps.map(row => row.id);
const row = {
position, selector: candidate.selector, id: candidate.id, repository: candidate.repository ?? 'local',
priority: candidate.priority, issue_type: candidate.issue_type, title: candidate.title,
parent: candidate.parent ?? null,
labels: candidate.labels ?? [], source_scope: scope, occupancy, tracker_overlap: conflicts,
shared_services: [...new Set(overlaps.flatMap(row => row.services))].sort(),
label_occupancy: labelOccupancy,
};
const queue = occupancy.some(item => item.kind === 'held') || labelOccupancy.length ? 'occupied'
: ['unknown', 'partial', 'invalid'].includes(scope.state) ? 'unknown'
: scope.state === 'unavailable' || occupancy.some(item => item.kind !== 'free') ? 'unavailable'
: conflicts.length ? 'tracker_conflicts' : 'eligible';
result[queue].push(row);
}
return result;
}
function displayText(value) {
return String(value ?? '—').replace(/[\x00-\x1f\x7f-\x9f]/g, ' ');
}
function displayCell(value) {
return displayText(value).replaceAll('|', '|');
}
function table(headers, rows) {
const line = cells => `| ${cells.map(displayCell).join(' | ')} |`;
return [line(headers), line(headers.map(() => '---')), ...rows.map(line)].join('\n');
}
const heldRoots = row => row.occupancy.filter(item => item.kind === 'held');
const isOccupied = row => heldRoots(row).length > 0 || (row.label_occupancy ?? []).length > 0;
function leaseCheck(row) {
if (heldRoots(row).length) return 'held';
if ((row.label_occupancy ?? []).length) return 'held (label)';
const scope = row.source_scope.state;
if (['unknown', 'partial', 'invalid'].includes(scope)) return scope;
if (scope === 'unavailable' || row.occupancy.some(item => item.kind !== 'free')) return 'n/a';
return 'free';
}
const shortRoot = root => root.split('/').filter(Boolean).at(-1) ?? root;
const isElapsed = row => row.defer_elapsed === true;
const deferCell = row => isElapsed(row) ? `${displayText(row.defer_until)} ⏰ elapsed` : row.defer_until ?? '—';
const elapsedNote = count => `⏰ ${count} elapsed wake ${count === 1 ? 'date' : 'dates'}: still stored deferred, not ready. Read-only listing never wakes work; review the awaited event before undeferring.`;
export function renderSafeList(result) {
const rows = ['eligible', 'occupied', 'unknown', 'unavailable', 'tracker_conflicts']
.flatMap(queue => result[queue]).sort((a, b) => a.position - b.position);
const occupied = rows.filter(isOccupied);
const overlaps = rows.filter(row => !occupied.includes(row) && row.tracker_overlap.length > 0);
const ready = rows.filter(row => !occupied.includes(row) && row.tracker_overlap.length === 0);
const repoHeaders = result.workspace ? ['Repo'] : [];
const fields = row => [...(result.workspace ? [row.repository] : []), row.id, `P${row.priority}`,
row.issue_type, row.labels?.length ? row.labels.join(', ') : '-', row.title, row.parent || '—'];
const headers = [...repoHeaders, 'ID', 'Pri', 'Type', 'Labels', 'Title', 'Parent'];
const stores = result.unavailable_stores ?? [];
const parts = stores.length ? [`## ⚠️ Beads store unavailable (${stores.length})`,
'Work from these stores is not listed below; this is not an empty backlog.',
stores.map(store => `- **${displayText(store.repository)}** — ${displayText(store.hint ?? store.reason)}`).join('\n')] : [];
if (result.machine) parts.push(`Machine: ${displayCell(result.machine.id ?? 'unknown')} (${displayCell(result.machine.state)}: ${displayCell(result.machine.reason)}); source: ${displayCell(result.machine.source)}`);
for (const [key, title, extra] of [['in_progress', 'Claimed — in progress', ''], ['blocked', 'Waiting — blocked', 'Blocked by'], ['deferred', 'Later — deferred', 'Defer until']]) {
if (!result[key]?.length) continue;
parts.push(`## ${title} (${result[key].length}; not selectable)`);
if (key === 'in_progress') parts.push('Tracker claims; session activity unverified.');
const elapsed = key === 'deferred' ? result[key].filter(isElapsed).length : 0;
if (elapsed) parts.push(elapsedNote(elapsed));
parts.push(table([...headers, ...(extra ? [extra] : [])], result[key].map(row => [...fields(row),
...(key === 'blocked' ? [row.blocked_by?.join(', ') || '—'] : key === 'deferred' ? [deferCell(row)] : [])])));
}
const reasons = rows.flatMap(row => row.occupancy.filter(item => item.kind === 'unavailable')
.map(item => `${row.selector}: ${item.root}: ${item.reason}`));
const diagnostics = [...new Set([...result.diagnostics, ...reasons])];
if (diagnostics.length) parts.push('### Check details', ...diagnostics.map(reason => `- ${displayCell(reason)}`));
if (result.other_machines?.length) parts.push(`## Other machines (${result.other_machines.length} beads; not selectable here)`,
'Machine suitability only; lease occupancy was not checked for these rows.',
table([...headers, 'Run on / reason'], result.other_machines.map(row => [...fields(row), row.machine_eligibility.reason])));
if (occupied.length) parts.push(`## Occupied — source held by another Pi session (${occupied.length} ${occupied.length === 1 ? 'bead' : 'beads'})`,
'held = a declared root is leased; held (label) = a label names a service directory another session leases.',
table([...headers, 'Lease check', 'Held roots'], occupied.map(row => [...fields(row), leaseCheck(row),
[...new Set([...heldRoots(row).map(item => shortRoot(item.root)), ...(row.label_occupancy ?? []).map(item => item.service)])].join(', ')])));
if (overlaps.length) parts.push(`## Held back — same service as in-progress work (${overlaps.length} ${overlaps.length === 1 ? 'bead' : 'beads'})`,
'May collide with claimed work; labels only, not lease evidence.',
table([...headers, 'Lease check', 'Shared service'], overlaps.map(row => [...fields(row), leaseCheck(row),
`${row.shared_services.join(', ')} (${row.tracker_overlap.join(', ')})`])));
parts.push(`## Ready to review (${ready.length} beads)`);
if (!ready.length && stores.length) parts.push('_Ready work unknown: the unavailable stores above were not read._');
else {
parts.push(ready.length ? table(['#', ...headers, 'Lease check'], ready.map((row, index) => [index + 1, ...fields(row), leaseCheck(row)]))
: '_No candidates without known occupancy or a shared in-progress service._');
const checked = ready.filter(row => leaseCheck(row) === 'free').length;
parts.push(`Lease check: ${checked} free, ${ready.length - checked} not checked. unknown = no source_scope declaration; partial = incomplete scope; n/a = observer unavailable. Not checked does not mean occupied. Local Pi only; no reservation.`);
}
parts.push(`Numbers are for review, not safe claims. ${result.workspace ? 'Selector = Repo:ID.' : 'Selector = local:ID.'} Only a fresh eligible recheck permits a safe claim; picking a not-checked row starts ordinary, not lease-checked, work.`);
return parts.join('\n\n');
}
export async function inspectCandidates(cwd, { selector, signal, loadObserver } = {}) {
const packet = await collectCandidates(cwd, signal);
validatePacket(packet);
if (selector !== undefined) {
const other = packet.other_machines?.find(row => row.selector === selector);
if (other) throw new Error(`Machine mismatch: ${other.machine_eligibility.reason}; current machine ${packet.machine?.id ?? 'unknown'}. Inspection is not execution authority.`);
packet.candidates = packet.candidates.filter(row => row.selector === selector);
if (packet.candidates.length !== 1) throw new Error('Selector is no longer ready or its owning source is unavailable; list again');
}
let observer;
const diagnostics = [...packet.diagnostics];
try {
if (process.platform !== 'linux') throw new Error('Linux process evidence required');
await access('/proc/self/stat');
await runFile('lslocks', ['--version'], { timeout: 1000, signal, maxBuffer: 4096 });
observer = await loadObserver?.();
if (typeof observer !== 'function') throw new Error('Observer missing');
} catch {
diagnostics.push('Pi observer/runtime unavailable: require Linux process evidence, lslocks and the matching public observer package');
}
packet.diagnostics = diagnostics;
return classifyCandidates(packet, observer, signal);
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |