fdeops 3.7.8 → 3.8.1

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md - working in the fdeops repository
 
-This repository **is** fdeops - the second brain for Forward Deployed Engineers. One `@fde` skill routes an entire client engagement across six domains, the `fde` CLI does the deterministic work, and per-customer memory writes itself into `.fde/` files.
+This repository **is** fdeops - the second brain for Forward Deployed Engineers. One `@fde` skill routes an entire client engagement across six domains, the `fde` CLI does the deterministic work, and per-customer memory lands in `.fde/` files as a side effect of the work (you still confirm judgment).
 
 ## If you are helping use fdeops in an engagement
 

package/README.md

@@ -37,7 +37,7 @@ A notes app stores what you type. fdeops loads the right client into your AI age
 | **After a meeting** | Notes rot in a scratch file | `fde debrief` routes decisions, risks, deliveries, and contacts into the record, dated |
 | **Scope dispute** | "Small" additions absorbed silently; no record when the sponsor asks | `fde receipts <term>` answers "when did we agree to that?" with dates |
 | **Quiet stakeholder** | Noticed three weeks too late | `fde log contact --signal amber` the day it happens; `fde status` surfaces it |
-| **Multiple clients** | Details blur across engagements | One folder per client, never cross-contaminated |
+| **Multiple clients** | Details blur across engagements | One folder per client; bind the workspace so writes cannot land on a name-alike checkout |
 
 ---
 
@@ -66,7 +66,7 @@ fdeops' `--init` creates the engagement memory at `~/fde-engagements/garvey/.fde
 @fde I just got the brief. New client, payments platform, they want it live before their Q3 audit.
 ```
 
-`@fde` is the one skill fdeops installs. Describe what's happening; it routes to the right field method and the memory writes itself. Full workflow: [docs/USAGE.md](docs/USAGE.md).
+`@fde` is the one skill fdeops installs. Describe what's happening; it routes to the right field method and writes matching `.fde/` artifacts — you still confirm judgment. Full workflow: [docs/USAGE.md](docs/USAGE.md).
 
 Not ready to install? `npx fdeops scan` runs on any repo you can read - day-1 recon (pure `git` + file reads, no config, no account) that maps hotspots, test gaps, and reverted attempts, and ends with the ASK ON DAY 1 questions the brief never mentions. The scan is heuristic by design - treat its output as leads to verify on day one, not findings.
 

package/bin/fde.js

@@ -93,7 +93,11 @@ function readRegistry() {
   } catch (_) { return [] }
 }
 
-function resolveEngagement() {
+function resolveEngagement(opts = {}) {
+  // opts.forWrite: memory mutations (log/debrief/capture) require an intentional
+  // bind - env, registry, pointer, or in-repo .fde. Basename matching is
+  // read-only convenience; writing on a folder-name guess contaminates clients.
+  const forWrite = !!opts.forWrite
   // 1) explicit env (back-compat: accept old FDEOS_ENGAGEMENT too)
   const env = (process.env.FDEOPS_ENGAGEMENT || process.env.FDEOS_ENGAGEMENT || '').replace(/^~/, HOME).trim()
   if (env && fs.existsSync(env)) return env
@@ -123,15 +127,21 @@ function resolveEngagement() {
       }
     } catch (_) {}
   }
-  // 4) workspace dir name matches an engagement slug. This is a convenience,
-  // NOT a binding - an unbound directory that merely happens to be named like a
-  // client (a fork, a demo, a second client with the same codename) would
-  // otherwise attach to that client's memory silently and get written into.
-  // Never silent: warn on stderr so cross-client contamination can't happen
-  // unnoticed, and tell the user how to make the binding explicit.
-  const guess = path.join(ENGAGEMENTS_ROOT, slugify(path.basename(cwd)), '.fde')
+  // 4) workspace dir name matches an engagement slug. Read-only convenience.
+  // NEVER a write target - an unbound checkout named like a client must not
+  // append into that client's memory.
+  const slugGuess = slugify(path.basename(cwd))
+  const guess = path.join(ENGAGEMENTS_ROOT, slugGuess, '.fde')
   if (fs.existsSync(guess)) {
-    process.stderr.write(`⚠ resolved engagement by directory name ("${slugify(path.basename(cwd))}"), not a saved binding. If this is the right client, run \`fde resume --init ${slugify(path.basename(cwd))}\` here to bind it; if not, you are about to read/write the WRONG client's memory.\n`)
+    if (forWrite) {
+      process.stderr.write(
+        `no binding for this workspace - folder name matched "${slugGuess}" but writes require an explicit bind.\n` +
+        `run: fde resume --init ${slugGuess}\n` +
+        ` or: export FDEOPS_ENGAGEMENT=${guess}\n`
+      )
+      return null
+    }
+    process.stderr.write(`⚠ resolved engagement by directory name ("${slugGuess}"), not a saved binding (read-only). If this is the right client, run \`fde resume --init ${slugGuess}\` here to bind it before logging or debriefing.\n`)
     return guess
   }
   // 5) in-repo .fde (engagement-approved only)
@@ -156,6 +166,95 @@ function readEng(eng, f) {
 // a markdown file, so a forgotten stripPrivate() call can't leak a <private> block.
 function readClean(eng, f) { return stripPrivate(readEng(eng, f)) }
 
+// CLI-owned append-only mirror of [signal:x] lines. Survives an agent rewrite
+// that drops stakeholders.md "## Signal history" - skill discipline still
+// matters, but CLI-logged trust tokens must not vanish with the markdown.
+const SIGNAL_LEDGER = '.signal-ledger'
+const LAST_WRITE = '.last-write'
+
+// Heuristic secret shapes - warn/block CLI writes so a wrong-client paste is not silent.
+// Not a scanner product; high-signal patterns an FDE actually pastes by mistake.
+const SECRET_PATTERNS = [
+  { name: 'AWS access key id', re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { name: 'GitHub token', re: /\bghp_[A-Za-z0-9]{20,}\b/ },
+  { name: 'GitHub fine-grained token', re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/ },
+  { name: 'OpenAI-style key', re: /\bsk-[A-Za-z0-9]{20,}\b/ },
+  { name: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+  { name: 'PEM private key', re: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/ },
+  { name: 'Bearer token', re: /\bBearer\s+[A-Za-z0-9._\-]{20,}\b/ },
+]
+
+function findSecretHit(text) {
+  for (const p of SECRET_PATTERNS) {
+    if (p.re.test(String(text))) return p.name
+  }
+  return null
+}
+
+function refuseSecret(kind, hit) {
+  console.error(
+    `refused: ${kind} looks like a ${hit}.\n` +
+    `Do not log credentials into engagement memory. Redact first, or pass --force if this is intentional.\n` +
+    `If you already wrote one: fde log --undo`
+  )
+}
+
+function recordLastWrite(eng, file, entry) {
+  const p = path.join(eng, LAST_WRITE)
+  withFileLock(p, () => {
+    atomicWriteFile(p, JSON.stringify({ file, entry, at: new Date().toISOString() }) + '\n')
+  })
+}
+
+function removeExactEntryLine(md, entry) {
+  const target = entry.trim()
+  const lines = md.split('\n')
+  const idx = lines.findIndex(l => l.trim() === target)
+  if (idx === -1) return null
+  lines.splice(idx, 1)
+  while (idx < lines.length && lines[idx] === '') lines.splice(idx, 1)
+  return lines.join('\n')
+}
+
+
+// Exclusive create lock + retry. Two parallel agent sessions (or hook + CLI)
+// appending the same .fde file otherwise interleave/corrupt under load.
+function withFileLock(targetPath, fn) {
+  const lockPath = targetPath + '.lock'
+  const deadline = Date.now() + 5000
+  while (true) {
+    let fd
+    try {
+      fd = fs.openSync(lockPath, 'wx')
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      if (Date.now() > deadline) {
+        console.error(`could not lock ${path.basename(targetPath)} - another writer is active; retry`)
+        process.exit(1)
+      }
+      const waitUntil = Date.now() + 20
+      while (Date.now() < waitUntil) { /* spin */ }
+      continue
+    }
+    try {
+      return fn()
+    } finally {
+      try { fs.closeSync(fd) } catch (_) {}
+      try { fs.unlinkSync(lockPath) } catch (_) {}
+    }
+  }
+}
+
+function atomicWriteFile(p, content) {
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`
+  fs.writeFileSync(tmp, content)
+  fs.renameSync(tmp, p)
+}
+
+function lockedAppendFile(p, text) {
+  withFileLock(p, () => { fs.appendFileSync(p, text) })
+}
+
 // Pull the body under a "## Heading" up to the next "##" (or EOF).
 function sectionBody(md, heading) {
   const lines = md.split('\n')
@@ -202,10 +301,15 @@ function appendUnderSection(md, heading, entry) {
 function appendLogEntry(eng, type, entry) {
   const p = path.join(eng, LOG_FILES[type])
   if (type === 'contact' && /\[signal:(red|amber|green)\]/i.test(entry)) {
-    fs.writeFileSync(p, appendUnderSection(readEng(eng, LOG_FILES[type]), 'Signal history', entry))
+    withFileLock(p, () => {
+      atomicWriteFile(p, appendUnderSection(readEng(eng, LOG_FILES[type]), 'Signal history', entry))
+    })
+    // Durable CLI ledger - not rewritten by agent artifact passes.
+    lockedAppendFile(path.join(eng, SIGNAL_LEDGER), `${entry}\n`)
   } else {
-    fs.appendFileSync(p, `\n${entry}\n`)
+    lockedAppendFile(p, `\n${entry}\n`)
   }
+  recordLastWrite(eng, LOG_FILES[type], entry)
 }
 
 // phase / trust / top risk / freshness - identical heuristic for status + dashboard.
@@ -215,21 +319,59 @@ function appendLogEntry(eng, type, entry) {
 // signal never silently drives triage. The keyword grep survives only as the
 // zero-effort floor when NO token exists anywhere - prose like "escalated to CTO,
 // resolved amicably" must not flip a client amber forever.
+function stakeholdersMemoryHealth(eng) {
+  // Hostile handoff: binary / unparseable stakeholders must not read as healthy green.
+  let buf
+  try { buf = fs.readFileSync(path.join(eng, 'stakeholders.md')) } catch (_) {
+    return { ok: true, warn: '' }
+  }
+  if (buf.includes(0)) {
+    return { ok: false, warn: 'memory unreadable - verify (binary data in stakeholders.md)' }
+  }
+  const md = buf.toString('utf8')
+  const ledger = readEng(eng, SIGNAL_LEDGER)
+  if (/\[signal:(red|amber|green)\]/i.test(md + '\n' + ledger)) {
+    return { ok: true, warn: '' }
+  }
+  const trustLine = md.match(/\*\*Trust:\*\*\s*([A-Za-z?]+)/i)
+  if (trustLine && !/^(red|amber|green)$/i.test(trustLine[1])) {
+    return { ok: false, warn: 'memory unreadable - verify (invalid trust value)' }
+  }
+  const table = parseMdTable(md)
+  const meaningful = md.split('\n').filter(l => {
+    const t = l.trim()
+    return t && !t.startsWith('#') && !t.startsWith('<!--') && !/^\|?\s*:?-{3,}/.test(t)
+  }).length
+  // Content present but no table and no structured signal → do not invent "green"
+  if (meaningful >= 3 && !table) {
+    return { ok: false, warn: 'memory unreadable - verify (stakeholders.md unparseable)' }
+  }
+  return { ok: true, warn: '' }
+}
+
 function computeSignals(eng) {
   // readClean, not readEng: status/dashboard echo topRisk and stakeholder lines
   // to the terminal and the rendered HTML - a <private> risk must never surface.
   const ctx = readClean(eng, 'context.md'); const stake = readClean(eng, 'stakeholders.md'); const risks = readClean(eng, 'risks.md')
+  // Prefer structured tokens from stakeholders + CLI ledger (ledger survives wipes)
+  const signalText = stake + '\n' + readClean(eng, SIGNAL_LEDGER)
   const phase = (ctx.match(/phase[:* ]+\**([a-z-]+)/i) || [])[1] || '?'
   let latest = null
-  for (const l of stake.split('\n')) {
+  for (const l of signalText.split('\n')) {
     const sm = l.match(/\[signal:(red|amber|green)\]/i)
     if (!sm) continue
     const date = (l.match(/\[(\d{4}-\d{2}-\d{2})\]/) || [])[1] || ''
-    if (!latest || date >= latest.date) latest = { date, sig: sm[1].toLowerCase() }
+    const text = l.replace(/^\s*-\s*/, '').replace(/\[signal:(red|amber|green)\]/i, '').replace(/\[\d{4}-\d{2}-\d{2}\]/, '').trim()
+    if (!latest || date >= latest.date) latest = { date, sig: sm[1].toLowerCase(), text }
   }
-  let trust, signalAge = null, stale = false
-  if (latest) {
+  const mem = stakeholdersMemoryHealth(eng)
+  let trust, signalAge = null, stale = false, trustReason = ''
+  if (!mem.ok && !latest) {
+    trust = 'amber'
+    trustReason = mem.warn
+  } else if (latest) {
     trust = latest.sig === 'red' ? 'RED' : latest.sig
+    trustReason = (latest.text || '').slice(0, 80)
     if (latest.date) {
       signalAge = Math.max(0, Math.floor((Date.now() - Date.parse(latest.date)) / 86400000))
       stale = signalAge > 21
@@ -244,12 +386,14 @@ function computeSignals(eng) {
     return /^[-|]/.test(t) && t.length > 20 && !/^\|?[-\s|]+$/.test(t) &&
       !/risk\s*\|\s*status|mitigation/i.test(t) && !t.startsWith('<!--')
   }) || '').replace(/\|/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80)
+  // Prefer the trust trigger (signal / memory warn) over a random risk line when triage is not green
+  const reason = (trust !== 'green' && (trustReason || mem.warn)) ? (trustReason || mem.warn) : topRisk
   let updated = 'never', ageDays = Infinity
   try {
     ageDays = Math.floor((Date.now() - fs.statSync(path.join(eng, 'context.md')).mtimeMs) / 86400000)
     updated = ageDays === 0 ? 'today' : `${ageDays}d ago`
   } catch (_) {}
-  return { phase, trust, signalAge, stale, topRisk, updated, ageDays }
+  return { phase, trust, signalAge, stale, topRisk, reason, memoryWarn: mem.warn, updated, ageDays }
 }
 
 // ---------- dashboard content extractors (best-effort, read-only) ----------
@@ -351,7 +495,8 @@ function extractStakeholders(eng) {
   // once the token is stripped, so match the token anywhere on the line rather
   // than requiring it immediately after the date; a debrief-written signal was
   // silently invisible to per-stakeholder matching before this.
-  sectionBody(md, 'Signal history').split('\n').forEach(l => {
+  const histText = sectionBody(md, 'Signal history') + '\n' + readEng(eng, SIGNAL_LEDGER)
+  histText.split('\n').forEach(l => {
     const dm = l.trim().match(/^-\s*\[(\d{4}-\d{2}-\d{2})\]\s*(.*)$/i)
     if (!dm) return
     const sm = dm[2].match(/\[signal:(red|amber|green)\]/i)
@@ -470,7 +615,8 @@ function extractLog(eng) {
   sectionBody(readClean(eng, 'risks.md'), 'Retired').split('\n').forEach(l => {
     const m = l.trim().match(FLAT); if (m) push(m[1], m[2], 'receipt')
   })
-  sectionBody(readClean(eng, 'stakeholders.md'), 'Signal history').split('\n').forEach(l => {
+  const signalLog = sectionBody(readClean(eng, 'stakeholders.md'), 'Signal history') + '\n' + readClean(eng, SIGNAL_LEDGER)
+  signalLog.split('\n').forEach(l => {
     const m = l.trim().match(FLAT); if (m) push(m[1], m[2], 'note')
   })
 
@@ -592,7 +738,7 @@ function cmdResume(args) {
     const prev = readRegistry().find(r => r.workspace === cwd)
     const kept = readRegistry().filter(r => r.workspace !== cwd).map(r => `${r.workspace} ${r.slug}`)
     kept.push(`${cwd} ${slug}`)
-    fs.writeFileSync(REGISTRY, kept.join('\n') + '\n')
+    withFileLock(REGISTRY, () => { atomicWriteFile(REGISTRY, kept.join('\n') + '\n') })
     console.log(`ENGAGEMENT READY: ${fdeDir}\nbound to workspace: ${cwd}`)
     if (prev && prev.slug !== slug) console.log(`rebound: this workspace previously wrote to "${prev.slug}" - that memory is untouched; sessions here now write to "${slug}"`)
     // NDA surface: engagement notes must not silently leave the machine via file sync
@@ -654,8 +800,39 @@ function resumeView(md) {
   return `${head}\n\n_(\u2026 ${hidden} lines of earlier session log hidden \u2014 \`fde resume --full\` or open context.md for the full history)_\n\n${tail}`
 }
 
+function cmdLogUndo() {
+  const eng = resolveEngagement({ forWrite: true })
+  if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+  const metaPath = path.join(eng, LAST_WRITE)
+  let meta
+  try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')) } catch (_) {
+    console.error('nothing to undo - no prior fde log/debrief write recorded')
+    process.exit(1)
+  }
+  if (!meta.file || !meta.entry) { console.error('corrupt .last-write - cannot undo'); process.exit(1) }
+  const target = path.join(eng, meta.file)
+  const before = readEng(eng, meta.file)
+  const after = removeExactEntryLine(before, meta.entry)
+  if (after == null) {
+    console.error(`cannot undo - entry no longer in ${meta.file} (edited by hand?). Remove it manually.`)
+    process.exit(1)
+  }
+  withFileLock(target, () => { atomicWriteFile(target, after.endsWith('\n') ? after : after + '\n') })
+  if (/\[signal:(red|amber|green)\]/i.test(meta.entry)) {
+    const ledgerPath = path.join(eng, SIGNAL_LEDGER)
+    const led = removeExactEntryLine(readEng(eng, SIGNAL_LEDGER), meta.entry)
+    if (led != null) withFileLock(ledgerPath, () => { atomicWriteFile(ledgerPath, led.endsWith('\n') ? led : led + '\n') })
+  }
+  try { fs.unlinkSync(metaPath) } catch (_) {}
+  console.log(`undid last write → ${meta.file}`)
+}
+
 function cmdLog(args) {
   args = args.slice()
+  if (args[0] === '--undo') { cmdLogUndo(); return }
+  let force = false
+  const forceIdx = args.indexOf('--force')
+  if (forceIdx !== -1) { force = true; args.splice(forceIdx, 1) }
   // --signal red|amber|green (contact only) → structured token computeSignals trusts
   let signal = ''
   const sigIdx = args.indexOf('--signal')
@@ -665,10 +842,13 @@ function cmdLog(args) {
     args.splice(sigIdx, 2)
   }
   const type = args[0]; const text = args.slice(1).join(' ')
-  if (!LOG_FILES[type] || !text) { console.error('usage: fde log <decision|risk|delivery|contact> <text> [--signal red|amber|green]'); process.exit(1) }
+  if (!LOG_FILES[type] || !text) { console.error('usage: fde log <decision|risk|delivery|contact> <text> [--signal red|amber|green] [--force]\n       fde log --undo'); process.exit(1) }
   if (signal && type !== 'contact') { console.error('--signal only applies to: fde log contact'); process.exit(1) }
-  const eng = resolveEngagement()
+  const eng = resolveEngagement({ forWrite: true })
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
+  const hit = findSecretHit(text)
+  if (hit && !force) { refuseSecret('log text', hit); process.exit(1) }
+  if (hit && force) console.error(`warning: logging possible ${hit} (--force)`)
   const date = new Date().toISOString().slice(0, 10)
   const entry = `- [${date}] ${signal ? `[signal:${signal}] ` : ''}${text}`
   appendLogEntry(eng, type, entry)
@@ -690,7 +870,10 @@ function cmdDebrief(args) {
   const dryIdx = args.indexOf('--dry-run')
   const dry = dryIdx !== -1
   if (dry) args.splice(dryIdx, 1)
-  const eng = resolveEngagement()
+  let force = false
+  const forceIdx = args.indexOf('--force')
+  if (forceIdx !== -1) { force = true; args.splice(forceIdx, 1) }
+  const eng = resolveEngagement({ forWrite: true })
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
   let input = ''
   if (args[0]) {
@@ -727,19 +910,31 @@ function cmdDebrief(args) {
     const m = bare.match(/^(decision|risk|delivery|contact):\s*(.+)$/i)
     if (m) {
       const type = m[1].toLowerCase()
-      const entry = `- [${date}] ${m[2]}`
+      const body = m[2]
+      const hit = findSecretHit(body)
+      if (hit && !force) {
+        console.error(`skipped ${type} line - looks like a ${hit}. Redact it, or re-run with --force.`)
+        continue
+      }
+      const entry = `- [${date}] ${body}`
       if (dry) console.log(`→ ${LOG_FILES[type]}  ${entry}`)
       // appendLogEntry, not a blind append: a contact: line may carry an
       // inline [signal:x] token (the skill's own convention) and must land
       // inside "## Signal history" the same way `fde log --signal` does.
       else appendLogEntry(eng, type, entry)
       counts[type]++
-    } else ctxLines.push(line)
+    } else {
+      if (findSecretHit(line) && !force) {
+        console.error('skipped context line - looks like a secret. Redact it, or re-run with --force.')
+        continue
+      }
+      ctxLines.push(line)
+    }
   }
   if (ctxLines.length) {
     const stamp = `${date} ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
     if (dry) ctxLines.forEach(l => console.log(`→ context.md  - ${l}`))
-    else fs.appendFileSync(path.join(eng, 'context.md'), `\n## Debrief - ${stamp}\n${ctxLines.map(l => `- ${l}`).join('\n')}\n`)
+    else lockedAppendFile(path.join(eng, 'context.md'), `\n## Debrief - ${stamp}\n${ctxLines.map(l => `- ${l}`).join('\n')}\n`)
   }
   const plural = { decision: 'decisions', risk: 'risks', delivery: 'deliveries', contact: 'contacts' }
   const parts = Object.keys(counts).filter(t => counts[t])
@@ -794,7 +989,7 @@ function cmdReceipts(args) {
 }
 
 function cmdCapture() {
-  const eng = resolveEngagement()
+  const eng = resolveEngagement({ forWrite: true })
   if (!eng) process.exit(0) // silent: capture must never break a session
   const branch = sh('git branch --show-current')
   const lastCommit = sh("git log -1 --format='%h %s'").slice(0, 100)
@@ -812,7 +1007,7 @@ function cmdCapture() {
   if (branch) block += `- workspace: \`${branch}\` @ ${lastCommit || 'no commits yet'}\n`
   if (changed) block += `- uncommitted: ${changed}\n`
   if (updated) block += `- engagement files updated: ${updated}\n`
-  try { fs.appendFileSync(path.join(eng, 'context.md'), block) } catch (_) {}
+  try { lockedAppendFile(path.join(eng, 'context.md'), block) } catch (_) {}
 }
 
 function engagementSlugFromPath(eng) {
@@ -829,7 +1024,7 @@ function cmdStatus(args) {
       const eng = path.join(ENGAGEMENTS_ROOT, d, '.fde')
       if (!fs.existsSync(eng)) continue
       const s = computeSignals(eng)
-      rows.push({ name: d, phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, topRisk: s.topRisk.slice(0, 60) })
+      rows.push({ name: d, phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, reason: (s.reason || s.topRisk).slice(0, 60) })
     }
   } else {
     const eng = resolveEngagement()
@@ -838,7 +1033,7 @@ function cmdStatus(args) {
       process.exit(2)
     }
     const s = computeSignals(eng)
-    rows.push({ name: engagementSlugFromPath(eng), phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, topRisk: s.topRisk.slice(0, 60) })
+    rows.push({ name: engagementSlugFromPath(eng), phase: s.phase, trust: s.trust, signalAge: s.signalAge, stale: s.stale, updated: s.updated, reason: (s.reason || s.topRisk).slice(0, 60) })
   }
   if (!rows.length) { console.log('no engagements yet'); return }
   const order = { RED: 0, amber: 1, green: 2 }
@@ -848,7 +1043,7 @@ function cmdStatus(args) {
     // "amber?" = structured signal went stale (>21d) - reconfirm before trusting it
     const label = r.trust + (r.stale ? '?' : '')
     const sig = r.signalAge != null ? `signal ${r.signalAge}d old${r.stale ? ' (STALE - reconfirm)' : ''}  ` : ''
-    console.log(`  [${label.padEnd(6)}] ${r.name.padEnd(24)} phase:${r.phase.padEnd(10)} updated:${r.updated.padEnd(8)} ${sig}${r.topRisk}`)
+    console.log(`  [${label.padEnd(6)}] ${r.name.padEnd(24)} phase:${r.phase.padEnd(10)} updated:${r.updated.padEnd(8)} ${sig}${r.reason}`)
   }
   if (!all) console.log('\n(current engagement only - pass --all for the full portfolio)')
   console.log('\ntrust: latest [signal:x] token in stakeholders.md wins (fde log contact --signal, fde debrief); keyword heuristic only when none exists - verify before acting.')
@@ -1609,6 +1804,24 @@ ${clientViews}
   }
 }
 
+function printUsage() {
+  console.log(`fde - deterministic core of fdeops
+  fde scan                 day-1 recon of this repo (facts, no AI)
+  fde resume               load this workspace's engagement memory (bounded)
+  fde resume --full        load the complete context.md (no bound)
+  fde resume --init <name> create + bind engagement for this workspace (rebind replaces)
+  fde resume --bind        show what this workspace is bound to, and what resolves
+  fde log <type> <text>    append decision|risk|delivery|contact (contact takes --signal red|amber|green; --force to allow secret-like text)
+  fde log --undo           remove the last CLI log/debrief entry from memory
+  fde debrief [file]       meeting notes → memory: decision:/risk:/delivery:/contact: lines route, rest → context.md (stdin if no file; --dry-run; --force)
+  fde receipts <term>      "what did we agree?" with dates
+  fde capture              session-end memory snapshot (hooks use this)
+  fde status [--all]       current engagement status (pass --all for full portfolio)
+  fde dashboard [--all]    current engagement fieldbook (pass --all for every client)
+  env FDEOPS_ENGAGEMENTS_ROOT  override ~/fde-engagements (init/status/dashboard/registry)
+  writes require a workspace bind (or FDEOPS_ENGAGEMENT) - folder-name match is read-only`)
+}
+
 const [cmd, ...args] = process.argv.slice(2)
 switch (cmd) {
   case 'scan': cmdScan(); break
@@ -1619,18 +1832,13 @@ switch (cmd) {
   case 'capture': cmdCapture(); break
   case 'status': cmdStatus(args); break
   case 'dashboard': cmdDashboard(args); break
+  case 'help':
+  case '-h':
+  case '--help':
+    printUsage()
+    break
   default:
-    console.log(`fde - deterministic core of fdeops
-  fde scan                 day-1 recon of this repo (facts, no AI)
-  fde resume               load this workspace's engagement memory (bounded)
-  fde resume --full        load the complete context.md (no bound)
-  fde resume --init <name> create + bind engagement for this workspace (rebind replaces)
-  fde resume --bind        show what this workspace is bound to, and what resolves
-  fde log <type> <text>    append decision|risk|delivery|contact (contact takes --signal red|amber|green)
-  fde debrief [file]       meeting notes → memory: decision:/risk:/delivery:/contact: lines route, rest → context.md (stdin if no file; --dry-run previews)
-  fde receipts <term>      "what did we agree?" with dates
-  fde capture              session-end memory snapshot (hooks use this)
-  fde status [--all]       current engagement status (pass --all for full portfolio)
-  fde dashboard [--all]    current engagement fieldbook (pass --all for every client)
-  env FDEOPS_ENGAGEMENTS_ROOT  override ~/fde-engagements (init/status/dashboard/registry)`)
+    printUsage()
+    // Missing or unknown command must fail - exit 0 made typos look like success in scripts/hooks.
+    process.exit(1)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fdeops",
-  "version": "3.7.8",
+  "version": "3.8.1",
   "description": "Field kit for engineers embedded in client work - a real CLI (recon, memory, portfolio), one @fde skill with field judgment on top, and hooks that make it automatic. Claude Code plugin and any agent that loads skills.",
   "bin": {
     "fdeops": "bin/install.js",

package/skills/fde/SKILL.md

@@ -38,7 +38,7 @@ This is what makes fdeops a second brain instead of a chat window.
 - Data tagged `<private>` in `trust-profile.md` (sacred data, PHI, cardholder, classified) **never enters your context or any subagent prompt** - work around it, never with it.
 - Locked-down engagement (no AI on their code)? Use the CLI + the fieldbook only. The memory layer is the FDE's own notes, not customer code.
 
-**Engagement path - zero ceremony.** Run `fde resume` (fallback: `node ~/.claude/fdeops/fde.js resume`). The **workspace registry** (written once by `fde resume --init <name>`) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match → `./.fde`. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
+**Engagement path - zero ceremony.** Run `fde resume` (fallback: `node ~/.claude/fdeops/fde.js resume`). The **workspace registry** (written once by `fde resume --init <name>`) is the normal path; resolution order is env var override → registry → pointer file → workspace-name match (read-only) → `./.fde`. Writes require a bind (or `FDEOPS_ENGAGEMENT`), not folder name alone. It prints a **bounded** view of `context.md` - the curated head (state, next action) plus the most recent activity, with the older session log collapsed (use `fde resume --full` when you genuinely need the whole history). If it reports NO ENGAGEMENT: confirm the client name in conversation (one question), then run `fde resume --init <name>` yourself - the one setup step; the FDE never runs setup commands. Never install fdeops on infrastructure the FDE does not control.
 
 **The `fde` CLI does the deterministic work - use it instead of improvising shell:**