vibeusage 0.2.19 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibeusage",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "Codex CLI token usage tracker (macOS-first, notify-driven).",
   "license": "MIT",
   "publishConfig": {
@@ -9,6 +9,7 @@
   "type": "commonjs",
   "scripts": {
     "test": "node --test test/*.test.js",
+    "ci:local": "npm test && npm run validate:copy && npm run validate:ui-hardcode && npm run validate:guardrails && node --test test/architecture-guardrails.test.js && npm run build:insforge:check && npm --prefix dashboard run build",
     "smoke": "node scripts/smoke/insforge-smoke.cjs",
     "build:insforge": "node scripts/build-insforge-functions.cjs",
     "build:insforge:check": "node scripts/build-insforge-functions.cjs --check",
@@ -24,6 +25,7 @@
     "architecture:canvas:focus": "node scripts/ops/architecture-canvas.cjs --focus",
     "architecture:canvas:list-modules": "node scripts/ops/architecture-canvas.cjs --list-modules",
     "validate:guardrails": "node scripts/validate-architecture-guardrails.cjs",
+    "validate:retros": "node scripts/validate-retros.cjs",
     "validate:insforge2-db": "node scripts/ops/insforge2-db-validate.cjs",
     "graph:scip": "node scripts/graph/generate-scip.cjs",
     "graph:auto-index": "node scripts/graph/auto-index.cjs"

package/src/commands/init.js

@@ -22,7 +22,11 @@ const {
   isGeminiHookConfigured
 } = require('../lib/gemini-config');
 const { resolveOpencodeConfigDir, upsertOpencodePlugin, isOpencodePluginInstalled } = require('../lib/opencode-config');
-const { installOpenclawHook, probeOpenclawHookState } = require('../lib/openclaw-hook');
+const { removeOpenclawHookConfig, probeOpenclawHookState } = require('../lib/openclaw-hook');
+const {
+  installOpenclawSessionPlugin,
+  probeOpenclawSessionPluginState
+} = require('../lib/openclaw-session-plugin');
 const { beginBrowserAuth, openInBrowser } = require('../lib/browser-auth');
 const {
   issueDeviceTokenWithPassword,
@@ -408,32 +412,47 @@ async function applyIntegrationSetup({ home, trackerDir, notifyPath, notifyOrigi
     summary.push({ label: 'Opencode Plugin', status: opencodeResult?.changed ? 'installed' : 'set', detail: 'Plugin installed' });
   }
 
-  const openclawBefore = await probeOpenclawHookState({ home, trackerDir, env: process.env });
-  const openclawInstall = await installOpenclawHook({ home, trackerDir, packageName: 'vibeusage', env: process.env });
+  const openclawBefore = await probeOpenclawSessionPluginState({ home, trackerDir, env: process.env });
+  const openclawInstall = await installOpenclawSessionPlugin({
+    home,
+    trackerDir,
+    packageName: 'vibeusage',
+    env: process.env
+  });
   if (openclawInstall?.skippedReason === 'openclaw-cli-missing') {
-    summary.push({ label: 'OpenClaw Hook', status: 'skipped', detail: 'OpenClaw CLI not found' });
-  } else if (openclawInstall?.skippedReason === 'openclaw-hooks-install-failed') {
+    summary.push({ label: 'OpenClaw Session Plugin', status: 'skipped', detail: 'OpenClaw CLI not found' });
+  } else if (openclawInstall?.skippedReason === 'openclaw-plugins-install-failed') {
     summary.push({
-      label: 'OpenClaw Hook',
+      label: 'OpenClaw Session Plugin',
       status: 'skipped',
       detail: `Install failed${openclawInstall.error ? `: ${openclawInstall.error}` : ''}`
     });
   } else if (openclawInstall?.skippedReason === 'openclaw-config-unreadable') {
     summary.push({
-      label: 'OpenClaw Hook',
+      label: 'OpenClaw Session Plugin',
       status: 'skipped',
       detail: openclawInstall.error ? `OpenClaw config unreadable: ${openclawInstall.error}` : 'OpenClaw config unreadable'
     });
   } else if (openclawInstall?.configured) {
     summary.push({
-      label: 'OpenClaw Hook',
+      label: 'OpenClaw Session Plugin',
       status: openclawBefore?.configured ? 'set' : 'installed',
       detail: openclawBefore?.configured
-        ? 'Hook already linked'
-        : 'Hook linked (restart OpenClaw gateway to activate)'
+        ? 'Session plugin already linked'
+        : 'Session plugin linked (restart OpenClaw gateway to activate)'
     });
   } else {
-    summary.push({ label: 'OpenClaw Hook', status: 'skipped', detail: 'OpenClaw hook unavailable' });
+    summary.push({ label: 'OpenClaw Session Plugin', status: 'skipped', detail: 'OpenClaw session plugin unavailable' });
+  }
+
+  const legacyHookState = await probeOpenclawHookState({ home, trackerDir, env: process.env });
+  if (legacyHookState?.configured || legacyHookState?.linked || legacyHookState?.enabled) {
+    await removeOpenclawHookConfig({ home, trackerDir, env: process.env });
+    summary.push({
+      label: 'OpenClaw Hook (legacy)',
+      status: 'updated',
+      detail: 'Removed legacy command hook (migrated to session plugin)'
+    });
   }
 
   const codeProbe = await probeFile(context.codeConfigPath);
@@ -515,22 +534,31 @@ async function previewIntegrations({ context }) {
     detail: opencodeDetail
   });
 
-  const openclawState = await probeOpenclawHookState({ home, trackerDir: context.trackerDir, env: process.env });
+  const openclawState = await probeOpenclawSessionPluginState({ home, trackerDir: context.trackerDir, env: process.env });
   if (openclawState?.skippedReason === 'openclaw-config-missing') {
-    summary.push({ label: 'OpenClaw Hook', status: 'skipped', detail: 'OpenClaw config not found' });
+    summary.push({ label: 'OpenClaw Session Plugin', status: 'skipped', detail: 'OpenClaw config not found' });
   } else if (openclawState?.skippedReason === 'openclaw-config-unreadable') {
     summary.push({
-      label: 'OpenClaw Hook',
+      label: 'OpenClaw Session Plugin',
       status: 'skipped',
       detail: openclawState.error ? `OpenClaw config unreadable: ${openclawState.error}` : 'OpenClaw config unreadable'
     });
   } else {
     summary.push({
-      label: 'OpenClaw Hook',
+      label: 'OpenClaw Session Plugin',
       status: openclawState?.configured ? 'set' : 'installed',
       detail: openclawState?.configured
-        ? 'Hook already linked'
-        : 'Will link hook (restart OpenClaw gateway to activate)'
+        ? 'Session plugin already linked'
+        : 'Will link session plugin (restart OpenClaw gateway to activate)'
+    });
+  }
+
+  const legacyHookState = await probeOpenclawHookState({ home, trackerDir: context.trackerDir, env: process.env });
+  if (legacyHookState?.configured || legacyHookState?.linked || legacyHookState?.enabled) {
+    summary.push({
+      label: 'OpenClaw Hook (legacy)',
+      status: 'updated',
+      detail: 'Will remove legacy command hook during migration'
     });
   }
 
@@ -787,6 +815,12 @@ async function installLocalTrackerApp({ appDir }) {
   const binFrom = path.join(packageRoot, 'bin', 'tracker.js');
   const nodeModulesFrom = path.join(packageRoot, 'node_modules');
 
+  // When running from the installed local runtime (or when appDir is symlinked to this package),
+  // source and destination resolve to the same place. Do not delete appDir in that case.
+  if (await pathsPointToSameLocation(packageRoot, appDir)) {
+    return;
+  }
+
   const srcTo = path.join(appDir, 'src');
   const binToDir = path.join(appDir, 'bin');
   const binTo = path.join(binToDir, 'tracker.js');
@@ -801,6 +835,21 @@ async function installLocalTrackerApp({ appDir }) {
   await copyRuntimeDependencies({ from: nodeModulesFrom, to: nodeModulesTo });
 }
 
+async function pathsPointToSameLocation(a, b) {
+  const aReal = await safeRealpath(a);
+  const bReal = await safeRealpath(b);
+  if (aReal && bReal) return aReal === bReal;
+  return path.resolve(a) === path.resolve(b);
+}
+
+async function safeRealpath(p) {
+  try {
+    return await fs.realpath(p);
+  } catch (_err) {
+    return null;
+  }
+}
+
 function spawnInitSync({ trackerBinPath, packageName }) {
   const fallbackPkg = packageName || 'vibeusage';
   const argv = ['sync', '--drain'];

package/src/commands/status.js

@@ -16,6 +16,7 @@ const { collectLocalSubscriptions } = require('../lib/subscriptions');
 const { normalizeState: normalizeUploadState } = require('../lib/upload-throttle');
 const { collectTrackerDiagnostics } = require('../lib/diagnostics');
 const { probeOpenclawHookState } = require('../lib/openclaw-hook');
+const { probeOpenclawSessionPluginState } = require('../lib/openclaw-session-plugin');
 const { resolveTrackerPaths } = require('../lib/tracker-paths');
 
 async function cmdStatus(argv = []) {
@@ -75,6 +76,7 @@ async function cmdStatus(argv = []) {
     hookCommand: geminiHookCommand
   });
   const opencodePluginConfigured = await isOpencodePluginInstalled({ configDir: opencodeConfigDir });
+  const openclawSessionPluginState = await probeOpenclawSessionPluginState({ home, trackerDir, env: process.env });
   const openclawHookState = await probeOpenclawHookState({ home, trackerDir, env: process.env });
 
   const lastUpload = uploadThrottle.lastSuccessMs
@@ -125,7 +127,8 @@ async function cmdStatus(argv = []) {
       `- Claude hooks: ${claudeHookConfigured ? 'set' : 'unset'}`,
       `- Gemini hooks: ${geminiHookConfigured ? 'set' : 'unset'}`,
       `- Opencode plugin: ${opencodePluginConfigured ? 'set' : 'unset'}`,
-      `- OpenClaw hook: ${openclawHookState?.configured ? 'set' : 'unset'}`,
+      `- OpenClaw session plugin: ${openclawSessionPluginState?.configured ? 'set' : 'unset'}`,
+      `- OpenClaw hook (legacy): ${openclawHookState?.configured ? 'set' : 'unset'}`,
       ...subscriptionLines,
       ''
     ]

package/src/commands/sync.js

@@ -123,6 +123,17 @@ async function cmdSync(argv) {
       });
     }
 
+    const openclawFallback = await applyOpenclawTotalsFallback({
+      trackerDir,
+      signal: openclawSignal,
+      cursors,
+      queuePath,
+      projectQueuePath
+    });
+    openclawResult.filesProcessed += openclawFallback.filesProcessed;
+    openclawResult.eventsAggregated += openclawFallback.eventsAggregated;
+    openclawResult.bucketsQueued += openclawFallback.bucketsQueued;
+
     const claudeFiles = await listClaudeProjectFiles(claudeProjectsDir);
     let claudeResult = { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
     if (claudeFiles.length > 0) {
@@ -432,10 +443,123 @@ function resolveOpenclawSignal({ home, env } = {}) {
   const openclawHome = normalizeString(env.VIBEUSAGE_OPENCLAW_HOME) || path.join(home || os.homedir(), '.openclaw');
   const sessionFile = path.join(openclawHome, 'agents', agentId, 'sessions', `${sessionId}.jsonl`);
 
-  return { agentId, sessionId, openclawHome, sessionFile };
+  const prevTotals = {
+    totalTokens: normalizeNonNegativeInt(env.VIBEUSAGE_OPENCLAW_PREV_TOTAL_TOKENS),
+    inputTokens: normalizeNonNegativeInt(env.VIBEUSAGE_OPENCLAW_PREV_INPUT_TOKENS),
+    outputTokens: normalizeNonNegativeInt(env.VIBEUSAGE_OPENCLAW_PREV_OUTPUT_TOKENS),
+    model: normalizeString(env.VIBEUSAGE_OPENCLAW_PREV_MODEL),
+    updatedAt: normalizeIsoOrEpoch(env.VIBEUSAGE_OPENCLAW_PREV_UPDATED_AT)
+  };
+
+  return {
+    agentId,
+    sessionId,
+    sessionKey: normalizeString(env.VIBEUSAGE_OPENCLAW_SESSION_KEY),
+    openclawHome,
+    sessionFile,
+    prevTotals
+  };
 }
 
 
+async function applyOpenclawTotalsFallback({ trackerDir, signal, cursors, queuePath, projectQueuePath }) {
+  const totalTokens = Number(signal?.prevTotals?.totalTokens || 0);
+  if (!trackerDir || !signal || totalTokens <= 0) {
+    return { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+  }
+
+  const sessionKey = `${signal.agentId}:${signal.sessionId}`;
+  const statePath = path.join(trackerDir, 'openclaw.fallback.state.json');
+  const fallbackFilePath = path.join(trackerDir, 'openclaw.fallback.jsonl');
+  const state = (await readJson(statePath)) || { version: 1, sessions: {} };
+  const sessions = state.sessions && typeof state.sessions === 'object' ? state.sessions : {};
+  const prev = sessions[sessionKey] && typeof sessions[sessionKey] === 'object' ? sessions[sessionKey] : null;
+
+  const current = {
+    totalTokens: normalizeNonNegativeInt(signal?.prevTotals?.totalTokens) || 0,
+    inputTokens: normalizeNonNegativeInt(signal?.prevTotals?.inputTokens) || 0,
+    outputTokens: normalizeNonNegativeInt(signal?.prevTotals?.outputTokens) || 0,
+    model: normalizeString(signal?.prevTotals?.model) || 'unknown',
+    updatedAt: normalizeIsoOrEpoch(signal?.prevTotals?.updatedAt) || new Date().toISOString(),
+    seenAt: new Date().toISOString()
+  };
+
+  let deltaTotal = current.totalTokens;
+  let deltaInput = current.inputTokens;
+  let deltaOutput = current.outputTokens;
+  if (prev) {
+    deltaTotal = Math.max(0, current.totalTokens - (normalizeNonNegativeInt(prev.totalTokens) || 0));
+    deltaInput = Math.max(0, current.inputTokens - (normalizeNonNegativeInt(prev.inputTokens) || 0));
+    deltaOutput = Math.max(0, current.outputTokens - (normalizeNonNegativeInt(prev.outputTokens) || 0));
+  }
+
+  if (deltaTotal > 0 && deltaInput + deltaOutput === 0) {
+    deltaInput = deltaTotal;
+  }
+
+  sessions[sessionKey] = current;
+  state.version = 1;
+  state.sessions = sessions;
+
+  if (deltaTotal <= 0) {
+    await writeJson(statePath, state);
+    return { filesProcessed: 0, eventsAggregated: 0, bucketsQueued: 0 };
+  }
+
+  await ensureDir(path.dirname(fallbackFilePath));
+  const syntheticMessage = {
+    type: 'message',
+    timestamp: current.updatedAt,
+    message: {
+      role: 'assistant',
+      model: current.model,
+      usage: {
+        input: deltaInput,
+        output: deltaOutput,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: deltaTotal
+      }
+    }
+  };
+  await fs.appendFile(fallbackFilePath, `${JSON.stringify(syntheticMessage)}\n`, 'utf8');
+  await writeJson(statePath, state);
+
+  return parseOpenclawIncremental({
+    sessionFiles: [{ path: fallbackFilePath, source: 'openclaw' }],
+    cursors,
+    queuePath,
+    projectQueuePath,
+    source: 'openclaw'
+  });
+}
+
+function normalizeNonNegativeInt(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.floor(n);
+}
+
+function normalizeIsoOrEpoch(value) {
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (trimmed.length > 0 && !Number.isNaN(Date.parse(trimmed))) return trimmed;
+    const numeric = Number(trimmed);
+    if (Number.isFinite(numeric) && numeric > 0) {
+      const ms = numeric < 1e12 ? Math.floor(numeric * 1000) : Math.floor(numeric);
+      const iso = new Date(ms).toISOString();
+      if (!Number.isNaN(Date.parse(iso))) return iso;
+    }
+  }
+
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  const ms = n < 1e12 ? Math.floor(n * 1000) : Math.floor(n);
+  const dt = new Date(ms);
+  if (Number.isNaN(dt.getTime())) return null;
+  return dt.toISOString();
+}
+
 async function safeStatSize(p) {
   try {
     const st = await fs.stat(p);

package/src/commands/uninstall.js

@@ -12,6 +12,7 @@ const {
 } = require('../lib/gemini-config');
 const { resolveOpencodeConfigDir, removeOpencodePlugin } = require('../lib/opencode-config');
 const { removeOpenclawHookConfig } = require('../lib/openclaw-hook');
+const { removeOpenclawSessionPluginConfig } = require('../lib/openclaw-session-plugin');
 const { resolveTrackerPaths } = require('../lib/tracker-paths');
 
 async function cmdUninstall(argv) {
@@ -62,6 +63,7 @@ async function cmdUninstall(argv) {
   const opencodeRemove = opencodeConfigExists
     ? await removeOpencodePlugin({ configDir: opencodeConfigDir })
     : { removed: false, skippedReason: 'config-missing' };
+  const openclawSessionPluginRemove = await removeOpenclawSessionPluginConfig({ home, trackerDir, env: process.env });
   const openclawHookRemove = await removeOpenclawHookConfig({ home, trackerDir, env: process.env });
 
   // Remove installed notify handler.
@@ -114,11 +116,16 @@ async function cmdUninstall(argv) {
               ? '- Opencode plugin: skipped (unexpected content)'
               : '- Opencode plugin: skipped'
         : `- Opencode plugin: skipped (${opencodeConfigDir} not found)`,
+      openclawSessionPluginRemove?.removed
+        ? `- OpenClaw session plugin removed: ${openclawSessionPluginRemove.openclawConfigPath}`
+        : openclawSessionPluginRemove?.skippedReason === 'openclaw-config-missing'
+          ? '- OpenClaw session plugin: skipped (openclaw config not found)'
+          : '- OpenClaw session plugin: no change',
       openclawHookRemove?.removed
-        ? `- OpenClaw hook removed: ${openclawHookRemove.openclawConfigPath}`
+        ? `- OpenClaw hook (legacy) removed: ${openclawHookRemove.openclawConfigPath}`
         : openclawHookRemove?.skippedReason === 'openclaw-config-missing'
-          ? '- OpenClaw hook: skipped (openclaw config not found)'
-          : '- OpenClaw hook: no change',
+          ? '- OpenClaw hook (legacy): skipped (openclaw config not found)'
+          : '- OpenClaw hook (legacy): no change',
       opts.purge ? `- Purged: ${path.join(home, '.vibeusage')}` : '- Purge: skipped (use --purge)',
       ''
     ].join('\n')

package/src/lib/diagnostics.js

@@ -14,6 +14,7 @@ const {
 const { resolveOpencodeConfigDir, isOpencodePluginInstalled } = require('./opencode-config');
 const { normalizeState: normalizeUploadState } = require('./upload-throttle');
 const { probeOpenclawHookState } = require('./openclaw-hook');
+const { probeOpenclawSessionPluginState } = require('./openclaw-session-plugin');
 const { resolveTrackerPaths } = require('./tracker-paths');
 
 async function collectTrackerDiagnostics({
@@ -69,6 +70,7 @@ async function collectTrackerDiagnostics({
     hookCommand: geminiHookCommand
   });
   const opencodePluginConfigured = await isOpencodePluginInstalled({ configDir: opencodeConfigDir });
+  const openclawSessionPluginState = await probeOpenclawSessionPluginState({ home, trackerDir, env: process.env });
   const openclawHookState = await probeOpenclawHookState({ home, trackerDir, env: process.env });
 
   const lastSuccessAt = uploadThrottle.lastSuccessMs ? new Date(uploadThrottle.lastSuccessMs).toISOString() : null;
@@ -120,6 +122,9 @@ async function collectTrackerDiagnostics({
       claude_hook_configured: claudeHookConfigured,
       gemini_hook_configured: geminiHookConfigured,
       opencode_plugin_configured: opencodePluginConfigured,
+      openclaw_session_plugin_configured: Boolean(openclawSessionPluginState?.configured),
+      openclaw_session_plugin_linked: Boolean(openclawSessionPluginState?.linked),
+      openclaw_session_plugin_enabled: Boolean(openclawSessionPluginState?.enabled),
       openclaw_hook_configured: Boolean(openclawHookState?.configured),
       openclaw_hook_linked: Boolean(openclawHookState?.linked),
       openclaw_hook_enabled: Boolean(openclawHookState?.enabled)

package/src/lib/openclaw-hook.js

@@ -252,12 +252,12 @@ function buildHookMarkdown() {
 name: ${OPENCLAW_HOOK_NAME}
 description: "Trigger vibeusage sync when OpenClaw sessions roll over"
 metadata:
-  { "openclaw": { "emoji": "📈", "events": ["command:new", "command:stop"], "requires": { "bins": ["node"] } } }
+  { "openclaw": { "emoji": "📈", "events": ["command:new", "command:reset", "command:stop"], "requires": { "bins": ["node"] } } }
 ---
 
 # VibeUsage OpenClaw Sync Hook
 
-Triggers non-blocking 'vibeusage sync --auto --from-openclaw' runs when OpenClaw command events indicate a session rollover/stop.
+Triggers non-blocking 'vibeusage sync --auto --from-openclaw' runs when OpenClaw command events indicate session rollover/reset/stop.
 `;
 }
 
@@ -281,13 +281,14 @@ function buildHookHandler({ trackerDir, packageName = 'vibeusage', openclawHome
     `module.exports = async function handler(event) {\n` +
     `  try {\n` +
     `    if (!event || event.type !== 'command') return;\n` +
-    `    if (event.action !== 'new' && event.action !== 'stop') return;\n` +
+    `    if (event.action !== 'new' && event.action !== 'reset' && event.action !== 'stop') return;\n` +
     `\n` +
     `    const sessionKey = normalize(event.sessionKey);\n` +
     `    const agentId = parseAgentId(sessionKey);\n` +
     `    if (!agentId) return;\n` +
     `\n` +
-    `    const sessionId = resolveSessionId(event);\n` +
+    `    const sessionEntry = resolveSessionEntry(event);\n` +
+    `    const sessionId = normalize(sessionEntry && sessionEntry.sessionId) || resolveSessionId(event);\n` +
     `    if (!sessionId) return;\n` +
     `\n` +
     `    const now = Date.now();\n` +
@@ -302,9 +303,20 @@ function buildHookHandler({ trackerDir, packageName = 'vibeusage', openclawHome
     `    const env = {\n` +
     `      ...process.env,\n` +
     `      VIBEUSAGE_OPENCLAW_AGENT_ID: agentId,\n` +
+    `      VIBEUSAGE_OPENCLAW_SESSION_KEY: sessionKey,\n` +
     `      VIBEUSAGE_OPENCLAW_PREV_SESSION_ID: sessionId,\n` +
     `      VIBEUSAGE_OPENCLAW_HOME: openclawHome\n` +
     `    };\n` +
+    `    const prevTotalTokens = toNonNegativeInt(sessionEntry && sessionEntry.totalTokens);\n` +
+    `    const prevInputTokens = toNonNegativeInt(sessionEntry && sessionEntry.inputTokens);\n` +
+    `    const prevOutputTokens = toNonNegativeInt(sessionEntry && sessionEntry.outputTokens);\n` +
+    `    const prevModel = normalize(sessionEntry && sessionEntry.model);\n` +
+    `    const prevUpdatedAt = toIso(sessionEntry && sessionEntry.updatedAt);\n` +
+    `    if (prevTotalTokens != null) env.VIBEUSAGE_OPENCLAW_PREV_TOTAL_TOKENS = String(prevTotalTokens);\n` +
+    `    if (prevInputTokens != null) env.VIBEUSAGE_OPENCLAW_PREV_INPUT_TOKENS = String(prevInputTokens);\n` +
+    `    if (prevOutputTokens != null) env.VIBEUSAGE_OPENCLAW_PREV_OUTPUT_TOKENS = String(prevOutputTokens);\n` +
+    `    if (prevModel) env.VIBEUSAGE_OPENCLAW_PREV_MODEL = prevModel;\n` +
+    `    if (prevUpdatedAt) env.VIBEUSAGE_OPENCLAW_PREV_UPDATED_AT = prevUpdatedAt;\n` +
     `\n` +
     `    const hasLocalRuntime = fs.existsSync(trackerBinPath);\n` +
     `    const hasLocalDeps = fs.existsSync(depsMarkerPath);\n` +
@@ -323,6 +335,33 @@ function buildHookHandler({ trackerDir, packageName = 'vibeusage', openclawHome
     `  return s.length > 0 ? s : null;\n` +
     `}\n` +
     `\n` +
+    `function resolveSessionEntry(event) {\n` +
+    `  const ctx = (event && event.context && typeof event.context === 'object') ? event.context : {};\n` +
+    `  if (!event || event.type !== 'command') return null;\n` +
+    `  if (event.action === 'stop') return (ctx.sessionEntry && typeof ctx.sessionEntry === 'object') ? ctx.sessionEntry : null;\n` +
+    `  if (ctx.previousSessionEntry && typeof ctx.previousSessionEntry === 'object') return ctx.previousSessionEntry;\n` +
+    `  if (ctx.sessionEntry && typeof ctx.sessionEntry === 'object') return ctx.sessionEntry;\n` +
+    `  return null;\n` +
+    `}\n` +
+    `\n` +
+    `function toNonNegativeInt(v) {\n` +
+    `  const n = Number(v);\n` +
+    `  if (!Number.isFinite(n) || n < 0) return null;\n` +
+    `  return Math.floor(n);\n` +
+    `}\n` +
+    `\n` +
+    `function toIso(v) {\n` +
+    `  if (typeof v === 'string') {\n` +
+    `    const s = normalize(v);\n` +
+    `    if (s && !Number.isNaN(Date.parse(s))) return s;\n` +
+    `  }\n` +
+    `  const n = Number(v);\n` +
+    `  if (!Number.isFinite(n) || n <= 0) return null;\n` +
+    `  const ms = n < 1e12 ? Math.floor(n * 1000) : Math.floor(n);\n` +
+    `  const d = new Date(ms);\n` +
+    `  return Number.isNaN(d.getTime()) ? null : d.toISOString();\n` +
+    `}\n` +
+    `\n` +
     `function parseAgentId(sessionKey) {\n` +
     `  const s = normalize(sessionKey);\n` +
     `  if (!s || !s.startsWith('agent:')) return null;\n` +

package/src/lib/openclaw-session-plugin.js

@@ -0,0 +1,496 @@
+const os = require('node:os');
+const path = require('node:path');
+const fs = require('node:fs/promises');
+const fssync = require('node:fs');
+const cp = require('node:child_process');
+
+const OPENCLAW_SESSION_PLUGIN_ID = 'openclaw-session-sync';
+const OPENCLAW_SESSION_PLUGIN_DIRNAME = 'openclaw-plugin';
+
+function resolveOpenclawSessionPluginPaths({ home = os.homedir(), trackerDir, env = process.env } = {}) {
+  if (!trackerDir) throw new Error('trackerDir is required');
+
+  const openclawConfigPath =
+    normalizeString(env.OPENCLAW_CONFIG_PATH) || path.join(home, '.openclaw', 'openclaw.json');
+
+  const openclawHome =
+    normalizeString(env.VIBEUSAGE_OPENCLAW_HOME) ||
+    normalizeString(env.OPENCLAW_STATE_DIR) ||
+    path.join(home, '.openclaw');
+
+  const pluginDir = path.join(trackerDir, OPENCLAW_SESSION_PLUGIN_DIRNAME);
+  const pluginEntryDir = path.join(pluginDir, OPENCLAW_SESSION_PLUGIN_ID);
+
+  return {
+    pluginId: OPENCLAW_SESSION_PLUGIN_ID,
+    pluginDir,
+    pluginEntryDir,
+    openclawConfigPath,
+    openclawHome
+  };
+}
+
+async function installOpenclawSessionPlugin({
+  home = os.homedir(),
+  trackerDir,
+  packageName = 'vibeusage',
+  env = process.env
+} = {}) {
+  const paths = resolveOpenclawSessionPluginPaths({ home, trackerDir, env });
+
+  await ensureOpenclawSessionPluginFiles({
+    pluginDir: paths.pluginDir,
+    trackerDir,
+    packageName,
+    openclawHome: paths.openclawHome
+  });
+
+  const installResult = runOpenclawCli(['plugins', 'install', '--link', paths.pluginEntryDir], env);
+  if (installResult.skippedReason) {
+    return { configured: false, ...paths, ...installResult };
+  }
+
+  const enableResult = runOpenclawCli(['plugins', 'enable', paths.pluginId], env);
+  if (enableResult.skippedReason) {
+    return {
+      configured: false,
+      ...paths,
+      skippedReason: enableResult.skippedReason,
+      error: enableResult.error,
+      stdout: `${installResult.stdout || ''}\n${enableResult.stdout || ''}`.trim(),
+      stderr: `${installResult.stderr || ''}\n${enableResult.stderr || ''}`.trim(),
+      code: enableResult.code
+    };
+  }
+
+  const state = await probeOpenclawSessionPluginState({ home, trackerDir, env });
+  return {
+    configured: state.configured,
+    changed:
+      /Linked plugin path:/i.test(installResult.stdout || '') ||
+      /Enabled plugin/i.test(enableResult.stdout || '') ||
+      /already enabled/i.test(enableResult.stdout || ''),
+    ...paths,
+    stdout: `${installResult.stdout || ''}\n${enableResult.stdout || ''}`.trim(),
+    stderr: `${installResult.stderr || ''}\n${enableResult.stderr || ''}`.trim(),
+    code: enableResult.code
+  };
+}
+
+async function ensureOpenclawSessionPluginFiles({ pluginDir, trackerDir, packageName = 'vibeusage', openclawHome } = {}) {
+  if (!pluginDir || !trackerDir) throw new Error('pluginDir and trackerDir are required');
+
+  const pluginEntryDir = path.join(pluginDir, OPENCLAW_SESSION_PLUGIN_ID);
+  await fs.mkdir(pluginEntryDir, { recursive: true });
+
+  const packageJsonPath = path.join(pluginEntryDir, 'package.json');
+  const pluginMetaPath = path.join(pluginEntryDir, 'openclaw.plugin.json');
+  const indexPath = path.join(pluginEntryDir, 'index.js');
+
+  await fs.writeFile(packageJsonPath, buildSessionPluginPackageJson(), 'utf8');
+  await fs.writeFile(pluginMetaPath, buildSessionPluginMeta(), 'utf8');
+  await fs.writeFile(
+    indexPath,
+    buildSessionPluginIndex({
+      trackerDir,
+      packageName,
+      openclawHome: openclawHome || path.join(os.homedir(), '.openclaw')
+    }),
+    'utf8'
+  );
+}
+
+async function probeOpenclawSessionPluginState({ home = os.homedir(), trackerDir, env = process.env } = {}) {
+  const paths = resolveOpenclawSessionPluginPaths({ home, trackerDir, env });
+  const { openclawConfigPath, pluginEntryDir, pluginId } = paths;
+
+  const pluginFilesReady =
+    fssync.existsSync(path.join(pluginEntryDir, 'package.json')) &&
+    fssync.existsSync(path.join(pluginEntryDir, 'index.js'));
+
+  let cfg = null;
+  try {
+    const raw = await fs.readFile(openclawConfigPath, 'utf8');
+    cfg = JSON.parse(raw);
+  } catch (err) {
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') {
+      return {
+        configured: false,
+        enabled: false,
+        linked: false,
+        installed: false,
+        pluginFilesReady,
+        skippedReason: 'openclaw-config-missing',
+        ...paths
+      };
+    }
+    return {
+      configured: false,
+      enabled: false,
+      linked: false,
+      installed: false,
+      pluginFilesReady,
+      skippedReason: 'openclaw-config-unreadable',
+      error: err?.message || String(err),
+      ...paths
+    };
+  }
+
+  const pluginEntry = cfg?.plugins?.entries?.[pluginId];
+  const enabled = pluginEntry ? pluginEntry.enabled !== false : false;
+
+  const loadPaths = Array.isArray(cfg?.plugins?.load?.paths) ? cfg.plugins.load.paths : [];
+  const normalizedPluginEntryDir = path.resolve(pluginEntryDir);
+  const linked = loadPaths.some((entry) => path.resolve(String(entry || '')) === normalizedPluginEntryDir);
+
+  const installs = cfg?.plugins?.installs && typeof cfg.plugins.installs === 'object' ? cfg.plugins.installs : {};
+  const installEntry = installs[pluginId];
+  const installed = Boolean(installEntry);
+
+  return {
+    configured: enabled && linked && pluginFilesReady,
+    enabled,
+    linked,
+    installed,
+    pluginFilesReady,
+    ...paths
+  };
+}
+
+async function removeOpenclawSessionPluginConfig({ home = os.homedir(), trackerDir, env = process.env } = {}) {
+  const paths = resolveOpenclawSessionPluginPaths({ home, trackerDir, env });
+  const { openclawConfigPath, pluginEntryDir, pluginId } = paths;
+
+  let cfg;
+  try {
+    cfg = JSON.parse(await fs.readFile(openclawConfigPath, 'utf8'));
+  } catch (err) {
+    if (err?.code === 'ENOENT' || err?.code === 'ENOTDIR') {
+      return { removed: false, skippedReason: 'openclaw-config-missing', ...paths };
+    }
+    return {
+      removed: false,
+      skippedReason: 'openclaw-config-unreadable',
+      error: err?.message || String(err),
+      ...paths
+    };
+  }
+
+  let changed = false;
+  const plugins = cfg?.plugins;
+
+  if (plugins?.entries && Object.prototype.hasOwnProperty.call(plugins.entries, pluginId)) {
+    delete plugins.entries[pluginId];
+    changed = true;
+    if (Object.keys(plugins.entries).length === 0) delete plugins.entries;
+  }
+
+  if (plugins?.load && Array.isArray(plugins.load.paths)) {
+    const target = path.resolve(pluginEntryDir);
+    const after = plugins.load.paths.filter((entry) => path.resolve(String(entry || '')) !== target);
+    if (after.length !== plugins.load.paths.length) {
+      plugins.load.paths = after;
+      changed = true;
+      if (after.length === 0) delete plugins.load.paths;
+      if (Object.keys(plugins.load).length === 0) delete plugins.load;
+    }
+  }
+
+  if (plugins?.installs && typeof plugins.installs === 'object') {
+    const installs = plugins.installs;
+    if (Object.prototype.hasOwnProperty.call(installs, pluginId)) {
+      delete installs[pluginId];
+      changed = true;
+    }
+
+    const target = path.resolve(pluginEntryDir);
+    for (const [id, entry] of Object.entries(installs)) {
+      const sourcePath = normalizeString(entry?.sourcePath);
+      const installPath = normalizeString(entry?.installPath);
+      if (
+        (sourcePath && path.resolve(sourcePath) === target) ||
+        (installPath && path.resolve(installPath) === target)
+      ) {
+        delete installs[id];
+        changed = true;
+      }
+    }
+
+    if (Object.keys(installs).length === 0) delete plugins.installs;
+  }
+
+  if (plugins && Object.keys(plugins).length === 0) {
+    delete cfg.plugins;
+    changed = true;
+  }
+
+  if (changed) {
+    await fs.writeFile(openclawConfigPath, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+  }
+
+  const hadFiles = await fs
+    .stat(pluginEntryDir)
+    .then((st) => st.isDirectory())
+    .catch(() => false);
+  await fs.rm(pluginEntryDir, { recursive: true, force: true }).catch(() => {});
+
+  return { removed: changed || hadFiles, ...paths };
+}
+
+function runOpenclawCli(args, env = process.env) {
+  let res;
+  try {
+    res = cp.spawnSync('openclaw', args, {
+      env,
+      encoding: 'utf8',
+      timeout: 30_000
+    });
+  } catch (err) {
+    return {
+      code: 1,
+      skippedReason: err?.code === 'ENOENT' ? 'openclaw-cli-missing' : 'openclaw-cli-error',
+      error: err?.message || String(err),
+      stdout: '',
+      stderr: ''
+    };
+  }
+
+  if (res.error?.code === 'ENOENT') {
+    return {
+      code: 1,
+      skippedReason: 'openclaw-cli-missing',
+      error: res.error.message,
+      stdout: res.stdout || '',
+      stderr: res.stderr || ''
+    };
+  }
+
+  if ((res.status || 0) !== 0) {
+    return {
+      code: Number(res.status || 1),
+      skippedReason: 'openclaw-plugins-install-failed',
+      error: (res.stderr || res.stdout || '').trim() || 'openclaw plugins install failed',
+      stdout: res.stdout || '',
+      stderr: res.stderr || ''
+    };
+  }
+
+  return {
+    code: 0,
+    stdout: res.stdout || '',
+    stderr: res.stderr || ''
+  };
+}
+
+function buildSessionPluginPackageJson() {
+  return `${JSON.stringify(
+    {
+      name: '@vibeusage/openclaw-session-sync',
+      version: '0.0.0',
+      private: true,
+      type: 'module',
+      openclaw: {
+        extensions: ['./index.js']
+      }
+    },
+    null,
+    2
+  )}\n`;
+}
+
+function buildSessionPluginMeta() {
+  return `${JSON.stringify(
+    {
+      id: OPENCLAW_SESSION_PLUGIN_ID,
+      name: 'VibeUsage OpenClaw Session Sync',
+      description: 'Trigger vibeusage sync on OpenClaw agent/session lifecycle events.',
+      configSchema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {}
+      }
+    },
+    null,
+    2
+  )}\n`;
+}
+
+function buildSessionPluginIndex({ trackerDir, packageName = 'vibeusage', openclawHome }) {
+  const trackerBinPath = path.join(trackerDir, 'app', 'bin', 'tracker.js');
+  const fallbackPkg = packageName || 'vibeusage';
+  const safeOpenclawHome = openclawHome || path.join(os.homedir(), '.openclaw');
+
+  return `import fs from 'node:fs';\n` +
+    `import path from 'node:path';\n` +
+    `import cp from 'node:child_process';\n` +
+    `\n` +
+    `const trackerDir = ${JSON.stringify(trackerDir)};\n` +
+    `const trackerBinPath = ${JSON.stringify(trackerBinPath)};\n` +
+    `const fallbackPkg = ${JSON.stringify(fallbackPkg)};\n` +
+    `const openclawHome = ${JSON.stringify(safeOpenclawHome)};\n` +
+    `const depsMarkerPath = path.join(trackerDir, 'app', 'node_modules', '@insforge', 'sdk', 'package.json');\n` +
+    `const triggerStatePath = path.join(trackerDir, 'openclaw.session-sync.trigger-state.json');\n` +
+    `const SESSION_TRIGGER_THROTTLE_MS = 15_000;\n` +
+    `\n` +
+    `export default function register(api) {\n` +
+    `  api.on('agent_end', async (_event, ctx) => {\n` +
+    `    try {\n` +
+    `      const sessionKey = normalize(ctx && ctx.sessionKey);\n` +
+    `      if (!sessionKey) return;\n` +
+    `\n` +
+    `      const agentId = normalize(ctx && ctx.agentId) || parseAgentId(sessionKey);\n` +
+    `      if (!agentId) return;\n` +
+    `\n` +
+    `      const sessionInfo = resolveSessionInfo(agentId, sessionKey);\n` +
+    `      const sessionId = normalize(sessionInfo && sessionInfo.sessionId);\n` +
+    `      if (!sessionId) return;\n` +
+    `\n` +
+    `      if (!allowTrigger('agent_end', agentId, sessionId)) return;\n` +
+    `\n` +
+    `      spawnSync({\n` +
+    `        args: ['sync', '--auto', '--from-openclaw'],\n` +
+    `        env: buildSessionEnv({\n` +
+    `          agentId,\n` +
+    `          sessionId,\n` +
+    `          sessionKey,\n` +
+    `          sessionEntry: sessionInfo && sessionInfo.entry\n` +
+    `        })\n` +
+    `      });\n` +
+    `    } catch (_) {}\n` +
+    `  });\n` +
+    `\n` +
+    `  api.on('gateway_start', async () => {\n` +
+    `    try {\n` +
+    `      if (!allowTrigger('gateway_start', 'gateway', 'startup')) return;\n` +
+    `      spawnSync({ args: ['sync', '--auto'] });\n` +
+    `    } catch (_) {}\n` +
+    `  });\n` +
+    `\n` +
+    `  api.on('gateway_stop', async () => {\n` +
+    `    try {\n` +
+    `      if (!allowTrigger('gateway_stop', 'gateway', 'stop')) return;\n` +
+    `      spawnSync({ args: ['sync', '--auto'] });\n` +
+    `    } catch (_) {}\n` +
+    `  });\n` +
+    `}\n` +
+    `\n` +
+    `function spawnSync({ args, env = {} }) {\n` +
+    `  const hasLocalRuntime = fs.existsSync(trackerBinPath);\n` +
+    `  const hasLocalDeps = fs.existsSync(depsMarkerPath);\n` +
+    `  const argv = Array.isArray(args) && args.length > 0 ? args : ['sync', '--auto'];\n` +
+    `  const cmd = hasLocalRuntime && hasLocalDeps\n` +
+    `    ? [process.execPath, trackerBinPath, ...argv]\n` +
+    `    : ['npx', '--yes', fallbackPkg, ...argv];\n` +
+    `  const child = cp.spawn(cmd[0], cmd.slice(1), {\n` +
+    `    detached: true,\n` +
+    `    stdio: 'ignore',\n` +
+    `    env: { ...process.env, ...env }\n` +
+    `  });\n` +
+    `  child.unref();\n` +
+    `}\n` +
+    `\n` +
+    `function buildSessionEnv({ agentId, sessionId, sessionKey, sessionEntry }) {\n` +
+    `  const out = {\n` +
+    `    VIBEUSAGE_OPENCLAW_AGENT_ID: agentId,\n` +
+    `    VIBEUSAGE_OPENCLAW_PREV_SESSION_ID: sessionId,\n` +
+    `    VIBEUSAGE_OPENCLAW_HOME: openclawHome\n` +
+    `  };\n` +
+    `  const key = normalize(sessionKey);\n` +
+    `  if (key) out.VIBEUSAGE_OPENCLAW_SESSION_KEY = key;\n` +
+    `  const prevTotalTokens = toNonNegativeInt(sessionEntry && sessionEntry.totalTokens);\n` +
+    `  const prevInputTokens = toNonNegativeInt(sessionEntry && sessionEntry.inputTokens);\n` +
+    `  const prevOutputTokens = toNonNegativeInt(sessionEntry && sessionEntry.outputTokens);\n` +
+    `  const prevModel = normalize(sessionEntry && sessionEntry.model);\n` +
+    `  const prevUpdatedAt = toIso(sessionEntry && sessionEntry.updatedAt);\n` +
+    `  if (prevTotalTokens != null) out.VIBEUSAGE_OPENCLAW_PREV_TOTAL_TOKENS = String(prevTotalTokens);\n` +
+    `  if (prevInputTokens != null) out.VIBEUSAGE_OPENCLAW_PREV_INPUT_TOKENS = String(prevInputTokens);\n` +
+    `  if (prevOutputTokens != null) out.VIBEUSAGE_OPENCLAW_PREV_OUTPUT_TOKENS = String(prevOutputTokens);\n` +
+    `  if (prevModel) out.VIBEUSAGE_OPENCLAW_PREV_MODEL = prevModel;\n` +
+    `  if (prevUpdatedAt) out.VIBEUSAGE_OPENCLAW_PREV_UPDATED_AT = prevUpdatedAt;\n` +
+    `  return out;\n` +
+    `}\n` +
+    `\n` +
+    `function resolveSessionInfo(agentId, sessionKey) {\n` +
+    `  const key = normalize(sessionKey);\n` +
+    `  if (!key) return null;\n` +
+    `  const sessionsPath = path.join(openclawHome, 'agents', agentId, 'sessions', 'sessions.json');\n` +
+    `  try {\n` +
+    `    const raw = fs.readFileSync(sessionsPath, 'utf8');\n` +
+    `    const parsed = JSON.parse(raw);\n` +
+    `    if (!parsed || typeof parsed !== 'object') return null;\n` +
+    `    const entry = parsed[key];\n` +
+    `    if (!entry || typeof entry !== 'object') return null;\n` +
+    `    return {\n` +
+    `      sessionKey: key,\n` +
+    `      sessionId: normalize(entry.sessionId),\n` +
+    `      entry\n` +
+    `    };\n` +
+    `  } catch (_) {}\n` +
+    `  return null;\n` +
+    `}\n` +
+    `\n` +
+    `function parseAgentId(sessionKey) {\n` +
+    `  const s = normalize(sessionKey);\n` +
+    `  if (!s || !s.startsWith('agent:')) return null;\n` +
+    `  const parts = s.split(':');\n` +
+    `  return parts.length >= 2 ? normalize(parts[1]) : null;\n` +
+    `}\n` +
+    `\n` +
+    `function allowTrigger(kind, scope, target) {\n` +
+    `  const key = [kind, scope || 'na', target || 'na'].join(':');\n` +
+    `  const now = Date.now();\n` +
+    `  let state = {};\n` +
+    `  try {\n` +
+    `    state = JSON.parse(fs.readFileSync(triggerStatePath, 'utf8'));\n` +
+    `    if (!state || typeof state !== 'object') state = {};\n` +
+    `  } catch (_) {}\n` +
+    `  const last = Number(state[key] || 0);\n` +
+    `  if (Number.isFinite(last) && now - last < SESSION_TRIGGER_THROTTLE_MS) return false;\n` +
+    `  state[key] = now;\n` +
+    `  try {\n` +
+    `    fs.mkdirSync(path.dirname(triggerStatePath), { recursive: true });\n` +
+    `    fs.writeFileSync(triggerStatePath, JSON.stringify(state), 'utf8');\n` +
+    `  } catch (_) {}\n` +
+    `  return true;\n` +
+    `}\n` +
+    `\n` +
+    `function normalize(v) {\n` +
+    `  if (typeof v !== 'string') return null;\n` +
+    `  const s = v.trim();\n` +
+    `  return s.length > 0 ? s : null;\n` +
+    `}\n` +
+    `\n` +
+    `function toNonNegativeInt(v) {\n` +
+    `  const n = Number(v);\n` +
+    `  if (!Number.isFinite(n) || n < 0) return null;\n` +
+    `  return Math.floor(n);\n` +
+    `}\n` +
+    `\n` +
+    `function toIso(v) {\n` +
+    `  if (typeof v === 'string') {\n` +
+    `    const s = normalize(v);\n` +
+    `    if (s && !Number.isNaN(Date.parse(s))) return s;\n` +
+    `  }\n` +
+    `  const n = Number(v);\n` +
+    `  if (!Number.isFinite(n) || n <= 0) return null;\n` +
+    `  const ms = n < 1e12 ? Math.floor(n * 1000) : Math.floor(n);\n` +
+    `  const d = new Date(ms);\n` +
+    `  return Number.isNaN(d.getTime()) ? null : d.toISOString();\n` +
+    `}\n`;
+}
+
+function normalizeString(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+module.exports = {
+  OPENCLAW_SESSION_PLUGIN_ID,
+  OPENCLAW_SESSION_PLUGIN_DIRNAME,
+  resolveOpenclawSessionPluginPaths,
+  ensureOpenclawSessionPluginFiles,
+  installOpenclawSessionPlugin,
+  probeOpenclawSessionPluginState,
+  removeOpenclawSessionPluginConfig
+};