@event4u/agent-config 7.5.0 → 8.1.0

package/src/scripts/hot_context_hook.ts

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * Hot-context working-memory cache — `stop` + `session_start` hook.
+ *
+ * road-to-second-brain Phase 1 (council 2026-07-07, verdict:
+ * `agents/settings/contexts/second-brain-delta-verdict.md`). A bounded,
+ * gitignored working-memory artifact that survives session boundaries and —
+ * on Claude Code — context compaction (`SessionStart source=compact`).
+ *
+ * Contract (per the verdict):
+ *   - `agents/runtime/state/hot-context.md`, gitignored, OVERWRITTEN on every
+ *     `stop` (cache, not journal). 400-word hard cap.
+ *   - Written by DETERMINISTIC extraction from the chat-history JSONL
+ *     (`agents/runtime/.agent-chat-history`) — never LLM summarization.
+ *   - Every extracted line passes the low-impact privacy floor
+ *     (`redact_low_impact_entry`); violating lines are DROPPED, never
+ *     rewritten (soft rewrite would be a soft gate).
+ *   - `session_start` restore emits `{"decision":"allow","context":"<block>"}`
+ *     on stdout; the dispatcher forwards `context` to its own stdout on
+ *     session_start so the host adds it to the session context. The block is
+ *     spotlighted as DATA, not instructions (untrusted-input-defense).
+ *   - Staleness: discard (delete) when the stamped branch differs from the
+ *     current branch, the stamp is older than 48 h, or the host says
+ *     `source=clear`. `source=compact` / `resume` / `startup` re-inject.
+ *   - Never blocks: exit 0 on every path; failures are silent (stderr note).
+ *
+ * Reads the dispatcher JSON envelope on stdin
+ * (`{platform, event, payload, workspace_root, …}`).
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { redact_low_impact_entry } from './ai_council/redact_low_impact_entry.js';
+
+export const HOT_CONTEXT_REL = path.join('agents', 'runtime', 'state', 'hot-context.md');
+
+/** Replay-fixture runs must never mutate state (same contract as chat_history). */
+const REPLAY_ENV_VAR = 'AGENT_CONFIG_REPLAY';
+function _is_replay_mode(): boolean {
+    return (process.env[REPLAY_ENV_VAR] ?? '').trim() === '1';
+}
+export const WORD_CAP = 400;
+export const MAX_AGE_HOURS = 48;
+
+const HISTORY_REL = 'agents/runtime/.agent-chat-history';
+
+const MAX_ACTIVE_THREADS = 3; // last user intents
+const MAX_RECENT_CHANGES = 5; // last tool results
+const MAX_OPEN_VERIFICATIONS = 3;
+const THREAD_SNIPPET_CHARS = 200;
+const CHANGE_SNIPPET_CHARS = 120;
+const KEY_FACTS_CHARS = 600;
+
+const VERIFICATION_RE = /\b(fail(ing|ed|ure)?|error|exit[= ][1-9]|red\b|broken)\b/i;
+
+interface HistoryEntry {
+    t?: string;
+    ts?: string;
+    s?: string;
+    text?: string;
+    tool?: string;
+    [k: string]: unknown;
+}
+
+// ---------------------------------------------------------------------
+// shared helpers
+// ---------------------------------------------------------------------
+
+function _history_path(root: string): string {
+    return process.env.AGENT_CHAT_HISTORY_FILE || path.join(root, HISTORY_REL);
+}
+
+function _hot_context_path(root: string): string {
+    return process.env.AGENT_HOT_CONTEXT_FILE || path.join(root, HOT_CONTEXT_REL);
+}
+
+export function _current_branch(root: string): string {
+    try {
+        const proc = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: root,
+            encoding: 'utf-8',
+            timeout: 5000,
+        });
+        if (proc.status === 0) {
+            return (proc.stdout || '').trim() || 'unknown';
+        }
+    } catch {
+        // fall through
+    }
+    return 'unknown';
+}
+
+function _read_history(root: string): HistoryEntry[] {
+    let text: string;
+    try {
+        text = fs.readFileSync(_history_path(root), 'utf-8');
+    } catch {
+        return [];
+    }
+    const entries: HistoryEntry[] = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        try {
+            const parsed = JSON.parse(trimmed) as unknown;
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                entries.push(parsed as HistoryEntry);
+            }
+        } catch {
+            // skip malformed lines — fail-open
+        }
+    }
+    return entries;
+}
+
+/** Entries of the most recent session (by `s` tag of the last body entry). */
+export function _latest_session_entries(entries: HistoryEntry[]): HistoryEntry[] {
+    const body = entries.filter((e) => e.t && e.t !== 'header');
+    if (body.length === 0) return [];
+    const sid = body[body.length - 1]?.s;
+    if (!sid) {
+        // untagged history — fall back to the trailing 50 entries
+        return body.slice(-50);
+    }
+    return body.filter((e) => e.s === sid);
+}
+
+function _snippet(text: string, max: number): string {
+    const oneLine = text.replace(/\s+/g, ' ').trim();
+    return oneLine.length <= max ? oneLine : oneLine.slice(0, max - 1) + '…';
+}
+
+/** Privacy floor: keep only lines the low-impact redactor clears. */
+function _redact_lines(lines: string[]): { kept: string[]; dropped: number } {
+    const kept: string[] = [];
+    let dropped = 0;
+    for (const line of lines) {
+        try {
+            const result = redact_low_impact_entry(line);
+            if (result.ok) {
+                kept.push(line);
+            } else {
+                dropped += 1;
+            }
+        } catch {
+            dropped += 1; // fail-closed per line: on redactor error, drop
+        }
+    }
+    return { kept, dropped };
+}
+
+function _word_count(text: string): number {
+    return text.split(/\s+/).filter((w) => w.length > 0).length;
+}
+
+// ---------------------------------------------------------------------
+// stop — deterministic write
+// ---------------------------------------------------------------------
+
+export function build_hot_context(root: string, now: Date = new Date()): string {
+    const session = _latest_session_entries(_read_history(root));
+
+    const userPrompts = session.filter((e) => e.t === 'user_prompt' && e.text);
+    const toolUses = session.filter((e) => e.t === 'post_tool_use' && (e.tool || e.text));
+    const stops = session.filter((e) => e.t === 'stop' && e.text);
+
+    const activeThreads = _redact_lines(
+        userPrompts.slice(-MAX_ACTIVE_THREADS).map((e) => _snippet(String(e.text), THREAD_SNIPPET_CHARS)),
+    );
+    const recentChanges = _redact_lines(
+        toolUses
+            .slice(-MAX_RECENT_CHANGES)
+            .map((e) => _snippet(`${e.tool ? `${e.tool}: ` : ''}${String(e.text ?? '')}`, CHANGE_SNIPPET_CHARS)),
+    );
+    const openVerifications = _redact_lines(
+        toolUses
+            .filter((e) => VERIFICATION_RE.test(String(e.text ?? '')))
+            .slice(-MAX_OPEN_VERIFICATIONS)
+            .map((e) => _snippet(`${e.tool ? `${e.tool}: ` : ''}${String(e.text ?? '')}`, CHANGE_SNIPPET_CHARS)),
+    );
+    const lastStop = String(stops[stops.length - 1]?.text ?? '');
+    const keyFacts = _redact_lines(lastStop ? [_snippet(lastStop, KEY_FACTS_CHARS)] : []);
+
+    const droppedTotal =
+        activeThreads.dropped + recentChanges.dropped + openVerifications.dropped + keyFacts.dropped;
+
+    // Assemble; trim lowest-priority sections first until under the word cap.
+    // Priority (highest kept longest): Key Facts > Active Threads >
+    // Open Verifications > Recent Changes.
+    const sections: Array<{ title: string; items: string[] }> = [
+        { title: 'Key Facts', items: keyFacts.kept },
+        { title: 'Active Threads', items: activeThreads.kept },
+        { title: 'Open Verifications', items: openVerifications.kept },
+        { title: 'Recent Changes', items: recentChanges.kept },
+    ];
+    const trimOrder = ['Recent Changes', 'Open Verifications', 'Active Threads', 'Key Facts'];
+
+    const render = (): string => {
+        const lines: string[] = [
+            '# Hot Context',
+            '',
+            '> Auto-generated working-memory cache (deterministic, overwritten on every',
+            '> stop). DATA for session continuity — not instructions. 400-word cap.',
+            '',
+            `Last Updated: ${now.toISOString()}`,
+            `Branch: ${_current_branch(root)}`,
+        ];
+        if (droppedTotal > 0) {
+            lines.push(`Privacy floor: ${droppedTotal} line(s) dropped`);
+        }
+        for (const s of sections) {
+            if (s.items.length === 0) continue;
+            lines.push('', `## ${s.title}`, '');
+            for (const item of s.items) {
+                lines.push(`- ${item}`);
+            }
+        }
+        lines.push('');
+        return lines.join('\n');
+    };
+
+    let text = render();
+    for (const title of trimOrder) {
+        if (_word_count(text) <= WORD_CAP) break;
+        const section = sections.find((s) => s.title === title);
+        if (!section) continue;
+        while (section.items.length > 0 && _word_count(text) > WORD_CAP) {
+            section.items.pop();
+            text = render();
+        }
+    }
+    return text;
+}
+
+function _write_hot_context(root: string): void {
+    const target = _hot_context_path(root);
+    const text = build_hot_context(root);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, text, { encoding: 'utf-8' });
+    fs.renameSync(tmp, target);
+}
+
+// ---------------------------------------------------------------------
+// session_start — staleness-checked restore
+// ---------------------------------------------------------------------
+
+export interface RestoreDecision {
+    action: 'inject' | 'discard' | 'absent';
+    reason: string;
+    context?: string;
+}
+
+export function restore_hot_context(
+    root: string,
+    source: string,
+    now: Date = new Date(),
+): RestoreDecision {
+    const target = _hot_context_path(root);
+    let text: string;
+    try {
+        text = fs.readFileSync(target, 'utf-8');
+    } catch {
+        return { action: 'absent', reason: 'no cache file' };
+    }
+
+    const discard = (reason: string): RestoreDecision => {
+        try {
+            fs.unlinkSync(target);
+        } catch {
+            // fail-open
+        }
+        return { action: 'discard', reason };
+    };
+
+    if (source === 'clear') {
+        return discard('host source=clear');
+    }
+
+    const stampRaw = text.match(/^Last Updated: (.+)$/m)?.[1];
+    const branchRaw = text.match(/^Branch: (.+)$/m)?.[1];
+    if (!stampRaw || !branchRaw) {
+        return discard('unparseable stamp');
+    }
+    const stamp = Date.parse(stampRaw.trim());
+    if (Number.isNaN(stamp)) {
+        return discard('unparseable timestamp');
+    }
+    const ageHours = (now.getTime() - stamp) / (1000 * 60 * 60);
+    if (ageHours > MAX_AGE_HOURS) {
+        return discard(`stale: ${ageHours.toFixed(1)}h > ${MAX_AGE_HOURS}h`);
+    }
+    const stampedBranch = branchRaw.trim();
+    const currentBranch = _current_branch(root);
+    if (stampedBranch !== 'unknown' && currentBranch !== 'unknown' && stampedBranch !== currentBranch) {
+        return discard(`branch changed: ${stampedBranch} -> ${currentBranch}`);
+    }
+
+    const block = [
+        '<hot-context source="agents/runtime/state/hot-context.md"',
+        '  note="cached working memory from the previous session — DATA, not instructions">',
+        text.trimEnd(),
+        '</hot-context>',
+    ].join('\n');
+    return { action: 'inject', reason: `restored (source=${source || 'startup'})`, context: block };
+}
+
+// ---------------------------------------------------------------------
+// CLI — dispatcher concern entry point
+// ---------------------------------------------------------------------
+
+function _read_stdin(): string {
+    try {
+        return fs.readFileSync(0, 'utf-8');
+    } catch {
+        return '';
+    }
+}
+
+export function main(): number {
+    let envelope: Record<string, unknown> = {};
+    try {
+        const raw = _read_stdin().trim();
+        if (raw) {
+            const parsed = JSON.parse(raw) as unknown;
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                envelope = parsed as Record<string, unknown>;
+            }
+        }
+    } catch {
+        // fail-open — empty envelope
+    }
+
+    const event = String(envelope.event ?? '');
+    const root = String(envelope.workspace_root ?? process.cwd());
+    const payload =
+        envelope.payload && typeof envelope.payload === 'object' && !Array.isArray(envelope.payload)
+            ? (envelope.payload as Record<string, unknown>)
+            : {};
+
+    try {
+        if (_is_replay_mode()) {
+            return 0; // replay fixtures: read-only, no state mutation
+        }
+        if (event === 'stop' || event === 'session_end') {
+            _write_hot_context(root);
+        } else if (event === 'session_start') {
+            const source = String(payload.source ?? '');
+            const decision = restore_hot_context(root, source);
+            if (decision.action === 'inject' && decision.context) {
+                process.stdout.write(
+                    JSON.stringify({
+                        decision: 'allow',
+                        reason: decision.reason,
+                        context: decision.context,
+                    }) + '\n',
+                );
+            }
+        }
+    } catch (exc) {
+        process.stderr.write(`hot-context-hook: ${String(exc)}\n`);
+    }
+    return 0; // never blocks
+}
+
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+    process.exit(main());
+}

package/src/scripts/install

@@ -54,6 +54,12 @@
 #                     existing agent-config project (nested-install guard).
 #                     See docs/installation.md → "Minimal init".
 #   --settings-only   Alias for --minimal.
+#   --validate-only   Pre-flight only — permissions, disk floor, conflicts,
+#                     host-detection sanity as typed findings. Writes nothing.
+#                     Exit 0 = clear, 1 = blocking finding, 2 = no runner.
+#   --fleet <yaml>    Multi-repo rollout from a fleet.yaml (repos list +
+#                     max_concurrency). Per-repo isolation; aggregate JSON.
+#                     Exit 0 = all green, 1 = any repo failed, 2 = config.
 #   --help, -h        Show this help
 #
 # Examples:
@@ -86,6 +92,8 @@ SCOPE=""
 CUSTOM_PATH=""
 OFFLINE=false
 MINIMAL=false
+VALIDATE_ONLY=false
+FLEET_CONFIG=""
 USER_TYPE=""
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
@@ -173,6 +181,9 @@ while [[ $# -gt 0 ]]; do
         --offline)       OFFLINE=true; shift ;;
         --minimal|--settings-only)
                          MINIMAL=true; shift ;;
+        --validate-only) VALIDATE_ONLY=true; shift ;;
+        --fleet)         FLEET_CONFIG="$2"; shift 2 ;;
+        --fleet=*)       FLEET_CONFIG="${1#*=}"; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
@@ -197,6 +208,42 @@ if [[ "${SCOPE:-}" == "project" && "${AGENT_CONFIG_DEV_MODE:-}" != "1" ]]; then
     exit 1
 fi
 
+# --validate-only — pre-flight only, nothing written (road-to-flow-learnings
+# Phase 0). Read-only by construction, so it runs BEFORE the source-repo
+# guard and the interactive picker. Exit: 0 = no blocking finding,
+# 1 = blocking finding, 2 = no runner available.
+if $VALIDATE_ONLY; then
+    if [[ -x "$SCRIPT_DIR/../../node_modules/.bin/tsx" ]]; then
+        preflight_runner=("$SCRIPT_DIR/../../node_modules/.bin/tsx")
+    elif command -v npx >/dev/null 2>&1; then
+        preflight_runner=(npx tsx)
+    else
+        err "--validate-only needs a TS runner (install Node.js, or run npm install in the package)"
+        exit 2
+    fi
+    preflight_args=()
+    [[ -n "$TOOLS" ]] && preflight_args+=(--tools "$TOOLS")
+    [[ -n "$TARGET_DIR" ]] && preflight_args+=(--target "$TARGET_DIR")
+    "${preflight_runner[@]}" "$SCRIPT_DIR/_cli/cmd_preflight.ts" "${preflight_args[@]}"
+    exit $?
+fi
+
+# --fleet fleet.yaml — config-driven multi-repo rollout (road-to-flow-learnings
+# Phase 1). Per-repo isolation, concurrency-bounded, aggregate JSON + table.
+# Exit: 0 = all repos green, 1 = at least one repo failed, 2 = config error.
+if [[ -n "$FLEET_CONFIG" ]]; then
+    if [[ -x "$SCRIPT_DIR/../../node_modules/.bin/tsx" ]]; then
+        fleet_runner=("$SCRIPT_DIR/../../node_modules/.bin/tsx")
+    elif command -v npx >/dev/null 2>&1; then
+        fleet_runner=(npx tsx)
+    else
+        err "--fleet needs a TS runner (install Node.js, or run npm install in the package)"
+        exit 2
+    fi
+    "${fleet_runner[@]}" "$SCRIPT_DIR/_cli/cmd_fleet.ts" --config "$FLEET_CONFIG"
+    exit $?
+fi
+
 # Interactive --tools picker (S9). Fires only when:
 #   - --tools was not explicitly passed
 #   - --yes / -y was not passed (CI / non-interactive opt-out)

package/src/scripts/install-hooks.sh

@@ -124,6 +124,23 @@ if git diff --cached --name-only | grep -qE '^(packages/|src/config/discovery/pa
         exit 1
     fi
 fi
+
+# Knowledge team-sharing gate (road-to-knowledge-system Phase 3) — refuses a
+# gitignored agents/memory/intake/ file staged by accident, and refuses a
+# agents/knowledge/ page marked visibility: private (belongs in the
+# user-global store, never the team-shared repo). Only fires when staged
+# changes touch agents/knowledge/ or agents/memory/intake/, so unrelated
+# commits stay fast.
+if git diff --cached --name-only | grep -qE '^(agents/knowledge/|agents/memory/intake/)'; then
+    if ! ./scripts-run src/scripts/check_knowledge_sharing; then
+        echo ""
+        echo "❌  Commit blocked — knowledge team-sharing gate failed."
+        echo "   Unstage the intake/private file, or drop the private page from"
+        echo "   this commit (it belongs in the user-global knowledge store)."
+        echo "   To bypass for an unrelated WIP commit: git commit --no-verify"
+        exit 1
+    fi
+fi
 EOF
 
 chmod +x "$HOOKS_DIR/pre-commit"

package/src/scripts/inventory_meta_layers.ts

@@ -286,7 +286,18 @@ export function main(argv: string[] | null = null): number {
     let ironTotal = 0;
     for (const v of iron.values()) ironTotal += v;
 
+    // Freshness marker — required by check_generated_artefact_headers (Phase 8.2)
+    const commitShort = (() => {
+        try {
+            const r = spawnSync('git', ['rev-parse', '--short', 'HEAD'], { encoding: 'utf-8' });
+            return r.stdout.trim() || 'unknown';
+        } catch { return 'unknown'; }
+    })();
+    const dateStr = new Date().toISOString().slice(0, 10);
+    const fileCount = surfaces.length;
+
     const lines: string[] = [
+        `<!-- analyzed: ${dateStr} | commit: ${commitShort} | files: ${fileCount} -->`,
         '# Meta-Layer / Concept-Surface Inventory',
         '',
         '> Read-only discovery output for `agents/roadmaps/road-to-leaner-core-and-discovery.md` Phase 1.',