@phuetz/code-buddy 1.0.0 → 1.1.0

package/README.md

@@ -193,7 +193,7 @@ From source, Cowork requires Node.js `>=22` in `cowork/`; the root CLI still sup
 |:---------|:-----------|:-----|
 | **AI Providers** | 15 providers (Grok, Claude, GPT, Gemini, Ollama, LM Studio, AWS Bedrock, Azure, Groq, Together, Fireworks, OpenRouter, vLLM, Copilot, Mistral), circuit breaker, model pairs | [providers.md](docs/providers.md) |
 | **Tools** | ~110 tools with RAG selection, multi-strategy edit matching, Codex-style apply_patch, streaming, BM25 tool search, code exec sandbox | [tools-reference.md](docs/tools-reference.md) |
-| **Commands** | 190+ slash commands, CLI subcommands (`/dev`, `/pr`, `/lint`, `/switch`, `/think`, `/batch`, `/watch`, `/conflicts`, `/vulns`, `/replace`) | [commands.md](docs/commands.md) |
+| **Commands** | 190+ slash commands, CLI subcommands (`/goal`, `/dev`, `/pr`, `/lint`, `/switch`, `/think`, `/batch`, `/watch`, `/conflicts`, `/vulns`, `/replace`) | [commands.md](docs/commands.md) |
 | **Cowork Desktop** | Electron cockpit, embedded Code Buddy engine, backend health/start controls, model settings, permission rules, visual workflows, traces, artifacts, MCP/skills/plugin management | [Cowork Desktop](docs/cowork.md), [cowork/readme.md](cowork/readme.md), [cowork/ARCHITECTURE.md](cowork/ARCHITECTURE.md) |
 | **Buddy Companion** | ChatGPT-backed identity, voice/TTS, proactive check-ins, self-evaluation, competitive radar, mission board, learned routines, safety ledger, local percept journal | [commands.md](docs/commands.md) |
 | **Vision & Presence** | Opt-in webcam snapshots, MediaPipe face/hand/pose/finger-tip analysis, local face enrollment, presence state for the agent | [cowork/ARCHITECTURE.md](cowork/ARCHITECTURE.md) |
@@ -202,7 +202,7 @@ From source, Cowork requires Node.js `>=22` in `cowork/`; the root CLI still sup
 | **Security** | Guardian Agent (AI risk scoring), OS/Docker/OpenShell sandbox, SSRF guard, secrets vault, write policy, exec policy, loop detection, omission detection, output sanitizer | [security.md](docs/security.md) |
 | **Channels** | 20+ messaging channels (Telegram, Discord, Slack, WhatsApp, Signal, Teams, Matrix, IRC, and more), DM pairing, send policy | [channels.md](docs/channels.md) |
 | **Context Engine** | Smart compression, tool output masking, image pruning, transcript repair, pre-compaction flush, restorable compression, JIT context, importance-weighted window | [context-engine.md](docs/context-engine.md) |
-| **Fleet & Autonomy** | Peer-to-peer hub (`peer.chat` / `peer.tool.invoke` / `peer_delegate`), A2A + ACP + MCP interop, 24/7 autonomous service (`buddy autonomy install`), event-driven daemon, claim TTL/lease, DAG task dependencies, workers→verifier→synthesizer swarm, free-first local→Tailscale→paid model tier | [fleet-guide.md](docs/fleet-guide.md) |
+| **Fleet & Autonomy** | Peer-to-peer hub (`peer.chat` / `peer.tool.invoke` / `peer_delegate`), A2A + ACP + MCP interop, 24/7 autonomous service (`buddy autonomy install`), event-driven daemon, claim TTL/lease, DAG task dependencies, workers→verifier→synthesizer swarm, free-first local→Tailscale→paid model tier, judge-gated goal loops (`/goal` Ralph loop, `buddy goal`, board goal-mode, peer-session goals) | [fleet-guide.md](docs/fleet-guide.md) |
 | **Infrastructure** | HTTP server (OpenAI-compatible), WebSocket gateway, daemon mode, cron, device nodes, canvas/A2UI, 6 cloud deploy configs, MCP, plugins | [infrastructure.md](docs/infrastructure.md) |
 | **Configuration** | Env vars, TOML config with profiles, model-aware limits, per-agent params, i18n (6 locales), personas | [configuration.md](docs/configuration.md) |
 | **Development** | TypeScript strict, Vitest (27,334 tests), ESM, middleware pipeline, facade architecture | [development.md](docs/development.md) |
@@ -214,6 +214,7 @@ From source, Cowork requires Node.js `>=22` in `cowork/`; the root CLI still sup
 - **Vision**: local camera snapshots, MediaPipe face/hand/pose/finger-tip percepts, face enrollment, and presence state for context-aware collaboration
 - **Memory**: Persistent + semantic + prospective + decision + coding style memory, ICM cross-session memory
 - **Knowledge**: Knowledge base injection, 40 bundled skills, self-authoring skills at runtime
+- **Goal Loops (Ralph loop)**: `/goal <text>` + `/subgoal` — a judge model re-checks completion after every turn and auto-continues until done (turn budget, pause/resume, fail-open judge); also headless (`buddy goal`), on fleet board tasks (`--goal-mode`, blocks for human review when the budget is spent), and on peer sessions (`peer.chat-session.goal`)
 - **Git Workflow**: Auto-commit (Aider-style), `/pr` creation, merge conflict resolver, ghost snapshots
 - **Code Intelligence**: LSP rename/refactor, auto-import, bug finder (25+ patterns, 6 langs), OpenAPI generator, log analyzer
 - **IDE Integration**: VS Code extension (diff view, inline edit, model switch), JetBrains plugin, LSP server

package/dist/agent/codebuddy-agent.js

@@ -121,6 +121,11 @@ export class CodeBuddyAgent extends BaseAgent {
         // This is safe because the singletons returned by getters are the concrete implementations
         this.tokenCounter = this.infrastructure.tokenCounter;
         this.contextManager = this.infrastructure.contextManager;
+        // WS3-T2 — periodic memory snapshot for very long sessions. Interval from
+        // CODEBUDDY_SNAPSHOT_INTERVAL_MIN (default 45 min, 0 disables); the timer
+        // is unref'd so it never keeps a finished process alive. Optional call:
+        // test doubles and custom context engines may not implement snapshots.
+        this.contextManager.startPeriodicSnapshot?.(() => this.historyManager.getMessagesRef());
         this.checkpointManager = this.infrastructure.checkpoints;
         this.sessionStore = this.infrastructure.sessions;
         this.modeManager = this.infrastructure.modeManager;
@@ -295,6 +300,20 @@ export class CodeBuddyAgent extends BaseAgent {
                 catch (err) {
                     logger.debug('Failed to register ContextWarningMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
                 }
+                // Session duration middleware (priority 35) — suggests a clean pause
+                // with a fresh resume point past CODEBUDDY_SESSION_PAUSE_HOURS (12 h)
+                try {
+                    const { SessionDurationMiddleware } = await import('./middleware/session-duration.js');
+                    pipeline.use(new SessionDurationMiddleware({
+                        takeSnapshot: () => {
+                            this.contextManager.takeSnapshot?.(this.historyManager.getMessagesRef());
+                        },
+                    }));
+                    logger.debug('SessionDurationMiddleware registered in pipeline (priority 35)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register SessionDurationMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
                 // Reasoning middleware (priority 42) — auto-detects complex queries
                 try {
                     const { createReasoningMiddleware } = await import('./middleware/reasoning-middleware.js');
@@ -1637,6 +1656,19 @@ Look at the screenshot and find the element matching the user's intent. Output o
                 });
             }
         }
+        // WS3-T1 — session-end flush: handoff + review-gated lesson candidates.
+        // Fire-and-forget like the dialectic above; callers that need the flush
+        // to complete before process exit await runSessionEndFlush directly.
+        {
+            const chatHistory = this.historyManager.getChatHistory();
+            if (chatHistory && chatHistory.length > 0) {
+                import('./session-end-flush.js')
+                    .then(({ runSessionEndFlush }) => runSessionEndFlush({ chatHistory, client: this.codebuddyClient }))
+                    .catch((err) => {
+                    logger.debug('[session-end-flush] dispose-path flush failed', { error: String(err) });
+                });
+            }
+        }
         // Remove only the forwarding listeners we attached (not other listeners)
         const { start, success, failed, error } = this.repairListeners;
         if (start) {
@@ -1661,6 +1693,7 @@ Look at the screenshot and find the element matching the user's intent. Output o
                 error: err instanceof Error ? err.message : String(err),
             });
         });
+        this.contextManager.stopPeriodicSnapshot?.();
         this.peerRoutingConfig = null;
         super.dispose();
     }

package/dist/agent/lesson-auto-proposer.js

@@ -15,6 +15,7 @@
 import { CodeBuddyClient } from '../codebuddy/client.js';
 import { detectProviderFromEnv } from '../utils/provider-detector.js';
 import { getLessonCandidateQueue, } from './lesson-candidate-queue.js';
+import { scanForSecrets } from '../fleet/privacy-lint.js';
 import { logger } from '../utils/logger.js';
 const VALID = ['PATTERN', 'RULE', 'CONTEXT', 'INSIGHT'];
 const SYSTEM_PROMPT = `You extract REUSABLE PROCEDURAL LESSONS from a coding session that just completed.
@@ -98,6 +99,15 @@ export async function proposeLessonsFromSession(chatHistory, workDir = process.c
         const content = (cand.content || '').trim();
         if (!content || !VALID.includes(category))
             continue;
+        // WS3 guard-rail: never persist secrets/PII into memory — even into the
+        // review queue, where a reviewer could approve them into lessons.md.
+        const lint = scanForSecrets(`${content}\n${cand.context ?? ''}`);
+        if (lint.hasSecrets) {
+            logger.warn('[lesson-auto-proposer] candidate dropped: contains secret/PII material', {
+                kinds: lint.matches.map((m) => m.kind),
+            });
+            continue;
+        }
         try {
             const { candidate } = queue.propose({
                 category,

package/dist/agent/middleware/session-duration.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Session Duration Middleware (WS3-T3 — auto-pause & resume)
+ *
+ * Very long sessions (12 h+) degrade context quality and pile up risk.
+ * Past a configurable threshold this middleware suggests a clean pause,
+ * takes a fresh context snapshot as the resume point (WS3-T2), and
+ * reminds periodically instead of nagging every turn.
+ *
+ * It never stops the loop — pausing stays the operator's decision; the
+ * autonomous runner has its own bounded budgets (WS1).
+ *
+ * @module agent/middleware
+ */
+import { ConversationMiddleware, MiddlewareContext, MiddlewareResult } from './types.js';
+export interface SessionDurationOptions {
+    /** Pause-suggestion threshold in ms. Default: CODEBUDDY_SESSION_PAUSE_HOURS (12 h); 0 disables. */
+    maxSessionMs?: number;
+    /** Re-warn cadence once past the threshold. Default 60 min. */
+    remindEveryMs?: number;
+    /** Injectable clock for tests. */
+    now?: () => number;
+    /** Take a fresh context snapshot when the pause is suggested (WS3-T2 hook). */
+    takeSnapshot?: () => void;
+}
+export declare class SessionDurationMiddleware implements ConversationMiddleware {
+    readonly name = "session-duration";
+    readonly priority = 35;
+    private readonly startedAt;
+    private readonly thresholdMs;
+    private readonly remindEveryMs;
+    private readonly now;
+    private readonly takeSnapshot;
+    private lastWarnedAt;
+    constructor(options?: SessionDurationOptions);
+    beforeTurn(_context: MiddlewareContext): MiddlewareResult;
+}

package/dist/agent/middleware/session-duration.js

@@ -0,0 +1,78 @@
+/**
+ * Session Duration Middleware (WS3-T3 — auto-pause & resume)
+ *
+ * Very long sessions (12 h+) degrade context quality and pile up risk.
+ * Past a configurable threshold this middleware suggests a clean pause,
+ * takes a fresh context snapshot as the resume point (WS3-T2), and
+ * reminds periodically instead of nagging every turn.
+ *
+ * It never stops the loop — pausing stays the operator's decision; the
+ * autonomous runner has its own bounded budgets (WS1).
+ *
+ * @module agent/middleware
+ */
+import { RunStore } from '../../observability/run-store.js';
+import { logger } from '../../utils/logger.js';
+const HOUR_MS = 3_600_000;
+function defaultThresholdMs() {
+    const hours = parseFloat(process.env.CODEBUDDY_SESSION_PAUSE_HOURS || '12');
+    if (!Number.isFinite(hours) || hours <= 0)
+        return 0; // 0/invalid → disabled
+    return hours * HOUR_MS;
+}
+export class SessionDurationMiddleware {
+    name = 'session-duration';
+    priority = 35;
+    startedAt;
+    thresholdMs;
+    remindEveryMs;
+    now;
+    takeSnapshot;
+    lastWarnedAt = null;
+    constructor(options = {}) {
+        this.now = options.now ?? Date.now;
+        this.startedAt = this.now();
+        this.thresholdMs = options.maxSessionMs ?? defaultThresholdMs();
+        this.remindEveryMs = options.remindEveryMs ?? HOUR_MS;
+        this.takeSnapshot = options.takeSnapshot;
+    }
+    beforeTurn(_context) {
+        if (this.thresholdMs <= 0)
+            return { action: 'continue' };
+        const elapsed = this.now() - this.startedAt;
+        if (elapsed < this.thresholdMs)
+            return { action: 'continue' };
+        if (this.lastWarnedAt !== null && this.now() - this.lastWarnedAt < this.remindEveryMs) {
+            return { action: 'continue' };
+        }
+        this.lastWarnedAt = this.now();
+        // Fresh resume point right when the pause is suggested.
+        try {
+            this.takeSnapshot?.();
+        }
+        catch (err) {
+            logger.debug('[session-duration] snapshot on pause suggestion failed', { error: String(err) });
+        }
+        try {
+            const runStore = RunStore.getInstance();
+            if (runStore.getCurrentRunId()) {
+                runStore.appendEvent('pause_suggested', {
+                    elapsedMs: elapsed,
+                    thresholdMs: this.thresholdMs,
+                });
+            }
+        }
+        catch {
+            // Observability must never break the loop.
+        }
+        const hours = (elapsed / HOUR_MS).toFixed(1);
+        return {
+            action: 'warn',
+            message: `⏸️ Session running for ${hours} h. Consider a clean pause: a fresh context ` +
+                `snapshot was just written (.codebuddy/context-snapshot.json), a handoff is ` +
+                `written on exit (.codebuddy/HANDOFF.md), and \`buddy --continue\` reloads the ` +
+                `session. Long sessions degrade context quality — \`/compact\` also helps.`,
+        };
+    }
+}
+//# sourceMappingURL=session-duration.js.map

package/dist/agent/session-end-flush.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Session-end flush (WS3-T1 — Mémoire & continuité du run).
+ *
+ * When a session ends, persist what the next run needs to not start from
+ * zero:
+ *  1. a short HANDOFF file (`.codebuddy/HANDOFF.md`) — last goal, last
+ *     state, files touched, open risks — written synchronously so it also
+ *     works from process `exit` handlers;
+ *  2. reusable lesson candidates via the existing review-gated
+ *     auto-proposer (PENDING only — a human approves them into lessons.md,
+ *     which the per-turn `<lessons_context>` injection then re-injects on
+ *     future runs).
+ *
+ * Guard-rails: trivial sessions are skipped (no LLM call, no file), and
+ * everything written here passes the privacy lint first (PII/secret spans
+ * are redacted from the handoff; tainted lesson candidates are dropped by
+ * the proposer itself).
+ *
+ * @module agent/session-end-flush
+ */
+import type { CodeBuddyClient } from '../codebuddy/client.js';
+import type { ChatEntry } from './types.js';
+export interface SessionEndFlushInput {
+    chatHistory: ChatEntry[];
+    workDir?: string;
+    /** Reuse the session's LLM client for the lesson proposal (no re-auth). */
+    client?: CodeBuddyClient;
+    sessionId?: string;
+    /** Session start (ms epoch) — used for the duration line of the handoff. */
+    startedAt?: number;
+}
+export interface SessionEndFlushResult {
+    /** Lesson candidates enqueued for review (`buddy lessons` to approve). */
+    proposedLessons: number;
+    /** Absolute path of the handoff file, when one was (re)written. */
+    handoffPath?: string;
+    openRisks: string[];
+    skipped?: 'disabled' | 'trivial';
+}
+/**
+ * Heuristic open-risk extraction: error-ish tool results, deduped per tool,
+ * newest kept. No LLM involved — deterministic and free.
+ */
+export declare function extractOpenRisks(history: ChatEntry[]): string[];
+/** Files touched through write-ish tool calls, for the handoff. */
+export declare function extractTouchedFiles(history: ChatEntry[]): string[];
+export interface HandoffOptions {
+    sessionId?: string;
+    startedAt?: number;
+    /** Force a write even below the size threshold (used by tests). */
+    force?: boolean;
+}
+/**
+ * Write `.codebuddy/HANDOFF.md` synchronously. Returns the path when
+ * written, undefined when the session didn't warrant one. Idempotent per
+ * history array so the async flush and a process-exit fallback don't both
+ * write.
+ */
+export declare function writeHandoffSync(history: ChatEntry[], workDir?: string, options?: HandoffOptions): string | undefined;
+/**
+ * Run the complete session-end flush. Safe to call from any exit path:
+ * no-ops on trivial sessions, never throws.
+ */
+export declare function runSessionEndFlush(input: SessionEndFlushInput): Promise<SessionEndFlushResult>;
+/** Test hook: reset the per-history idempotence latch. */
+export declare function resetSessionEndFlushState(): void;

package/dist/agent/session-end-flush.js

@@ -0,0 +1,217 @@
+/**
+ * Session-end flush (WS3-T1 — Mémoire & continuité du run).
+ *
+ * When a session ends, persist what the next run needs to not start from
+ * zero:
+ *  1. a short HANDOFF file (`.codebuddy/HANDOFF.md`) — last goal, last
+ *     state, files touched, open risks — written synchronously so it also
+ *     works from process `exit` handlers;
+ *  2. reusable lesson candidates via the existing review-gated
+ *     auto-proposer (PENDING only — a human approves them into lessons.md,
+ *     which the per-turn `<lessons_context>` injection then re-injects on
+ *     future runs).
+ *
+ * Guard-rails: trivial sessions are skipped (no LLM call, no file), and
+ * everything written here passes the privacy lint first (PII/secret spans
+ * are redacted from the handoff; tainted lesson candidates are dropped by
+ * the proposer itself).
+ *
+ * @module agent/session-end-flush
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { isFeatureEnabled } from '../config/feature-flags.js';
+import { redactSecrets } from '../fleet/privacy-lint.js';
+import { logger } from '../utils/logger.js';
+// ============================================================================
+// Gates & heuristics
+// ============================================================================
+/** Below this many assistant turns the session is too trivial to flush. */
+const MIN_ASSISTANT_TURNS = 2;
+/** Handoff is only worth writing past this transcript size (chars) … */
+const HANDOFF_MIN_TRANSCRIPT_CHARS = 8_000;
+/** … unless open risks were detected, which always deserve a handoff. */
+const RISK_PATTERN = /\b(error|failed|failure|exception|denied|timeout|timed out|blocked|fatal|refused)\b/i;
+const MAX_RISKS = 5;
+const SNIPPET_MAX = 240;
+function meaningfulTurns(history) {
+    let assistant = 0;
+    let tools = 0;
+    for (const e of history) {
+        if (e.type === 'assistant' && e.content.trim())
+            assistant++;
+        else if (e.type === 'tool_result')
+            tools++;
+    }
+    return { assistant, tools };
+}
+function firstLine(text) {
+    const line = text.trim().split('\n')[0] ?? '';
+    return line.length > SNIPPET_MAX ? `${line.slice(0, SNIPPET_MAX)}…` : line;
+}
+/**
+ * Heuristic open-risk extraction: error-ish tool results, deduped per tool,
+ * newest kept. No LLM involved — deterministic and free.
+ */
+export function extractOpenRisks(history) {
+    const byKey = new Map();
+    for (const e of history) {
+        if (e.type !== 'tool_result')
+            continue;
+        if (!RISK_PATTERN.test(e.content))
+            continue;
+        const tool = e.toolCall?.function?.name || 'tool';
+        byKey.set(tool, `\`${tool}\`: ${firstLine(redactSecrets(e.content))}`);
+    }
+    return [...byKey.values()].slice(-MAX_RISKS);
+}
+/** Files touched through write-ish tool calls, for the handoff. */
+export function extractTouchedFiles(history) {
+    const WRITE_TOOLS = new Set([
+        'str_replace', 'str_replace_editor', 'create_file', 'write_file',
+        'apply_patch', 'edit_file', 'text_editor',
+    ]);
+    const files = new Set();
+    for (const e of history) {
+        const calls = e.toolCalls ?? (e.toolCall ? [e.toolCall] : []);
+        for (const call of calls) {
+            if (!call?.function?.name || !WRITE_TOOLS.has(call.function.name))
+                continue;
+            try {
+                const args = JSON.parse(call.function.arguments || '{}');
+                const p = args.path ?? args.file_path ?? args.filePath;
+                if (typeof p === 'string' && p.trim())
+                    files.add(p.trim());
+            }
+            catch { /* unparseable args — skip */ }
+        }
+    }
+    return [...files].slice(0, 20);
+}
+// ============================================================================
+// Handoff (sync — usable from process exit handlers)
+// ============================================================================
+let handoffWrittenFor = null;
+/**
+ * Write `.codebuddy/HANDOFF.md` synchronously. Returns the path when
+ * written, undefined when the session didn't warrant one. Idempotent per
+ * history array so the async flush and a process-exit fallback don't both
+ * write.
+ */
+export function writeHandoffSync(history, workDir = process.cwd(), options = {}) {
+    if (handoffWrittenFor === history)
+        return undefined;
+    const { assistant } = meaningfulTurns(history);
+    if (assistant < MIN_ASSISTANT_TURNS)
+        return undefined;
+    const transcriptChars = history.reduce((n, e) => n + e.content.length, 0);
+    const risks = extractOpenRisks(history);
+    if (!options.force && transcriptChars < HANDOFF_MIN_TRANSCRIPT_CHARS && risks.length === 0) {
+        return undefined;
+    }
+    const lastUser = [...history].reverse().find((e) => e.type === 'user' && e.content.trim());
+    const lastAssistant = [...history].reverse().find((e) => e.type === 'assistant' && e.content.trim());
+    const touched = extractTouchedFiles(history);
+    const startedAt = options.startedAt;
+    const durationMin = startedAt ? Math.round((Date.now() - startedAt) / 60_000) : undefined;
+    const lines = [
+        '# Session Handoff',
+        '',
+        `> Auto-generated at session end — latest session wins. Read this before resuming work.`,
+        '',
+        `- Date: ${new Date().toISOString()}`,
+        ...(options.sessionId ? [`- Session: ${options.sessionId}`] : []),
+        ...(durationMin !== undefined ? [`- Durée: ~${durationMin} min`] : []),
+        `- Échanges: ${meaningfulTurns(history).assistant} réponses assistant, ${meaningfulTurns(history).tools} résultats d'outils`,
+        '',
+        '## Dernier objectif (utilisateur)',
+        '',
+        lastUser ? firstLine(redactSecrets(lastUser.content)) : '(aucun message utilisateur)',
+        '',
+        '## Dernier état (assistant)',
+        '',
+        lastAssistant ? redactSecrets(lastAssistant.content).trim().slice(0, 800) : '(aucune réponse)',
+        '',
+    ];
+    if (touched.length > 0) {
+        lines.push('## Fichiers touchés', '', ...touched.map((f) => `- \`${f}\``), '');
+    }
+    lines.push('## Risques ouverts', '');
+    if (risks.length > 0) {
+        lines.push(...risks.map((r) => `- ${r}`));
+    }
+    else {
+        lines.push('- Aucun détecté.');
+    }
+    lines.push('', '## Reprise', '', risks.length > 0
+        ? '- Commencer par lever les risques ouverts ci-dessus.'
+        : '- Continuer le dernier objectif, ou `buddy --continue` pour recharger la session.', '- Leçons en attente de revue : `buddy lessons` (candidats proposés en fin de session).', '');
+    const content = redactSecrets(lines.join('\n'));
+    const dir = path.join(workDir, '.codebuddy');
+    const target = path.join(dir, 'HANDOFF.md');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(target, content, 'utf8');
+        handoffWrittenFor = history;
+        return target;
+    }
+    catch (err) {
+        logger.debug('[session-end-flush] handoff write failed', { err: String(err) });
+        return undefined;
+    }
+}
+// ============================================================================
+// Full async flush (handoff + lesson proposal)
+// ============================================================================
+/**
+ * Run the complete session-end flush. Safe to call from any exit path:
+ * no-ops on trivial sessions, never throws.
+ */
+export async function runSessionEndFlush(input) {
+    const empty = { proposedLessons: 0, openRisks: [] };
+    try {
+        if (!isFeatureEnabled('SESSION_END_FLUSH')) {
+            return { ...empty, skipped: 'disabled' };
+        }
+        const history = input.chatHistory ?? [];
+        const { assistant } = meaningfulTurns(history);
+        if (assistant < MIN_ASSISTANT_TURNS) {
+            return { ...empty, skipped: 'trivial' };
+        }
+        const workDir = input.workDir ?? process.cwd();
+        const openRisks = extractOpenRisks(history);
+        const handoffPath = writeHandoffSync(history, workDir, {
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            ...(input.startedAt !== undefined ? { startedAt: input.startedAt } : {}),
+        });
+        // Lesson proposal last — it is the only step that may call an LLM, so a
+        // killed process still leaves the handoff behind.
+        let proposedLessons = 0;
+        try {
+            const { proposeLessonsFromSession } = await import('./lesson-auto-proposer.js');
+            const proposed = await proposeLessonsFromSession(history, workDir, input.client);
+            proposedLessons = proposed.length;
+        }
+        catch (err) {
+            logger.debug('[session-end-flush] lesson proposal failed', { err: String(err) });
+        }
+        if (proposedLessons > 0 || handoffPath) {
+            logger.info(`[session-end-flush] ${proposedLessons} lesson candidate(s) proposed` +
+                (handoffPath ? `, handoff written to ${path.relative(workDir, handoffPath)}` : ''));
+        }
+        return {
+            proposedLessons,
+            ...(handoffPath ? { handoffPath } : {}),
+            openRisks,
+        };
+    }
+    catch (err) {
+        logger.debug('[session-end-flush] flush failed', { err: String(err) });
+        return empty;
+    }
+}
+/** Test hook: reset the per-history idempotence latch. */
+export function resetSessionEndFlushState() {
+    handoffWrittenFor = null;
+}
+//# sourceMappingURL=session-end-flush.js.map

package/dist/commands/cli/native-engine-commands.js

@@ -817,6 +817,8 @@ export function registerFleetAutonomyCommands(program) {
         .option('--priority <p>', 'critical | high | medium | low', 'medium')
         .option('--depends-on <ids>', 'comma-separated task ids this task depends on')
         .option('--description <text>', 'task description')
+        .option('--goal-mode', 'judge-gated loop: the worker keeps going until an LLM judge confirms the task is done, then blocks for human review when the budget is spent')
+        .option('--goal-max-turns <n>', 'goal-mode turn budget (default 5)')
         .option('--dir <path>', 'colab dir')
         .option('--json', 'output JSON')
         .action(async (title, opts) => {
@@ -828,12 +830,15 @@ export function registerFleetAutonomyCommands(program) {
             priority,
             ...(opts.description ? { description: opts.description } : {}),
             ...(opts.dependsOn ? { dependsOn: opts.dependsOn.split(',').map((s) => s.trim()).filter(Boolean) } : {}),
+            ...(opts.goalMode ? { goalMode: true } : {}),
+            ...(opts.goalMaxTurns ? { goalMaxTurns: parseInt(opts.goalMaxTurns, 10) } : {}),
         });
         if (opts.json) {
             console.log(JSON.stringify({ task }, null, 2));
             return;
         }
-        console.log(`Added task ${task.id} [${task.priority}]${task.dependsOn ? ` depends on ${task.dependsOn.join(', ')}` : ''}`);
+        const goalNote = task.goalMode ? ` goal-mode(${task.goalMaxTurns ?? 5} turns)` : '';
+        console.log(`Added task ${task.id} [${task.priority}]${goalNote}${task.dependsOn ? ` depends on ${task.dependsOn.join(', ')}` : ''}`);
     });
     fleet
         .command('swarm <goal>')

package/dist/commands/enhanced-command-handler.js

@@ -62,6 +62,8 @@ handleFastMode,
 handleBtw, setBtwClient, 
 // Heartbeat handler (V4.x — wire user-facing activation of HeartbeatEngine)
 handleHeartbeat, 
+// Goal handler (Hermes Agent parity — Ralph loop)
+handleGoal, handleSubgoal, 
 // Daily reset handler (audit OpenClaw heritage activation)
 handleDailyReset, 
 // Team session handler — slash /share (audit OpenClaw heritage activation, TeamSessionManager wake)
@@ -337,6 +339,9 @@ export class EnhancedCommandHandler {
         ['__BTW__', (args) => handleBtw(args)],
         // Heartbeat engine activation (fleet AUTONOMOUS-FLEET-PROTOCOL v0.1)
         ['__HEARTBEAT__', (args) => handleHeartbeat(args)],
+        // Standing goal — judge + auto-continue loop (Hermes Agent parity)
+        ['__GOAL__', (args) => handleGoal(args)],
+        ['__SUBGOAL__', (args) => handleSubgoal(args)],
         // Daily reset scheduler (audit OpenClaw heritage activation)
         ['__DAILY_RESET__', (args) => handleDailyReset(args)],
         // Team session manager — slash /share (audit OpenClaw heritage, TeamSessionManager wake)

package/dist/commands/goal-cli.d.ts

@@ -0,0 +1,41 @@
+/**
+ * buddy goal — headless Ralph loop.
+ *
+ * Runs the full agentic loop toward a standing goal: each turn the agent
+ * works with tools, then the goal judge decides done/continue. Continuation
+ * prompts are fed back in-process until the goal is achieved, the turn
+ * budget is exhausted, or the judge auto-pauses.
+ *
+ * Usage:
+ *   buddy goal "Fix every failing test in tests/auth/"
+ *   buddy goal "Ship the feature" --max-turns 10 --judge-model qwen3:8b
+ *
+ * Exit codes: 0 = goal done, 1 = paused (budget/judge) or error.
+ */
+import { Command } from 'commander';
+import type { ChatEntry } from '../agent/codebuddy-agent.js';
+import type { CodeBuddyClient } from '../codebuddy/client.js';
+import { GoalStatus } from '../goals/goal-state.js';
+/** The slice of CodeBuddyAgent the loop needs — injectable for tests. */
+export interface GoalLoopAgent {
+    processUserMessage(input: string): Promise<ChatEntry[]>;
+    getClient(): CodeBuddyClient;
+}
+export interface GoalLoopRunOptions {
+    maxTurns?: number;
+    /** Progress sink (status lines ⊙/↻/✓/⏸). Defaults to silent. */
+    onMessage?: (text: string) => void;
+}
+export interface GoalLoopRunResult {
+    status: GoalStatus | 'unknown';
+    turnsUsed: number;
+    lastReason?: string;
+}
+/**
+ * Drive the goal loop headlessly on an in-process agent. Sets the goal,
+ * runs the first turn with the goal text (mirroring the interactive
+ * `/goal <text>` kick-off), then follows judge verdicts until the loop
+ * stops continuing.
+ */
+export declare function runGoalLoop(agent: GoalLoopAgent, goalText: string, options?: GoalLoopRunOptions): Promise<GoalLoopRunResult>;
+export declare function createGoalCommand(): Command;