sno-ai/sno-station-skills / skills/R-recursive-self-improvement/rem-reflect/skill
rem-reflect
VerifiedSelf Learning from this machine's Claude Code, Codex, Hermes, OpenClaw and Cursor sessions. Decide skill changes and lessons with accept/reject/tbd; recall lessons at session start.
scripts/rem-reflect.ts
View on GitHubimport { appendFileSync, existsSync, realpathSync } from 'node:fs';
import { join } from 'node:path';
import { pathToFileURL } from 'node:url';
import { execFileSync } from 'node:child_process';
import {
calendar, commands, defaultConfig, isObject, loadConfig, messages, reflectionFiles, storePath,
validateConfig, validateRoots,
} from './config.ts';
import { harvest } from './harvest.ts';
import { readUserId } from './identity.ts';
import {
atomicWrite, commitStore, emptyState, headRevision, initializeStore, parseState, privateDirectory,
processAlive, readHead, readLock, readState, releaseLock, takeOverLock, writeState,
} from './store.ts';
import type { Lock, State } from './store.ts';
import { RealBackend, seedLoopHomes } from './backend.ts';
import type { Backend } from './backend.ts';
import { reflect } from './reflect.ts';
import { lessonsFrom } from './lessons.ts';
import { observe } from './observe.ts';
import { flushCloudVerdicts } from './cloud.ts';
import { buildReport } from './report.ts';
import { verdictCommand } from './adopt.ts';
import { firstMessageRecall, installHooksPrint, lessonDetail, recall } from './recall.ts';
import { cursorRecall, installCursorHooks } from './cursor.ts';
import type { Harness } from './identity.ts';
import { readFileSync } from 'node:fs';
export interface CommandResult { code: number; lines: string[]; stderr?: string[] }
function held(lock: Lock): CommandResult {
return { code: 0, lines: [`lock held by ${lock.command} ${lock.id} (pid ${lock.pid})`] };
}
// One committed SUCCESSFUL reflection per day. A run no-ops only when today already reached a
// terminal success ('no_action' is a successful reflection that proposed nothing); a day whose only
// run failed, timed out, or found no backend is not done, so a retry that day proceeds.
function succeededToday(store: string, date: string): string | undefined {
const text = readHead(store, 'state.json');
const t = text ? parseState(text).last_terminal : null;
return t && t.date === date && (t.status === 'success' || t.status === 'no_action') ? t.id : undefined;
}
export function run(store: string, now: Date = new Date(), user?: string,
backend: Backend = new RealBackend(undefined, { loopHomeBase: join(store, '.loop-home') }),
clock: () => number = () => Date.now(), trigger: 'timer' | 'manual' = 'manual'): CommandResult {
const started = clock();
// Directory existence is not proof of a finished bootstrap: a first run killed after mkdir but
// before config.json, or an empty directory the owner created, would send loadConfig straight
// into a permanent "no config" error that no recovery path can reach. A store that has a commit
// is established, so a config.json missing there stays the hard error it is meant to be.
const bootstrapped = existsSync(join(store, 'config.json')) || headRevision(store) !== undefined;
const fresh = !existsSync(store) || !bootstrapped;
const config = fresh ? defaultConfig() : loadConfig(store);
validateRoots(config, store);
const start = calendar(now, config.time_zone);
const prior = readLock(store);
if (prior && processAlive(prior.pid)) return held(prior);
let state = fresh ? emptyState() : readState(store);
const cloudErrors = fresh ? [] : flushCloudVerdicts(store).errors;
const succeeded = succeededToday(store, start.date);
if (succeeded) return { code: 0, lines: [`no-op: ${succeeded} already succeeded on ${start.date}`, ...cloudErrors] };
privateDirectory(store);
// Finish the bootstrap before recovery touches git. A first run killed mid-initialization can
// leave a store with no repository, or one with a repository and no config.json — recovering
// either would fail outright, or commit a HEAD that every later run rejects for a missing config.
if (fresh) initializeStore(store, config, state);
const userId = user ?? readUserId(store);
const lock: Lock = { pid: process.pid, command: 'run', id: start.id };
// A dead holder is a stale file, not an incident: take the lock over and run. Whatever the dead
// run left behind is in the store's own git history, where it can be inspected or dropped.
const notice = prior ? `previous run ${prior.id} did not finish` : '';
if (!takeOverLock(store, lock)) {
const holder = readLock(store);
return holder ? held(holder) : { code: 0, lines: ['no-op: concurrent store writer; retry later'] };
}
// The same-day guard above ran before the lock existed, so a run that started and finished while
// this one waited is invisible to it. Read the state again now that the lock is held: otherwise
// the day runs twice and the second run writes back a state it read before the first.
if (existsSync(join(store, 'state.json'))) {
state = readState(store);
const succeeded = succeededToday(store, start.date);
if (succeeded) {
releaseLock(store);
return { code: 0, lines: [`no-op: ${succeeded} already succeeded on ${start.date}`, ...cloudErrors] };
}
}
const result = executeHarvest(store, config, state, start, now, userId, notice, backend, clock, started, trigger);
result.lines.push(...cloudErrors);
return result;
}
function executeHarvest(store: string, config: ReturnType<typeof defaultConfig>, state: State,
start: ReturnType<typeof calendar>, now: Date, user: string, notice: string, backend: Backend,
clock: () => number, started: number, trigger: 'timer' | 'manual'): CommandResult {
let code = 0;
let sessionsRead = 0;
let lines: string[] = [];
let committed = false;
const runLog = join(store, 'staging', start.id, 'run.log');
try {
state.last_start = start;
// Persist the date before initialization or harvest can change any other store data.
writeState(store, state);
initializeStore(store, config, state);
atomicWrite(runLog, '');
try {
if (backend instanceof RealBackend && existsSync(config.cursor_root)) seedLoopHomes(store, config, lines);
const result = harvest(store, config, state, user, now);
sessionsRead = result.traces.length;
lines = result.log;
const reflection = reflect(store, config, start.id, backend, lines, now);
state.last_terminal = { ...start, status: reflection.failed ? 'no_backend' : 'success' };
if (reflection.failed) code = 1;
const statusLines = lines.filter(line => line.includes('labeler-'));
const report = buildReport({ store, config, runId: start.id, notice,
labelerLines: statusLines, harvested: result.traces.length,
reflectionReport: reflection.report });
atomicWrite(join(store, 'staging', start.id, 'REPORT.md'), report);
} catch (error) {
code = 1;
const message = error instanceof Error ? error.message : String(error);
lines.push(`harvest failed: ${message}`);
state.last_terminal = { ...start, status: 'failed' };
atomicWrite(join(store, 'staging', start.id, 'REPORT.md'), `${notice ? `${notice}\n` : ''}Run ${start.id} failed\n${message}\n`);
}
appendFileSync(runLog, `${lines.join('\n')}\n`);
writeState(store, state);
commitStore(store, start.id);
committed = true;
observe('rsi.run', { sessions_read: sessionsRead, duration_ms: clock() - started, trigger,
outcome: state.last_terminal?.status === 'success' || state.last_terminal?.status === 'no_action' ? 'ok' : 'fail' }, runLog);
return { code, lines: [`${start.id} ${state.last_terminal?.status}`, ...lines] };
} finally {
// A failed commit keeps the lock and last_start as crash-recovery evidence.
if (committed) releaseLock(store);
}
}
export function heartbeatLine(output: string): string | undefined {
return output.split('\n').find(line => /(?:^|\s)rem-reflect\s+\d+(?:\s|$)/.test(line));
}
function listedHeartbeat(): string {
try {
return execFileSync('sno', ['heartbeat', '--list'], {
encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
});
} catch { return ''; }
}
// sno setup schedules the run with a systemd user timer (Linux) or a launchd agent (macOS) instead of a heartbeat.
function setupTimerOn(): boolean {
try {
if (process.platform === 'darwin') {
execFileSync('launchctl', ['list', 'ai.sno.rem-reflect'], { timeout: 5000, stdio: 'ignore' });
return true;
}
return execFileSync('systemctl', ['--user', 'show', 'sno-rem-reflect.timer', '--property=ActiveState', '--value'], {
encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
}).trim() === 'active';
} catch { return false; }
}
export function status(store: string, now: Date = new Date(), heartbeat: string = listedHeartbeat(),
timer: boolean = setupTimerOn()): CommandResult {
const revision = headRevision(store);
const stateText = readHead(store, 'state.json', revision);
const configText = readHead(store, 'config.json', revision);
const state = stateText ? parseState(stateText) : emptyState();
const config = configText ? validateConfig(JSON.parse(configText)) : defaultConfig();
const lines: string[] = ['Self Learning'];
let code = 0;
const terminal = state.last_terminal;
if (!terminal) { lines.push(' Last run never; start one now with: sno rem-reflect run'); code = 1; }
else {
const bad = ['failed', 'timed_out', 'no_backend', 'died'].includes(terminal.status);
lines.push(` Last run ${terminal.date} · ${terminal.status.replace('_', ' ')} · run ${terminal.id}`);
const today = calendar(now, config.time_zone).date;
if ((Date.parse(today) - Date.parse(terminal.date)) / 86_400_000 > 2) {
lines.push(' ! more than two days ago; the daily run is not happening'); code = 1;
}
if (bad) { lines.push(` ! see what went wrong in ${join(store, 'staging', terminal.id, 'run.log')}`); code = 1; }
}
const lock = readLock(store);
if (lock) {
const alive = processAlive(lock.pid);
lines.push(alive ? ` Running ${lock.command} ${lock.id} (pid ${lock.pid})`
: ` ! ${lock.command} ${lock.id} stopped halfway (pid ${lock.pid} is gone); the next run cleans it up`);
if (!alive) code = 1;
}
const beat = timer || heartbeatLine(heartbeat);
lines.push(beat ? ' Schedule on, once a day in the background'
: ' Schedule off; turn on with: sno heartbeat --interval 24h --max-hours 0 --label rem-reflect -- sno rem-reflect run --trigger timer');
if (!beat) code = 1;
const lessons = lessonsFrom(readHead(store, reflectionFiles.lessons, revision) ?? '');
const count = (...wanted: string[]) => lessons.filter(lesson => wanted.includes(lesson.status)).length;
const waiting = count('candidate', 'under_review');
lines.push(` Lessons ${count('accepted')} accepted · ${waiting} waiting for your yes · ${count('rejected')} rejected`);
if (waiting) lines.push(' decide one with: sno rem-reflect accept <lesson id> or reject <lesson id>');
return { code, lines };
}
function parseFlags(rest: string[]): { positional: string[]; opts: Record<string, string> } {
const opts: Record<string, string> = {};
const positional: string[] = [];
for (let i = 0; i < rest.length; i++) {
if (rest[i].startsWith('--')) { opts[rest[i].slice(2)] = rest[i + 1] ?? ''; i++; }
else positional.push(rest[i]);
}
return { positional, opts };
}
function recallCommand(rest: string[]): CommandResult {
const firstMessage = rest.includes('--first-message');
const { opts } = parseFlags(rest.filter(arg => arg !== '--first-message'));
const agent = opts.agent as Harness;
if (rest[0] === 'install') return installCursorHooks();
if (!['claude-code', 'codex', 'hermes', 'openclaw', 'cursor'].includes(agent)) return { code: 2, lines: ['recall: --agent claude-code|codex|hermes|openclaw|cursor is required'] };
if (agent === 'cursor') {
let stdin = '';
try { stdin = readFileSync(0, 'utf8'); } catch { /* no stdin available */ }
return cursorRecall(storePath(), firstMessage, stdin, listedHeartbeat);
}
let session: string | undefined = opts.session;
let cwd: string | undefined = opts.cwd;
let prompt: string | undefined;
let hookEvent: string | undefined;
let source: string | undefined;
let hermesHook = false;
if (firstMessage || !session || !cwd) {
// the SessionStart hook pipes the harness's JSON on stdin; both harnesses pass session_id and cwd
try {
const value: unknown = JSON.parse(readFileSync(0, 'utf8'));
if (isObject(value)) {
hermesHook = agent === 'hermes' && value.hook_event_name === 'pre_llm_call';
const fields = isObject(value.extra) ? value.extra : value;
if (hermesHook && fields.is_first_turn !== true) return { code: 0, lines: [] };
// The Cursor IDE also runs Claude-format hooks, with its own input; the Cursor entries own Cursor.
if (agent === 'claude-code' && 'cursor_version' in value) return { code: 0, lines: [] };
if (!session && typeof value.session_id === 'string') session = value.session_id;
if (!cwd && typeof value.cwd === 'string') cwd = value.cwd;
if (typeof value.prompt === 'string') prompt = value.prompt;
if (typeof value.hook_event_name === 'string') hookEvent = value.hook_event_name;
if (typeof value.source === 'string') source = value.source;
}
} catch { /* no stdin available */ }
}
// A compaction restart must resend every approved lesson, which only the first-message path does.
const result = firstMessage || hookEvent === 'SessionStart' && source === 'compact' ? firstMessageRecall(storePath(), agent, { session_id: session, cwd, prompt, hook_event_name: hookEvent, source })
: recall(storePath(), agent, { session_id: session, cwd }, new Date(), listedHeartbeat(), setupTimerOn());
if (hermesHook) return { ...result, lines: result.code === 0 ? [JSON.stringify({ context: result.lines.join('\n') })] : [] };
return result;
}
function lessonCommand(rest: string[]): CommandResult {
const { positional, opts } = parseFlags(rest);
if (!positional.length) return { code: 2, lines: ['lesson: a lesson id is required'] };
const agent = opts.agent as Harness | undefined;
if (agent && !['claude-code', 'codex', 'hermes', 'openclaw', 'cursor'].includes(agent)) return { code: 2, lines: ['lesson: --agent must be claude-code, codex, hermes, openclaw or cursor'] };
return lessonDetail(storePath(), positional[0], { session: opts.session, cwd: opts.cwd, agent }, new Date());
}
export function main(args: string[] = process.argv.slice(2)): number {
if (args.length === 0 || (args.length === 1 && (args[0] === '--help' || args[0] === '-h'))) {
console.log(messages.help); return 0;
}
const [command, ...rest] = args;
if (!commands.includes(command)) { console.error(messages.help); return 2; }
const verdicts = ['accept', 'reject', 'tbd'];
try {
let result: CommandResult;
if (command === 'run') {
const opts: Record<string, string> = {};
for (let i = 0; i < rest.length; i += 2) {
const flag = rest[i];
if (!['--now', '--trigger'].includes(flag) || !rest[i + 1] || flag in opts) {
console.error(`run: unexpected argument ${flag}`); return 2;
}
opts[flag] = rest[i + 1];
}
const trigger = opts['--trigger'] ?? 'manual';
if (trigger !== 'timer' && trigger !== 'manual') { console.error('run: --trigger requires timer|manual'); return 2; }
const now = opts['--now'] ? new Date(opts['--now']) : new Date();
if (Number.isNaN(now.getTime())) { console.error('run: --now requires a valid timestamp'); return 2; }
const store = storePath();
if (process.env.REM_SELFTEST && (!process.env.REM_REFLECT_STORE || !existsSync(store))) {
throw new Error(`self-test store missing: ${process.env.REM_REFLECT_STORE || 'REM_REFLECT_STORE'}`);
}
result = run(store, now, undefined, undefined, undefined, trigger);
}
else if (command === 'status') { if (rest.length) { console.error(`status: unexpected argument ${rest[0]}`); return 2; } result = status(storePath()); }
else if (verdicts.includes(command)) {
const scopeFlags = ['--all-projects', '--this-project'];
const flags = rest.filter(arg => scopeFlags.includes(arg));
const ids = rest.filter(arg => !scopeFlags.includes(arg));
if (flags.length > 1 || ids.length !== 1) { console.error(`${command}: one proposal id or lesson id is required`); return 2; }
if (flags.length && (command !== 'accept' || !ids[0].startsWith('L-'))) {
console.error(`${flags[0]} is valid only for lesson accept`); return 2;
}
result = verdictCommand(storePath(), command, ids[0], new Date(), flags[0] === '--all-projects', flags[0] === '--this-project');
if (result.code === 0) {
try {
const sync = flushCloudVerdicts(storePath());
result.lines.push(...sync.errors);
if (sync.pending) result.lines.push(`${sync.pending} cloud verdict pending`);
} catch (error) {
result.lines.push(`local decision persisted; cloud verdict ${ids[0]} pending: ${String(error)}`);
}
}
}
else if (command === 'recall') result = recallCommand(rest);
else if (command === 'lesson') result = lessonCommand(rest);
else if (command === 'install-hooks') {
if (rest[0] !== '--print') { console.error('install-hooks: only --print is supported'); return 2; }
result = installHooksPrint();
}
else { console.error(messages.later); return 3; }
if (result.lines.length) console.log(result.lines.join('\n'));
if (result.stderr?.length) console.error(result.stderr.join('\n'));
return result.code;
} catch (error) {
console.error(error instanceof Error ? error.message : String(error)); return 1;
}
}
// Compare real paths: `import.meta.url` is symlink-resolved by Node, and the deployed skill lives under
// a symlinked harness root, so a raw resolve() of argv[1] would never match and main() would silently
// not run. realpathSync resolves the symlink on both sides.
if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) process.exitCode = main();
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |