create-pmos 0.45.0 → 0.47.0

package/payload/mods/pmos-cockpit/hooks/register.tsx

@@ -13,6 +13,11 @@ import { PROCESS_LIMIT_MS, isFresh, parseFactsOutput, sliceRows, summarize } fro
 import { clean, formatStatus } from './lib/status-line.mjs'
 import { SECTION_ID, buildSection } from './lib/prompt-section.mjs'
 import { PROBES, aheadProbe, interpretGit } from './lib/probes.mjs'
+import { describeMode, detectMode, slicePolicy } from './lib/mode.mjs'
+import { UNPUSHED_PROBES, cloudBandText, interpretUnpushed } from './lib/unpushed.mjs'
+import { HANDOVER_PROBES, buildPlan, countSince, interpretSince, notePaths, parseNote, planStillGood, renderNote, resumeText, sinceProbes, subjectsProbe } from './lib/handover.mjs'
+import { carryOut } from './lib/handover-run.mjs'
+import { REVIEWER_AGENT, REVIEWER_PROMPT, REVIEWER_TOOLS, REVIEWER_TYPE, buildReviewPrompt, offerText, parseVerdict, pickReviewerModel, planEval } from './lib/review.mjs'
 
 const status = atom({ plugin: 'pmos-cockpit', key: 'status' } as const, null)
 const isHidden = atom({ plugin: 'pmos-cockpit', key: 'isHidden' } as const, false)
@@ -22,6 +27,19 @@ const offer = atom({ plugin: 'pmos-cockpit', key: 'offer' } as const, null)
 // of the ladder. `factsCache` holds the last ladder read, for one initiative at one commit.
 const view = atom({ plugin: 'pmos-cockpit', key: 'view' } as const, null)
 const factsCache = atom({ plugin: 'pmos-cockpit', key: 'factsCache' } as const, null)
+// Where this session runs (M12). Read from two environment variables when the mod loads and kept here;
+// nothing a tool call does afterwards moves it. It changes what is drawn, never what is guarded.
+const modeAtom = atom({ plugin: 'pmos-cockpit', key: 'mode' } as const, null)
+// Continuity (M13). The plan `/pmos-handover` showed, waiting for a person's confirmation; it holds the
+// facts of the checkout it was made for. The resume summary read at session start, and whether the
+// person dismissed it. None of the three is ever given to the model.
+const handoverPlan = atom({ plugin: 'pmos-cockpit', key: 'handoverPlan' } as const, null)
+const resume = atom({ plugin: 'pmos-cockpit', key: 'resume' } as const, null)
+const resumeGone = atom({ plugin: 'pmos-cockpit', key: 'resumeGone' } as const, false)
+// The independent evaluator (M14). `review` is the one reviewer in flight; `reviewOffer` is its answer,
+// held until a person presses Record or types /pmos-record-review. Neither is ever written to a ledger.
+const review = atom({ plugin: 'pmos-cockpit', key: 'review' } as const, null)
+const reviewOffer = atom({ plugin: 'pmos-cockpit', key: 'reviewOffer' } as const, null)
 // The width the person's terminal draws the band at, seen at the last render. Lost on a reload, which
 // only returns the status line to its default width.
 let lastColumns = 0
@@ -52,6 +70,14 @@ async function gitFacts($: any, root: string) {
   return { branch, defaultBranch, commitsAhead }
 }
 
+// Read the two variables once per load. The names are literals, as the engine requires.
+async function readMode($: any): Promise<{ mode: string; signal: string | null }> {
+  const get = async (name: 'CLAUDE_CODE_REMOTE' | 'PMOS_WORKSPACE'): Promise<string | undefined> => {
+    try { return name === 'CLAUDE_CODE_REMOTE' ? await $.env.get('CLAUDE_CODE_REMOTE') : await $.env.get('PMOS_WORKSPACE') } catch { return undefined }
+  }
+  return detectMode({ remote: await get('CLAUDE_CODE_REMOTE'), workspace: await get('PMOS_WORKSPACE') })
+}
+
 const isPerson = (e: any): boolean => e?.origin?.kind === 'composer' || e?.origin?.kind === 'bridge'
 
 async function readText($: any, path: string): Promise<string | null> {
@@ -308,6 +334,142 @@ async function repair($: any): Promise<CockpitStatus> {
   return gather($, done, error)
 }
 
+// ── continuity (M13) ─────────────────────────────────────────────────────────────────────────────
+// What the checkout looks like to a handover: git, the initiative the branch names, and what is changed
+// or unpushed. Read-only; every process has the 5 second limit.
+async function readCheckout($: any, root: string, layout: any) {
+  const run = (argv: string[], limit = PROCESS_LIMIT_MS) => sh($, argv, { cwd: root, timeoutMs: limit })
+  const r: Record<string, any> = {}
+  for (const k of ['inside', 'branch', 'sha', 'dirs', 'defaultBranch'] as const) r[k] = await run(PROBES[k])
+  const g = interpretGit(r)
+  const idGuess = g.branch?.startsWith('initiative/') ? g.branch.slice('initiative/'.length) : null
+  const rp = idGuess ? recordPath(layout, idGuess) : null
+  const initiative = resolveInitiative({ branch: g.noGit ? null : g.branch, recordExists: rp ? await $.fs.exists(rp) : null, commitsAhead: null })
+  let porcelain = ''
+  let hasOrigin = false
+  let unpushed = { unpushed: false }
+  if (!g.noGit) {
+    const st = await run(HANDOVER_PROBES.status as string[])
+    porcelain = st.exitCode === 0 ? st.stdout : ''
+    hasOrigin = (await run(HANDOVER_PROBES.origin as string[])).exitCode === 0
+    const u: Record<string, any> = {}
+    for (const [k, argv] of Object.entries(UNPUSHED_PROBES)) u[k] = await run(argv as string[])
+    unpushed = interpretUnpushed(u)
+  }
+  return { run, g, initiative, porcelain, hasOrigin, unpushed }
+}
+
+// What the plan, and the confirmation that follows it, compare: the facts a plan was made for.
+const keyOf = (c: any, words: string) => ({ branch: c.g.branch, sha: c.g.sha, porcelain: c.porcelain, words })
+
+async function planHandover($: any, words: string): Promise<string> {
+  const { root, layout } = await rootAndLayout($)
+  const c = await readCheckout($, root, layout)
+  const p = buildPlan({ layout, root, initiative: c.initiative, git: c.g, porcelain: c.porcelain, hasOrigin: c.hasOrigin, unpushed: c.unpushed, words, nowMs: await $.clock.now() })
+  if (!p.ok) { await update($, handoverPlan, () => null); return p.text }
+  await update($, handoverPlan, () => p.plan)
+  return p.text
+}
+
+// Called only from a person's typed command or press. The plan must still match the checkout.
+async function confirmHandover($: any, push: boolean): Promise<string> {
+  const plan: any = await read($, handoverPlan)
+  const { root, layout } = await rootAndLayout($)
+  const c = await readCheckout($, root, layout)
+  const now: number = await $.clock.now()
+  const good = planStillGood(plan, plan ? keyOf(c, plan.words) : { branch: null, sha: null, porcelain: '', words: '' }, now)
+  if (!good.ok) {
+    await update($, handoverPlan, () => null)
+    return `Nothing was written. ${good.why}${plan ? ' Run /pmos-handover again to see a new plan.' : ''}`
+  }
+  // the note's facts, read fresh: the ladder for this initiative, and how far the branch is from the default
+  await refreshView($, true)
+  const v: any = await read($, view)
+  const def: string = c.g.defaultBranch ?? 'main'
+  const ahead = await c.run(['git', 'rev-list', '--count', `${def}..HEAD`])
+  const subj = await c.run(subjectsProbe(def) as string[])
+  const noteText = renderNote({
+    id: plan.id, branch: plan.branch, sha: c.g.sha, summary: v?.initiative?.id === plan.id ? v.summary : null,
+    commits: ahead.exitCode === 0 && /^\d{1,9}$/.test(out(ahead)) ? Number(out(ahead)) : 0, defaultBranch: def,
+    subjects: subj.exitCode === 0 ? out(subj).split('\n').filter(Boolean) : [], paths: plan.paths, words: plan.words, atIso: new Date(now).toISOString(),
+  })
+  // a note path that is a link, or that sits behind one, is never written through
+  const rootReal = (await $.fs.stat(root, { resolve: true }).catch(() => undefined))?.realPath ?? root
+  const noteDir = plan.noteRel.split('/').slice(0, -1).join('/')
+  const write = async (path: string, text: string) => {
+    for (const [p, expect] of [[path, `${rootReal}/${plan.noteRel}`], [`${root}/${noteDir}`, `${rootReal}/${noteDir}`]] as const) {
+      const st = await $.fs.stat(p, { resolve: true }).catch(() => undefined)
+      if (st && (st.isLink || (st.realPath && st.realPath !== expect))) throw new Error(`${p} is, or sits behind, a link`)
+    }
+    await $.fs.write(path, text)
+  }
+  const r = await carryOut({ plan, push, noteText, run: c.run, write })
+  await update($, handoverPlan, () => null)
+  await update($, resume, () => null)
+  await refreshView($, true)
+  return r.text
+}
+
+async function pressHandover($: any, push: boolean) {
+  try { $.ui.toast(`pmos-cockpit: ${await confirmHandover($, push)}`) } catch (e: any) { $.ui.toast(`pmos-cockpit: the handover did not run. ${String(e?.message ?? e)}`) }
+}
+
+// At session start: the newest note for this branch's initiative, and how far the branch has moved.
+async function loadResume($: any): Promise<void> {
+  try {
+    const { root, layout } = await rootAndLayout($)
+    const v: any = await read($, view)
+    const id: string | null = v?.initiative?.state === 'ok' ? v.initiative.id : null
+    const np = id === null ? null : notePaths(layout, root, id)
+    const text = np === null ? null : await readText($, np.abs)
+    const note = text === null ? null : parseNote(text)
+    if (id === null || np === null || note === null || note.id !== id || note.headSha === null) { await update($, resume, () => null); return }
+    const run = (argv: string[]) => sh($, argv, { cwd: root, timeoutMs: PROCESS_LIMIT_MS })
+    const pr = sinceProbes(note, np.rel) as any
+    const r: Record<string, any> = { ancestor: await run(pr.ancestor) }
+    if (r.ancestor.exitCode === 0) {
+      r.handoverCommit = await run(pr.handoverCommit)
+      const h = out(r.handoverCommit)
+      r.count = await run(countSince(/^[0-9a-f]{40,64}$/.test(h) ? h : note.headSha) as string[])
+    }
+    const line = resumeText(note, id, interpretSince(r))
+    await update($, resume, () => (line === null ? null : { text: line }))
+  } catch {
+    await update($, resume, () => null)
+  }
+}
+
+// Recording a reviewer's verdict: called only from a person's press or typed command. The offer is
+// cleared before the writer runs, so a second press records nothing.
+async function recordReview($: any): Promise<{ ok: boolean; text: string }> {
+  const o: any = await read($, reviewOffer)
+  if (!o) return { ok: false, text: 'There is no reviewer verdict waiting to be recorded.' }
+  await update($, reviewOffer, () => null)
+  const { root, layout } = await rootAndLayout($)
+  const plan = planEval({ layout, root, review: o, atIso: new Date(await $.clock.now()).toISOString() })
+  if (!plan.ok) return { ok: false, text: plan.reason }
+  const r = await sh($, plan.argv, { cwd: root, env: plan.env, timeoutMs: PROCESS_LIMIT_MS })
+  if (r.exitCode !== 0) return { ok: false, text: `Not recorded. ${(r.stderr || out(r)).trim()}` }
+  return { ok: true, text: `Recorded ${o.verdict} ${o.score} for ${o.run_id}, evaluator ${o.evaluator_model}.${plan.storesFindings ? '' : ' The findings are not stored in a kit: copy them from above if you want them kept.'}` }
+}
+
+// The reviewer's answer: parsed, shown, and held. This writes nothing.
+async function takeReviewerAnswer($: any, e: any): Promise<void> {
+  try {
+    const pending: any = await read($, review)
+    if (!pending || e.agentId !== pending.agentId) return
+    await update($, review, () => null)
+    const v = parseVerdict(e.answer)
+    if (v.ok) {
+      const o = { run_id: pending.run_id, initiative_id: pending.initiative_id, rubric_path: pending.rubric_path, verdict: v.verdict, score: v.score, evaluator_model: pending.model, findings: v.findings }
+      await update($, reviewOffer, () => o)
+      $.ui.toast(`pmos-cockpit: ${offerText(o)} Press Record above the prompt, or type /pmos-record-review.`)
+    } else {
+      $.ui.toast(`pmos-cockpit: the reviewer's answer had no verdict, so nothing is offered. ${v.reason}.`)
+    }
+  } catch { /* bookkeeping for a convenience: never reaches the turn */ }
+}
+
 const baseName = (p: string): string => p.split('/').filter(Boolean).pop() ?? p
 
 // The session view (M11): one read of the checkout and, at most once a minute for each commit, one read
@@ -363,6 +525,14 @@ async function refreshView($: any, force = false): Promise<void> {
       links = { record: rp ? clean(rp.replace(`${root}/`, ''), 80) : null, prd: field('prd_path'), rubric: field('rubric_path') }
     }
 
+    // cloud only: what would be lost with the session. Read-only git; the band says it, a person acts.
+    let cloud: string | null = null
+    if (((await read($, modeAtom)) as any)?.mode === 'cloud' && !g.noGit) {
+      const u: Record<string, any> = {}
+      for (const [k, argv] of Object.entries(UNPUSHED_PROBES)) u[k] = await run(argv as string[])
+      cloud = cloudBandText(interpretUnpushed(u), g.branch)
+    }
+
     const text = formatStatus({
       repo: baseName(root),
       worktree: g.linked ? baseName(root) : null,
@@ -374,7 +544,7 @@ async function refreshView($: any, force = false): Promise<void> {
     })
     $.ui.status(text)
     const stateRel = layout.stateRoot ? layout.stateRoot.replace(`${root}/`, '') : null
-    await update($, view, () => ({ text, initiative, summary, unavailable, links, sha: g.sha, at: started, stateRel, noGit: g.noGit }))
+    await update($, view, () => ({ text, initiative, summary, unavailable, links, sha: g.sha, at: started, stateRel, noGit: g.noGit, cloud }))
   } catch {
     /* the view is a convenience: on any failure the last view stays, and the turn is not told */
   }
@@ -415,10 +585,20 @@ export const register: Register = (on) => {
     await $.command.register({ name: 'pmos-repair-skills', description: 'Link the kit skills that are not registered in .claude/skills' })
     await $.command.register({ name: 'pmos-grant', description: 'Mint one single-use grant: /pmos-grant merge:<PR> | publish:<artifact> [minutes] [your words]' })
     await $.command.register({ name: 'pmos-slice', description: 'Open the initiative slice: the ladder, step by step, for the branch you are on' })
+    await $.command.register({ name: 'pmos-handover', description: 'Hand the branch over: /pmos-handover [your words] shows a plan; /pmos-handover confirm [local] commits and pushes it' })
     await $.command.register({ name: 'pmos-accept', description: 'Record your Acceptance of a run: /pmos-accept <run_id> pass|fail <note>' })
+    await $.command.register({ name: 'pmos-review', description: 'Ask a read-only reviewer on another model to judge the newest run: /pmos-review [model]' })
+    await $.command.register({ name: 'pmos-record-review', description: 'Record the reviewer verdict that is waiting (the same as pressing Record)' })
+    try {
+      await $.agent.register({ name: REVIEWER_AGENT, description: 'Independent read-only reviewer started by /pmos-review. Not for the builder to call.', prompt: REVIEWER_PROMPT, tools: [...REVIEWER_TOOLS] })
+    } catch { /* the review command says so when it cannot start the reviewer */ }
+    const m = await readMode($)
+    await update($, modeAtom, () => m)
     const s = await gather($)
     await update($, status, () => s)
     await refreshView($)
+    await update($, resumeGone, () => false)
+    await loadResume($)
     if (s.skills && s.skills.missing.length > 0) {
       $.ui.toast(`PMOS: ${s.skills.missing.length} kit skill(s) are not registered. Run /pmos-repair-skills.`)
     }
@@ -431,16 +611,24 @@ export const register: Register = (on) => {
     await refreshView($, true)
     const v: any = await read($, view)
     const lines = [summary(s)]
+    const m: any = await read($, modeAtom)
+    if (m) lines.push(describeMode(m))
+    const rs: any = await read($, resume)
+    if (rs?.text) lines.push(`resume   ${String(rs.text).replace(/^PMOS: /, '')}`)
+    try { lines.push(`surfaces ${(await $.session.surfaces()).join(', ') || 'none reported'}`) } catch { lines.push('surfaces unavailable') }
     if (v?.summary) lines.push(`stage    ${v.summary.stage}${v.summary.next ? ` (next: ${v.summary.next.key})` : ''}${v.summary.gateFailures.length ? `; blocking: ${v.summary.gateFailures.join(', ')}` : ''}`)
     else if (v?.unavailable) lines.push(`stage    unavailable: ${v.unavailable}`)
     return { text: lines.join('\n') }
   })
 
-  // The slice opens only when asked. Nothing in this module opens it unasked (modes, M12, come later).
+  // The slice opens only when asked, and not at all when the workspace already shows it (hosted).
   on('command.run', { command: 'pmos-slice' }, async ($) => {
+    const m: any = await read($, modeAtom)
+    const policy = slicePolicy(m?.mode ?? 'local')
+    if (!policy.opens) return { text: policy.text }
     await refreshView($)
     await $.ui.open({ id: 'pmos-slice', title: 'PMOS initiative' })
-    return { text: 'Opened the initiative slice. Esc closes it.' }
+    return { text: policy.text }
   })
 
   on('ui.render', { component: 'Pane', requestId: 'pmos-slice' }, async ($, e) => {
@@ -479,6 +667,7 @@ export const register: Register = (on) => {
 
   // The status line follows the branch: refreshed at the end of each turn, never per tool call.
   on('turn.complete', async ($, e, next) => {
+    await takeReviewerAnswer($, e)
     await refreshView($)
     return next(e)
   })
@@ -540,6 +729,43 @@ export const register: Register = (on) => {
     return v
   })
 
+  // ── the independent evaluator (M14) ─────────────────────────────────────────────────────────
+  // The builder's model never sees the reviewer in its list of agents: only the person starts it.
+  on('agent.offer', { agent: REVIEWER_TYPE }, () => ({ isOffered: false }))
+
+  on('command.run', { command: 'pmos-review' }, async ($, e) => {
+    if (!isPerson(e)) return { text: 'A review is started only by your own typed command. This run did not come from you, so nothing was started.' }
+    if (await read($, review)) return { text: 'A review is already running. Its verdict will appear above the prompt.' }
+    try {
+      const { root, layout } = await rootAndLayout($)
+      if (layout.kind === 'none') return { text: 'No review started. There is no PMOS state here.' }
+      const facts = await gitFacts($, root)
+      const id = facts.branch?.startsWith('initiative/') ? facts.branch.slice('initiative/'.length) : null
+      if (id === null) return { text: 'No review started. The branch names no initiative.' }
+      const run = (await runsOf($, layout)).filter((r) => r.initiative_id === id).pop()
+      if (!run) return { text: `No review started. Initiative ${id} has no run in ${layout.stateRoot ?? 'the state root'}.` }
+      const rp = recordPath(layout, id)
+      const rec = rp ? await readText($, rp) : null
+      const m = rec === null ? null : /^rubric_path:[ \t]*(\S[^\n]*)$/m.exec(rec)
+      const rubricPath = m ? m[1].replace(/^["']|["']$/g, '').trim() : ''
+      const model = pickReviewerModel(await $.session.model(), String(e.args ?? '').trim())
+      if (!model.ok) return { text: `No review started. ${model.reason}` }
+      const prompt = buildReviewPrompt({ initiativeId: id, runId: run.run_id, rubricPath })
+      if (!prompt.ok) return { text: `No review started. ${prompt.reason}.` }
+      const sp: any = await $.agent.spawn({ subagentType: REVIEWER_TYPE, prompt: prompt.text, description: `review ${run.run_id}`, model: model.model })
+      if (sp?.deny || typeof sp?.agentId !== 'string') return { text: `No review started. ${sp?.deny ?? 'the reviewer could not be started.'}` }
+      await update($, review, () => ({ agentId: sp.agentId, run_id: run.run_id, initiative_id: id, rubric_path: rubricPath, model: model.model }))
+      return { text: `Started a read-only reviewer on ${model.model} (builder family ${model.builderFamily}) for run ${run.run_id}. Its verdict will appear above the prompt, and nothing is recorded until you press Record.` }
+    } catch (err: any) {
+      return { text: `No review started. ${String(err?.message ?? err).slice(0, 200)}` }
+    }
+  })
+
+  on('command.run', { command: 'pmos-record-review' }, async ($, e) => {
+    if (!isPerson(e)) return { text: 'A verdict is recorded only by your own typed command or press. This run did not come from you, so nothing was written.' }
+    return { text: (await recordReview($)).text }
+  })
+
   // ── commands that are a person's act ────────────────────────────────────────────────────────
   on('command.run', { command: 'pmos-grant' }, async ($, e) => {
     if (!isPerson(e)) return { text: 'A grant is minted only by your own typed command or press. This run did not come from you, so nothing was written.' }
@@ -550,6 +776,18 @@ export const register: Register = (on) => {
     return { text: r.exitCode === 0 ? `Granted ${plan.scope.kind}:${plan.scope.target}, single use, ${plan.ttl} minutes. ${out(r).split('\n').pop()}` : `No grant written. ${(r.stderr || out(r)).trim()}` }
   })
 
+  // A handover is a person's act: a plan first, and only a typed confirm or a press carries it out.
+  on('command.run', { command: 'pmos-handover' }, async ($, e) => {
+    if (!isPerson(e)) return { text: 'A handover commits and pushes only on your own typed command or press. This run did not come from you, so nothing was done.' }
+    const args = String(e.args ?? '').trim()
+    const m = /^confirm(?:[ \t]+(local))?$/.exec(args)
+    try {
+      return { text: m ? await confirmHandover($, m[1] !== 'local') : await planHandover($, args) }
+    } catch (err: any) {
+      return { text: `Nothing was done. The handover could not run: ${String(err?.message ?? err)}` }
+    }
+  })
+
   on('command.run', { command: 'pmos-accept' }, async ($, e) => {
     if (!isPerson(e)) return { text: 'An acceptance is recorded only by your own typed command or press. This run did not come from you, so nothing was written.' }
     const a = parseAccept(e.args)
@@ -584,6 +822,29 @@ export const register: Register = (on) => {
         </Box>
       )
     }
+    const hp: any = await read($, handoverPlan)
+    if (hp && !e.props.hasSurvey) {
+      const { Box, Button, Text } = $.ui.resolve(e)
+      return (
+        <Box>
+          <Text>PMOS: handover plan for {hp.id}, {hp.paths.length} path(s){hp.push.run ? `, then ${hp.push.text}` : ', no push'}. </Text>
+          {hp.push.run && <Button key="go" label="Commit and push" variant="primary" onPress={() => pressHandover($, true)} />}
+          <Button key="local" label="Commit only" onPress={() => pressHandover($, false)} />
+          <Button key="cancel" label="Cancel" onPress={() => update($, handoverPlan, () => null)} />
+        </Box>
+      )
+    }
+    const rv: any = await read($, reviewOffer)
+    if (rv && !e.props.hasSurvey) {
+      const { Box, Button, Text } = $.ui.resolve(e)
+      return (
+        <Box>
+          <Text>PMOS: {offerText(rv)} </Text>
+          <Button key="record" label="Record" variant="primary" onPress={async () => { const r = await recordReview($); $.ui.toast(`pmos-cockpit: ${r.text}`) }} />
+          <Button key="later" label="Not now" onPress={() => update($, reviewOffer, () => null)} />
+        </Box>
+      )
+    }
     if (e.props.hasSurvey || (await read($, isHidden))) return next(e)
     // one line, only when something blocks, in this order: skill drift, a blocking ladder step, a branch
     // with commits and no initiative record. The text comes from checked fields, never from a record.
@@ -608,6 +869,25 @@ export const register: Register = (on) => {
         </Box>
       )
     }
+    if (!hasDrift(s) && v?.cloud) {
+      const { Box, Button, Text } = $.ui.resolve(e)
+      return (
+        <Box>
+          <Text>{clean(v.cloud, 300)} </Text>
+          <Button key="hide" label="Hide" onPress={() => update($, isHidden, () => true)} />
+        </Box>
+      )
+    }
+    const rs: any = await read($, resume)
+    if (!hasDrift(s) && rs?.text && !(await read($, resumeGone))) {
+      const { Box, Button, Text } = $.ui.resolve(e)
+      return (
+        <Box>
+          <Text>{clean(rs.text, 400)} </Text>
+          <Button key="dismiss" label="Dismiss" onPress={() => update($, resumeGone, () => true)} />
+        </Box>
+      )
+    }
     if (!hasDrift(s)) return next(e)
     const { Box, Button, Text } = $.ui.resolve(e)
     const k = s!.skills!

package/payload/mods/pmos-cockpit/types/index.d.ts

@@ -49,12 +49,28 @@ export type ViewState = {
   at: number
   stateRel: string | null
   noGit: boolean
+  cloud: string | null
 }
 
 export type FactsCache = { id: string | null; sha: string; at: number; summary: NonNullable<ViewState['summary']> }
 
+export type HandoverPlan = {
+  id: string
+  branch: string
+  noteRel: string
+  noteAbs: string
+  paths: string[]
+  addPaths: string[]
+  push: { run: boolean; argv: string[] | null; text: string }
+  message: string
+  words: string
+  key: string
+  at: number
+  sha: string | null
+}
+
 declare module 'claude-code' {
   interface PluginState {
-    'pmos-cockpit': { status: CockpitStatus | null; isHidden: boolean; offer: { run_id: string; initiative_id: string; message: string } | null; view: ViewState | null; factsCache: FactsCache | null }
+    'pmos-cockpit': { status: CockpitStatus | null; isHidden: boolean; offer: { run_id: string; initiative_id: string; message: string } | null; view: ViewState | null; factsCache: FactsCache | null; mode: { mode: 'local' | 'hosted' | 'cloud'; signal: string | null } | null; review: { agentId: string; run_id: string; initiative_id: string; rubric_path: string; model: string } | null; reviewOffer: { run_id: string; initiative_id: string; rubric_path: string; verdict: string; score: number; evaluator_model: string; findings: string } | null; handoverPlan: HandoverPlan | null; resume: { text: string } | null; resumeGone: boolean }
   }
 }

package/payload/okf/core/concepts/frontmatter-format.md

@@ -46,9 +46,10 @@ OKF's reserved filenames carry **no** frontmatter and are skipped by both the mi
 The enforced list lives in [`scripts/frontmatter_registry.txt`](/scripts/frontmatter_registry.txt) — the single source `frontmatter_lint.py` reads. A `type:` value not in it fails CI (this catches typos).
 
 - **OKF core:** `Concept`, `ADR`, `Template`, `Playbook`, `Reference`
-- **Planning:** `Initiative`, `PRD`, `Story`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`
+- **Planning:** `Initiative`, `PRD`, `Story`, `Rubric`, `OKR`, `Radar`, `Checklist`, `Calibration`, `Research`, `Design`, `Prototype`, `Handover`
   - `Initiative` is the repo-native initiative record in [`planning/initiatives/`](/planning/initiatives/), read by the [Initiative Gate](/.github/scripts/initiative-gate.sh). Its D56 **work-type lane** rides a separate `lane:` key — not `type:` — so the lane vocabulary and this registry never collide.
   - `Story` is a **user-story document** — the decomposition of a spec into the units of work handed to whoever builds them. It is the one type in this registry that is also **checked positionally** (see below), and it may carry an optional `jira:` / `confluence:` / `google_doc:` key naming the tracker record it corresponds to. That key is a *declaration* the workspace displays, never a lookup: PMOS holds no credential and makes no outbound request.
+  - `Handover` is the note the cockpit mod's `/pmos-handover` writes (`planning/handovers/<id>.md`, or `pmos/state/handovers/<id>.md` in a kit): one per initiative, replaced on each handover, with checked fields (`id`, `head_sha`, `branch`, `stage`, `next`, `commits`, `files`, `handover_at`) read back by the resume summary ([D81](/okf/products/pmos/adr/d81-cockpit-mod-and-grants.md)).
 - **Root governance:** `Decision`, `Principle`, `Debt`, `Discovery`, `Guide`
 
 ### When the path decides the type
@@ -72,6 +73,10 @@ Add **one line** to `scripts/frontmatter_registry.txt` and a matching row above.
 - [`scripts/frontmatter_lint.py`](/scripts/frontmatter_lint.py) — deterministic, no secrets; asserts the three required keys (and `type` ∈ registry) on every non-reserved tracked `.md`. Run in `.github/workflows/frontmatter-ci.yml`.
 - [`scripts/backfill_frontmatter.py`](/scripts/backfill_frontmatter.py) — the one-time migration: prepend-only, idempotent; reuses a file's already-declared `type`/`date` when present, else infers from path (`type`), the first H1 (`title`), and the last git-commit date (`timestamp`).
 
+## Typed relation keys (opt-in)
+
+A document may carry `supersedes`, `amended_by`, `cites` and `initiative` as one-line lists of paths to `.md` files. The knowledge graph (`pmos kg`) reads them as stated edges of that type. The keys are optional and are not backfilled. See [the knowledge-graph guide](/workspace/guide/knowledge-graph.md).
+
 ## Tenant repositories follow OKF v0.2 (D73)
 
 Since [D74](/okf/products/pmos/adr/d74-pmos-self-drops-timestamp.md) PMOS's own repository follows OKF v0.2 too: the Frontmatter Gate requires `type` and `title`, `timestamp` is optional and still checked when present, and `generated`, `sources`, `status`, `verified` and `stale_after` are accepted. Nothing was backfilled. The documents PMOS and its agents write into a **tenant** repository, such as a PM's, follow [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) instead: `type`, `title` and `description`, then `generated: {by, at}` in place of `timestamp`, `sources` in place of a body `# Citations` list, and `status` (`draft | stable | deprecated`), `verified` and `stale_after` as they apply. Every key sits on **one line**, because five of PMOS's frontmatter readers stop at the first indented line. Actors are `claude-code/<skill>` for an agent run, `human:<id>` for a person and `process:<name>` for a tool.

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-04T09:05:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T10:38:12Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-04T09:05:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T10:38:12Z"}
 status: stable
 ---
 

package/payload/skills/SKILL-FORMAT.md

@@ -1,6 +1,7 @@
 ---
 type: Reference
 title: "SKILL-FORMAT.md — Required Format for PMOS Skills"
+description: "The required structure of every .skill file in PMOS, and why it keeps skills cheap to keep available and expensive to load only when used."
 timestamp: 2026-07-23
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-04T09:05:06Z"}
+generated: {by: process:create-pmos, at: "2026-10-04T10:38:12Z"}
 status: stable
 ---
 

package/workspace/README.md

@@ -76,7 +76,7 @@ After the session ends, `GET /api/next-step/summary` returns the files the branc
 
 ## Today: what is waiting for you (`proactive-engine`, slice D1)
 
-`lib/proactive.js` is a pure core: it reads the records the workspace already derives and finds five conditions: a need waiting on the PM, an initiative returned at acceptance, an ended next-step session with no review, a scheduled task whose last run failed, and an active initiative with no agent run for the stalled threshold (5 days by default). The ranking is fixed and stated in the guide. `GET /api/proactive/today` computes the list on each request. A scan (`POST /api/proactive/scan`, and a 10-minute automatic tick inside the existing 60-second interval) appends new items once a day to `signals.jsonl`. Feedback (`useful`, `not-useful`, `wrong-priority`, `missed` with a note, and the events `opened`, `dismissed`) is appended to `proactive-feedback.jsonl`; a dismissed item is hidden for 7 days. Settings are in `proactive-settings.json` (engine on or off, one trigger off, the stalled threshold, quiet hours, pause learning; the last has no effect yet because nothing learns from the verdicts in this slice). The same actions are in `pmos proactive today|scan|settings|feedback` (`lib/proactive-cli.js`), a thin client of those routes. The list is drawn in the navigation column by the `today` drawer item. It runs only while the server runs, reads no mail or calendar, and starts no session, sends nothing and changes no record of an initiative (`proactive.test.js` E25-E26 read the source for that). Tests: `proactive.test.js` (pure core, routes, CLI) and `pm-r22-test.js` (the page). The guide page is `guide/proactive-engine.md`.
+`lib/proactive.js` is a pure core: it reads the records the workspace already derives and finds five conditions: a need waiting on the PM, an initiative returned at acceptance, an ended next-step session with no review, a scheduled task whose last run failed, and an active initiative with no agent run for the stalled threshold (5 days by default). The ranking is fixed and stated in the guide. `GET /api/proactive/today` computes the list on each request. A scan (`POST /api/proactive/scan`, and a 10-minute automatic tick inside the existing 60-second interval) appends new items once a day to `signals.jsonl`. Feedback (`useful`, `not-useful`, `wrong-priority`, `missed` with a note, and the events `opened`, `dismissed`) is appended to `proactive-feedback.jsonl`; a dismissed item is hidden for 7 days. Settings are in `proactive-settings.json` (engine on or off, one trigger off, the stalled threshold, quiet hours, pause learning). The same actions are in `pmos proactive today|scan|settings|feedback` (`lib/proactive-cli.js`), a thin client of those routes. The list is drawn in the navigation column by the `today` drawer item. It runs only while the server runs, reads no mail or calendar, and starts no session, sends nothing and changes no record of an initiative (`proactive.test.js` E25-E26 read the source for that). Tests: `proactive.test.js` (pure core, routes, CLI) and `pm-r22-test.js` (the page). The guide page is `guide/proactive-engine.md`. **Learning (D4).** `lib/learn.js` is a second pure core. It joins the PM's verdicts, events and step reviews to items through the candidate id in `signals.jsonl` (which now records the initiative's lane), moves three bounded weights (per trigger, per lane, per trigger and time of day; caps 8, 4, 3 and 15 in all, no cell before 5 events) that `rank` adds to the fixed score, reports a 7-day rollup with every count and a watermelon check, leaves a trigger off Today when it was rated useful under 30% of the time over 10 or more ratings in 28 days, and proposes lessons from four templates. A lesson is approved, rejected or retired only by the PM's press; an approved lesson is read by the morning-brief session through `pmos proactive learn lessons` and goes into no other prompt, so the C1 prompt and plan hash are unchanged. The weekly review runs from the existing 10-minute proactive tick and does not catch up. needs and returned are never lowered or narrowed. Pause learning gives zero weights and no review. Ledgers: `learn-events.jsonl`, `lessons.jsonl`, `proactive-rollups.jsonl`. Routes `GET /api/proactive/learn` and `POST /api/proactive/learn/{run,lesson,restore,reset}`; commands `pmos proactive learn …`. Tests: `learn.test.js` and `pm-r26-test.js`.
 
 ## The morning brief (`proactive-engine`, slice D2)
 

package/workspace/guide/initiatives-and-next-steps.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: initiatives and next steps"
+description: "What the initiative detail shows, top to bottom: status, lifecycle control, and the next step the workspace proposes."
 timestamp: 2026-10-03
 ---
 

package/workspace/guide/knowledge-graph.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: find knowledge without reading whole files"
+description: "How to use pmos kg to find one card, section or decision without reading whole files, and the limits of the map."
 timestamp: 2026-10-03
 ---
 
@@ -18,7 +19,7 @@ The map has an **edge** only where a file states a relation:
 |---|---|
 | link | A Markdown link to a tracked file. |
 | frontmatter | A path in `prd_path`, `rubric_path`, `explainer_path` or `sources`. |
-| supersedes, amended_by, cites | A document that chooses to carry one of these keys. |
+| supersedes, amended_by, cites, initiative | A document that chooses to carry one of these keys. |
 | initiative | An `initiative_id` that names an initiative record. |
 | anchor | A `parent_kr` of `health:<id>` or a KR id. |
 | cites (mention) | A `D<nn>` in the text, such as `D65`, with two or more digits. |
@@ -27,6 +28,10 @@ A link that points at a missing file is **dangling**. It is listed and never bec
 
 It does not guess. A file that talks about a topic without a link, a path or a `D<nn>` is not connected to it. It does not use embeddings or a model, and it does not use the network.
 
+## Typed keys
+
+A document may carry `supersedes`, `amended_by`, `cites` and `initiative` in its frontmatter. Each key is one line and holds one or more paths to `.md` files, separated by commas. The map reads each path as a stated edge of that type. A path to a file that does not exist is listed as dangling and never becomes an edge. Nobody fills these keys in for existing documents; add them to new or edited ones. `pmos kg stats` shows how many edges are typed and how many are inferred from a `D<nn>` in the text.
+
 ## Commands
 
 | Command | What it does |

package/workspace/guide/layout.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: layout"
+description: "The three workspace columns: navigation, detail and tabs, and what each one holds."
 timestamp: 2026-10-03
 ---
 

package/workspace/guide/proactive-engine.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: Today and the proactive engine"
+description: "What the Today item shows, how the morning brief is made, and how the workspace works out what is waiting for you."
 timestamp: 2026-10-03
 ---
 
@@ -39,6 +40,22 @@ From a Today item that names an initiative, you can ask for the plan and approve
 
 The states of an entry are queued, started, skipped, expired and cancelled.
 
+## What it learns
+
+Today learns from you, and only from you. The evidence is your own records on this computer: the verdict you give an item, what you do with it (opened, acted, dismissed, ignored), and your accept or send-back on a prepared session. The workspace makes no model call to do this. The weights are arithmetic, and the lessons are written from fixed templates filled with counts.
+
+- **Weights.** Three adjustments are added to an item's place in the order: one for its trigger (at most 8 points), one for its lane (at most 4) and one for its trigger at this time of day (at most 3). Time of day is morning 05-12, afternoon 12-17, evening 17-22 and night, in your local time. A cell moves only after 5 events, and moves less than the raw average. The total is at most 15, so learning reorders items that are close and cannot turn the stated order upside down. An item shows its adjustment and the counts behind it.
+- **What it never does.** It never lowers or hides what blocks on you: the needs and returned triggers get no negative adjustment and are never narrowed. Items of the morning brief teach no weight, because their order is fixed. Pause learning makes every weight zero and stops the weekly review, the proposals and the narrowing; feedback is still recorded.
+- **The weekly review.** About every 7 days, only while the workspace server runs, the workspace takes one snapshot. It does not catch up after a gap: it takes one snapshot of the last 7 days. **run the weekly review now** does the same on demand and is refused while learning is paused. Quiet hours hold scans, not this review.
+- **The rollup.** For the last 7 days: the hit rate (useful and acted, over useful, acted, not useful, wrong priority and dismissed), the used-as-is rate (accepted over accepted and sent back), corrections per prepared run (sends-back over every session started from a step, reviewed or not), and the items you reported as missed. Every rate shows its count. With fewer than 5 rated items, or 3 runs, it says there is not enough evidence and shows no rate.
+- **The watermelon check.** It looks only when the hit rate is 0.6 or more. It then names any of these: 2 or more items reported as missed, a used-as-is rate under 0.5 over 3 or more reviewed runs, or 0.5 or more corrections per prepared run over 3 or more runs. A good hit rate with one of these under it is not a good week.
+- **Lessons.** The review proposes lessons from four templates: a trigger that was useful under 40% or at least 80% of the time (5 or more ratings), items you reported as missed (2 or more), and a trigger that did badly in one part of the day only. A lesson is a proposal. It is approved, rejected or retired only when you press the button. A rejected lesson is not proposed again for 28 days. At most 10 lessons are approved at once.
+- **Where an approved lesson goes.** Into the state folder, and from there to the morning-brief session, which reads it with `pmos proactive learn lessons`. It goes into no other prompt, so the prompt and the plan hash of a prepared step do not change, and no file of any repository is written. To keep a lesson in repository memory, copy it there yourself.
+- **Narrowing.** A trigger other than needs and returned that you rated useful under 30% of the time over 10 or more ratings in 28 days is left off Today. Today says so, with the numbers and a **restore** button. The trigger is still scanned. A restore holds until 10 new ratings of that trigger have arrived.
+- **forget what it learned** makes the workspace ignore all earlier feedback from then on. Nothing is deleted.
+
+The records are `learn-events.jsonl` (restore and reset), `lessons.jsonl` and `proactive-rollups.jsonl`, in the workspace state folder. They are not committed.
+
 ## What it shows
 
 Today scans for five conditions. Each one becomes one item with the reason and the evidence.
@@ -60,7 +77,7 @@ The order is fixed and you can read it: what blocks on you first, then an unrevi
 - dismiss 7 days hides the item for 7 days.
 - something was missed records a note about what Today should have shown. It needs a note.
 
-A verdict never changes a status, a lifecycle record or an acceptance. In this release a verdict is only recorded. Nothing uses it to change the order yet.
+A verdict never changes a status, a lifecycle record or an acceptance. It is recorded, and it is evidence for what Today learns, as described above.
 
 ## Settings
 
@@ -74,7 +91,7 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 | name | Used in the greeting. |
 | stalled after N days | The stalled threshold, from 1 to 90 days. |
 | quiet hours | A start and an end time. No automatic scan runs between them. |
-| pause learning | Saved for later. Nothing learns from your verdicts in this release, so it changes nothing today. |
+| pause learning | Stops all learning: weights are zero, and there is no weekly review, no proposal and no narrowing. Feedback is still recorded. |
 
 ## The commands
 
@@ -83,12 +100,13 @@ A verdict never changes a status, a lifecycle record or an acceptance. In this r
 - `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--background-prepare on|off`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
 - `pmos proactive brief` shows today's brief. `pmos proactive brief submit --file PATH` submits one. `pmos proactive brief schedule` makes the 06:45 schedule for the current repository.
 - `pmos proactive prepare` shows the queue. `pmos proactive prepare plan --initiative ID` shows a plan and its hash. `pmos proactive prepare queue --initiative ID --item ITEM --sha HASH` approves it. `pmos proactive prepare cancel ID` cancels an entry. `pmos proactive prepare run` looks at the queue now.
+- `pmos proactive learn` shows the rollup, the weights, the narrowed triggers and the lessons. `pmos proactive learn run` takes the weekly review now. `pmos proactive learn lessons` lists the approved lessons. `pmos proactive learn approve ID`, `reject ID` and `retire ID` decide a lesson. `pmos proactive learn restore TRIGGER` brings back a narrowed trigger. `pmos proactive learn reset` makes it ignore earlier feedback.
 - `pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed` records feedback. Use `--missed "text"` for a missed item.
 
 ## Limits
 
 - It runs only while the workspace server runs. It does not catch up for time the server was off. A sleeping computer gets no scan.
 - The items from the records come from this computer. The workspace itself does not read your mail or your calendar. Only the morning-brief session does, and only the sources you switched on.
-- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
+- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback, and learns from it as described above. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
 - An unreadable repository is listed as not read. An empty list is not proof that nothing waits there.
 - The records stay in the workspace state folder on this computer. They are not committed.

package/workspace/guide/scheduled-tasks-and-cli.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: scheduled tasks and the command line"
+description: "How scheduled tasks run a skill in a terminal session, their limits, and the command line that manages them."
 timestamp: 2026-10-03
 ---
 

package/workspace/guide/statuses.md

@@ -1,6 +1,7 @@
 ---
 type: Guide
 title: "Guide: statuses"
+description: "The nine initiative statuses, who acts on each, and why a status is worked out again each time and never typed."
 timestamp: 2026-10-03
 ---