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
import { describe, it, expect } from 'vitest';
import { join } from 'path';
import { DONE_SENTINEL_NAME, doneSentinelAgentId, doneSentinelCandidateNames, doneSentinelName, doneSentinelPath, extractSentinelPayloadFromTranscript, missingSentinelLogMessage, parseSentinelPayload, salvageSentinelPayload } from './agentSentinel.js';
describe('missingSentinelLogMessage', () => {
it('names a startup failure as the reason the sentinel was never written', () => {
const message = missingSentinelLogMessage({
agentId: 'agent-1',
reason: 'paste-not-rendered',
sentinelPath: '/work/.agent-done-agent-1',
});
expect(message).toContain('startup failed (paste-not-rendered)');
expect(message).not.toContain('finalized');
});
it('names the TUI command and provider on a startup failure, and only there', () => {
const base = { agentId: 'agent-1', reason: 'paste-not-rendered', sentinelPath: '/work/.agent-done-agent-1' };
expect(missingSentinelLogMessage({ ...base, command: 'codex', providerId: 'codex-tui' }))
.toBe('agent-1 startup failed (paste-not-rendered tui=codex provider=codex-tui) before a completion sentinel could be written');
expect(missingSentinelLogMessage({ ...base, reason: 'idle-timeout', command: 'codex', providerId: 'codex-tui' }))
.toBe('agent-1 finalized (idle-timeout) with no completion sentinel — expected /work/.agent-done-agent-1');
});
it('reads a missing TUI binary as a startup failure too', () => {
// `command-not-found` exits before the prompt was sent — the login-shell
// path printing "command not found" — so it is the same no-prompt shape.
expect(missingSentinelLogMessage({
agentId: 'agent-1',
reason: 'command-not-found',
sentinelPath: '/work/.agent-done-agent-1',
})).toContain('startup failed (command-not-found)');
});
it('keeps the expected path when a run that was working exits without the sentinel', () => {
expect(missingSentinelLogMessage({
agentId: 'agent-1',
reason: 'idle-timeout',
sentinelPath: '/work/.agent-done-agent-1',
})).toContain('expected /work/.agent-done-agent-1');
});
});
describe('agentSentinel', () => {
it('exposes the sentinel filename', () => {
expect(DONE_SENTINEL_NAME).toBe('.agent-done');
});
describe('doneSentinelName', () => {
it('scopes the filename to the agent instance', () => {
expect(doneSentinelName('agent-1a2b3c')).toBe('.agent-done-agent-1a2b3c');
});
it('gives two concurrent agents distinct filenames', () => {
expect(doneSentinelName('agent-aaa')).not.toBe(doneSentinelName('agent-bbb'));
});
it('falls back to the shared name when no id is available', () => {
expect(doneSentinelName(null)).toBe('.agent-done');
expect(doneSentinelName(' ')).toBe('.agent-done');
expect(doneSentinelName(42)).toBe('.agent-done');
});
it('sanitizes path separators out of the id so the name stays one file in the workspace', () => {
// A traversal-shaped id must not escape the workspace directory.
expect(doneSentinelName('../../etc/passwd')).toBe('.agent-done-passwd');
expect(doneSentinelName('a b/c')).toBe('.agent-done-c');
});
});
describe('doneSentinelCandidateNames', () => {
it('keeps the canonical name first and bounds recovery to one dropped hex suffix', () => {
expect(doneSentinelCandidateNames('agent-ded2dccb')).toEqual([
'.agent-done-agent-ded2dccb',
'.agent-done-agent-ded2dcc',
]);
});
it('does not broaden recovery for non-generated or non-hex ids', () => {
expect(doneSentinelCandidateNames('agent-1a2b3c')).toEqual(['.agent-done-agent-1a2b3c']);
expect(doneSentinelCandidateNames('agent-1234567g')).toEqual(['.agent-done-agent-1234567g']);
expect(doneSentinelCandidateNames(null)).toEqual(['.agent-done']);
});
});
describe('doneSentinelPath', () => {
it('resolves the run-scoped file inside the workspace', () => {
// Worktree-less agents share the primary checkout: a bare `.agent-done`
// there may be a sibling run's, and must never finalize this one.
// join(), not a '/'-joined literal: doneSentinelPath composes with path.join,
// so the separator is '\' on Windows and the contract under test is the
// COMPOSITION, not the separator.
expect(doneSentinelPath('/repo', 'agent-1')).toBe(join('/repo', '.agent-done-agent-1'));
});
it('degrades to the shared name when no agent id is available', () => {
expect(doneSentinelPath('/repo', null)).toBe(join('/repo', '.agent-done'));
});
it('returns null without a workspace path', () => {
expect(doneSentinelPath(null, 'agent-1')).toBeNull();
});
});
describe('doneSentinelAgentId', () => {
it('round-trips every id doneSentinelName produces', () => {
for (const id of ['agent-1a2b3c', 'agent-aaa', 'a-b.c_d']) {
expect(doneSentinelAgentId(doneSentinelName(id))).toBe(id);
}
});
it('reports the bare sentinel as belonging to no agent', () => {
expect(doneSentinelAgentId(DONE_SENTINEL_NAME)).toBe('');
});
it('rejects names that are not sentinels', () => {
// `.agent-done-` with nothing after it is a truncated name, not an id of ''
// — treating it as the bare sentinel would delete it on the wrong rule.
expect(doneSentinelAgentId('.agent-done-')).toBeNull();
expect(doneSentinelAgentId('.agent-doneish')).toBeNull();
expect(doneSentinelAgentId('README.md')).toBeNull();
expect(doneSentinelAgentId(null)).toBeNull();
});
});
describe('parseSentinelPayload', () => {
it('returns empty summary + null payload for missing/blank contents', () => {
expect(parseSentinelPayload(null)).toEqual({ summary: '', payload: null });
expect(parseSentinelPayload(undefined)).toEqual({ summary: '', payload: null });
expect(parseSentinelPayload(' \n ')).toEqual({ summary: '', payload: null });
});
it('treats a plain-markdown sentinel as text (legacy back-compat)', () => {
const md = '## Done\n\n- Fixed the bug\n- Opened PR #42';
expect(parseSentinelPayload(md)).toEqual({ summary: md, payload: null });
});
it('does NOT misread a bare JSON array or scalar as structured', () => {
expect(parseSentinelPayload('[1, 2, 3]')).toEqual({ summary: '[1, 2, 3]', payload: null });
expect(parseSentinelPayload('42')).toEqual({ summary: '42', payload: null });
});
it('extracts summary + payload from a JSON object sentinel', () => {
const contents = JSON.stringify({
summary: 'Proposed one improvement',
payload: { proposal: { slug: 'add-telemetry', title: 'Add telemetry' } }
});
expect(parseSentinelPayload(contents)).toEqual({
summary: 'Proposed one improvement',
payload: { proposal: { slug: 'add-telemetry', title: 'Add telemetry' } }
});
});
it('tolerates a JSON object missing summary (payload still surfaces)', () => {
const contents = JSON.stringify({ payload: { proposal: null } });
expect(parseSentinelPayload(contents)).toEqual({ summary: '', payload: { proposal: null } });
});
it('surfaces an explicit null payload as null (not absent)', () => {
const contents = JSON.stringify({ summary: 'nothing to file', payload: null });
expect(parseSentinelPayload(contents)).toEqual({ summary: 'nothing to file', payload: null });
});
it('degrades malformed JSON that opens with { to text', () => {
const broken = '{ not valid json';
expect(parseSentinelPayload(broken)).toEqual({ summary: broken, payload: null });
});
});
describe('salvageSentinelPayload', () => {
const envelope = {
summary: 'Proposed one improvement',
payload: { analysis: 'a', proposal: { slug: 'add-telemetry', title: 'Add telemetry' } }
};
it('returns null payload for blank / brace-free contents', async () => {
expect(await salvageSentinelPayload(null)).toEqual({ summary: '', payload: null });
expect(await salvageSentinelPayload('nothing structured here')).toEqual({ summary: 'nothing structured here', payload: null });
});
it('recovers an envelope wrapped in ```json fences', async () => {
const fenced = '```json\n' + JSON.stringify(envelope) + '\n```';
const { payload } = await salvageSentinelPayload(fenced);
expect(payload).toEqual(envelope.payload);
});
it('recovers an envelope with leading/trailing prose', async () => {
const noisy = `Here is my result:\n${JSON.stringify(envelope)}\nDone.`;
const { summary, payload } = await salvageSentinelPayload(noisy);
expect(payload).toEqual(envelope.payload);
expect(summary).toBe('Proposed one improvement');
});
it('recovers an envelope with raw newlines inside a string value', async () => {
// A local model pastes a multi-line markdown body verbatim (literal \n,
// not the escaped \\n JSON requires) — strict JSON.parse rejects it.
const raw = '{"summary":"s","payload":{"proposal":{"slug":"x","body":"line one\nline two\ttabbed"}}}';
expect(parseSentinelPayload(raw).payload).toBeNull(); // strict parse fails
const { payload } = await salvageSentinelPayload(raw);
expect(payload).toEqual({ proposal: { slug: 'x', body: 'line one\nline two\ttabbed' } });
});
it('recovers an envelope whose proposal body contains a markdown code fence', async () => {
// A reasoner proposing code writes a ```-fenced snippet into the body
// string. The inner-fence heuristic would otherwise lock onto that body
// fence and discard the envelope — salvage must skip it.
const withCodeBody = {
summary: 's',
payload: { proposal: { slug: 'x', body: 'Change this:\n```js\nconst a = 1;\n```\ndone' } }
};
// Both a fenced-wrapper form and a raw (unwrapped) form must recover.
const fenced = '```json\n' + JSON.stringify(withCodeBody) + '\n```';
expect((await salvageSentinelPayload(fenced)).payload).toEqual(withCodeBody.payload);
expect((await salvageSentinelPayload(JSON.stringify(withCodeBody))).payload).toEqual(withCodeBody.payload);
});
it('does NOT misread a legacy markdown summary as structured', async () => {
const md = '## Done\n\nRefactored `foo()` to return `{ ok: true }` on success.';
expect(await salvageSentinelPayload(md)).toEqual({ summary: md, payload: null });
});
it('does NOT adopt an incidental non-envelope JSON object as payload', async () => {
const md = 'Summary of work:\n{"unrelated": "config", "count": 3}';
expect((await salvageSentinelPayload(md)).payload).toBeNull();
});
it('surfaces an explicit null payload from a fenced envelope', async () => {
const fenced = '```json\n{"summary":"nothing to file","payload":null}\n```';
expect(await salvageSentinelPayload(fenced)).toEqual({ summary: 'nothing to file', payload: null });
});
});
describe('extractSentinelPayloadFromTranscript', () => {
const isReasonerPayload = (p) => !!p && typeof p === 'object' && !Array.isArray(p)
&& ['analysis', 'proposal', 'pause'].some(k => Object.hasOwn(p, k));
const ANSWER = '{"analysis":"quiet cycle","proposal":null,"pause":null}';
it('recovers a bare payload object the model printed, ANSI and all', async () => {
const transcript = `\u001b[32m\u25cf\u001b[0m ${ANSWER}\u001b[0m\r\n`;
const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
expect(payload).toEqual({ analysis: 'quiet cycle', proposal: null, pause: null });
});
it('unwraps the documented { summary, payload } envelope when that is what was printed', async () => {
const transcript = 'done: {"summary":"nothing to file","payload":{"proposal":null}}';
expect(await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload))
.toEqual({ summary: 'nothing to file', payload: { proposal: null } });
});
it('takes the LAST matching object, so the final answer beats an earlier prompt echo', async () => {
const transcript = `schema: {"analysis":"<example>","proposal":null}\nanswer: ${ANSWER}`;
const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
expect(payload.analysis).toBe('quiet cycle');
});
it('prefers the enclosing object over its own nested children', async () => {
const transcript = '{"analysis":"a","proposal":{"scope":"self-improve","title":"t"}}';
const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
expect(payload.proposal.title).toBe('t');
});
it('survives a truncated repaint that leaves an unmatched brace before the answer', async () => {
const { payload } = await extractSentinelPayloadFromTranscript(`{ half a redraw ${ANSWER}`, isReasonerPayload);
expect(payload).not.toBeNull();
});
it('keeps a bare deliverable that merely carries its own \`payload\` key', async () => {
// Unwrapping unconditionally would hand the hook the nested value and drop
// the answer the model actually printed.
const transcript = '{"analysis":"a","proposal":null,"payload":"unrelated"}';
const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
expect(payload).toEqual({ analysis: 'a', proposal: null, payload: 'unrelated' });
});
it('yields no payload for malformed or partial JSON', async () => {
expect(await extractSentinelPayloadFromTranscript('{"analysis":"cut off mid-thoug', isReasonerPayload))
.toEqual({ summary: '', payload: null });
expect(await extractSentinelPayloadFromTranscript('{analysis: not json}', isReasonerPayload))
.toEqual({ summary: '', payload: null });
});
it('recovers a printed deliverable that has a trailing comma before a closing brace', async () => {
// Observed in the wild: a no-tool review stage printed a well-formed
// verdict, but one nested array item had a trailing comma before its
// closing `}` — strict JSON.parse rejected the whole block and the
// review was discarded as "no output" even though it approved the PR.
const transcript = '```json\n{"analysis":"a","proposal":{"scope":"self-improve","title":"t",}}\n```';
const { payload } = await extractSentinelPayloadFromTranscript(transcript, isReasonerPayload);
expect(payload.proposal.title).toBe('t');
});
it('recovers the answer even when an earlier line left an unmatched quote', async () => {
const { payload } = await extractSentinelPayloadFromTranscript(`\u2502 renaming "foo\n${ANSWER}`, isReasonerPayload);
expect(payload).not.toBeNull();
});
it('yields no payload for JSON that is not the hook deliverable', async () => {
expect((await extractSentinelPayloadFromTranscript('{"tokens":1200}', isReasonerPayload)).payload).toBeNull();
});
it('yields no payload without a predicate, or for empty/brace-free text', async () => {
expect((await extractSentinelPayloadFromTranscript(ANSWER, null)).payload).toBeNull();
expect((await extractSentinelPayloadFromTranscript('no json here', isReasonerPayload)).payload).toBeNull();
expect((await extractSentinelPayloadFromTranscript(null, isReasonerPayload)).payload).toBeNull();
});
});
});