fdeops 3.9.20 → 3.10.2

package/bin/fde.js

@@ -206,13 +206,97 @@ function stripControlChars(s) {
   return String(s || '').replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '')
 }
 
+const PRIVATE_MARKER = '(private - redacted)'
+// Openers tolerate whitespace and attributes (<private >, <private data-x="1">)
+// so a near-miss tag still seals instead of failing open.
+const PRIVATE_TAG = /<(\/)?private\b[^>]*>/gi
+
+// Depth-aware split of a markdown body into public text and sealed blocks. A
+// nested block seals to the outermost close, an unclosed one seals to EOF, and a
+// stray close is dropped - a regex pair cannot do any of those safely.
+// HTML comments go first: template hints and pasted notes hide content there, and
+// `clean` is what debrief/ingest preview to a human and route into memory.
+// opts.sealDangling seals an unterminated `<!--` to EOF. Only untrusted input
+// gets that: on the read path a stray `<!--` already stored in memory would
+// otherwise hide every line after it from every view.
+function splitPrivate(md, opts = {}) {
+  let text = String(md || '').replace(/<!--[\s\S]*?-->/g, '')
+  if (opts.sealDangling) text = text.replace(/<!--[\s\S]*$/, '')
+  const blocks = []
+  let out = ''
+  let cursor = 0
+  let depth = 0
+  let start = 0
+  let m
+  PRIVATE_TAG.lastIndex = 0
+  while ((m = PRIVATE_TAG.exec(text))) {
+    const closing = Boolean(m[1])
+    if (!closing) {
+      if (depth === 0) {
+        out += text.slice(cursor, m.index)
+        start = m.index
+      }
+      depth++
+    } else if (depth > 0) {
+      depth--
+      if (depth === 0) {
+        blocks.push(text.slice(start, m.index + m[0].length))
+        out += PRIVATE_MARKER
+        cursor = m.index + m[0].length
+      }
+    } else {
+      out += text.slice(cursor, m.index)
+      cursor = m.index + m[0].length
+    }
+  }
+  if (depth > 0) {
+    blocks.push(text.slice(start))
+    out += PRIVATE_MARKER
+  } else {
+    out += text.slice(cursor)
+  }
+  return { clean: out, blocks }
+}
+
 function stripPrivate(md) {
-  return stripControlChars(
-    String(md || '')
-      .replace(/<private>[\s\S]*?<\/private>/gi, '(private - redacted)')
-      .replace(/<private>[\s\S]*$/i, '(private - redacted)')
-      .replace(/<!--[\s\S]*?-->/g, '')
-  )
+  return stripControlChars(splitPrivate(md).clean)
+}
+
+// Persisted blocks must be balanced. splitPrivate() seals an unclosed block to
+// EOF and hands it back exactly as written; storing that would leave a dangling
+// opener that swallows every note appended to the file afterwards.
+function sealedText(blocks) {
+  return blocks.map((b) => {
+    let open = 0
+    let m
+    PRIVATE_TAG.lastIndex = 0
+    while ((m = PRIVATE_TAG.exec(b))) {
+      if (m[1]) open = Math.max(0, open - 1)
+      else open++
+    }
+    // Balance by count, not by suffix: one block can hold several unclosed
+    // openers, and each needs its own closer or the tail still dangles.
+    return `${b}\n${'</private>\n'.repeat(open)}`
+  }).join('')
+}
+
+// Unbalanced markers do not leak a sealed block, but they change what is public:
+// a stray `</private>` leaves the text after it in the clear, and a forgotten
+// closer seals everything appended later. Counts only - never the content.
+function privateMarkerImbalance(md) {
+  const text = String(md || '')
+  let depth = 0
+  let unclosed = 0
+  let stray = 0
+  let m
+  PRIVATE_TAG.lastIndex = 0
+  while ((m = PRIVATE_TAG.exec(text))) {
+    if (!m[1]) depth++
+    else if (depth > 0) depth--
+    else stray++
+  }
+  unclosed = depth
+  return { unclosed, stray }
 }
 
 // Read + redact in one step - the default way dashboard code should ever touch
@@ -351,7 +435,10 @@ function atomicWriteFile(p, content, opts = {}) {
   }
   const tmp = `${p}.${process.pid}.${Date.now()}.tmp`
   try {
-    fs.writeFileSync(tmp, content)
+    // opts.mode is set at create time: a secret must never exist world-readable,
+    // not even for the window between rename and a follow-up chmod.
+    fs.writeFileSync(tmp, content, opts.mode ? { mode: opts.mode } : undefined)
+    if (opts.mode) fs.chmodSync(tmp, opts.mode)
     fs.renameSync(tmp, p)
   } catch (e) {
     try { fs.unlinkSync(tmp) } catch (_) {}
@@ -385,6 +472,10 @@ function rmTreeQuiet(dir) {
 
 const OWNER_FILE = '.owner'
 const DEBRIEF_PROPOSE = '.debrief-propose'
+// The agent is told to open and rewrite .debrief-propose, so sealed blocks are
+// held out of it in an owner-only sidecar that only --apply reads back.
+const DEBRIEF_PRIVATE = '.debrief-private'
+const DEBRIEF_SEAL = '.debrief-seal'
 
 function gitBinOk() {
   try {
@@ -601,12 +692,18 @@ function detectOverlay(eng) {
 // prose section (e.g. risks.md's "## Retired") after the table is never
 // swept in as rows.
 function parseMdTable(md) {
-  const cells = r => r.replace(/^\s*\|/, '').replace(/\|\s*$/, '').split('|').map(c => c.trim())
+  // Split on unescaped pipes only, then unescape: a ledger full of "40% \| p95"
+  // otherwise shifts every later cell and the table reads as a different table.
+  const cells = r => r.replace(/^\s*\|/, '').replace(/(?<!\\)\|\s*$/, '')
+    .split(/(?<!\\)\|/).map(c => c.replace(/\\\|/g, '|').trim())
   const isSep = r => r.includes('-') && /^\|?[\s:|-]+\|?$/.test(r.trim())
   let headers = null
   const rows = []
   for (const raw of md.split('\n')) {
     const t = raw.trim()
+    // A redacted row is still a row: sealing one line must not truncate the
+    // table and silently hide every row under it.
+    if (t === PRIVATE_MARKER) continue
     if (!/^\|.*\|/.test(t)) { if (headers) break; continue }
     if (isSep(t)) continue
     const cs = cells(t)
@@ -796,8 +893,9 @@ function extractLog(eng) {
   const FLAT = /^-\s*\[(\d{4}-\d{2}-\d{2})\]\s*(.+)$/
   const entries = []
   const push = (date, text, kind) => {
+    const sig = (text.match(/\[signal:(red|amber|green)\]/i) || [])[1] || ''
     text = text.replace(/\[signal:(red|amber|green)\]\s*/i, '').trim()
-    if (date && text) entries.push({ date, text, kind })
+    if (date && text) entries.push({ date, text, kind, sig: sig.toLowerCase() })
   }
 
   readClean(eng, 'decisions.md').split('\n').forEach(l => {
@@ -818,7 +916,18 @@ function extractLog(eng) {
   })
 
   entries.sort((a, b) => b.date.localeCompare(a.date))
-  return entries.slice(0, 15)
+  // `fde log contact` records one entry in two places (stakeholders.md "Signal
+  // history" and .signal-ledger); the timeline reads both, so collapse identical
+  // rows or the same note renders twice and looks like a double write.
+  const seen = new Set()
+  return entries.filter(e => {
+    // The signal is part of the event: the same note logged amber then red on
+    // one day is an escalation, not a duplicate.
+    const key = `${e.kind}|${e.date}|${e.sig}|${e.text}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  }).slice(0, 15)
 }
 
 // ---------- commands ----------
@@ -1001,7 +1110,9 @@ function cmdResume(args) {
   const eng = resolveEngagement()
   if (!eng) {
     const list = fs.existsSync(ENGAGEMENTS_ROOT)
-      ? fs.readdirSync(ENGAGEMENTS_ROOT).filter(d => !d.startsWith('.')).join(', ') || '(none yet)'
+      ? fs.readdirSync(ENGAGEMENTS_ROOT).sort()
+        .filter(d => !d.startsWith('.') && fs.existsSync(path.join(ENGAGEMENTS_ROOT, d, '.fde')))
+        .join(', ') || '(none yet)'
       : '(none yet)'
     console.log(`NO ENGAGEMENT for this workspace.\nexisting: ${list}\ncreate + bind one:  fde resume --init <client-name>`)
     process.exit(2)
@@ -1290,14 +1401,57 @@ function previewLine(text, max = 240) {
   return `${t.slice(0, max)}… (${t.length} chars)`
 }
 
-function routeDebriefInput(eng, input, { dry, force }) {
+function writeProposal(eng, text) {
+  const { clean, blocks } = splitPrivate(text, { sealDangling: true })
+  const proposePath = path.join(eng, DEBRIEF_PROPOSE)
+  const privatePath = path.join(eng, DEBRIEF_PRIVATE)
+  // Seal first. A refused or failed sidecar write must not leave behind a
+  // proposal whose (private - redacted) marker has nothing left behind it.
+  if (blocks.length) {
+    const blocked = refuseSymlinkWrite(privatePath, { soft: true })
+    if (blocked) { console.error(blocked); process.exit(1) }
+    withFileLock(privatePath, () => { atomicWriteFile(privatePath, sealedText(blocks), { mode: 0o600 }) })
+    try { fs.chmodSync(privatePath, 0o600) } catch (_) {}
+  } else {
+    try { fs.unlinkSync(privatePath) } catch (_) {}
+  }
+  withFileLock(proposePath, () => { atomicWriteFile(proposePath, clean) })
+  // Receipt, so apply knows how many blocks the human actually approved. Counting
+  // (private - redacted) markers in the proposal instead would refuse forever on
+  // notes that merely quote the wording - the CLI prints it, so it gets pasted back.
+  withFileLock(path.join(eng, DEBRIEF_SEAL), () => {
+    atomicWriteFile(path.join(eng, DEBRIEF_SEAL), `${blocks.length}\n`)
+  })
+  return { proposePath, clean, blocks }
+}
+
+function readSealCount(eng) {
+  try {
+    const n = parseInt(fs.readFileSync(path.join(eng, DEBRIEF_SEAL), 'utf8').trim(), 10)
+    return Number.isInteger(n) && n >= 0 ? n : null
+  } catch (_) { return null }
+}
+
+function readSealedProposal(eng) {
+  try {
+    return splitPrivate(stripControlChars(fs.readFileSync(path.join(eng, DEBRIEF_PRIVATE), 'utf8'))).blocks
+  } catch (_) { return [] }
+}
+
+function routeDebriefInput(eng, input, { dry, force, sealed = [] }) {
   const d = new Date()
   const date = d.toISOString().slice(0, 10)
   const counts = { decision: 0, risk: 0, delivery: 0, contact: 0, next: 0 }
   const ctxLines = []
   let nextAction = ''
   ensureMemoryGit(eng)
-  for (const raw of input.split('\n')) {
+  // Sealed blocks are pulled out before routing, so a <private> block's interior
+  // lines are never previewed and never routed into decisions/risks/stakeholders
+  // unsealed. They land verbatim in context.md instead: the preview a human
+  // approves is exactly what --apply writes.
+  const { clean: routable, blocks: inlinePrivate } = splitPrivate(input, { sealDangling: true })
+  const privateBlocks = [...inlinePrivate, ...sealed]
+  for (const raw of routable.split('\n')) {
     let line = raw.trim()
     if (!line) continue
     const bare = line.replace(/^[-*+]\s+/, '').replace(/^\*\*(decision|risk|delivery|contact|next):?\*\*:?\s*/i, '$1: ')
@@ -1331,12 +1485,16 @@ function routeDebriefInput(eng, input, { dry, force }) {
     }
   }
   if (nextAction && !dry) setNextAction(eng, nextAction)
-  if (ctxLines.length) {
+  if (ctxLines.length || privateBlocks.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  - ${previewLine(l)}`))
-    else lockedAppendFile(path.join(eng, 'context.md'), `\n## Debrief - ${stamp}\n${ctxLines.map(l => `- ${l}`).join('\n')}\n`)
+    else {
+      const bullets = ctxLines.length ? `${ctxLines.map(l => `- ${l}`).join('\n')}\n` : ''
+      const sealed = privateBlocks.length ? sealedText(privateBlocks) : ''
+      lockedAppendFile(path.join(eng, 'context.md'), `\n## Debrief - ${stamp}\n${bullets}${sealed}`)
+    }
   }
-  return { counts, ctxLines, date, nextAction }
+  return { counts, ctxLines, date, nextAction, privateBlocks }
 }
 
 function cmdDebrief(args) {
@@ -1358,36 +1516,45 @@ function cmdDebrief(args) {
   if (!eng) { console.error('no engagement - run: fde resume --init <name>'); process.exit(2) }
 
   let input = ''
+  let sealed = []
   if (apply && !smart && !args[0]) {
     try { input = stripControlChars(fs.readFileSync(path.join(eng, DEBRIEF_PROPOSE), 'utf8')) } catch (_) {
       console.error('nothing to apply - run: fde debrief --smart <notes.md>   then   fde debrief --apply')
       process.exit(1)
     }
+    sealed = readSealedProposal(eng)
+    const expected = readSealCount(eng)
+    if (expected === null ? (!sealed.length && input.includes(PRIVATE_MARKER)) : sealed.length < expected) {
+      console.error(`refused: the proposal seals a private note but ${DEBRIEF_PRIVATE} is missing or unreadable - applying now would drop it silently.`)
+      console.error('re-run the propose step (fde debrief --smart <notes> | fde ingest propose <id>).')
+      process.exit(1)
+    }
   } else {
     input = readDebriefInput(args)
   }
 
   if (smart) {
-    const proposed = smartProposeText(input)
-    const proposePath = path.join(eng, DEBRIEF_PROPOSE)
-    withFileLock(proposePath, () => { atomicWriteFile(proposePath, proposed) })
+    const { proposePath, clean, blocks } = writeProposal(eng, smartProposeText(input))
     console.log('SMART PROPOSE (heuristic - review before apply; no new facts invented beyond line rewrites)\n')
-    routeDebriefInput(eng, proposed, { dry: true, force })
+    routeDebriefInput(eng, clean, { dry: true, force, sealed: blocks })
     if (!apply) {
       console.log(`\nproposal saved → ${proposePath}`)
       console.log('confirm:  fde debrief --apply')
       console.log('(edit the propose file first if a line mis-routed)')
       return
     }
-    input = proposed
+    input = clean
+    sealed = blocks
   }
 
-  const { counts, ctxLines } = routeDebriefInput(eng, input, { dry, force })
+  const { counts, ctxLines, privateBlocks } = routeDebriefInput(eng, input, { dry, force, sealed })
   if (!dry) {
     const hash = commitMemory(eng, 'debrief', {
       files: ['decisions.md', 'risks.md', 'delivery.md', 'stakeholders.md', 'context.md', SIGNAL_LEDGER],
     })
     try { fs.unlinkSync(path.join(eng, DEBRIEF_PROPOSE)) } catch (_) {}
+    try { fs.unlinkSync(path.join(eng, DEBRIEF_PRIVATE)) } catch (_) {}
+  try { fs.unlinkSync(path.join(eng, DEBRIEF_SEAL)) } catch (_) {}
     if (hash) console.log(`memory @${hash}`)
   }
   const plural = {
@@ -1396,6 +1563,7 @@ function cmdDebrief(args) {
   const parts = Object.keys(counts).filter(t => counts[t])
     .map(t => `${counts[t]} ${counts[t] === 1 ? (t === 'next' ? 'next action' : t) : plural[t]}`)
   if (ctxLines.length) parts.push(`${ctxLines.length} context line${ctxLines.length === 1 ? '' : 's'}`)
+  if (privateBlocks.length) parts.push(`${privateBlocks.length} sealed private note${privateBlocks.length === 1 ? '' : 's'}`)
   const verb = dry ? 'debrief would route' : 'debrief routed'
   console.log(parts.length ? `${verb} → ${parts.join(', ')}` : 'debrief empty - nothing routed')
 }
@@ -1506,11 +1674,9 @@ function cmdIngest(args) {
       console.error(`ingest propose refused: staged item is over ${DEBRIEF_MAX_BYTES} bytes after provenance. Split it.`)
       process.exit(1)
     }
-    const proposed = smartProposeText(input)
-    const proposePath = path.join(eng, DEBRIEF_PROPOSE)
-    withFileLock(proposePath, () => { atomicWriteFile(proposePath, proposed) })
+    const { proposePath, clean, blocks } = writeProposal(eng, smartProposeText(input))
     console.log(`INGEST PROPOSE from ${path.basename(item)} (via:${source})\n`)
-    routeDebriefInput(eng, proposed, { dry: true, force: false })
+    routeDebriefInput(eng, clean, { dry: true, force: false, sealed: blocks })
     console.log(`\nproposal saved → ${proposePath}`)
     console.log('confirm:  fde ingest apply')
     console.log('(agent: rewrite lines with decision:/risk:/contact:/next: prefixes before apply)')
@@ -1820,6 +1986,17 @@ function collectDoctorIssues(eng) {
       issues.push('memory not git-versioned - next write will init, or re-run resume --init')
     }
   }
+  for (const file of REDACT_FILES) {
+    const abs = path.join(eng, file)
+    if (!fs.existsSync(abs)) continue
+    const { unclosed, stray } = privateMarkerImbalance(readEng(eng, file))
+    if (stray) {
+      issues.push(`${file} has ${stray} unmatched </private> - text after it is PUBLIC; pair or delete the marker`)
+    }
+    if (unclosed) {
+      issues.push(`${file} has ${unclosed} unclosed <private> - everything after it is sealed, including notes added later`)
+    }
+  }
   const success = readClean(eng, 'success.md')
   if (!firstLine(success, 80)) issues.push('success.md has no stated done-definition - fill before plan/build')
   const ctxMd = readClean(eng, 'context.md')
@@ -1841,6 +2018,12 @@ function collectDoctorIssues(eng) {
         `phase is ${s.phase} with no value bucket (cost-save | risk-mitigation | revenue-uplift) in success.md or delivery value ledger`
       )
     }
+    const value = claimedValueRows(eng)
+    if (value.claimed) {
+      issues.push(
+        `${value.claimed} value ledger row(s) measured but not accepted by anyone on the customer side${value.columnMissing ? ' (no "Accepted by" column)' : ''} - a number only we agree with is claimed, not delivered; name who signed off in delivery.md`
+      )
+    }
     if (engagementTouchesAI(eng) && !hasEvalReceipt(eng)) {
       issues.push(
         `phase is ${s.phase} with AI in scope but no eval receipt (evals.md Verdict or delivery Eval / Ship receipts) — required before green ship/close`
@@ -1973,6 +2156,31 @@ function hasValueBucket(eng) {
   return false
 }
 
+// A measured number the FDE calculated is not a benefit the customer agreed to.
+// Rows carrying a real Measured value need a named customer-side owner in
+// "Accepted by", or they close as claimed - the distinction the renewal turns on.
+// "pending review", "TBD.", "n/a (blocked)" and "..." are all the same thing an
+// FDE means by an empty cell - nagging about them teaches people to ignore doctor.
+const PENDING_CELL_RE =
+  /^(?:pending|tbd|to ?be ?(?:measured|confirmed|determined)|n\s*\/\s*a|na|none|unknown|not measured|\?+|\.{2,}|…|-+|—+|–+)(?:[^\w].*)?$/i
+
+function claimedValueRows(eng) {
+  const ledger = stripTemplateNoise(sectionBody(readClean(eng, 'delivery.md'), 'Value ledger') || '')
+  const table = parseMdTable(ledger)
+  if (!table) return { claimed: 0, columnMissing: false }
+  const mIdx = colIndex(table.headers, /measured/i)
+  if (mIdx === -1) return { claimed: 0, columnMissing: false }
+  const aIdx = colIndex(table.headers, /accept/i)
+  let claimed = 0
+  for (const row of table.rows) {
+    const measured = String(row[mIdx] || '').trim()
+    if (!measured || PENDING_CELL_RE.test(measured)) continue
+    const accepted = aIdx === -1 ? '' : String(row[aIdx] || '').trim()
+    if (!accepted || PENDING_CELL_RE.test(accepted)) claimed++
+  }
+  return { claimed, columnMissing: aIdx === -1 }
+}
+
 // AI in scope for ship/close hygiene — delivery/decisions/trust evidence only.
 // Do not scan terrain.md: its template headers mention LLM and would false-positive every ship.
 function engagementTouchesAI(eng) {
@@ -2463,8 +2671,152 @@ function cmdDashboard(args) {
   }
 }
 
+// ---------- demo (see the value before touching a real client) ----------
+// Everything below runs the real commands against a throwaway engagement under
+// ~/fde-engagements/.demo/ - the leading dot keeps it out of every portfolio
+// listing (status --all, dashboard --all, resume's "existing:" line). Nothing
+// here fabricates output: the fieldbook you see is what debrief/log actually
+// wrote, so the demo cannot drift from the product.
+const DEMO_SLUG = 'acme-payments'
+const DEMO_NOTES = `Kickoff call with Acme payments team - Priya (VP Eng, sponsor), Tom (staff eng)
+
+decision: settle on the existing Stripe connector instead of the in-house rewrite - Priya wants the Q3 audit clean first
+risk: nobody can name who owns the reconciliation job; it has failed silently twice since March
+delivery: read-only access to the payments repo and the last 90 days of audit logs
+contact: Priya is bought in but travelling for two weeks - Tom is the day-to-day decision maker
+next: get the reconciliation runbook from Tom before touching anything
+
+<private>
+Priya hinted the previous vendor was let go mid-contract. Do not repeat this to the team.
+</private>
+`
+
+// What `@fde land` drafts with the human in the chat. The CLI has no command for
+// these two files by design (they are judgment, not appends), so the demo writes
+// them and says so - the transcript stays honest either way.
+const DEMO_LAND_ARTIFACTS = {
+  'brief.md': `# Brief - Acme payments
+
+**As stated:** clean up payment reconciliation before the Q3 audit.
+**What we heard instead:** nobody owns the reconciliation job, and it fails silently.
+**Out of scope (agreed):** the in-house connector rewrite.
+`,
+  'success.md': `# Success
+
+- Reconciliation failures alert someone within 15 minutes, with a named owner.
+- The Q3 audit can trace any settlement discrepancy to a dated record.
+
+**Signed off by:** Priya (VP Eng) - 2026-08-07
+`,
+}
+
+function demoRoot() { return path.join(ENGAGEMENTS_ROOT, '.demo') }
+
+// Piping the demo into a file or a docs snippet must not litter escape codes.
+const DEMO_BOLD = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR
+function demoHead(s) { return DEMO_BOLD ? `\x1b[1m${s}\x1b[0m` : s }
+
+function demoStep(label, argv, cwd, env) {
+  console.log(`\n${demoHead(label)}`)
+  console.log(`  $ fde ${argv.join(' ')}\n`)
+  const r = require('child_process').spawnSync(process.execPath, [__filename, ...argv], {
+    cwd, env, encoding: 'utf8',
+  })
+  const out = `${r.stdout || ''}${r.stderr || ''}`.trimEnd()
+  if (out) console.log(out.split('\n').map(l => `  ${l}`).join('\n'))
+  // doctor exits 1 on hygiene findings, resume exits 2 when unbound: a demo step
+  // failing means the product is broken, so surface it instead of pretending.
+  if (r.status !== 0 && !(argv[0] === 'doctor')) {
+    console.error(`\n  demo step failed (exit ${r.status}): fde ${argv.join(' ')}`)
+    process.exit(1)
+  }
+  return out
+}
+
+function cmdDemo(args) {
+  const root = demoRoot()
+  if (args.includes('--clean')) {
+    rmTreeQuiet(root)
+    console.log(`removed ${root}\n(your real engagements under ${ENGAGEMENTS_ROOT} were not touched)`)
+    return
+  }
+  // Always start from empty, so the demo is the same on the tenth run as the first.
+  rmTreeQuiet(root)
+  const workspace = path.join(root, 'acme-payments-repo')
+  try {
+    fs.mkdirSync(workspace, { recursive: true })
+  } catch (e) { failFs(e, 'create demo workspace', workspace) }
+  const notes = path.join(workspace, 'kickoff-notes.md')
+  fs.writeFileSync(notes, DEMO_NOTES)
+  const env = {
+    ...process.env,
+    FDEOPS_ENGAGEMENTS_ROOT: root,
+    // the demo must resolve to its own sandbox, never to whatever the shell points at
+    FDEOPS_ENGAGEMENT: '',
+    FDEOS_ENGAGEMENT: '',
+  }
+
+  console.log(`
+  fdeops demo - a fake client, real commands, nothing sent anywhere
+
+  Sandbox:  ${root}
+  Fake client: Acme (payments platform). No data of yours is read or written.`)
+
+  demoStep('1. Monday of week 1 - create the fieldbook for this client', ['resume', '--init', DEMO_SLUG], workspace, env)
+  demoStep('2. You walk out of the kickoff with messy notes - hand them over', ['debrief', '--smart', notes], workspace, env)
+  demoStep('3. You confirm. Only now does anything enter the record', ['debrief', '--apply'], workspace, env)
+  demoStep('4. Say where you are in the engagement', ['log', 'phase', 'land'], workspace, env)
+  const engDir = path.join(root, DEMO_SLUG, '.fde')
+  console.log(`\n${demoHead('5. During land, @fde drafts the brief and the definition of done with you')}`)
+  console.log('  (the two files the agent writes with you in the chat - not a CLI command)\n')
+  for (const [file, body] of Object.entries(DEMO_LAND_ARTIFACTS)) {
+    try { fs.writeFileSync(path.join(engDir, file), body) } catch (e) { failFs(e, 'write demo artifact', file) }
+    console.log(`  → ${file}`)
+  }
+  // The header fields the agent fills during land, in place - the debrief content
+  // below them stays untouched.
+  const ctxPath = path.join(engDir, 'context.md')
+  const ctx = fs.readFileSync(ctxPath, 'utf8')
+    .replace(/^\*\*Engagement:\*\*\s*$/m, '**Engagement:** Acme payments reconciliation')
+    .replace(/^\*\*Customer:\*\*\s*$/m, '**Customer:** Acme (fake - this is the demo)')
+  fs.writeFileSync(ctxPath, ctx)
+  console.log('  → context.md (engagement + customer header)')
+  // Land them in the ledger the way the agent would, or every later step warns
+  // about uncommitted manual edits - correct behaviour, wrong lesson for a demo.
+  const landHash = commitMemory(engDir, 'land: brief + success', { files: [...Object.keys(DEMO_LAND_ARTIFACTS), 'context.md'] })
+  if (landHash) console.log(`  memory @${landHash}`)
+  demoStep('6. Two days later, the sponsor goes quiet', ['log', 'contact', 'Priya has not replied to two emails about the runbook', '--signal', 'amber'], workspace, env)
+  demoStep('7. Next morning, a fresh agent session with no memory of any of this', ['resume'], workspace, env)
+  demoStep('8. A meeting in ten minutes - what do you walk in knowing?', ['prep', 'sponsor check-in'], workspace, env)
+  demoStep('9. Six weeks later: "we never agreed to drop the rewrite"', ['receipts', 'rewrite'], workspace, env)
+  demoStep('10. The whole engagement on one page', ['dashboard'], workspace, env)
+  // cmdDashboard's default out path, computed rather than scraped from its output:
+  // a HOME with a space in it truncates any whitespace-delimited parse.
+  const html = path.join(root, 'fieldbook-current.html')
+
+  console.log(`
+  ${demoHead('What just happened')}
+
+  - Every line above came from the real CLI - no canned output.
+  - The kickoff notes became dated decisions, risks, deliveries and a stakeholder
+    signal, and you confirmed before any of it was written.
+  - The <private> block in those notes never appears in resume, prep, receipts or
+    the dashboard - it is sealed in context.md and redacted from anything an agent
+    or a screen share can see.
+  - Tomorrow's session starts from the record instead of a blank chat.
+${fs.existsSync(html) ? `\n  Open the fieldbook:  ${html}` : ''}
+
+  ${demoHead('Your turn')}  (inside your own client's workspace)
+
+    fde resume --init <client-name>
+
+  Delete this demo whenever you like:  fde demo --clean
+`)
+}
+
 function printUsage() {
   console.log(`fde - deterministic core of fdeops
+  fde demo                 the whole loop on a fake client (fde demo --clean removes it)
   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)
@@ -2498,6 +2850,7 @@ function printUsage() {
 
 const [cmd, ...args] = process.argv.slice(2)
 switch (cmd) {
+  case 'demo': cmdDemo(args); break
   case 'scan': cmdScan(); break
   case 'resume': cmdResume(args); break
   case 'triage': cmdTriage(); break