kimal3 0.6.5 → 0.8.0

package/README.md

@@ -42,8 +42,11 @@ kimal3 kontext fragen     Die Fragen über deine Firma beantworten — Claude f
 kimal3 kontext hoch       Deine lokalen Änderungen an den fünf Firmen-Texten hochschicken
 kimal3 projekt neu …      Ein Projekt ins Erfolgsprofil eintragen
 kimal3 projekt liste      Deine eingetragenen Projekte anzeigen
-kimal3 plan               Planung hochladen oder Rückmeldungen holen
-kimal3 plan hoch          Die Planung aus plan/stand.json hochschicken (--probe: nur prüfen)
+kimal3 plan               Den Stand der Planung holen und Änderungen melden
+kimal3 plan melde         Eine Änderung an die Projektseite melden (Meldung als JSON von der Eingabe)
+kimal3 plan senden        Gemerkte Meldungen nachschicken, die offline nicht ankamen
+kimal3 projekt verbinden  Den Projektordner mit seinem Projekt in der App verbinden
+kimal3 plan hoch          Nur noch mit --ueberschreiben: den ganzen Stand durch plan/stand.json ersetzen
 kimal3 kurs               Zeigen, wo du im Mini-Kurs stehst
 kimal3 firma daten        Die Daten deiner Firma holen, damit Claude sie auswerten kann
 kimal3 zeigen start       Eine Aufnahme starten, während du eine Aufgabe vormachst
@@ -184,8 +187,11 @@ kimal3 context questions  Answer the questions about your company — Claude tak
 kimal3 context upload     Upload your local changes to the five company texts
 kimal3 project new …      Add a project to your success profile
 kimal3 project list       Show the projects you've added
-kimal3 plan               Upload planning or fetch responses
-kimal3 plan upload        Upload the planning in plan/stand.json (--dry-run: only check)
+kimal3 plan               Fetch the planning state and report changes
+kimal3 plan report        Report a change to the project page (report as JSON from the input)
+kimal3 plan send          Send kept reports that didn't arrive while offline
+kimal3 project connect    Connect the project folder with its project in the app
+kimal3 plan upload        Only with --overwrite: replace the whole state with plan/stand.json
 kimal3 course             Show where you are in the mini-course
 kimal3 company data       Fetch your company's data so Claude can analyse it
 kimal3 show start         Start a recording while you show a task

package/claude-plugins/.claude-plugin/marketplace.json

@@ -3,6 +3,7 @@
   "owner": { "name": "KImal3", "url": "https://kimal3.de" },
   "description": "Eingetragen vom Programm kimal3 · Added by the kimal3 program",
   "plugins": [
-    { "name": "kimal3-logo", "source": "./kimal3-logo", "description": "KImal3-Logo über dem Eingabefeld · KImal3 logo above the prompt" }
+    { "name": "kimal3-logo", "source": "./kimal3-logo", "description": "KImal3-Logo über dem Eingabefeld · KImal3 logo above the prompt" },
+    { "name": "kimal3-plan", "source": "./kimal3-plan", "description": "Hält das Board der Projektseite aktuell · Keeps the project page board current" }
   ]
 }

package/claude-plugins/README.md

@@ -2,6 +2,8 @@
 
 Diesen Ordner legt `kimal3 einrichten` an und ersetzt ihn bei jedem Lauf. Eigene Änderungen hier gehen dabei verloren.
 Das Logo abschalten: in Claude unter **Plugins** `kimal3-logo` ausschalten — `kimal3` schaltet es danach nicht wieder ein.
+`kimal3-plan` hält das Board der Projektseite in der App aktuell (Punkt, solange die Sitzung arbeitet; Spec-Texte). Abschalten genauso: unter **Plugins** `kimal3-plan` ausschalten.
 
 `kimal3 setup` creates this folder and replaces it on every run; your own changes here are lost.
 To turn the logo off: switch off `kimal3-logo` under **Plugins** in Claude — `kimal3` won't switch it back on.
+`kimal3-plan` keeps the board on the app's project page current (dot while the session works; spec texts). Turn it off the same way: switch off `kimal3-plan` under **Plugins**.

package/claude-plugins/kimal3-logo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "kimal3-logo",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "KImal3-Logo über dem Eingabefeld, öffnet beim Start das Projekt in der App, benennt den Chat nach seinem Thema · KImal3 logo above the prompt, opens the project in the app on start, names the chat after its topic",
   "author": { "name": "KImal3", "url": "https://kimal3.de" },
   "types": "./types/index.d.ts"

package/claude-plugins/kimal3-logo/hooks/app-oeffnen.ts

@@ -16,7 +16,10 @@ const ANSICHT = 'ccd_view'
 const EINBLENDEN = 'mcp__ccd_view__show_pane'
 const geoeffnet = atom({ plugin: 'kimal3-logo', key: 'appGeoeffnet' } as const, false)
 
-/** Die Adresse für den Inhalt von `plan/stand.json` (`null`: keine Datei). Ohne gültige Nummer der Kurs, wie der Link in der Leiste (S-3, S-4). */
+/**
+ * Die Adresse für den Inhalt von `plan/projekt.json` oder `plan/stand.json` (`null`: keine Datei) -- beide tragen die
+ * Nummer als `projekt_id`. Ohne gültige Nummer der Kurs, wie der Link in der Leiste (S-3, S-4).
+ */
 export function adresseFuer(standJson: string | null): string {
   if (standJson !== null) {
     try {
@@ -30,6 +33,21 @@ export function adresseFuer(standJson: string | null): string {
   return `${APP}/kurs`
 }
 
+/**
+ * Ist das ein gueltiger Ordnerzettel (`plan/projekt.json`: `format: 1`, Projektnummer, Titel)? Dieselbe Pruefung wie
+ * `zettelAus` im Mod `kimal3-plan` und in `cli/src/projekt-ordner.ts` -- ein ungueltiger zaehlt nicht, dann gilt die
+ * alte `plan/stand.json`.
+ */
+export function istZettel(text: string | null): boolean {
+  if (text === null) return false
+  try {
+    const z = JSON.parse(text.replace(/^\uFEFF/, '')) as { format?: unknown; projekt_id?: unknown; titel?: unknown } | null
+    return z?.format === 1 && typeof z.projekt_id === 'string' && PROJEKTNUMMER.test(z.projekt_id) && typeof z.titel === 'string' && z.titel.trim() !== ''
+  } catch {
+    return false
+  }
+}
+
 /** Die eigene Erlaubnis (unten): nur der Aufruf dieses Mods, nur eine Adresse der App. Herausgelöst, damit `check:logo` die Grenze prüft. */
 export function istEigenerAufruf(plugin: string, input: unknown): boolean {
   const url = (input as { url?: unknown } | null)?.url
@@ -83,29 +101,39 @@ async function liesDatei($: Engine, pfad: string): Promise<string | null> {
 }
 
 /**
- * `plan/stand.json` des Projekts, in dem Claude läuft (S-5, S-24, S-25): vom Startordner nach oben, bis zur Wurzel des
+ * Eine Datei des Projekts, in dem Claude läuft (S-5, S-24, S-25): vom Startordner nach oben, bis zur Wurzel des
  * eigenen Git-Projekts und nie darüber hinaus — sonst bekäme ein Projekt ohne Plan die Seite eines anderen. Ist die
- * Wurzel eine Arbeitskopie (`.git` ist dort eine Datei), zählt danach die Projektdatei ihres Hauptprojekts.
+ * Wurzel eine Arbeitskopie (`.git` ist dort eine Datei), zählt danach die Datei ihres Hauptprojekts.
  */
-async function findeStand($: Engine, cwd: string): Promise<string | null> {
+async function findePlanDatei($: Engine, cwd: string, datei: string): Promise<string | null> {
   for (const ordner of ordnerNachOben(cwd)) {
-    const stand = await liesDatei($, `${ordner}/plan/stand.json`)
-    if (stand !== null) return stand
+    const text = await liesDatei($, `${ordner}/${datei}`)
+    if (text !== null) return text
     if (!(await $.fs.exists(`${ordner}/.git`))) continue
     // Ein Ordner `.git` lässt sich nicht lesen: echte Projektwurzel, hier ist Schluss.
     const gitdatei = await liesDatei($, `${ordner}/.git`)
     const haupt = gitdatei === null ? null : hauptordnerAusGitdatei(gitdatei)
-    return haupt === null ? null : liesDatei($, `${haupt}/plan/stand.json`)
+    return haupt === null ? null : liesDatei($, `${haupt}/${datei}`)
   }
   return null
 }
 
+/**
+ * Erst der Ordnerzettel `plan/projekt.json`, dann `plan/stand.json` für alte Ordner (Spec 2026-10-23-brett-in-echtzeit,
+ * 1.4, US-8) — dieselbe Reihenfolge wie `kimal3` (`cli/src/projekt-ordner.ts`). Ein ungültiger Zettel zählt nicht.
+ */
+async function adresseJetzt($: Engine): Promise<string> {
+  const cwd = await $.session.cwd()
+  const zettel = await findePlanDatei($, cwd, 'plan/projekt.json')
+  return adresseFuer(istZettel(zettel) ? zettel : await findePlanDatei($, cwd, 'plan/stand.json'))
+}
+
 async function oeffne($: Engine): Promise<boolean> {
-  const stand = await findeStand($, await $.session.cwd())
+  const adresse = await adresseJetzt($)
   // Scheitern meldet sich als Scheitern, nie im Chat (S-13): eine Zeile nur im Debug-Protokoll (`to: 'debug'` —
   // ohne steht sie im Chatverlauf, Befund der Durchsicht 23.10.).
   try {
-    const antwort = await $.mcp.call(BROWSER, 'navigate', { url: adresseFuer(stand) })
+    const antwort = await $.mcp.call(BROWSER, 'navigate', { url: adresse })
     if (!antwort.isError) {
       await einblenden($)
       return true

package/claude-plugins/kimal3-logo/hooks/register.tsx

@@ -6,7 +6,7 @@ import { updateClaudeFragen, updateInstallieren, updateZustand } from './update'
 import { satzWeicht, TEXTE, type Zustand } from './update-rechnung'
 
 // Die Sprache des Kontos. `kimal3 einrichten` setzt diese Zeile beim Ablegen in `~/.kimal3/claude-plugins` und prüft
-// danach, dass sie gesetzt ist (`cli/src/logo-ablegen.ts`).
+// danach, dass sie gesetzt ist (`cli/src/mods-ablegen.ts`).
 const SPRACHE: 'de' | 'en' = 'de'
 // Fassung und Orte von `kimal3` auf diesem Rechner; beim Ablegen gesetzt wie die Sprache (hooks/ablage.ts).
 const ABLAGE: Ablage = KEINE_ABLAGE

package/claude-plugins/kimal3-plan/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "kimal3-plan",
+  "version": "0.1.1",
+  "description": "Hält das Board der Projektseite in der App aktuell: Punkt solange die Sitzung arbeitet, Spec-Texte, hält Claude vor dem ersten Bau-Schritt an · Keeps the board on the app's project page current: dot while the session works, spec texts, stops Claude before the first build step",
+  "author": { "name": "KImal3", "url": "https://kimal3.de" },
+  "types": "./types/index.d.ts"
+}

package/claude-plugins/kimal3-plan/hooks/erinnerung.ts

@@ -0,0 +1,83 @@
+import { atom, read, update, type EngineInterface, type On } from 'claude-code'
+import { TEXTE, type Lauf } from './lauf'
+import { relativImOrdner } from './ordner'
+
+/**
+ * Die drei Saetze, die NUR Claude bekommt (Spec 1.3 Aufgabe 3, 1.5, 1.7, S-25, S-26, US-6, US-8; Bauplan R-4).
+ * Der Mensch sieht keinen davon (gemessen M-3, Claude-App). Zwei Wege, je nachdem, ob der Satz eine Runde starten soll:
+ *
+ * - **Sperre vor dem ersten Bau-Schritt** (US-6, Dennis 25.10.: „Ich will das Problem gleich gefixt haben“): Will Claude
+ *   eine Datei aendern, ohne dass diese Sitzung eine Story „in Arbeit“ hat, lehnt der Mod die Aenderung VORHER ab
+ *   (`deny`), und Claude liest den Satz als Grund. Bis zum 25.10. kam der Satz erst NACH der Aenderung als `context` --
+ *   gemessen in einer echten Sitzung: Claude schrieb zuerst die Pruefung und meldete danach. Der zweite Versuch geht
+ *   durch (30-Minuten-Sperre): Eine Aenderung ohne Story (Statuszettel, neue Spec) haengt so nie fest. Nur die
+ *   Hauptsitzung: Ein Subagent (`e.agentId`) baut im Auftrag und meldet nicht. Nur in einem Projektordner mit
+ *   Ordnerzettel (S-30), und nur, wenn die App zuletzt „nichts in Arbeit“ gesagt hat -- weiss der Mod es nicht (noch
+ *   keine Antwort, App weg), haelt er nichts an. 🔴 Scheitert der Hook selbst, ueberspringt ihn die Maschine und die
+ *   Aenderung laeuft (`tool.call`, Typen: „A guard that fails is skipped and the tool runs“) -- so gewollt: Ein Fehler
+ *   im Mod darf die Arbeit nie aufhalten.
+ * - **Anstoss „Projekt anlegen“** (US-8) und **„gemerkte Meldungen senden“** (R-4) sind eine Zeile im Gespraech
+ *   (`$.session.append`): Claude liest sie sofort und handelt.
+ */
+const SPERRE_MS = 30 * 60_000
+
+// In `$.state`, weil ein Neuladen des Mods die Variablen des Moduls zuruecksetzt -- die Sperre und der einmalige Anstoss
+// sollen das ueberstehen.
+const letzteErinnerung = atom({ plugin: 'kimal3-plan', key: 'letzteErinnerung' } as const, null)
+const angestossen = atom({ plugin: 'kimal3-plan', key: 'anstossGegeben' } as const, false)
+
+/** Die Datei eines Schreib-Werkzeugs (`file_path`, bei Notebooks `notebook_path`). */
+export function dateiAus(e: unknown): string | null {
+  const o = e as { file_path?: unknown; notebook_path?: unknown }
+  const datei = o.file_path ?? o.notebook_path
+  return typeof datei === 'string' && datei !== '' ? datei : null
+}
+
+export function erinnerung(on: On, lauf: Lauf): void {
+  on('tool.call', { tool: ['Write', 'Edit', 'NotebookEdit'] }, async ($, e, next) => {
+    const satz = e.agentId === undefined ? await satzFuer($, lauf, dateiAus(e)) : null
+    return satz === null ? next(e) : { deny: satz }
+  })
+}
+
+async function satzFuer($: EngineInterface, lauf: Lauf, datei: string | null): Promise<string | null> {
+  const lage = lauf.lage
+  if (lauf.inArbeit !== false || lage.art !== 'projekt' || lage.zettel === null || datei === null) return null
+  // Markdown ist Planung (Spec, Bauplan, Statuszettel), kein Bau-Schritt: Eine neue Spec entsteht, bevor es eine Story gibt.
+  if (datei.toLowerCase().endsWith('.md')) return null
+  if (relativImOrdner(datei, lage.ordner, await $.session.cwd()) === null) return null
+  const jetzt = await $.clock.now()
+  const zuletzt = await read($, letzteErinnerung)
+  if (zuletzt !== null && jetzt - zuletzt < SPERRE_MS) return null
+  await update($, letzteErinnerung, () => jetzt)
+  return TEXTE[lauf.sprache].erinnerung(lage.zettel.titel)
+}
+
+/** Projektordner ohne Ordnerzettel: einmal je Sitzung „leg das Projekt an“ (US-8). */
+export async function anstossOhneZettel($: EngineInterface, lauf: Lauf): Promise<void> {
+  if (lauf.lage.art !== 'projekt' || lauf.lage.zettel !== null || (await read($, angestossen))) return
+  if (await anClaude($, TEXTE[lauf.sprache].anstoss)) await update($, angestossen, () => true)
+}
+
+/** Liegen gemerkte Meldungen (`~/.kimal3/meldungen/*.json`; `.tmp` sind Reste) und ist die App erreichbar: senden lassen. */
+export async function gemerkteMeldungenAnstossen($: EngineInterface, lauf: Lauf): Promise<void> {
+  if (lauf.heim === null) return
+  const eintraege = await $.fs.list(`${lauf.heim}/.kimal3/meldungen`).catch(() => [])
+  if (eintraege.some((d: { kind: string; name: string }) => d.kind === 'file' && d.name.endsWith('.json'))) await anClaude($, TEXTE[lauf.sprache].gemerkt)
+}
+
+/** Nach `/clear` beginnt eine neue Sitzung: ihre eigene Sperre, ihr eigener Anstoss. */
+export async function sitzungNeu($: EngineInterface): Promise<void> {
+  await update($, letzteErinnerung, () => null)
+  await update($, angestossen, () => false)
+}
+
+async function anClaude($: EngineInterface, text: string): Promise<boolean> {
+  try {
+    await $.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } })
+    return true
+  } catch (fehler) {
+    $.ui.log(`kimal3-plan: Satz an Claude nicht angehaengt: ${String(fehler).slice(0, 200)}`, { to: 'debug' })
+    return false
+  }
+}

package/claude-plugins/kimal3-plan/hooks/fehlerzeile.ts

@@ -0,0 +1,41 @@
+import type { EngineInterface } from 'claude-code'
+import { TEXTE, type Fehler, type Lauf } from './lauf'
+
+/**
+ * Die eine Fehlerzeile des Mods (Spec 1.3, 1.5, US-4, S-11, S-22; Bauplan R-8): in der Statuszeile unter dem
+ * Eingabefeld, weil eine farbige Zeile dort in der Claude-App gar nicht erscheint (gemessen M-4). Sie steht, solange der
+ * Fehler besteht, und verschwindet danach -- `$.ui.status` wird nur gerufen, wenn sich der Satz AENDERT, so bleibt es
+ * bei zehn gescheiterten Versuchen bei EINER Zeile. Bei mehreren Fehlern zeigt sie den ersten nach diesem Vorrang:
+ * Wer nicht angemeldet ist, dem hilft „nicht erreichbar“ nichts.
+ */
+const VORRANG: readonly Fehler[] = ['nicht-angemeldet', 'kimal3-fehlt', 'nicht-erreichbar']
+
+function zeige($: EngineInterface, lauf: Lauf): void {
+  const art = VORRANG.find(f => lauf.fehler.has(f))
+  const satz = art === undefined ? undefined : TEXTE[lauf.sprache].fehler[art]
+  if (satz === lauf.zeile) return
+  lauf.zeile = satz
+  $.ui.status(satz)
+}
+
+/** Die Fehler nach einem Lebenszeichen: Es prueft Ausweis UND App, sein Ergebnis ersetzt alles Bisherige. */
+export function fehlerSind($: EngineInterface, lauf: Lauf, fehler: readonly Fehler[]): void {
+  lauf.fehler = new Set(fehler)
+  merkeAusfall(lauf)
+  zeige($, lauf)
+}
+
+/** Einzelne Fehler kommen hinzu (`true`) oder sind behoben (`false`), etwa nach dem Hochladen eines Spec-Texts. */
+export function fehlerSetzen($: EngineInterface, lauf: Lauf, aenderung: Partial<Record<Fehler, boolean>>): void {
+  for (const [art, besteht] of Object.entries(aenderung) as [Fehler, boolean][]) {
+    if (besteht) lauf.fehler.add(art)
+    else lauf.fehler.delete(art)
+  }
+  merkeAusfall(lauf)
+  zeige($, lauf)
+}
+
+/** War die App weg, koennen sich in der Zeit Meldungen angesammelt haben: nach der Rueckkehr nachsehen (R-4). */
+function merkeAusfall(lauf: Lauf): void {
+  if (lauf.fehler.has('nicht-erreichbar')) lauf.meldungenPruefen = true
+}

package/claude-plugins/kimal3-plan/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/claude-plugins/kimal3-plan/hooks/lauf.ts

@@ -0,0 +1,143 @@
+import type { EngineInterface, Timer } from 'claude-code'
+import { liesDatei, normiert, type Ordnerlage } from './ordner'
+
+/**
+ * Was die Teile des Mods gemeinsam wissen (ein Objekt je Laden des Mods, angelegt in `register.tsx`), dazu die Saetze in
+ * beiden Sprachen und der eine Weg zur App.
+ */
+
+export type Sprache = 'de' | 'en'
+export type Fehler = 'nicht-angemeldet' | 'kimal3-fehlt' | 'nicht-erreichbar'
+
+export type Lauf = {
+  /** Die SPRACHE-Zeile aus `register.tsx` -- gilt, wenn `~/.kimal3/sprache.json` fehlt (S-23). */
+  vorgabe: Sprache
+  sprache: Sprache
+  /** Der Benutzerordner mit `/` (`USERPROFILE`, sonst `HOME`) -- dort liegt `.kimal3/` (M-5). */
+  heim: string | null
+  basis: string
+  lage: Ordnerlage
+  /** Die letzte Antwort der App auf ein Lebenszeichen: `null`, solange keine gekommen ist (R-5). */
+  inArbeit: boolean | null
+  /** Zaehlt jede Meldung, die Claude gerade abgeschickt hat: Ein Lebenszeichen, das davor losging, setzt `inArbeit` nicht. */
+  meldungen: number
+  /** Die Spec-Dateien des Projekts aus dem letzten Lebenszeichen -- nur deren Texte gehen hoch (Datensparsamkeit). */
+  specDateien: readonly string[]
+  takt: Timer | null
+  /** Ein Start laeuft gerade (zwischen erstem `await` und dem Zeitgeber): ein zweiter wartet nicht, er unterbleibt. */
+  startet: boolean
+  /** Zaehlt jedes Sitzungsende hoch: Eine Antwort, die fuer eine fruehere Sitzung unterwegs war, wirkt nicht mehr. */
+  generation: number
+  /** `session.end` ist gelaufen: Ein Lebenszeichen, das noch unterwegs war, darf danach nichts mehr tun. */
+  beendet: boolean
+  /** Fuer diese Projektnummer hat die App `403` gesagt (nicht Eigentuemer, geloescht): nicht weiter fragen. */
+  abgelehnt: string | null
+  /** Fuer dieses Projekt ging ein Lebenszeichen raus -- nur dann gibt es etwas abzumelden. */
+  gemeldetFuer: string | null
+  /** Beim naechsten erfolgreichen Lebenszeichen nach gemerkten Meldungen sehen (R-4): beim Start und nach jedem Ausfall. */
+  meldungenPruefen: boolean
+  fehler: Set<Fehler>
+  /** Was gerade in der Statuszeile steht (`undefined`: nichts; `null`: noch nie gesetzt -- die erste Auswertung nach dem
+   * Laden ruft `$.ui.status` in jedem Fall und raeumt so eine Zeile ab, die ein frueherer Lauf stehen liess). */
+  zeile: string | undefined | null
+}
+
+export function neuerLauf(vorgabe: Sprache): Lauf {
+  return {
+    vorgabe, sprache: vorgabe, heim: null, basis: APP, lage: { art: 'kein-projektordner' }, inArbeit: null, meldungen: 0, specDateien: [],
+    takt: null, startet: false, generation: 0, beendet: false, abgelehnt: null, gemeldetFuer: null, meldungenPruefen: true,
+    fehler: new Set(), zeile: null,
+  }
+}
+
+const APP = 'https://app.kimal3.de'
+
+// Wortlaut: Spec 1.3 (Erinnerung), 1.7 (Anstoss), S-11, S-22, US-4; Bauplan R-4 (gemerkte Meldungen).
+// Englische Befehlswoerter wie in `cli/src/befehlswoerter.ts` (`project connect`, `plan send`).
+export const TEXTE = {
+  de: {
+    erinnerung: (titel: string) => `Halt, die Datei ist noch nicht geändert: Du arbeitest im Projekt ${titel}, aber diese Sitzung hat keine Story ‚in Arbeit‘ gemeldet. Melde zuerst die Story, an der du arbeitest, und ändere die Datei danach. Gehört die Änderung zu keiner Story, notiere sie als Thema oder versuch es einfach noch einmal.`,
+    anstoss: 'Für diesen Projektordner gibt es noch kein Projekt in der App — leg es mit `kimal3 projekt verbinden` an.',
+    gemerkt: 'Gemerkte Meldungen warten — führe `kimal3 plan senden` aus.',
+    fehler: {
+      'nicht-erreichbar': 'Die Projektseite ist gerade nicht erreichbar — ich versuche es gleich wieder.',
+      'nicht-angemeldet': 'Du bist bei kimal3 nicht mehr angemeldet — `kimal3 login`.',
+      'kimal3-fehlt': 'kimal3 fehlt oder ist zu alt — `npm install -g kimal3@latest`.',
+    },
+  },
+  en: {
+    erinnerung: (titel: string) => `Stop, the file has not been changed: You are working in the project ${titel}, but this session hasn't reported a story as ‘in progress’. Report the story you're working on first, then change the file. If the change belongs to no story, note it as a topic or simply try again.`,
+    anstoss: 'There is no project in the app for this project folder yet — create it with `kimal3 project connect`.',
+    gemerkt: 'Saved reports are waiting — run `kimal3 plan send`.',
+    fehler: {
+      'nicht-erreichbar': "The project page can't be reached right now — I'll try again shortly.",
+      'nicht-angemeldet': "You're no longer signed in to kimal3 — `kimal3 login`.",
+      'kimal3-fehlt': 'kimal3 is missing or too old — `npm install -g kimal3@latest`.',
+    },
+  },
+} as const
+
+/**
+ * Benutzerordner, Sprache und App-Adresse -- bei jedem Sitzungsstart neu, damit eine umgestellte Kontosprache ohne neues
+ * `kimal3 einrichten` gilt (S-23). `KIMAL3_URL` wie in `cli/src/anmeldung.ts` (Messen gegen den lokalen Server).
+ */
+export async function umgebungLesen($: EngineInterface, lauf: Lauf): Promise<void> {
+  const heim = (await $.env.get('USERPROFILE')) ?? (await $.env.get('HOME'))
+  lauf.heim = heim === undefined || heim === '' ? null : normiert(heim)
+  lauf.basis = ((await $.env.get('KIMAL3_URL')) ?? APP).replace(/\/+$/, '')
+  lauf.sprache = lauf.vorgabe
+  const text = lauf.heim === null ? null : await liesDatei($, `${lauf.heim}/.kimal3/sprache.json`)
+  try {
+    const s: unknown = text === null ? null : JSON.parse(text.replace(/^\uFEFF/, ''))?.sprache
+    if (s === 'de' || s === 'en') lauf.sprache = s
+  } catch {
+    // kaputte Datei: die SPRACHE-Zeile gilt
+  }
+}
+
+/**
+ * Der Geraeteschluessel aus `~/.kimal3/anmeldung.json` (M-5), bei jedem Gebrauch frisch gelesen -- so wirkt ein
+ * `kimal3 login` sofort. 🔴 Der Schluessel wird nur benutzt, nie ausgegeben oder protokolliert.
+ * Ohne Schluessel: Gibt es `~/.kimal3/`, ist `kimal3` da und nur abgemeldet (S-11, `kimal3 login`); fehlt der Ordner ganz,
+ * fehlt `kimal3` (S-22, installieren) -- Ruling der Fixrunde.
+ */
+export async function liesAusweis($: EngineInterface, lauf: Lauf): Promise<{ schluessel: string } | { fehler: Fehler }> {
+  if (lauf.heim === null) return { fehler: 'kimal3-fehlt' }
+  const text = await liesDatei($, `${lauf.heim}/.kimal3/anmeldung.json`)
+  try {
+    const s: unknown = text === null ? null : JSON.parse(text.replace(/^\uFEFF/, ''))?.schluessel
+    if (typeof s === 'string' && s !== '') return { schluessel: s }
+  } catch {
+    // kaputte Datei: wie keine
+  }
+  const ordnerDa = await $.fs.exists(`${lauf.heim}/.kimal3`).catch(() => false)
+  return { fehler: ordnerDa ? 'nicht-angemeldet' : 'kimal3-fehlt' }
+}
+
+/** Wie lange ein Abruf an die App hoechstens dauern darf: `$.http.fetch` kennt keine eigene Zeitgrenze. */
+const ZEITGRENZE_MS = 8_000
+
+/**
+ * Ein Abruf an `/api/mod/*`. `null`: die App war nicht zu erreichen (kein Netz, abgelehnt, oder keine Antwort innerhalb
+ * von `grenzeMs`). 🔴 Ohne die Zeitgrenze haengt ein Abruf, der nie antwortet, das Lebenszeichen fuer immer auf --
+ * still, ohne Statuszeile (Befund der Durchsicht).
+ */
+export function anApp($: EngineInterface, lauf: Lauf, pfad: string, schluessel: string, rumpf: unknown, grenzeMs = ZEITGRENZE_MS): Promise<{ status: number; text: string } | null> {
+  return new Promise(fertig => {
+    const frist = $.clock.after(Math.max(0, Math.min(grenzeMs, ZEITGRENZE_MS)), () => fertig(null))
+    $.http.fetch(`${lauf.basis}${pfad}`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${schluessel}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(rumpf),
+    }).then(
+      antwort => {
+        frist.cancel()
+        fertig({ status: antwort.status, text: antwort.text })
+      },
+      () => {
+        frist.cancel()
+        fertig(null)
+      },
+    )
+  })
+}

package/claude-plugins/kimal3-plan/hooks/lebenszeichen.ts

@@ -0,0 +1,197 @@
+import type { EngineInterface, On } from 'claude-code'
+import { anstossOhneZettel, gemerkteMeldungenAnstossen, sitzungNeu } from './erinnerung'
+import { fehlerSind } from './fehlerzeile'
+import { anApp, liesAusweis, umgebungLesen, type Lauf } from './lauf'
+import { lageJetzt } from './ordner'
+
+/**
+ * Den Punkt am Leben halten (Spec 1.3 Aufgabe 2, E-4, US-2; Bauplan R-5, Review Focus 5). Solange die Sitzung in einem
+ * Projektordner mit Ordnerzettel offen ist, meldet sich der Mod alle 10 Sekunden bei der App (`POST
+ * /api/mod/lebenszeichen`, gemessen M-2: der Zeitgeber laeuft auch, waehrend Claude arbeitet) und merkt sich, ob diese
+ * Sitzung eine Story „in Arbeit“ hat. Beim Ende der Sitzung meldet er sich ab, damit der Punkt in unter 1 Sekunde weg
+ * ist; ein abgeschossener Prozess meldet sich nie ab, dafuer gibt es die 30-Sekunden-Regel der App.
+ *
+ * Jeder Takt liest Ordner, Zettel und Ausweis neu: So kommt ein Zettel, den Claude nach dem Anstoss anlegt (US-8), und ein
+ * `kimal3 login` beim naechsten Takt an, ohne Neustart.
+ */
+const TAKT_MS = 10_000
+const MELDUNG = /\bplan\s+(melde|report|senden|send)\b/
+
+/**
+ * Die Nummer dieser Sitzung fuer `kimal3 plan melde` (Ruling Final, Important 2): Ob `CLAUDE_CODE_SESSION_ID` nach
+ * `/clear` neu ist, ist ungemessen -- der Mod setzt deshalb bei jedem Start, auch nach `/clear`, `KIMAL3_SITZUNG`, und
+ * das Programm nimmt sie vor Claudes eigener Variable (die bleibt unberuehrt). Gemessen am 23.10.: die Variable kommt
+ * bei einem Bash-Aufruf an (docs/qa/2026-10-23-brett-echtzeit-messungen.md, „Final — Sitzungskennung“). Scheitert das
+ * Setzen, laeuft der Mod weiter; das Programm faellt dann auf `CLAUDE_CODE_SESSION_ID` zurueck.
+ */
+async function sitzungFuerProgramm($: EngineInterface): Promise<void> {
+  await $.env.set('KIMAL3_SITZUNG', await $.session.id()).catch(() => undefined)
+}
+
+export function lebenszeichen(on: On, lauf: Lauf): void {
+  on('session.start', async ($, e, next) => {
+    const ergebnis = await next(e)
+    await sitzungFuerProgramm($)
+    await starte($, lauf)
+    return ergebnis
+  })
+  // Haengt sich eine Oberflaeche an, ohne dass es lief (etwa nach einem frueheren Fehlstart): noch einmal versuchen.
+  on('session.attach', async ($, e, next) => {
+    const ergebnis = await next(e)
+    await starte($, lauf)
+    return ergebnis
+  })
+  // `/clear` beendet die Sitzung (abgemeldet unten), der Prozess laeuft unter einer neuen Kennung weiter -- ohne
+  // `session.start`. Die neue Sitzung meldet sich deshalb hier wieder an.
+  on('classic.SessionStart', async ($, e, next) => {
+    const ergebnis = await next(e)
+    if (e.source === 'clear') {
+      Object.assign(lauf, { beendet: false, inArbeit: null, specDateien: [], abgelehnt: null, gemeldetFuer: null, meldungenPruefen: true })
+      await sitzungNeu($)
+      await sitzungFuerProgramm($)
+      await starte($, lauf)
+    }
+    return ergebnis
+  })
+  // Claude hat gerade gemeldet (`kimal3 plan melde`/`plan senden`): Was der Mod ueber „in Arbeit“ weiss, ist ab jetzt
+  // veraltet -- bis zu 10 s lang kaeme sonst die Erinnerung, obwohl die Meldung schon raus ist (Final-Review, Important 1).
+  // Also gilt es als unbekannt (keine Erinnerung), und ein Lebenszeichen holt sofort den neuen Stand. Ein Fehlalarm des
+  // Musters kostet nur ein Lebenszeichen mehr.
+  on('tool.call', { tool: ['Bash', 'PowerShell'] }, async ($, e, next) => {
+    const ergebnis = await next(e)
+    if (!MELDUNG.test(e.command)) return ergebnis
+    lauf.inArbeit = null
+    lauf.meldungen++
+    // Nur, wenn der Zeitgeber laeuft (Projektordner, nicht beendet): kein zweiter Zeitgeber, und `takt` faellt aus, wenn
+    // schon eines unterwegs ist -- dessen Antwort zaehlt dann nicht (`meldungen`), bis der naechste Takt fragt.
+    if (lauf.takt !== null) $.clock.after(0, () => void takt($, lauf))
+    return ergebnis
+  })
+  on('session.end', async ($, e, next) => {
+    // 🔴 ZUERST den Zeitgeber anhalten, DANN abmelden (Review Focus 5): sonst kann ein letzter Takt nach dem Abmelden
+    // ankommen. Die App lehnt ihn zwar ab (`410`), aber `beendet` haelt auch einen Takt an, der schon unterwegs ist.
+    lauf.beendet = true
+    lauf.generation++
+    lauf.takt?.cancel()
+    lauf.takt = null
+    lauf.inArbeit = null
+    // Die ganze Kette von `session.end` hat ~1,5 s (gemessen M-2); der Abruf endet vorher, damit Claude Code nicht
+    // mitten in ihm abschneidet und die Hooks nach uns ihre Zeit behalten.
+    const grenze = next.budget.remainingMs - 100
+    if (lauf.gemeldetFuer !== null) await abmelden($, lauf, lauf.gemeldetFuer, e.sessionId, grenze)
+    lauf.gemeldetFuer = null
+    return next(e)
+  })
+}
+
+async function starte($: EngineInterface, lauf: Lauf): Promise<void> {
+  // 🔴 `startet` steht VOR dem ersten `await`: `session.start` und `session.attach` kommen fast gleichzeitig, und
+  // beide bestanden sonst die Pruefung auf `takt` -- zwei Zeitgeber, einer davon nie angehalten (Befund der Durchsicht).
+  if (lauf.takt !== null || lauf.startet || lauf.beendet) return
+  lauf.startet = true
+  try {
+    await umgebungLesen($, lauf)
+    lauf.lage = await lageJetzt($)
+    // Kein Projektordner (Werkbank, Beispielordner, ausserhalb): der Mod tut nichts (S-30).
+    if (lauf.lage.art !== 'projekt') return
+    await anstossOhneZettel($, lauf)
+    lauf.takt = $.clock.every(TAKT_MS, () => void takt($, lauf))
+    // Das erste Lebenszeichen sofort (Punkt in unter 1 s, E-3), aber ohne den Sitzungsstart darauf warten zu lassen.
+    $.clock.after(0, () => void takt($, lauf))
+  } finally {
+    lauf.startet = false
+  }
+}
+
+/** Die Sitzung (`generation`), fuer die gerade ein Lebenszeichen unterwegs ist -- je Sitzung hoechstens eines. */
+let unterwegs: number | null = null
+
+async function takt($: EngineInterface, lauf: Lauf): Promise<void> {
+  // Ein Takt, dessen Vorgaenger noch auf die App wartet (langsames Netz), faellt aus, statt sich zu stapeln.
+  const generation = lauf.generation
+  if (lauf.beendet || unterwegs === generation) return
+  unterwegs = generation
+  try {
+    await einTakt($, lauf, generation)
+  } finally {
+    if (unterwegs === generation) unterwegs = null
+  }
+}
+
+async function einTakt($: EngineInterface, lauf: Lauf, generation: number): Promise<void> {
+  // Nach jedem `await`: Ist die Sitzung, fuer die dieser Takt lief, inzwischen vorbei (Ende, `/clear`), wirkt er nicht
+  // mehr -- sonst haelt ein spaetes `410` der alten Sitzung den Zeitgeber der neuen an.
+  const vorbei = () => lauf.beendet || lauf.generation !== generation
+  const lage = await lageJetzt($)
+  if (vorbei()) return
+  lauf.lage = lage
+  if (lage.art !== 'projekt') return
+  const ausweis = await liesAusweis($, lauf)
+  if (vorbei()) return
+  if ('fehler' in ausweis) {
+    lauf.inArbeit = null
+    return fehlerSind($, lauf, [ausweis.fehler])
+  }
+  const zettel = lage.zettel
+  // Ohne Zettel gibt es noch kein Projekt (den Anstoss bekam Claude beim Start); nach `403` fragt der Mod nicht mehr.
+  if (zettel === null || zettel.projekt_id === lauf.abgelehnt) return fehlerSind($, lauf, [])
+
+  const sitzung = await $.session.id()
+  if (vorbei()) return
+  // Kam waehrend des Abrufs eine Meldung, ist seine Antwort zu „in Arbeit“ womoeglich von davor: sie zaehlt nicht.
+  const meldungen = lauf.meldungen
+  lauf.gemeldetFuer = zettel.projekt_id
+  const antwort = await anApp($, lauf, '/api/mod/lebenszeichen', ausweis.schluessel, { projektId: zettel.projekt_id, sitzung })
+  if (vorbei()) return
+
+  if (antwort?.status === 200) {
+    const gelesen = antwortAus(antwort.text)
+    // Kann der Mod nicht feststellen, ob es geklappt hat, gilt es als Fehler (US-4).
+    if (gelesen === null) return fehlerSind($, lauf, ['nicht-erreichbar'])
+    if (lauf.meldungen === meldungen) lauf.inArbeit = gelesen.inArbeit
+    lauf.specDateien = gelesen.specDateien
+    fehlerSind($, lauf, [])
+    if (lauf.meldungenPruefen) {
+      lauf.meldungenPruefen = false
+      await gemerkteMeldungenAnstossen($, lauf)
+    }
+    return
+  }
+  if (antwort?.status === 401) return fehlerSind($, lauf, ['nicht-angemeldet'])
+  // `403`: das Projekt gehoert diesem Konto nicht (mehr) -- etwa ein Kollege mit demselben Repo, oder in der App
+  // geloescht (das klaert `kimal3 projekt verbinden`, S-31). Kein Fehler fuer den Menschen, kein weiterer Versuch.
+  if (antwort?.status === 403) {
+    lauf.abgelehnt = zettel.projekt_id
+    lauf.inArbeit = null
+    return fehlerSind($, lauf, [])
+  }
+  // `410`: diese Sitzung ist schon abgemeldet -- nie wiederbeleben, sonst kaeme der Punkt zurueck (Review Focus 5).
+  if (antwort?.status === 410) {
+    lauf.takt?.cancel()
+    lauf.takt = null
+    lauf.inArbeit = null
+    return fehlerSind($, lauf, [])
+  }
+  fehlerSind($, lauf, ['nicht-erreichbar'])
+}
+
+/** `{ inArbeit, specDateien }` aus der Antwort; ohne gueltiges `inArbeit` `null`. Fehlt `specDateien` (aeltere App): leer. */
+function antwortAus(text: string): { inArbeit: boolean; specDateien: string[] } | null {
+  try {
+    const o: unknown = JSON.parse(text)
+    const inArbeit = (o as { inArbeit?: unknown } | null)?.inArbeit
+    const dateien = (o as { specDateien?: unknown } | null)?.specDateien
+    if (typeof inArbeit !== 'boolean') return null
+    return { inArbeit, specDateien: Array.isArray(dateien) ? dateien.filter((d): d is string => typeof d === 'string') : [] }
+  } catch {
+    return null
+  }
+}
+
+async function abmelden($: EngineInterface, lauf: Lauf, projektId: string, sitzung: string, grenzeMs: number): Promise<void> {
+  const ausweis = await liesAusweis($, lauf)
+  if ('fehler' in ausweis) return
+  // Der Abruf brauchte gemessen 4 ms (M-2). Reicht die Zeit nicht, kostet das hoechstens den Punkt fuer 30 Sekunden.
+  const antwort = await anApp($, lauf, '/api/mod/abmelden', ausweis.schluessel, { projektId, sitzung }, grenzeMs)
+  if (antwort?.status !== 204) $.ui.log(`kimal3-plan: abmelden ${antwort === null ? 'nicht erreichbar' : antwort.status}`, { to: 'debug' })
+}