vault-go 0.20.0 → 0.22.0

package/dist/transcript-parser.js

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+import { redact } from './capture-privacy.js';
+const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+const text = (v) => typeof v === 'string' ? v : '';
+function messageText(v) {
+    if (typeof v === 'string')
+        return v;
+    return Array.isArray(v) ? v.map(object).filter(b => ['text', 'input_text', 'output_text'].includes(text(b.type))).map(b => text(b.text)).join('\n') : '';
+}
+export const emptyTranscriptState = () => ({ session: '', cwd: '', private: false, pending: {} });
+function inputObject(v) {
+    if (typeof v === 'string') {
+        try {
+            return object(JSON.parse(v));
+        }
+        catch {
+            return { input: v };
+        }
+    }
+    return object(v);
+}
+function bounded(v) {
+    const value = redact(v), json = JSON.stringify(value ?? null);
+    return json.length <= 16_000 ? value : { truncated: true, preview: String(redact(json.slice(0, 12_000))) };
+}
+// Rollout response_item is canonical. event_msg mirrors are deliberately ignored.
+export function parseTranscript(adapter, value, previous, offset) {
+    const state = structuredClone(previous), row = object(value), events = [];
+    const timestamp = text(row.timestamp);
+    const recordId = text(row.uuid) || createHash('sha256').update(JSON.stringify([state.session, offset, value])).digest('hex');
+    function emit(event, input, id = recordId) {
+        if (!state.private && state.session && state.cwd)
+            events.push({ event, input: { session_id: state.session, cwd: state.cwd, turn_id: id, timestamp, ...input } });
+    }
+    function prompt(content, privateFlag = false) {
+        state.private = privateFlag || /<(?:private|vault-private)\b/i.test(content);
+        state.pending = {};
+        state.summarized = false;
+        if (content.trim())
+            emit('session-init', { prompt: content });
+    }
+    function call(id, name, input) {
+        if (!id || !name || state.private || /vault[_-]go|vault[_-]mem/i.test(name))
+            return;
+        if (Object.keys(state.pending).length >= 16)
+            delete state.pending[Object.keys(state.pending)[0]];
+        state.pending[id] = { name, input: object(bounded(inputObject(input))), timestamp };
+    }
+    function result(id, output) {
+        const call = state.pending[id];
+        if (!call)
+            return;
+        emit('observation', { tool_name: call.name, tool_input: call.input, tool_response: bounded(output), tool_use_id: id, timestamp: call.timestamp }, id);
+        delete state.pending[id];
+    }
+    function scope(session, cwd) {
+        if (session && session !== state.session || cwd && cwd !== state.cwd) {
+            state.pending = {};
+            state.private = true;
+        }
+        if (session)
+            state.session = session;
+        if (cwd)
+            state.cwd = cwd;
+    }
+    if (adapter === 'claude') {
+        scope(text(row.sessionId), text(row.cwd));
+        if (row.private === true || row.isPrivate === true || row.is_private === true) {
+            state.private = true;
+            state.pending = {};
+        }
+        const message = object(row.message), blocks = Array.isArray(message.content) ? message.content.map(object) : [];
+        if (row.type === 'user') {
+            if (blocks.some(b => b.type === 'tool_result')) {
+                for (const b of blocks)
+                    if (b.type === 'tool_result')
+                        result(text(b.tool_use_id), b.content);
+            }
+            else
+                prompt(messageText(message.content), row.isPrivate === true || row.is_private === true || row.private === true || row.isMeta === true);
+        }
+        else if (row.type === 'assistant') {
+            for (const b of blocks)
+                if (b.type === 'tool_use')
+                    call(text(b.id), text(b.name), b.input);
+            const content = messageText(message.content);
+            if (content.trim() && !blocks.some(b => b.type === 'tool_use'))
+                emit('summarize', { last_assistant_message: content });
+        }
+    }
+    else {
+        const payload = object(row.payload);
+        if (row.type === 'session_meta')
+            scope(text(payload.id), text(payload.cwd));
+        if (row.type === 'turn_context')
+            scope('', text(payload.cwd));
+        if (row.type === 'response_item') {
+            if (payload.type === 'message' && payload.role === 'user')
+                prompt(messageText(payload.content));
+            else if (payload.type === 'message' && payload.role === 'assistant') {
+                const content = messageText(payload.content);
+                if (content.trim() && (payload.phase === undefined || payload.phase === 'final_answer')) {
+                    emit('summarize', { last_assistant_message: content });
+                    state.summarized = true;
+                }
+            }
+            else if (payload.type === 'function_call' || payload.type === 'custom_tool_call')
+                call(text(payload.call_id), text(payload.name), payload.arguments ?? payload.input);
+            else if (payload.type === 'function_call_output' || payload.type === 'custom_tool_call_output')
+                result(text(payload.call_id), payload.output);
+        }
+        if (row.type === 'event_msg' && payload.type === 'task_complete' && !state.summarized && text(payload.last_agent_message).trim()) {
+            emit('summarize', { last_assistant_message: payload.last_agent_message });
+            state.summarized = true;
+        }
+    }
+    return { state, events };
+}

package/dist/transcript-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { VaultMemoryApi } from './cloud.js';
+export declare function registerTranscriptTools(server: McpServer, home: string, cloud: VaultMemoryApi): void;

package/dist/transcript-tools.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { run } from './mcp-result.js';
+import { configureTranscriptWatcher, transcriptStatus } from './transcript-config.js';
+import { pollTranscripts } from './transcript-watchers.js';
+import { configureContextChain, contextChainStatus } from './context-chain.js';
+export function registerTranscriptTools(server, home, cloud) {
+    const path = z.string().trim().min(1).max(2000);
+    server.registerTool('vault_go_transcripts_status', { description: 'Watchers opt-in de Claude/Codex neste dispositivo e conta. Requer automaticCapture para enviar eventos; geração usa o motor já escolhido.', inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: false } }, () => run(async () => transcriptStatus(home)));
+    server.registerTool('vault_go_transcripts_configure', {
+        description: 'Ativa/desativa captura persistente de um workspace com consentimento explícito. Por padrão ignora histórico existente; fromStart importa histórico. Hooks nativos preservam contexto e cedem escrita ao watcher enquanto ativo. O worker local precisa estar em execução.',
+        inputSchema: { adapter: z.enum(['claude', 'codex']), workspace: path, root: path.optional(), enabled: z.boolean(), consent: z.boolean().default(false), fromStart: z.boolean().default(false) },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, input => run(async () => { const { root, ...rest } = input; return configureTranscriptWatcher(home, { ...rest, ...(root === undefined ? {} : { root }) }); }));
+    server.registerTool('vault_go_transcripts_poll', { description: 'Processa um lote limitado dos watchers já consentidos. Retomada e idempotência persistem entre reinícios; não ativa captura nem muda o motor.', inputSchema: {}, annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true } }, () => run(() => pollTranscripts(home, cloud)));
+    server.registerTool('vault_go_context_chain', { description: 'Lista vínculos locais entre workspaces para contexto multi-project do SessionStart. Vínculos são específicos desta conta.', inputSchema: {}, annotations: { readOnlyHint: true, openWorldHint: false } }, () => run(async () => contextChainStatus(home)));
+    server.registerTool('vault_go_context_chain_configure', {
+        description: 'Define até quatro raízes relacionadas e/ou o checkout pai de um worktree. Exige consentimento; só consulta projetos já existentes e acessíveis na conta, dentro do orçamento total de contexto. Lista vazia remove os vínculos.',
+        inputSchema: { workspace: path, roots: z.array(path).max(4), consent: z.boolean().default(false), includeWorktreeParent: z.boolean().default(false) },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, input => run(async () => configureContextChain(home, input)));
+}

package/dist/transcript-watchers.d.ts

@@ -0,0 +1,13 @@
+import { type VaultMemoryApi } from './cloud.js';
+export interface TranscriptPollResult {
+    files: number;
+    events: number;
+    bytes: number;
+    busy: boolean;
+    lastError?: string;
+}
+export declare function pollTranscripts(home: string, cloud?: VaultMemoryApi): Promise<TranscriptPollResult>;
+export declare function startTranscriptWatchers(home: string, cloud?: VaultMemoryApi, intervalMs?: number): {
+    isIdle: () => boolean;
+    close: () => Promise<void>;
+};

package/dist/transcript-watchers.js

@@ -0,0 +1,311 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readFileSync, readSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { VaultCloudClient } from './cloud.js';
+import { executeHook } from './hooks.js';
+import { captureCredential, captureOwner, privateJson, readPrivateJson, transcriptTargets, workspaceRoot } from './transcript-config.js';
+import { emptyTranscriptState, parseTranscript } from './transcript-parser.js';
+const MAX_CHUNK = 256_000, MAX_BYTES = 2_000_000, MAX_RECORDS = 200;
+function lock(home) {
+    const path = join(home, 'transcript-consumer.lock'), token = randomUUID();
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            writeFileSync(path, JSON.stringify({ pid: process.pid, token }), { flag: 'wx', mode: 0o600 });
+            return () => { try {
+                if (JSON.parse(readFileSync(path, 'utf8')).token === token)
+                    unlinkSync(path);
+            }
+            catch { /* another owner */ } };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            try {
+                const value = JSON.parse(readFileSync(path, 'utf8'));
+                if (!Number.isInteger(value.pid) || Number(value.pid) <= 0)
+                    throw new Error('Invalid lock');
+                try {
+                    process.kill(Number(value.pid), 0);
+                    return null;
+                }
+                catch (e) {
+                    if (e.code !== 'ESRCH')
+                        return null;
+                }
+                unlinkSync(path);
+            }
+            catch {
+                try {
+                    if (Date.now() - lstatSync(path).mtimeMs > 300_000) {
+                        unlinkSync(path);
+                        continue;
+                    }
+                }
+                catch { /* lock changed */ }
+                return null;
+            }
+        }
+    }
+    return null;
+}
+function scan(root) {
+    const files = [], dirs = [{ path: root, mtime: 0 }];
+    let entries = 0;
+    while (dirs.length && entries < 4096 && files.length < 1000) {
+        dirs.sort((a, b) => b.mtime - a.mtime || b.path.localeCompare(a.path));
+        const directory = dirs.shift().path;
+        let handle;
+        try {
+            handle = opendirSync(directory);
+        }
+        catch {
+            continue;
+        }
+        try {
+            for (let entry = handle.readSync(); entry; entry = handle.readSync()) {
+                if (++entries > 4096 || files.length >= 1000)
+                    break;
+                if (entry.isSymbolicLink())
+                    continue;
+                const path = join(directory, entry.name);
+                if (entry.isDirectory()) {
+                    if (!entry.name.startsWith('.') && dirs.length < 512) {
+                        try {
+                            dirs.push({ path, mtime: lstatSync(path).mtimeMs });
+                        }
+                        catch { /* directory removed */ }
+                    }
+                }
+                else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+                    try {
+                        files.push({ path, mtime: lstatSync(path).mtimeMs });
+                    }
+                    catch { /* rotated during scan */ }
+                }
+            }
+        }
+        finally {
+            handle.closeSync();
+        }
+    }
+    return files.sort((a, b) => b.mtime - a.mtime || a.path.localeCompare(b.path)).map(f => f.path);
+}
+function bytesAt(fd, offset, length) {
+    const bytes = Buffer.alloc(length);
+    return bytes.subarray(0, readSync(fd, bytes, 0, length, offset));
+}
+const digest = (value) => createHash('sha256').update(value).digest('hex');
+function initialCursor(fd, target, existing) {
+    let bytes = 0;
+    const read = (offset, length) => { const result = bytesAt(fd, offset, length); bytes += result.length; return result; };
+    const stat = fstatSync(fd), prefixBytes = Math.min(128, stat.size);
+    const cursor = { dev: stat.dev, ino: stat.ino, offset: 0, prefix: digest(read(0, prefixBytes)), prefixBytes, discarding: false, state: emptyTranscriptState() };
+    cursor.state.private = true;
+    if (!target.fromStart && !existing && Math.floor(stat.birthtimeMs || stat.ctimeMs) <= target.since) {
+        // Metadata bootstrap only; never capture historical records without --from-start.
+        if (target.adapter === 'codex') {
+            const head = read(0, Math.min(16_000, stat.size)).toString('utf8');
+            for (const line of head.split('\n').slice(0, 16)) {
+                try {
+                    const row = JSON.parse(line);
+                    if (row.type === 'session_meta')
+                        cursor.state = parseTranscript(target.adapter, row, cursor.state, 0).state;
+                }
+                catch { /* partial or malformed header */ }
+            }
+        }
+        cursor.offset = stat.size;
+        cursor.discarding = stat.size > 0 && read(stat.size - 1, 1)[0] !== 10;
+    }
+    return { cursor, bytes };
+}
+function saveCheckpoints(home, state, current = '') {
+    let serialized = JSON.stringify(state);
+    for (const key of Object.keys(state.files)) {
+        if (Buffer.byteLength(serialized, 'utf8') <= 4_000_000 && Object.keys(state.files).length <= 1000)
+            break;
+        if (key !== current) {
+            delete state.files[key];
+            serialized = JSON.stringify(state);
+        }
+    }
+    privateJson(home, 'transcript-checkpoints.json', state);
+}
+export async function pollTranscripts(home, cloud = new VaultCloudClient(home)) {
+    const result = { files: 0, events: 0, bytes: 0, busy: false };
+    const targets = transcriptTargets(home), owner = captureOwner(home);
+    if (!owner || !targets.some(t => t.enabled))
+        return result;
+    const release = lock(home);
+    if (!release)
+        return { ...result, busy: true };
+    const saved = readPrivateJson(home, 'transcript-checkpoints.json');
+    const checkpoints = saved?.owner === owner && saved.files && typeof saved.files === 'object' ? saved : { owner, files: {} };
+    let records = 0;
+    try {
+        const preferences = await cloud.preferences?.();
+        if (preferences?.automaticCapture !== true)
+            return result;
+        const credential = captureCredential(home);
+        for (const target of targets.filter(t => t.enabled)) {
+            const allowed = () => {
+                if (owner !== captureOwner(home) || credential !== captureCredential(home) || !transcriptTargets(home).some(t => t.id === target.id && t.enabled && t.since === target.since && t.root === target.root))
+                    throw new Error('capture_consent_changed');
+            };
+            // Keep every API operation bound to the account/consent used at the start of this poll.
+            const guardedCloud = new Proxy(cloud, { get(object, property) {
+                    const method = Reflect.get(object, property);
+                    if (typeof method !== 'function')
+                        return method;
+                    return async (...args) => { allowed(); const value = property === 'preferences' ? preferences : await method.apply(object, args); allowed(); return value; };
+                } });
+            allowed();
+            let files;
+            try {
+                if (realpathSync(target.root) !== target.root)
+                    throw new Error('transcript_root_changed');
+                files = scan(target.root);
+            }
+            catch {
+                result.lastError = 'transcript_capture_failed';
+                checkpoints.lastError = result.lastError;
+                continue;
+            }
+            for (const file of files) {
+                if (result.bytes > MAX_BYTES - 16_257 || records >= MAX_RECORDS || result.files >= 32)
+                    break;
+                const key = digest(JSON.stringify([target.id, file]));
+                let fd;
+                try {
+                    // Recheck real path and O_NOFOLLOW: a replaced file cannot escape the consented root.
+                    try {
+                        if (realpathSync(file) !== file)
+                            continue;
+                        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+                    }
+                    catch (error) {
+                        if (['ENOENT', 'ELOOP'].includes(error.code ?? ''))
+                            continue;
+                        throw error;
+                    }
+                    const stat = fstatSync(fd);
+                    if (!stat.isFile())
+                        continue;
+                    const prior = checkpoints.files[key];
+                    let cursor = prior && Number.isSafeInteger(prior.offset) && prior.offset >= 0 && typeof prior.state?.session === 'string' && typeof prior.state.cwd === 'string' && prior.state.pending && Number.isInteger(prior.prefixBytes) && prior.prefixBytes >= 0 && prior.prefixBytes <= 128 ? prior : undefined;
+                    const prefix = cursor ? bytesAt(fd, 0, cursor.prefixBytes) : Buffer.alloc(0);
+                    result.bytes += prefix.length;
+                    let initialized = false;
+                    if (!cursor || cursor.dev !== stat.dev || cursor.ino !== stat.ino || cursor.offset > stat.size || digest(prefix) !== cursor.prefix) {
+                        const initial = initialCursor(fd, target, Boolean(prior));
+                        cursor = initial.cursor;
+                        result.bytes += initial.bytes;
+                        initialized = true;
+                        result.files++;
+                    }
+                    if (cursor.offset === stat.size) {
+                        checkpoints.files[key] = cursor;
+                        continue;
+                    }
+                    if (!initialized)
+                        result.files++;
+                    const bytes = bytesAt(fd, cursor.offset, Math.min(MAX_CHUNK, MAX_BYTES - result.bytes, stat.size - cursor.offset));
+                    result.bytes += bytes.length;
+                    let position = 0;
+                    while (position < bytes.length && records < MAX_RECORDS) {
+                        const newline = bytes.indexOf(10, position);
+                        if (newline < 0) {
+                            // An oversized line is skipped in bounded chunks; partial normal lines wait for append.
+                            if (cursor.discarding || bytes.length === MAX_CHUNK && position === 0) {
+                                cursor.offset += bytes.length - position;
+                                cursor.discarding = true;
+                                cursor.state.private = true;
+                                cursor.state.pending = {};
+                            }
+                            break;
+                        }
+                        const size = newline - position + 1;
+                        if (!cursor.discarding) {
+                            let value;
+                            try {
+                                value = JSON.parse(bytes.subarray(position, newline).toString('utf8'));
+                            }
+                            catch {
+                                value = null;
+                            }
+                            let parsed;
+                            if (value !== null) {
+                                try {
+                                    parsed = parseTranscript(target.adapter, value, cursor.state, cursor.offset);
+                                }
+                                catch { /* invalid/deeply nested record: fail private below */ }
+                            }
+                            if (parsed) {
+                                if (parsed.state.cwd && workspaceRoot(parsed.state.cwd) === target.workspace) {
+                                    for (const event of parsed.events) {
+                                        allowed();
+                                        await executeHook(target.adapter, event.event, event.input, guardedCloud, home, { transcript: true });
+                                        allowed();
+                                        result.events++;
+                                    }
+                                }
+                                else {
+                                    parsed.state.pending = {};
+                                    parsed.state.private = true;
+                                }
+                                cursor.state = parsed.state;
+                            }
+                            else {
+                                cursor.state.private = true;
+                                cursor.state.pending = {};
+                            }
+                            records++;
+                        }
+                        cursor.offset += size;
+                        cursor.discarding = false;
+                        position = newline + 1;
+                        checkpoints.files[key] = cursor;
+                        // Persist only after API + durable generation queue acknowledge each complete record.
+                        allowed();
+                        saveCheckpoints(home, checkpoints, key);
+                    }
+                    checkpoints.files[key] = cursor;
+                }
+                finally {
+                    if (fd !== undefined)
+                        closeSync(fd);
+                }
+            }
+        }
+        if (!result.lastError)
+            delete checkpoints.lastError;
+    }
+    catch {
+        result.lastError = 'transcript_capture_failed';
+        checkpoints.lastError = result.lastError;
+    }
+    finally {
+        checkpoints.lastScan = Date.now();
+        // Bound checkpoint growth while retaining recent files; replay remains API-idempotent.
+        try {
+            if (owner === captureOwner(home))
+                saveCheckpoints(home, checkpoints);
+        }
+        finally {
+            release();
+        }
+    }
+    return result;
+}
+export function startTranscriptWatchers(home, cloud, intervalMs = 5_000) {
+    let stopped = false, running;
+    const tick = () => {
+        if (stopped || running)
+            return;
+        running = pollTranscripts(home, cloud).catch(() => ({ files: 0, events: 0, bytes: 0, busy: false, lastError: 'transcript_capture_failed' })).finally(() => { running = undefined; });
+    };
+    const timer = setInterval(tick, Math.max(100, intervalMs));
+    timer.unref();
+    tick();
+    return { isIdle: () => !running, close: async () => { stopped = true; clearInterval(timer); await running; } };
+}

package/dist/update-control.d.ts

@@ -3,6 +3,8 @@ import { type UpdateState } from './updater.js';
 export declare function activatePreparedUpdate(home: string, state: UpdateState, operations?: {
     stop: (home: string) => Promise<boolean>;
     start: (home: string) => Promise<LocalHealth>;
+    repair?: (home: string) => void;
+    warn?: (message: string) => void;
 }, options?: {
     automatic?: boolean;
 }): Promise<LocalHealth>;

package/dist/update-control.js

@@ -2,10 +2,12 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync, openSync, closeSync, readFileSync, realpathSync, renameSync, rmSync, lstatSync, unlinkSync, writeFileSync } from 'node:fs';
 import { join, relative, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
 import { stageLocalRuntime, startLocal, stopLocal } from './local-install.js';
 import { installUpdate, updateStatus } from './updater.js';
 import { vaultHome } from './config.js';
 import { generationQueueStatus } from './hook-queue.js';
+import { repairAdditionalClientHooks } from './hook-install.js';
 function preparedPackage(home, state) {
     if (state.status !== 'ready' || !state.packageRoot || !state.latest)
         throw new Error('No validated update is ready.');
@@ -18,8 +20,20 @@ function preparedPackage(home, state) {
         throw new Error('Invalid prepared update.');
     return root;
 }
-export async function activatePreparedUpdate(home, state, operations = { stop: stopLocal, start: startLocal }, options = {}) {
+export async function activatePreparedUpdate(home, state, operations = { stop: stopLocal, start: startLocal, repair: home => repairAdditionalClientHooks(homedir(), home) }, options = {}) {
     const release = await acquireActivationLock(home);
+    const repair = () => {
+        try {
+            operations.repair?.(home);
+        }
+        catch {
+            const message = 'Vault Go: runtime atualizado; reparo dos hooks dos clientes pendente.';
+            try {
+                (operations.warn ?? (warning => { process.stderr.write(warning + '\n'); }))(message);
+            }
+            catch { }
+        }
+    };
     try {
         if (options.automatic && !updateStatus(home).enabled)
             throw new Error('Automatic updates are disabled.');
@@ -29,11 +43,14 @@ export async function activatePreparedUpdate(home, state, operations = { stop: s
             const health = await operations.start(home);
             if (health.version !== state.latest)
                 throw new Error('Active worker version mismatch.');
+            repair();
             return health;
         }
         if (active && compareVersions(active, state.latest) > 0)
             throw new Error('Refusing to activate an older runtime.');
-        return await replaceRuntime(home, state, source, operations);
+        const health = await replaceRuntime(home, state, source, operations);
+        repair();
+        return health;
     }
     finally {
         release();

package/docs/ast-and-awareness.md

@@ -0,0 +1,72 @@
+# AST completo e awareness local do Grok
+
+## Idiomas AST
+
+`vault_go_smart_languages` publica o catálogo e a disponibilidade real na plataforma. `smart_outline`, `smart_unfold` e `smart_search` usam grammars Tree-sitter carregadas pelo ast-grep; indisponibilidade nunca vira parsing por regex. Os limites anteriores de workspace, arquivos privados, bytes, quantidade de arquivos/símbolos e tamanho da saída continuam valendo.
+
+| Idioma | Extensões |
+| --- | --- |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |
+| TypeScript | `.ts`, `.mts`, `.cts` |
+| TSX | `.tsx` |
+| HTML | `.html`, `.htm` |
+| CSS | `.css` |
+| Python | `.py`, `.pyw` |
+| Go | `.go` |
+| Rust | `.rs` |
+| Ruby | `.rb` |
+| Java | `.java` |
+| C | `.c`, `.h` |
+| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hh` |
+| Kotlin | `.kt`, `.kts` |
+| Swift | `.swift` |
+| PHP | `.php` |
+| Lua | `.lua` |
+| Scala | `.scala`, `.sc` |
+| Bash | `.sh`, `.bash`, `.zsh` |
+| Haskell | `.hs` |
+| TOML | `.toml` |
+| YAML | `.yml`, `.yaml` |
+| SQL | `.sql` |
+| Markdown | `.md`, `.mdx` |
+| Zig | `.zig` |
+| SCSS | `.scss` |
+
+Isso cobre os 24 idiomas do `LANG_MAP` upstream, além do HTML que o Vault já suportava. `.mdx` usa a grammar Markdown e `.zsh` usa Bash, como no upstream; não promete validar extensões próprias de MDX/Zsh.
+
+JS/TS/TSX/HTML/CSS usam as grammars de `@ast-grep/napi`. Dezoito outras usam pacotes oficiais `@ast-grep/lang-*`, fixados no `package.json`/lock. Zig e SCSS usam os símbolos C `tree_sitter_zig` e `tree_sitter_scss` exportados pelos prebuilds dos pacotes `@tree-sitter-grammars/tree-sitter-zig@1.1.2` e `tree-sitter-scss@1.0.0`. Carregar esses símbolos diretamente permite usar o mesmo AST/matcher do ast-grep, sem compilar ou executar scripts de instalação.
+
+Os prebuilds são dependências do MCP instalado. O worker local e a fila não importam o parser nem essas dependências. `npm ci --ignore-scripts` é suportado nos sistemas com prebuild compatível. O pacote SCSS não publica prebuild Linux ARM64; ali o catálogo informa indisponibilidade e operações diretas falham explicitamente. Outros alvos também dependem da presença e compatibilidade do prebuild: não há download ou compilação automática durante o uso. Todos os 25 foram verificados nesta implementação em macOS ARM64.
+
+Os nomes/símbolos, corpos e posições vêm de nós e campos da árvore. Markdown usa a árvore de seções para desdobrar uma seção completa. Buscas com metavariáveis foram verificadas também em Python, Go, Zig e SCSS, incluindo a distinção entre chamadas reais e textos em comentários/strings.
+
+O registro segue a [API oficial do ast-grep](https://ast-grep.github.io/guide/api-usage/js-api): todas as grammars são registradas juntas uma vez por processo. Os [pacotes oficiais de grammars](https://github.com/ast-grep/langs) fornecem os parsers pré-compilados. Nenhuma biblioteca escolhida por caminho de workspace/configuração é carregada como código executável.
+
+## Awareness do Grok
+
+Awareness é escrita local de uma linha factual em `agents/<UUID>/memory/log/YYYY-MM.md`, consumida pelo agente Grok. Não é uma integração Telegram.
+
+1. Use `vault_go_grok_awareness_configure` com `enabled=true`, `consent=true`, `agentDataRoot` absoluto existente, `agentIds` permitidos e ao menos um filtro em `triggerTypes` ou `triggerConcepts`.
+2. Use `vault_go_grok_awareness_push` com `agentId` permitido e `memoryIds` UUID para enviar memórias já existentes na conta autenticada.
+3. Consulte `vault_go_grok_awareness_status` ou desative com `enabled=false`.
+
+Nada é ativado por padrão. Não há escolha automática de diretório ou agentes piloto. O consentimento fica em `grok-awareness.json`, privado e específico da conta. Troca de conta revoga o consentimento local. A leitura MCP confere também a credencial antes/depois da API, impedindo publicar um resultado recebido durante troca de conta.
+
+Hooks que recebem `agent_id`/`agentId` preservam esse agente na fila. Após persistir a memória no Vault, a fila envia o fato apenas ao agente correspondente e permitido; não faz broadcast. O pipeline atual grava essas memórias como `discovery`, portanto a automação usa esse tipo e os conceitos gerados. O push por IDs preserva o `memoryType` armazenado e atende aos demais tipos, como `decision` ou `bugfix`. Sem identidade de agente, a fila não escreve awareness.
+
+Cada linha usa a forma `- YYYY-MM-DD [awareness] tipo — título: subtítulo. primeiro fato`, com whitespace colapsado e até 500 caracteres. Flags/blocos privados são rejeitados; credenciais usam a mesma redação da captura. A deduplicação compara o corpo, ignorando a data, dentro do log mensal. O mês usa UTC. `profile.md` não é alterado.
+
+O writer limita lotes a 100 observações e arquivos mensais a 1 MiB, valida a raiz e todos os diretórios descendentes, recusa symlinks/hardlinks de logs e usa lock entre processos e substituição atômica com arquivos 0600. Conteúdo anterior é preservado. Um log cheio ou destino inacessível produz `awareness_write_failed`, sem conteúdo sensível no status. Falha depois da persistência mantém o job para retry; o resultado do modelo já gerado é reutilizado e a importação mantém sua chave idempotente. Desativar awareness permite concluir esses jobs sem nova escrita local. Outros processos que escrevam o mesmo log precisam coordenar acesso para garantir ausência de sobrescrita concorrente.
+
+## Fontes e validação
+
+Contrato upstream consultado no SHA `adce0fdfaf1cd46646bbd0b22ae74cbd460ed787`:
+
+- `src/services/smart-file-read/parser.ts`: `LANG_MAP`, grammars e queries de símbolos.
+- `src/services/integrations/GrokBotAwarenessPusher.ts`: filtros, linha limitada, destino mensal, allowlist e deduplicação.
+- `src/services/worker/agents/ResponseProcessor.ts`: envio vinculado a `pendingAgentId`, após persistência.
+- `tests/integrations/grok-bot-awareness-pusher.test.ts`: casos do writer upstream.
+
+Fixtures do Vault verificam outlines/desdobramento de todos os idiomas, busca estrutural, consentimento/filtros, privacidade, conta, concorrência, rotação, caminho malicioso, retomada sem regeneração, MCP e carregamento do worker staged sem `node_modules`. Nenhum log de agente ou configuração da instalação real foi modificado. A revisão multimodelo foi substituída por revisão manual, pois o gateway LiteLLM não está configurado neste ambiente.
+
+Validação em 2026-09-20 sobre a base `8f08e19341eed95164ee9a77cf178486adeddb0f`: instalação limpa `npm ci --ignore-scripts`, `bun run build`, 178 testes / 1323 assertions (`bun test src`), `git diff --check` e pacote npm passaram. `npm audit --omit=dev` retornou zero vulnerabilidades. A validação posterior à instalação limpa confirmou que as grammars funcionam sem postinstall; o subprocesso staged confirmou que fila/awareness não precisam dessas dependências no worker.