siesa-agents 2.1.76 → 2.1.77

package/claude/settings.local.json

@@ -39,6 +39,16 @@
     "ask": []
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PROJECT_DIR}/siesa-agents/observability/scripts/sa-session.js\""
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": ".*",

package/claude/skills/clean-observability/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: clean-observability
+description: Safely clean up stale state files in ~/.claude/observability/ left by abandoned BMAD workflows. Triggered by /clean-observability. Files belonging to live Claude Code sessions are never touched. Run this weekly or whenever the observability dir feels cluttered.
+---
+
+# Clean Observability State
+
+Manual cleanup for `~/.claude/observability/`. Removes only files whose owning `claude.exe` PID is no longer alive. Leaves files of currently-running sessions intact.
+
+## What to do when invoked
+
+### Step 1 — Preview (dry-run)
+
+Run the cleanup script in dry-run mode and show its output verbatim to the user. The script lives in this project at `siesa-agents/observability/scripts/sa-clean.js`. The Bash tool's working directory is the project root, so a relative path is sufficient:
+
+```bash
+node siesa-agents/observability/scripts/sa-clean.js --dry-run
+```
+
+The script prints:
+- The set of currently-live Claude Code PIDs.
+- How many files will be kept.
+- The exact list of files that would be deleted.
+
+**Important:** do NOT use `${CLAUDE_PROJECT_DIR}` — that variable is not exported to the Bash tool's subshell and would resolve to empty, causing a "file not found" error. Always use the relative path above.
+
+### Step 2 — Ask the user
+
+Show the preview and ask:
+
+> ¿Procedo con el borrado de los N archivos listados? [s/N]
+
+Wait for explicit confirmation. Do **not** auto-proceed.
+
+### Step 3 — Apply (only if user confirms)
+
+If the user replies affirmatively (e.g., "sí", "s", "yes", "y"), run:
+
+```bash
+node siesa-agents/observability/scripts/sa-clean.js --apply --rotate-buffer
+```
+
+Report the script's output verbatim.
+
+If the user declines, end the turn with: `Ok, no borré nada.`
+
+## Notes
+
+- Never run `--apply` without explicit user confirmation in this turn.
+- Do not edit or delete files manually — always use `sa-clean.js`.
+- The `--rotate-buffer` flag rotates `buffer/events.jsonl` if it exceeds 5 MB. Safe for parallel sessions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.76",
+  "version": "2.1.77",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {

package/siesa-agents/observability/scripts/sa-clean.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// sa-clean.js — Manual cleanup of ~/.claude/observability/ state files.
+//
+// Safe for parallel CC sessions: deletes only files that don't belong to a
+// currently-alive claude.exe process. Files of live sessions are never touched.
+//
+// Usage:
+//   node sa-clean.js --dry-run               # list what would be deleted
+//   node sa-clean.js --apply                 # actually delete
+//   node sa-clean.js --apply --rotate-buffer # also rotate buffer/events.jsonl if > 5 MB
+//
+// Rules:
+//   - session-<pid>.json     → delete unless <pid> is alive
+//   - session-id-<uuid>.json → delete unless its recorded claude_pid is alive
+//   - wf-*.json / fix-*.json → delete unless its recorded claude_pid is alive
+//   - any other file (logs, etc.) → never touched
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { getAliveClaudePids } = require('./sa-pid')
+
+const STATE_DIR        = path.join(os.homedir(), '.claude', 'observability')
+const BUFFER_FILE      = path.join(STATE_DIR, 'buffer', 'events.jsonl')
+const BUFFER_MAX_BYTES = 5 * 1024 * 1024
+const BUFFER_KEEP_ROTATIONS = 3
+
+function parseArgs(argv) {
+  const flags = new Set()
+  for (const a of argv) if (a.startsWith('--')) flags.add(a.slice(2))
+  return flags
+}
+
+function readPidFromFile(p) {
+  try {
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'))
+    const v = data.claude_pid
+    return v == null ? null : parseInt(v, 10)
+  } catch (_) { return null }
+}
+
+function classify(alivePids) {
+  const toDelete = []
+  const toKeep   = []
+  if (!fs.existsSync(STATE_DIR)) return { toDelete, toKeep }
+
+  for (const name of fs.readdirSync(STATE_DIR)) {
+    const full = path.join(STATE_DIR, name)
+    let stat
+    try { stat = fs.statSync(full) } catch (_) { continue }
+    if (!stat.isFile()) continue
+    if (name === 'hook-errors.log') continue
+
+    if (name.startsWith('session-') && name.endsWith('.json')) {
+      if (name.startsWith('session-id-')) {
+        const pid = readPidFromFile(full)
+        if (pid != null && alivePids.has(pid)) toKeep.push(full)
+        else toDelete.push(full)
+      } else {
+        const m = name.match(/^session-(\d+)\.json$/)
+        if (!m) { toDelete.push(full); continue }
+        const pid = parseInt(m[1], 10)
+        if (alivePids.has(pid)) toKeep.push(full)
+        else toDelete.push(full)
+      }
+    } else if ((name.startsWith('wf-') || name.startsWith('fix-')) && name.endsWith('.json')) {
+      const pid = readPidFromFile(full)
+      if (pid != null && alivePids.has(pid)) toKeep.push(full)
+      else toDelete.push(full)
+    } else {
+      toKeep.push(full)
+    }
+  }
+  return { toDelete, toKeep }
+}
+
+function rotateBufferIfNeeded() {
+  if (!fs.existsSync(BUFFER_FILE)) return null
+  let size
+  try { size = fs.statSync(BUFFER_FILE).size } catch (_) { return null }
+  if (size < BUFFER_MAX_BYTES) return null
+  try {
+    for (let i = BUFFER_KEEP_ROTATIONS; i >= 1; i--) {
+      const src = `${BUFFER_FILE}.${i}`
+      const dst = `${BUFFER_FILE}.${i + 1}`
+      if (!fs.existsSync(src)) continue
+      if (i === BUFFER_KEEP_ROTATIONS) fs.unlinkSync(src)
+      else fs.renameSync(src, dst)
+    }
+    fs.renameSync(BUFFER_FILE, `${BUFFER_FILE}.1`)
+    return `rotated ${path.basename(BUFFER_FILE)} (${size.toLocaleString()} bytes)`
+  } catch (e) {
+    return `rotation failed: ${e && e.message}`
+  }
+}
+
+;(function main() {
+  const flags = parseArgs(process.argv.slice(2))
+  const dryRun = flags.has('dry-run')
+  const apply  = flags.has('apply')
+  const rotate = flags.has('rotate-buffer')
+
+  if (dryRun === apply) {
+    console.error('Usage: node sa-clean.js (--dry-run | --apply) [--rotate-buffer]')
+    process.exit(1)
+  }
+
+  const alivePids = getAliveClaudePids()
+  const { toDelete, toKeep } = classify(alivePids)
+
+  console.log(`Live claude.exe PIDs: ${alivePids.size ? '[' + [...alivePids].sort((a,b) => a-b).join(', ') + ']' : '(none detected)'}`)
+  console.log(`Files to keep:        ${toKeep.length}`)
+  console.log(`Files to delete:      ${toDelete.length}`)
+  for (const f of toDelete) console.log(`  - ${path.basename(f)}`)
+
+  if (apply) {
+    let deleted = 0
+    for (const f of toDelete) {
+      try { fs.unlinkSync(f); deleted++ }
+      catch (e) { console.log(`  ! failed to delete ${path.basename(f)}: ${e && e.message}`) }
+    }
+    console.log(`Deleted: ${deleted}`)
+    if (rotate) {
+      const r = rotateBufferIfNeeded()
+      console.log(r || `Buffer below ${BUFFER_MAX_BYTES / (1024 * 1024)} MB — no rotation needed.`)
+    }
+  } else if (rotate) {
+    const r = rotateBufferIfNeeded()
+    if (r) console.log(`(dry-run, but --rotate-buffer was applied) ${r}`)
+  }
+})()

package/siesa-agents/observability/scripts/sa-emit.js

@@ -1,5 +1,10 @@
 #!/usr/bin/env node
-// sa-emit.js — Emit BMAD workflow lifecycle events via OTLP to the OTel collector
+// sa-emit.js — Emit BMAD workflow lifecycle events via OTLP to the OTel collector.
+//
+// Resolves session_id automatically by walking up the process tree to find claude.exe
+// (its PID was recorded by the SessionStart hook in ~/.claude/observability/session-<pid>.json).
+// On *.finished events it reads the session's transcript JSONL and sums token usage
+// since the matching *.started event.
 //
 // Usage:
 //   node sa-emit.js --event workflow.started  --story "1-1-user-auth" --phase "create-story"
@@ -13,9 +18,13 @@
 //   --project-id "<name>"        Override the git-remote-derived project id
 //   --timestamp-offset-ms <ms>   Subtract ms from the event timestamp (backdate the log record)
 //
-// Environment:
-//   SA_OTLP_ENDPOINT — OTel collector HTTP endpoint (default: http://localhost:4318)
-//   SA_OTLP_HEADERS  — Additional headers, comma-separated: "Authorization=Bearer xxx,X-Other=yyy"
+// Endpoint resolution (in priority order):
+//   1. SA_OTLP_ENDPOINT                      — sa-emit-specific base URL ('/v1/logs' is appended)
+//   2. OTEL_EXPORTER_OTLP_LOGS_ENDPOINT      — CC native logs endpoint (full URL, used as-is)
+//   3. OTEL_EXPORTER_OTLP_ENDPOINT           — CC native generic endpoint ('/v1/logs' is appended)
+//   None ⇒ event is buffered to disk and a clear ERROR is logged. No localhost fallback.
+//
+// Headers resolution: SA_OTLP_HEADERS  ||  OTEL_EXPORTER_OTLP_HEADERS  ||  (empty)
 
 'use strict'
 
@@ -23,8 +32,10 @@ const fs = require('fs')
 const path = require('path')
 const os = require('os')
 const { execSync } = require('child_process')
+const { findClaudePid } = require('./sa-pid')
 
 function loadDotEnv() {
+  // Single source of truth: project-local .env in the current working directory.
   const envPath = path.join(process.cwd(), '.env')
   if (!fs.existsSync(envPath)) return
   try {
@@ -102,8 +113,23 @@ if (fixOption && !VALID_FIX_OPTIONS.includes(fixOption)) {
   process.exit(1)
 }
 
-const otlpEndpoint = process.env.SA_OTLP_ENDPOINT || 'http://localhost:4318'
-const stateDir     = path.join(os.homedir(), '.claude', 'observability')
+function resolveOtlpLogsUrl() {
+  if (process.env.SA_OTLP_ENDPOINT) {
+    return process.env.SA_OTLP_ENDPOINT.replace(/\/+$/, '') + '/v1/logs'
+  }
+  if (process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) {
+    return process.env.OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
+  }
+  if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+    return process.env.OTEL_EXPORTER_OTLP_ENDPOINT.replace(/\/+$/, '') + '/v1/logs'
+  }
+  return null
+}
+function resolveOtlpHeaders() {
+  return process.env.SA_OTLP_HEADERS || process.env.OTEL_EXPORTER_OTLP_HEADERS || ''
+}
+const otlpUrl  = resolveOtlpLogsUrl()
+const stateDir = path.join(os.homedir(), '.claude', 'observability')
 
 const epicIdMatch = story.match(/^(\d+)-/)
 const epicId      = epicIdMatch ? epicIdMatch[1] : 'unknown'
@@ -129,43 +155,123 @@ if (engineerOverride) {
   } catch (_) {}
 }
 
+// ---------- Session resolution via PID walk (helper in ./sa-pid) ----------
+
+function loadSessionByClaudePid(claudePid) {
+  if (claudePid == null) return null
+  const f = path.join(stateDir, `session-${claudePid}.json`)
+  if (!fs.existsSync(f)) return null
+  try {
+    return JSON.parse(fs.readFileSync(f, 'utf8'))
+  } catch (_) { return null }
+}
+
+const claudePid   = findClaudePid()
+const sessionInfo = loadSessionByClaudePid(claudePid)
+const sessionId   = sessionInfo && sessionInfo.session_id ? sessionInfo.session_id : null
+
+// ---------- State files (per workflow / fix) — now also include claude_pid for cleanup ----------
+
 const nowMs       = Date.now()
 const eventTimeMs = nowMs - (Number.isFinite(timestampOffsetMs) ? timestampOffsetMs : 0)
 const tsNano      = `${eventTimeMs}000000`
 
 const safeKey   = story.replace(/[^a-zA-Z0-9-]/g, '')
 const stateFile = path.join(stateDir, `wf-${phase}-${safeKey}.json`)
-let durationMs  = null
+let   durationMs = null
+let   wfStartMs  = null
 
 if (event === 'workflow.started') {
   fs.mkdirSync(stateDir, { recursive: true })
-  fs.writeFileSync(stateFile, JSON.stringify({ start_ms: nowMs }))
+  fs.writeFileSync(stateFile, JSON.stringify({ start_ms: nowMs, claude_pid: claudePid, session_id: sessionId }))
 }
 
 if (event === 'workflow.finished') {
   if (fs.existsSync(stateFile)) {
-    const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'))
-    durationMs = nowMs - state.start_ms
-    fs.unlinkSync(stateFile)
+    try {
+      const state = JSON.parse(fs.readFileSync(stateFile, 'utf8'))
+      wfStartMs   = state.start_ms
+      durationMs  = nowMs - state.start_ms
+      fs.unlinkSync(stateFile)
+    } catch (_) {}
   }
 }
 
 const fixStateFile = path.join(stateDir, `fix-${phase}-${safeKey}.json`)
+let   fixStartMs   = null
 
 if (event === 'fix.started') {
   fs.mkdirSync(stateDir, { recursive: true })
-  fs.writeFileSync(fixStateFile, JSON.stringify({ start_ms: nowMs, fix_option: fixOption }))
+  fs.writeFileSync(fixStateFile, JSON.stringify({
+    start_ms: nowMs, fix_option: fixOption, claude_pid: claudePid, session_id: sessionId,
+  }))
 }
 
 if (event === 'fix.finished') {
   if (fs.existsSync(fixStateFile)) {
-    const fixState = JSON.parse(fs.readFileSync(fixStateFile, 'utf8'))
-    durationMs = nowMs - fixState.start_ms
-    if (!fixOption) fixOption = fixState.fix_option
-    fs.unlinkSync(fixStateFile)
+    try {
+      const fixState = JSON.parse(fs.readFileSync(fixStateFile, 'utf8'))
+      fixStartMs     = fixState.start_ms
+      durationMs     = nowMs - fixState.start_ms
+      if (!fixOption) fixOption = fixState.fix_option
+      fs.unlinkSync(fixStateFile)
+    } catch (_) {}
+  }
+}
+
+// ---------- Token aggregation from the session JSONL (only on *.finished) ----------
+
+function parseIsoToMs(s) {
+  if (!s) return null
+  const t = Date.parse(s)
+  return Number.isNaN(t) ? null : t
+}
+
+function sumTokensFromTranscript(transcriptPath, sinceMs) {
+  const totals = { input: 0, output: 0, cache_read: 0, cache_creation: 0 }
+  const models = new Set()
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return { totals, models }
+  try {
+    const content = fs.readFileSync(transcriptPath, 'utf8')
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim()
+      if (!trimmed) continue
+      let rec
+      try { rec = JSON.parse(trimmed) } catch (_) { continue }
+      const tsMs = parseIsoToMs(rec.timestamp || rec.createdAt)
+      if (sinceMs != null && tsMs != null && tsMs < sinceMs) continue
+      const msg   = rec.message || {}
+      const usage = msg.usage || rec.usage
+      if (!usage) continue
+      totals.input          += parseInt(usage.input_tokens                || 0, 10) || 0
+      totals.output         += parseInt(usage.output_tokens               || 0, 10) || 0
+      totals.cache_read     += parseInt(usage.cache_read_input_tokens     || 0, 10) || 0
+      totals.cache_creation += parseInt(usage.cache_creation_input_tokens || 0, 10) || 0
+      const model = msg.model || rec.model
+      if (model) models.add(String(model))
+    }
+  } catch (_) {}
+  return { totals, models }
+}
+
+let tokenAttrs = []
+if ((event === 'workflow.finished' || event === 'fix.finished') && sessionInfo && sessionInfo.transcript_path) {
+  const sinceMs = (event === 'fix.finished') ? fixStartMs : wfStartMs
+  if (sinceMs != null) {
+    const { totals, models } = sumTokensFromTranscript(sessionInfo.transcript_path, sinceMs)
+    tokenAttrs = [
+      { key: 'tokens_input',          value: { intValue: totals.input } },
+      { key: 'tokens_output',         value: { intValue: totals.output } },
+      { key: 'tokens_cache_read',     value: { intValue: totals.cache_read } },
+      { key: 'tokens_cache_creation', value: { intValue: totals.cache_creation } },
+      { key: 'tokens_total',          value: { intValue: totals.input + totals.output + totals.cache_read + totals.cache_creation } },
+    ]
+    if (models.size) tokenAttrs.push({ key: 'models_used', value: { stringValue: [...models].sort().join(',') } })
   }
 }
 
+// ---------- Build OTLP log ----------
+
 const attributes = [
   { key: 'event',    value: { stringValue: event } },
   { key: 'story_id', value: { stringValue: story } },
@@ -173,10 +279,12 @@ const attributes = [
   { key: 'phase',    value: { stringValue: phase } },
 ]
 
-if (from)              attributes.push({ key: 'from',        value: { stringValue: from } })
-if (to)                attributes.push({ key: 'to',          value: { stringValue: to } })
-if (fixOption)         attributes.push({ key: 'fix_option',  value: { stringValue: fixOption } })
-if (durationMs !== null) attributes.push({ key: 'duration_ms', value: { intValue: durationMs } })
+if (sessionId)            attributes.push({ key: 'session_id',  value: { stringValue: sessionId } })
+if (from)                 attributes.push({ key: 'from',        value: { stringValue: from } })
+if (to)                   attributes.push({ key: 'to',          value: { stringValue: to } })
+if (fixOption)            attributes.push({ key: 'fix_option',  value: { stringValue: fixOption } })
+if (durationMs !== null)  attributes.push({ key: 'duration_ms', value: { intValue: durationMs } })
+for (const a of tokenAttrs) attributes.push(a)
 
 const otlpBody = {
   resourceLogs: [
@@ -197,7 +305,7 @@ const otlpBody = {
               observedTimeUnixNano: tsNano,
               severityNumber:       9,
               severityText:         'INFO',
-              body:                 { stringValue: `${event} | story=${story} phase=${phase} project=${projectId} engineer=${engineer}` },
+              body:                 { stringValue: `${event} | story=${story} phase=${phase} project=${projectId} engineer=${engineer}${sessionId ? ` session=${sessionId}` : ''}` },
               attributes,
             },
           ],
@@ -220,14 +328,24 @@ function parseHeaders(raw) {
   return out
 }
 
+function bufferEvent(reason) {
+  const bufferDir = path.join(stateDir, 'buffer')
+  fs.mkdirSync(bufferDir, { recursive: true })
+  fs.appendFileSync(path.join(bufferDir, 'events.jsonl'), JSON.stringify({ reason, otlpBody }) + '\n')
+}
+
 ;(async () => {
+  if (!otlpUrl) {
+    bufferEvent('no-endpoint-configured')
+    console.error(`[sa-emit] ERROR no OTLP endpoint configured (set SA_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT). Event buffered.`)
+    process.exit(0)
+  }
   try {
     const headers = {
       'Content-Type': 'application/json',
-      ...parseHeaders(process.env.SA_OTLP_HEADERS),
+      ...parseHeaders(resolveOtlpHeaders()),
     }
-
-    const response = await fetch(`${otlpEndpoint}/v1/logs`, {
+    const response = await fetch(otlpUrl, {
       method:  'POST',
       headers,
       body:    JSON.stringify(otlpBody),
@@ -235,12 +353,16 @@ function parseHeaders(raw) {
     if (!response.ok) throw new Error(`HTTP ${response.status}`)
 
     let msg = `[sa-emit] ${event} | story=${story} phase=${phase} project=${projectId} engineer=${engineer}`
-    if (durationMs !== null) msg += ` duration=${durationMs}ms`
+    if (sessionId)              msg += ` session=${sessionId}`
+    if (durationMs !== null)    msg += ` duration=${durationMs}ms`
+    if (tokenAttrs.length) {
+      const totalAttr = tokenAttrs.find(a => a.key === 'tokens_total')
+      if (totalAttr) msg += ` tokens=${totalAttr.value.intValue}`
+    }
     console.log(msg)
-  } catch (_) {
-    const bufferDir = path.join(stateDir, 'buffer')
-    fs.mkdirSync(bufferDir, { recursive: true })
-    fs.appendFileSync(path.join(bufferDir, 'events.jsonl'), JSON.stringify(otlpBody) + '\n')
-    console.log(`[sa-emit] BUFFERED (collector unavailable) | ${event} story=${story}`)
+  } catch (err) {
+    const errMsg = (err && err.message) ? err.message : String(err)
+    bufferEvent(`transport-error: ${errMsg}`)
+    console.log(`[sa-emit] BUFFERED (gateway unreachable: ${errMsg}) | ${event} story=${story}`)
   }
-})()
+})()

package/siesa-agents/observability/scripts/sa-pid.js

@@ -0,0 +1,106 @@
+// sa-pid.js — Shared helpers for finding the owning claude.exe PID and listing
+// currently-alive claude.exe PIDs on the host. Cross-platform (Windows + POSIX).
+
+'use strict'
+
+const fs = require('fs')
+const { execSync } = require('child_process')
+
+function snapshotProcessesWindows() {
+  // Returns Map<pid, { ppid, name }>. Empty Map on failure.
+  const map = new Map()
+  try {
+    const out = execSync(
+      'powershell -NoProfile -Command "Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,Name | ConvertTo-Csv -NoTypeInformation"',
+      { encoding: 'utf8', timeout: 10000, windowsHide: true },
+    )
+    for (const raw of out.split(/\r?\n/).slice(1)) {
+      const line = raw.trim()
+      if (!line) continue
+      const m = line.match(/^"(\d+)","(\d+)","([^"]+)"/)
+      if (!m) continue
+      map.set(parseInt(m[1], 10), { ppid: parseInt(m[2], 10), name: m[3] })
+    }
+  } catch (_) {}
+  return map
+}
+
+function findClaudePidWindows(startPid) {
+  const map = snapshotProcessesWindows()
+  let cur = startPid
+  for (let i = 0; i < 30; i++) {
+    const info = map.get(cur)
+    if (!info) return null
+    if (info.name && /^claude/i.test(info.name) && /\.exe$/i.test(info.name)) return cur
+    if (info.ppid === 0 || info.ppid === cur) return null
+    cur = info.ppid
+  }
+  return null
+}
+
+function findClaudePidPosix(startPid) {
+  try {
+    let cur = startPid
+    for (let i = 0; i < 30; i++) {
+      const status = `/proc/${cur}/status`
+      const comm   = `/proc/${cur}/comm`
+      if (!fs.existsSync(status)) return null
+      const lines = fs.readFileSync(status, 'utf8').split('\n')
+      let ppid = null
+      for (const ln of lines) {
+        if (ln.startsWith('PPid:')) { ppid = parseInt(ln.split(/\s+/)[1], 10); break }
+      }
+      const name = fs.existsSync(comm) ? fs.readFileSync(comm, 'utf8').trim() : ''
+      if (/^claude/i.test(name)) return cur
+      if (ppid === null || ppid === 0 || ppid === cur) return null
+      cur = ppid
+    }
+  } catch (_) {}
+  return null
+}
+
+function findClaudePid(startPid = process.pid) {
+  return process.platform === 'win32'
+    ? findClaudePidWindows(startPid)
+    : findClaudePidPosix(startPid)
+}
+
+function getAliveClaudePidsWindows() {
+  const alive = new Set()
+  try {
+    const out = execSync(
+      'powershell -NoProfile -Command "Get-CimInstance Win32_Process | Where-Object { $_.Name -like \\"claude*.exe\\" } | Select-Object -ExpandProperty ProcessId"',
+      { encoding: 'utf8', timeout: 10000, windowsHide: true },
+    )
+    for (const line of out.split(/\r?\n/)) {
+      const t = line.trim()
+      if (/^\d+$/.test(t)) alive.add(parseInt(t, 10))
+    }
+  } catch (_) {}
+  return alive
+}
+
+function getAliveClaudePidsPosix() {
+  const alive = new Set()
+  try {
+    if (!fs.existsSync('/proc')) return alive
+    for (const name of fs.readdirSync('/proc')) {
+      if (!/^\d+$/.test(name)) continue
+      const comm = `/proc/${name}/comm`
+      try {
+        if (!fs.existsSync(comm)) continue
+        const cn = fs.readFileSync(comm, 'utf8').trim()
+        if (/^claude/i.test(cn)) alive.add(parseInt(name, 10))
+      } catch (_) {}
+    }
+  } catch (_) {}
+  return alive
+}
+
+function getAliveClaudePids() {
+  return process.platform === 'win32'
+    ? getAliveClaudePidsWindows()
+    : getAliveClaudePidsPosix()
+}
+
+module.exports = { findClaudePid, getAliveClaudePids }

package/siesa-agents/observability/scripts/sa-session.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// sa-session.js — SessionStart hook handler.
+//
+// Persists session info keyed by the claude.exe PID, so any sa-emit.js
+// subprocess (running from inside a workflow's Bash) can later resolve its
+// own session_id by walking up the process tree.
+
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const { findClaudePid } = require('./sa-pid')
+
+const STATE_DIR = path.join(os.homedir(), '.claude', 'observability')
+
+function logError(msg) {
+  try {
+    fs.mkdirSync(STATE_DIR, { recursive: true })
+    fs.appendFileSync(path.join(STATE_DIR, 'hook-errors.log'), `sa-session: ${msg}\n`)
+  } catch (_) {}
+}
+
+;(async () => {
+  let raw = ''
+  try {
+    for await (const chunk of process.stdin) raw += chunk
+  } catch (e) {
+    logError(`stdin read failed: ${e && e.message}`)
+    process.exit(0)
+  }
+
+  let data = {}
+  if (raw.trim()) {
+    try { data = JSON.parse(raw) }
+    catch (e) {
+      logError(`stdin parse failed: ${e && e.message}`)
+      process.exit(0)
+    }
+  }
+
+  const sessionId = data.session_id
+  if (!sessionId) process.exit(0)
+
+  const claudePid = findClaudePid()
+
+  const state = {
+    session_id:      sessionId,
+    transcript_path: data.transcript_path || null,
+    cwd:             data.cwd || process.cwd(),
+    source:          data.source || null,
+    model:           data.model || null,
+    claude_pid:      claudePid,
+  }
+
+  try {
+    fs.mkdirSync(STATE_DIR, { recursive: true })
+    if (claudePid != null) {
+      fs.writeFileSync(path.join(STATE_DIR, `session-${claudePid}.json`), JSON.stringify(state))
+    }
+    fs.writeFileSync(path.join(STATE_DIR, `session-id-${sessionId}.json`), JSON.stringify(state))
+  } catch (e) {
+    logError(`persist failed: ${e && e.message}`)
+  }
+  process.exit(0)
+})()