kimal3 0.6.4 → 0.7.0

package/claude-plugins/kimal3-logo/hooks/update.ts

@@ -0,0 +1,244 @@
+import { atom, read, update, type Engine } from 'claude-code'
+import type { Ablage } from './ablage'
+import {
+  befehle, deutscherTag, fertigGilt, istFassung, istNeuer, sollFragen, sperreGilt, TEXTE, versionStimmt,
+  type Fertig, type Merkzettel, type Sperre, type Zustand,
+} from './update-rechnung'
+
+// Der Ablauf hinter „Update installieren“ in der Leiste (Bauplan docs/superpowers/plans/2026-10-23-update-in-der-leiste.md,
+// Abschnitte 1.2 und 1.3, Szenarien U-1 bis U-20). Die Entscheidungen selbst stehen rein in update-rechnung.ts; hier
+// steht, wann was gefragt, gemerkt und ausgeführt wird. Gezeichnet wird in register.tsx.
+
+const MINUTE = 60_000
+const NPM = 'https://registry.npmjs.org/kimal3/latest'
+// `HttpInit` kennt kein Zeitlimit: Was npm nach 5 s nicht beantwortet hat, zählt als Fehlschlag (Bauplan 1.2, A-6).
+const NPM_GEDULD = 5000
+// Was der Mod über Sitzungen und Fenster hinweg weiß (`$.store`, eine Datei je Mod): wann npm gefragt wurde, ob ein
+// Update läuft, und dass eines geklappt hat, aber Claude noch nicht neu gestartet ist.
+const MERKZETTEL = 'updateMerkzettel'
+const SPERRE = 'updateSperre'
+const FERTIG = 'updateFertig'
+// Die zwei Befehle, die der Klick ausführt, so wie Claude sie in seinen Erlaubnis-Regeln sähe (Bauplan 1.3 Punkt 2).
+// Beide Werkzeuge: Eine Firma, die `npm install` nur für PowerShell verbietet, verbietet es trotzdem (A-3).
+const WERKZEUGE = ['Bash', 'PowerShell']
+
+// Was die Leiste neu zeichnen soll, sobald es sich ändert (`$.state`, Vertrag in types/index.d.ts).
+const neueste = atom({ plugin: 'kimal3-logo', key: 'updateNeueste' } as const, '')
+const lauf = atom({ plugin: 'kimal3-logo', key: 'updateLauf' } as const, null)
+
+/**
+ * Die Fehlermeldung für die Bitte an Claude: die letzten 10 Zeilen, höchstens 1500 Zeichen (Bauplan 1.3 Punkt 6).
+ * npm schreibt vorne Fortschritt und hinten den Grund; der Grund ist, was Claude braucht.
+ */
+export function meldungKurz(text: string): string {
+  return text.trim().split(/\r?\n/).slice(-10).join('\n').slice(-1500)
+}
+
+// Was im Store steht, ist Daten von gestern — vielleicht von einer älteren Fassung des Mods. Nur Felder mit dem
+// richtigen Typ zählen; ein `fehlerAm` als Text ergäbe sonst `NaN`, und npm würde nie wieder gefragt.
+function merkzettelAus(roh: unknown): Merkzettel {
+  const m = (roh ?? {}) as Record<string, unknown>
+  return {
+    ...(typeof m.tag === 'string' ? { tag: m.tag } : {}),
+    ...(istFassung(m.neueste) ? { neueste: m.neueste } : {}),
+    ...(typeof m.fehlerAm === 'number' ? { fehlerAm: m.fehlerAm } : {}),
+  }
+}
+
+function versionAus(text: string): string | null {
+  try {
+    const version: unknown = (JSON.parse(text) as { version?: unknown } | null)?.version
+    return istFassung(version) ? version : null
+  } catch {
+    return null
+  }
+}
+
+function sperreAus(roh: unknown): Sperre | undefined {
+  const s = (roh ?? {}) as Record<string, unknown>
+  return istFassung(s.ziel) && typeof s.seit === 'number' ? { ziel: s.ziel, seit: s.seit } : undefined
+}
+
+// Ein Fehlschlag im Hintergrund gehört ins Debug-Protokoll, nie in den Chat (ohne `to: 'debug'` stünde er dort).
+function protokoll($: Engine, text: string): void {
+  $.ui.log(`kimal3-logo: ${text.slice(0, 300)}`, { to: 'debug' })
+}
+
+type Sprache = 'de' | 'en'
+// Gegen einen zweiten Klick, solange die Rückfrage noch offen ist oder der Lauf läuft.
+let beschaeftigt = false
+// Der Blick auf npm startet mit dem ersten Zeichnen der Leiste, einmal je Laden des Mods.
+let angestossen = false
+
+/** Nach dem Laden: Aufräumen, Wache-Schalter, Merkzettel — und npm fragen, wenn es heute noch nicht geschah. */
+async function beimLaden($: Engine, ablage: Ablage): Promise<void> {
+  const fassung = ablage.fassung
+  const jetzt = await $.clock.now()
+  // U-6b: Ein Mod, der die neue Fassung schon trägt, hat das Update hinter sich; nach 24 Stunden gilt der Haken nicht mehr.
+  const fertig = await $.store.get(FERTIG)
+  if (fertig !== undefined && !fertigGilt(fertig, jetzt, fassung)) await $.store.delete(FERTIG)
+  const sperre = sperreAus(await $.store.get(SPERRE))
+  if (sperre !== undefined && !istNeuer(sperre.ziel, fassung)) await $.store.delete(SPERRE)
+
+  if (await wacheAus($, ablage)) return
+  const merkzettel = merkzettelAus(await $.store.get(MERKZETTEL))
+  // Ein zweites Fenster am selben Tag zeigt den Knopf aus dem Merkzettel, ohne zu fragen (U-11).
+  if (merkzettel.tag === deutscherTag(jetzt) && merkzettel.neueste !== undefined) await update($, neueste, () => merkzettel.neueste ?? '')
+  if (sollFragen(merkzettel, jetzt)) await npmFragen($, jetzt)
+}
+
+/** `kimal3 wache aus` schaltet auch den Blick auf npm ab (E-8, U-8). Keine oder kaputte Datei: an. */
+async function wacheAus($: Engine, ablage: Ablage): Promise<boolean> {
+  try {
+    const inhalt: unknown = JSON.parse(await $.fs.read(`${ablage.kimal3Ordner}/wache.json`))
+    return (inhalt as { aus?: unknown } | null)?.aus === true
+  } catch {
+    return false
+  }
+}
+
+async function npmFragen($: Engine, jetzt: number): Promise<void> {
+  // Ein Zeitgeber statt `$.clock.sleep`: Ein `sleep` liefe auf das Zeitbudget des Hakens, aus dem `$` stammt — hier das
+  // Zeichnen der Leiste.
+  let zuEnde: (wert: null) => void = () => {}
+  const zuLangsam = new Promise<null>(aufloesen => { zuEnde = aufloesen })
+  const zeitgeber = $.clock.after(NPM_GEDULD, () => zuEnde(null))
+  const antwort = await Promise.race([$.http.fetch(NPM).catch(() => null), zuLangsam])
+  zeitgeber.cancel()
+  const version = versionAus(antwort?.ok ? antwort.text : '')
+  // Nur `1.2.3` zählt als Antwort; Vorabfassung, Unsinn, Fehler und Schweigen sind ein Fehlschlag (U-2, U-12).
+  if (version === null) {
+    protokoll($, `keine gültige Antwort von npm: ${antwort === null ? 'keine Antwort' : `${antwort.status} ${antwort.text}`}`)
+    await $.store.set(MERKZETTEL, { fehlerAm: jetzt } satisfies Merkzettel)
+    return
+  }
+  await $.store.set(MERKZETTEL, { tag: deutscherTag(jetzt), neueste: version } satisfies Merkzettel)
+  await update($, neueste, () => version)
+}
+
+/** Was die Leiste hinter der Fassung zeigt; `null` ohne Ablage (U-9). Schreibt nichts: Es wird gerade gezeichnet. */
+export async function updateZustand($: Engine, ablage: Ablage, claudeArbeitet: boolean): Promise<Zustand | null> {
+  const fassung = ablage.fassung
+  if (fassung === '') return null
+  // Erst danach, nie in diesem Zeichnen (es soll nicht auf npm warten, und schreiben darf es nicht). Am ersten Zeichnen
+  // statt an `session.start`: Den Start hört schon hooks/app-oeffnen.ts (je Ereignis ein Haken ohne Auswahl), und
+  // ohne Leiste — `claude -p`, Skripte — braucht niemand die Antwort von npm.
+  if (!angestossen) {
+    angestossen = true
+    $.clock.after(0, () => void beimLaden($, ablage).catch(f => protokoll($, `Update-Blick: ${String(f)}`)))
+  }
+  const jetzt = await $.clock.now()
+  const sperre = sperreAus(await $.store.get(SPERRE))
+  const laeuft = sperreGilt(sperre, jetzt, fassung)
+  const hier = await read($, lauf)
+  // „läuft“ aus diesem Fenster nur, solange die Sperre gilt: Sonst ist es liegen geblieben (der Lauf kam nie zu Ende,
+  // etwa weil der Mod mittendrin neu geladen wurde), und die Leiste zeigte für immer „wird installiert“.
+  if (hier !== null && (hier.art !== 'laeuft' || laeuft)) {
+    return hier.art === 'laeuft' || hier.art === 'geklappt' ? { fassung, art: hier.art, ziel: hier.ziel } : { fassung, art: hier.art }
+  }
+  // Aus einem anderen Fenster (oder vor dem Schließen): geklappt, aber noch nicht neu gestartet (U-6b) — oder es läuft (U-5).
+  const fertig = await $.store.get(FERTIG)
+  if (fertigGilt(fertig, jetzt, fassung)) return { fassung, art: 'geklappt', ziel: fertig.ziel }
+  if (sperre !== undefined && laeuft) return { fassung, art: 'laeuft', ziel: sperre.ziel }
+  // Kein Knopf, solange Claude antwortet (U-18): ein Klick mitten in einer Antwort stellte eine Frage quer dazu.
+  return istNeuer(await read($, neueste), fassung) && !claudeArbeitet ? { fassung, art: 'knopf' } : { fassung, art: 'still' }
+}
+
+/** Der Klick auf „Update installieren“ (Bauplan 1.3). */
+export async function updateInstallieren($: Engine, ablage: Ablage, sprache: Sprache): Promise<void> {
+  const t = TEXTE[sprache]
+  const fassung = ablage.fassung
+  const ziel = await read($, neueste)
+  if (beschaeftigt || !istNeuer(ziel, fassung)) return
+  beschaeftigt = true
+  try {
+    // K-4, U-10: Ohne npm-Pfad kein Direktbefehl — Claude bekommt die Bitte und fragt selbst um Erlaubnis.
+    const liste = befehle(ablage, ziel)
+    if (liste === null) {
+      await $.prompt.submit({ text: t.bitteOhneNpm(ziel) })
+      return
+    }
+    // U-3: Abbrechen, „Other“, eine Chat-Nachricht statt einer Antwort und das Wegklicken (Wurf): nichts passiert.
+    const antwort = await $.ui.ask(t.frage(fassung, ziel), [t.ja, t.nein]).catch(() => null)
+    if (antwort !== t.ja) return
+    // U-5: Während der Rückfrage kann ein anderes Fenster angefangen haben — dann zeigt auch dieses „wird installiert“.
+    const sperre = sperreAus(await $.store.get(SPERRE))
+    if (sperre !== undefined && sperreGilt(sperre, await $.clock.now(), fassung)) {
+      await update($, lauf, () => ({ art: 'laeuft', ziel: sperre.ziel, meldung: '' }))
+      return
+    }
+    if (await verboten($, ziel)) {
+      await update($, lauf, () => ({ art: 'gesperrt', ziel, meldung: '' }))
+      return
+    }
+    await ausfuehren($, ablage, liste, ziel)
+  } catch (fehler) {
+    // Etwa `$.store` scheitert (die Sperre lässt sich nicht schreiben): kein Erfolg und kein „gesperrt“, sondern ein Fehler mit Grund.
+    await update($, lauf, () => ({ art: 'fehler', ziel, meldung: meldungKurz(String(fehler)) }))
+  } finally {
+    beschaeftigt = false
+  }
+}
+
+/**
+ * U-4: Verbietet eine Erlaubnis-Regel einen der zwei Befehle in einem der zwei Werkzeuge? `ask` (der Normalfall im
+ * Auto-Modus, M-16) ist kein Verbot. ⚠️ Die Abfrage kennt nur die Regeln, nicht die PreToolUse-Hooks einer Firma und
+ * nicht den Prüfer des Auto-Modus (Typen von `ToolCheckResult.hook`; Bauplan Abschnitt 4).
+ * Gefragt werden nur Werkzeuge, die es hier gibt (ohne PowerShell etwa unter macOS); wirft die Liste, nur `Bash`. Eine
+ * Abfrage, die wirft, ist kein Verbot — nur ein ausgesprochenes `deny` sperrt; sonst hielte ein fehlendes Werkzeug
+ * jedes Update auf.
+ */
+async function verboten($: Engine, ziel: string): Promise<boolean> {
+  const da = await $.tool.list().then(liste => liste.map(w => w.name), () => ['Bash'])
+  for (const tool of WERKZEUGE.filter(w => da.includes(w))) {
+    for (const command of [`npm install -g kimal3@${ziel}`, 'kimal3 skill install']) {
+      const urteil = await $.tool.check({ tool, input: { command } }).catch((fehler: unknown) => {
+        protokoll($, `Regel-Abfrage ${tool}: ${String(fehler)}`)
+        return null
+      })
+      if (urteil?.decision === 'deny') return true
+    }
+  }
+  return false
+}
+
+/**
+ * Die drei Befehle nacheinander, jeder ohne Kommandozeile, im Ordner `~/.kimal3` (nie im Projekt: ein `.npmrc` dort
+ * gälte sonst mit). Scheitert eine Stufe, läuft die nächste nicht (U-6, U-7, U-7b). Die Sperre hält andere Fenster ab
+ * (U-5) und geht in `finally` weg — auch wenn ein Befehl wirft.
+ */
+async function ausfuehren($: Engine, ablage: Ablage, liste: string[][], ziel: string): Promise<void> {
+  await $.store.set(SPERRE, { ziel, seit: await $.clock.now() } satisfies Sperre)
+  await update($, lauf, () => ({ art: 'laeuft', ziel, meldung: '' }))
+  try {
+    const meldung = await stufen($, ablage.kimal3Ordner, liste, ziel).catch((fehler: unknown) => String(fehler))
+    if (meldung === null) {
+      // Bleibt stehen, bis ein Mod mit dieser Fassung lädt oder 24 Stunden um sind (beimLaden, `fertigGilt`): Erst der
+      // Neustart bringt Coach und Befehle.
+      await $.store.set(FERTIG, { ziel, am: await $.clock.now() } satisfies Fertig)
+      await update($, lauf, () => ({ art: 'geklappt', ziel, meldung: '' }))
+    } else {
+      await update($, lauf, () => ({ art: 'fehler', ziel, meldung: meldungKurz(meldung) }))
+    }
+  } finally {
+    await $.store.delete(SPERRE)
+  }
+}
+
+/** `null`: alle drei Stufen geklappt; sonst die Meldung der gescheiterten. */
+async function stufen($: Engine, ordner: string, [npm, version, skill]: string[][], ziel: string): Promise<string | null> {
+  const init = (minuten: number) => ({ cwd: ordner, timeoutMs: minuten * MINUTE })
+  const a = await $.process.run(npm, init(10))
+  if (a.exitCode !== 0) return `${a.stdout}\n${a.stderr}`
+  // Hat das npm dieses Node die Fassung wirklich dorthin gelegt, wo `kimal3` liegt? (Homebrew, Volta, A-8)
+  const b = await $.process.run(version, init(2))
+  if (b.exitCode !== 0 || !versionStimmt(b.stdout, ziel)) return `kimal3 --version:\n${b.stdout}\n${b.stderr}`
+  const c = await $.process.run(skill, init(2))
+  return c.exitCode !== 0 ? `${c.stdout}\n${c.stderr}` : null
+}
+
+/** „Claude fragen“ nach einem Fehlschlag: die Zielfassung und das Ende der Meldung (Bauplan 1.3 Punkt 6). */
+export async function updateClaudeFragen($: Engine, sprache: Sprache): Promise<void> {
+  const stand = await read($, lauf)
+  if (stand?.art === 'fehler') await $.prompt.submit({ text: TEXTE[sprache].bitteFehler(stand.ziel, stand.meldung) })
+}

package/claude-plugins/kimal3-logo/types/index.d.ts

@@ -7,6 +7,10 @@ declare module 'claude-code' {
       chatBenannt: boolean
       // Wie oft das Modell in dieser Sitzung schon gefragt wurde, ob das Thema klar ist (höchstens 8, B-8).
       benennenFragen: number
+      // Die neueste Fassung, die npm heute genannt hat ('' = keine bekannt); daraus zeichnet die Leiste den Knopf (hooks/update.ts).
+      updateNeueste: string
+      // Was der Klick in diesem Fenster angestoßen hat; `meldung` = Ende der Fehlermeldung für „Claude fragen“ (hooks/update.ts).
+      updateLauf: { art: 'laeuft' | 'geklappt' | 'fehler' | 'gesperrt'; ziel: string; meldung: string } | null
     }
   }
 }

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

@@ -0,0 +1,7 @@
+{
+  "name": "kimal3-plan",
+  "version": "0.1.0",
+  "description": "Hält das Board der Projektseite in der App aktuell: Punkt solange die Sitzung arbeitet, Spec-Texte, Erinnerung an Claude · Keeps the board on the app's project page current: dot while the session works, spec texts, reminder to Claude",
+  "author": { "name": "KImal3", "url": "https://kimal3.de" },
+  "types": "./types/index.d.ts"
+}

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

@@ -0,0 +1,79 @@
+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:
+ *
+ * - **Erinnerung ans Melden** haengt am Aendern einer Datei (`tool.call` mit `context`): keine eigene Runde, Claude liest
+ *   ihn direkt nach dem Werkzeug. Nur die Hauptsitzung bekommt ihn: Ein Subagent (`e.agentId`) baut im Auftrag und
+ *   meldet nicht; er wuerde die 30-Minuten-Sperre verbrauchen, ohne dass die Hauptsitzung je erinnert wird (Ruling). Hoechstens einmal je 30 Minuten je Sitzung, 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), schweigt er.
+ * - **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 ergebnis = await next(e)
+    // Abgelehnt oder gescheitert: Es hat sich nichts geaendert. Ein Subagent: nur die Hauptsitzung wird erinnert.
+    if (ergebnis.deny !== undefined || ergebnis.isError === true || e.agentId !== undefined) return ergebnis
+    const satz = await satzFuer($, lauf, dateiAus(e))
+    return satz === null ? ergebnis : { ...ergebnis, context: [...(ergebnis.context ?? []), 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
+  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) => `Du arbeitest im Projekt ${titel}, aber diese Sitzung hat keine Story ‚in Arbeit‘ gemeldet. Welche ist dran? Gehört die Änderung zu keiner Spec, notiere sie als Thema oder arbeite weiter.`,
+    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) => `You are working in the project ${titel}, but this session hasn't reported a story as ‘in progress’. Which one is it? If the change belongs to no spec, note it as a topic or keep working.`,
+    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)
+      },
+    )
+  })
+}