+
+package main
+
+import (
+ "context"
+ "fmt"
+ "path/filepath"
+ "strings"
+
+ "github.com/charmbracelet/bubbles/viewport"
+ tea "github.com/charmbracelet/bubbletea"
+ "github.com/charmbracelet/lipgloss"
+)
+
+// === Styles ===
+
+var (
+ // Tier header colors match the CLI formatter.
+ tierColors = [4]lipgloss.Color{
+ lipgloss.Color("#00FFFF"), // T0 cyan
+ lipgloss.Color("#00FF00"), // T1 green
+ lipgloss.Color("#FFFF00"), // T2 yellow
+ lipgloss.Color("#5555FF"), // T3 blue
+ }
+
+ tierNames = [4]string{"T0 Sentence", "T1 Paragraph", "T2 CogDoc", "T3 Raw"}
+
+ activeBorderStyle = lipgloss.NewStyle().
+ Border(lipgloss.RoundedBorder()).
+ BorderForeground(lipgloss.Color("#00FFFF"))
+
+ inactiveBorderStyle = lipgloss.NewStyle().
+ Border(lipgloss.RoundedBorder()).
+ BorderForeground(mutedColor)
+
+ decompTitleBarStyle = lipgloss.NewStyle().
+ Bold(true).
+ Foreground(lipgloss.Color("#FFFFFF")).
+ Background(lipgloss.Color("#7C3AED")).
+ Padding(0, 1)
+
+ metricsBarStyle = lipgloss.NewStyle().
+ Foreground(lipgloss.Color("#D1D5DB")).
+ Background(lipgloss.Color("#374151")).
+ Padding(0, 1)
+
+ helpBarStyle = lipgloss.NewStyle().
+ Foreground(mutedColor)
+
+ spinnerFrames = []string{"⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"}
+)
+
+// === Messages ===
+
+type decompDoneMsg struct {
+ result *DecompositionResult
+ err error
+}
+
+// === Model ===
+
+type decompTUIModel struct {
+ input *DecompInput
+ result *DecompositionResult
+ runner *DecompositionRunner
+ viewports [4]viewport.Model
+ active int // 0-3, which viewport has focus
+ running bool
+ err error
+ width int
+ height int
+ ready bool
+}
+
+func initialDecompTUIModel(input *DecompInput, result *DecompositionResult, runner *DecompositionRunner) decompTUIModel {
+ var vps [4]viewport.Model
+ for i := range vps {
+ vps[i] = viewport.New(40, 10)
+ }
+
+ m := decompTUIModel{
+ input: input,
+ result: result,
+ runner: runner,
+ viewports: vps,
+ active: 0,
+ }
+ if result != nil {
+ m.populateViewports()
+ }
+ return m
+}
+
+func (m *decompTUIModel) populateViewports() {
+ r := m.result
+ if r == nil {
+ return
+ }
+
+ // T0
+ if r.Tier0 != nil {
+ m.viewports[0].SetContent(r.Tier0.Summary)
+ } else {
+ m.viewports[0].SetContent("(not generated)")
+ }
+
+ // T1
+ if r.Tier1 != nil {
+ var sb strings.Builder
+ sb.WriteString(r.Tier1.Summary)
+ if len(r.Tier1.KeyTerms) > 0 {
+ sb.WriteString("\n\nKey terms: ")
+ sb.WriteString(strings.Join(r.Tier1.KeyTerms, ", "))
+ }
+ m.viewports[1].SetContent(sb.String())
+ } else {
+ m.viewports[1].SetContent("(not generated)")
+ }
+
+ // T2
+ if r.Tier2 != nil {
+ var sb strings.Builder
+ fmt.Fprintf(&sb, "Title: %s\n", r.Tier2.Title)
+ fmt.Fprintf(&sb, "Type: %s\n", r.Tier2.Type)
+ fmt.Fprintf(&sb, "Tags: %s\n", strings.Join(r.Tier2.Tags, ", "))
+ sb.WriteString("\n")
+ sb.WriteString(r.Tier2.Summary)
+ for _, s := range r.Tier2.Sections {
+ fmt.Fprintf(&sb, "\n\n## %s\n%s", s.Heading, s.Content)
+ }
+ if len(r.Tier2.Refs) > 0 {
+ sb.WriteString("\n\nRefs:")
+ for _, ref := range r.Tier2.Refs {
+ fmt.Fprintf(&sb, "\n %s (%s)", ref.URI, ref.Relation)
+ }
+ }
+ m.viewports[2].SetContent(sb.String())
+ } else {
+ m.viewports[2].SetContent("(not generated)")
+ }
+
+ // T3
+ if r.Tier3Raw != "" {
+ m.viewports[3].SetContent(r.Tier3Raw)
+ } else {
+ m.viewports[3].SetContent("(not generated)")
+ }
+}
+
+// === Bubbletea Interface ===
+
+func (m decompTUIModel) Init() tea.Cmd {
+ return nil
+}
+
+func (m decompTUIModel) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+ switch msg := msg.(type) {
+
+ case tea.KeyMsg:
+ switch msg.String() {
+ case "q", "ctrl+c":
+ return m, tea.Quit
+ case "tab":
+ m.active = (m.active + 1) % 4
+ return m, nil
+ case "shift+tab":
+ m.active = (m.active + 3) % 4
+ return m, nil
+ case "1":
+ m.active = 0
+ return m, nil
+ case "2":
+ m.active = 1
+ return m, nil
+ case "3":
+ m.active = 2
+ return m, nil
+ case "4":
+ m.active = 3
+ return m, nil
+ case "r":
+ if !m.running {
+ m.running = true
+ m.err = nil
+ return m, m.rerunCmd()
+ }
+ return m, nil
+ }
+
+ case tea.WindowSizeMsg:
+ m.width = msg.Width
+ m.height = msg.Height
+ m.ready = true
+ m.resizeViewports()
+ return m, nil
+
+ case decompDoneMsg:
+ m.running = false
+ if msg.err != nil {
+ m.err = msg.err
+ } else {
+ m.result = msg.result
+ m.populateViewports()
+ }
+ return m, nil
+ }
+
+ // Forward scroll events to the active viewport.
+ var cmd tea.Cmd
+ m.viewports[m.active], cmd = m.viewports[m.active].Update(msg)
+ return m, cmd
+}
+
+func (m *decompTUIModel) rerunCmd() tea.Cmd {
+ return func() tea.Msg {
+ result, err := m.runner.Run(context.Background(), m.input)
+ return decompDoneMsg{result: result, err: err}
+ }
+}
+
+func (m *decompTUIModel) resizeViewports() {
+ if m.width == 0 || m.height == 0 {
+ return
+ }
+ // Layout: title(1) + grid(2 rows) + metrics(1) + help(1) + borders
+ // Each panel has 2 lines of border (top+bottom) and 1 line header
+ panelW := (m.width - 1) / 2 // two columns, 1 char divider
+ contentW := panelW - 4 // border(2) + padding(2)
+ if contentW < 10 {
+ contentW = 10
+ }
+
+ // Vertical: title=1, metrics=1, help=1, two rows of panels
+ usableH := m.height - 3 // title + metrics + help
+ panelH := usableH / 2
+ contentH := panelH - 3 // border(2) + header(1)
+ if contentH < 2 {
+ contentH = 2
+ }
+
+ for i := range m.viewports {
+ m.viewports[i].Width = contentW
+ m.viewports[i].Height = contentH
+ }
+}
+
+func (m decompTUIModel) View() string {
+ if !m.ready {
+ return "Initializing..."
+ }
+
+ var sb strings.Builder
+
+ // Title bar
+ sourceName := "stdin"
+ if m.input.SourceURI != "" {
+ sourceName = filepath.Base(strings.TrimPrefix(m.input.SourceURI, "file://"))
+ }
+ title := fmt.Sprintf(" Decomposition Workbench — %s (%s bytes) ",
+ sourceName, decompFormatBytes(m.input.ByteSize))
+ titleBar := decompTitleBarStyle.Width(m.width).Render(title)
+ sb.WriteString(titleBar)
+ sb.WriteString("\n")
+
+ // 2x2 grid
+ panelW := (m.width - 1) / 2
+ if panelW < 12 {
+ panelW = 12
+ }
+
+ topRow := m.renderPanelRow(0, 1, panelW)
+ sb.WriteString(topRow)
+
+ bottomRow := m.renderPanelRow(2, 3, panelW)
+ sb.WriteString(bottomRow)
+
+ // Metrics bar
+ metrics := m.renderMetrics()
+ metricsBar := metricsBarStyle.Width(m.width).Render(metrics)
+ sb.WriteString(metricsBar)
+ sb.WriteString("\n")
+
+ // Help bar
+ help := "[r] Re-run [1-4] Focus tier [Tab] Next [q] Quit"
+ if m.running {
+ help = "Running... [q] Quit"
+ }
+ helpBar := helpBarStyle.Width(m.width).Render(help)
+ sb.WriteString(helpBar)
+
+ return sb.String()
+}
+
+func (m decompTUIModel) renderPanelRow(left, right, panelW int) string {
+ leftPanel := m.renderPanel(left, panelW)
+ rightPanel := m.renderPanel(right, panelW)
+ return lipgloss.JoinHorizontal(lipgloss.Top, leftPanel, " ", rightPanel) + "\n"
+}
+
+func (m decompTUIModel) renderPanel(idx, totalW int) string {
+ style := inactiveBorderStyle
+ if idx == m.active {
+ style = activeBorderStyle.BorderForeground(tierColors[idx])
+ }
+
+ headerStyle := lipgloss.NewStyle().Bold(true).Foreground(tierColors[idx])
+ header := headerStyle.Render(tierNames[idx])
+
+ content := header + "\n" + m.viewports[idx].View()
+
+ return style.Width(totalW - 2).Render(content)
+}
+
+func (m decompTUIModel) renderMetrics() string {
+ if m.err != nil {
+ return fmt.Sprintf("Error: %v", m.err)
+ }
+ if m.running {
+ return "Running decomposition..."
+ }
+ if m.result == nil {
+ return "No results yet"
+ }
+
+ r := m.result
+ parts := []string{
+ fmt.Sprintf("Total: %s", formatLatency(r.Metrics.TotalLatencyMs)),
+ }
+ if r.Metrics.CompressionRatio > 0 {
+ parts = append(parts, fmt.Sprintf("%.0f:1 compression", r.Metrics.CompressionRatio))
+ }
+ parts = append(parts, r.InputHash)
+ return strings.Join(parts, " | ")
+}
+
+// === Entry Point ===
+
+func runDecompWorkbench(input *DecompInput, runner *DecompositionRunner) error {
+ // Run initial decomposition before starting TUI
+ result, err := runner.Run(context.Background(), input)
+ if err != nil {
+ return fmt.Errorf("initial decomposition: %w", err)
+ }
+
+ m := initialDecompTUIModel(input, result, runner)
+ p := tea.NewProgram(m, tea.WithAltScreen())
+ _, err = p.Run()
+ return err
+}
diff --git a/decompose_tui_test.go b/decompose_tui_test.go
new file mode 100644
index 0000000..fdcc797
--- /dev/null
+++ b/decompose_tui_test.go
@@ -0,0 +1,97 @@
+package main
+
+import (
+ "testing"
+ "time"
+)
+
+func TestDecompTUIModelInit(t *testing.T) {
+ input := &DecompInput{
+ Text: "Test input for decomposition workbench.",
+ Format: "plaintext",
+ SourceURI: "file://test.md",
+ ByteSize: 39,
+ }
+
+ result := &DecompositionResult{
+ InputHash: "abc123def456",
+ InputSize: 39,
+ InputFormat: "plaintext",
+ SourceURI: "file://test.md",
+ Tier0: &Tier0Result{Summary: "A test summary."},
+ Tier1: &Tier1Result{
+ Summary: "A longer test summary with more detail.",
+ KeyTerms: []string{"test", "decomposition"},
+ },
+ Tier2: &Tier2Result{
+ Title: "Test Document",
+ Type: "knowledge",
+ Tags: []string{"test"},
+ Summary: "Test summary for tier 2.",
+ Sections: []Tier2Section{
+ {Heading: "Overview", Content: "Some content."},
+ },
+ },
+ Tier3Raw: "Test input for decomposition workbench.",
+ Metrics: DecompMetrics{
+ Tier0Tokens: 4,
+ Tier0LatencyMs: 100,
+ Tier1Tokens: 10,
+ Tier1LatencyMs: 200,
+ Tier2Tokens: 25,
+ Tier2LatencyMs: 500,
+ TotalLatencyMs: 800,
+ CompressionRatio: 2.6,
+ },
+ CreatedAt: time.Now(),
+ }
+
+ // Runner can be nil for init test — we only check model state.
+ m := initialDecompTUIModel(input, result, nil)
+
+ // Verify initial state
+ if m.active != 0 {
+ t.Errorf("expected active=0, got %d", m.active)
+ }
+ if m.running {
+ t.Error("expected running=false")
+ }
+ if m.err != nil {
+ t.Errorf("expected nil error, got %v", m.err)
+ }
+ if m.input != input {
+ t.Error("input not stored")
+ }
+ if m.result != result {
+ t.Error("result not stored")
+ }
+
+ // Verify viewports were populated
+ t0Content := m.viewports[0].View()
+ if t0Content == "" {
+ t.Error("T0 viewport should have content after populate")
+ }
+
+ // Init should return nil (no initial command)
+ cmd := m.Init()
+ if cmd != nil {
+ t.Error("Init() should return nil")
+ }
+}
+
+func TestDecompTUIModelNilResult(t *testing.T) {
+ input := &DecompInput{
+ Text: "Some text",
+ Format: "plaintext",
+ ByteSize: 9,
+ }
+
+ m := initialDecompTUIModel(input, nil, nil)
+
+ if m.result != nil {
+ t.Error("expected nil result")
+ }
+ if m.active != 0 {
+ t.Errorf("expected active=0, got %d", m.active)
+ }
+}
diff --git a/internal/engine/process.go b/internal/engine/process.go
index 46e26e5..c5109e1 100644
--- a/internal/engine/process.go
+++ b/internal/engine/process.go
@@ -28,9 +28,32 @@ import (
"sync"
"time"
+ "github.com/cogos-dev/cogos/trace"
"github.com/google/uuid"
)
+// TraceEmitter is the bus-publish hook for cycle-trace events. The main
+// package sets this at startup; engine calls it best-effort (never blocks
+// the metabolic cycle on a nil hook or a slow consumer).
+var TraceEmitter func(ev trace.CycleEvent)
+
+// TraceIdentity returns the identity name stamped as the `source` field on
+// emitted events. Set by the main package at startup; defaults to "cog".
+var TraceIdentity = func() string { return "cog" }
+
+// emitTrace is a best-effort wrapper around TraceEmitter that swallows
+// construction errors and never blocks the cycle.
+func emitTrace(ev trace.CycleEvent, err error) {
+ if err != nil {
+ slog.Debug("process: trace event build failed", "err", err)
+ return
+ }
+ if TraceEmitter == nil {
+ return
+ }
+ TraceEmitter(ev)
+}
+
// ProcessState represents the four operational states of the v3 process.
type ProcessState int
@@ -129,6 +152,16 @@ type Process struct {
// lastIndexHEAD tracks the HEAD hash at last index rebuild, so we skip
// rebuilding when nothing has changed.
lastIndexHEAD string
+
+ // currentCycleID correlates all cycle-trace events emitted during one
+ // iteration of the metabolic cycle (external event handling or a
+ // consolidation tick). Set fresh at the start of each iteration;
+ // protected by mu.
+ currentCycleID string
+
+ // hookRegistry holds ADR-072 state-transition hooks loaded from
+ // .cog/hooks/transitions/*.yaml. May be nil if the directory is missing.
+ hookRegistry *stateHookRegistry
}
// NewProcess constructs and initialises the process.
@@ -157,7 +190,16 @@ func NewProcess(cfg *Config, nucleus *Nucleus) *Process {
lastMaintenanceTick: now,
nodeHealth: NewNodeHealth(),
nodeManifest: loadManifestQuiet(cfg),
+ hookRegistry: loadStateHookRegistry(workspaceRootFromCfg(cfg)),
+ }
+}
+
+// workspaceRootFromCfg returns the workspace root from the config, or "" if nil.
+func workspaceRootFromCfg(cfg *Config) string {
+ if cfg == nil {
+ return ""
}
+ return cfg.WorkspaceRoot
}
// loadManifestQuiet loads the node manifest, returning nil if not found.
@@ -269,6 +311,23 @@ func (p *Process) Send(evt *GateEvent) bool {
}
}
+// SubmitExternal is the canonical entry point for external perturbations
+// (dashboard chat, modality inlets, etc.) into the metabolic cycle. It is a
+// non-blocking alias of Send(): the external channel has bounded capacity and
+// the cycle must never stall on a slow or noisy producer. Callers that need
+// backpressure should observe the returned bool and drop/log accordingly.
+func (p *Process) SubmitExternal(evt *GateEvent) bool {
+ if p == nil || evt == nil {
+ return false
+ }
+ select {
+ case p.externalCh <- evt:
+ return true
+ default:
+ return false
+ }
+}
+
// Run starts the continuous process loop. It blocks until ctx is cancelled.
func (p *Process) Run(ctx context.Context) error {
// Build CogDoc index first (fast — just frontmatter parsing).
@@ -414,8 +473,9 @@ func (p *Process) handleTailerBlock(block CogBlock) {
// handleExternal processes an external perturbation.
func (p *Process) handleExternal(evt *GateEvent) {
+ p.beginCycle()
result := p.gate.Process(evt)
- p.transition(result.StateTransition)
+ p.transitionWithReason(result.StateTransition, fmt.Sprintf("external:%s", evt.Type))
slog.Debug("process: external event",
"type", evt.Type,
"state", p.State(),
@@ -430,7 +490,8 @@ func (p *Process) handleExternal(evt *GateEvent) {
// Loop 2: the TrajectoryModel is updated (prediction + error computation)
// Loop 3: the model acts on the field (pre-warm, attenuate, coherence signal)
func (p *Process) runConsolidation() {
- p.transition(StateConsolidating)
+ p.beginCycle()
+ p.transitionWithReason(StateConsolidating, "consolidation.tick")
// Record the current tick window before updating the maintenance watermark.
now := time.Now()
@@ -534,7 +595,7 @@ func (p *Process) runConsolidation() {
"surprise": surprise,
})
- p.transition(StateReceptive)
+ p.transitionWithReason(StateReceptive, "consolidation.complete")
}
// NodeHealth returns the current node health state (for use by the serve layer).
@@ -572,7 +633,8 @@ func (p *Process) emitHeartbeat() {
p.TrustState.CoherenceFingerprint = coherenceHash
p.mu.Unlock()
- p.transition(StateDormant)
+ p.beginCycle()
+ p.transitionWithReason(StateDormant, "heartbeat")
state := p.State().String()
fieldSize := p.field.Len()
fingerprint := p.Fingerprint()
@@ -663,13 +725,51 @@ func (p *Process) emitHeartbeat() {
// transition moves the process to a new state (with logging).
func (p *Process) transition(next ProcessState) {
+ p.transitionWithReason(next, "")
+}
+
+// transitionWithReason is transition() with a human-readable reason string
+// that is attached to the emitted cycle-trace event. Best-effort emission:
+// a nil TraceEmitter or a build error never blocks the cycle.
+func (p *Process) transitionWithReason(next ProcessState, reason string) {
p.mu.Lock()
prev := p.state
p.state = next
+ cycleID := p.currentCycleID
p.mu.Unlock()
- if prev != next {
- slog.Debug("process: state transition", "from", prev, "to", next)
+ if prev == next {
+ return
}
+ slog.Debug("process: state transition", "from", prev, "to", next, "reason", reason)
+ if cycleID == "" {
+ // Fall back to a one-shot ID so events remain correlatable at least
+ // within this single transition; real iterations mint their own.
+ cycleID = uuid.NewString()
+ }
+ emitTrace(trace.NewStateTransition(TraceIdentity(), cycleID, prev, next, reason))
+ // ADR-072: dispatch per-state enter handlers + declarative StateHooks on a
+ // goroutine so transition() never blocks the caller (may hold p.mu upstream).
+ go p.dispatchEnterHandler(prev, next)
+}
+
+// beginCycle mints a new cycle ID for the start of a metabolic-cycle
+// iteration (consolidation tick or external event). All trace events emitted
+// during the iteration share this ID. Returns the new ID.
+func (p *Process) beginCycle() string {
+ id := uuid.NewString()
+ p.mu.Lock()
+ p.currentCycleID = id
+ p.mu.Unlock()
+ return id
+}
+
+// CurrentCycleID returns the current iteration's cycle ID (may be empty
+// between iterations). Exported so the agent harness and tool dispatch paths
+// can correlate their own trace events with the running kernel cycle.
+func (p *Process) CurrentCycleID() string {
+ p.mu.RLock()
+ defer p.mu.RUnlock()
+ return p.currentCycleID
}
// emitEvent records a ledger event for the process session.
diff --git a/internal/engine/transition_hooks.go b/internal/engine/transition_hooks.go
new file mode 100644
index 0000000..276428f
--- /dev/null
+++ b/internal/engine/transition_hooks.go
@@ -0,0 +1,330 @@
+// transition_hooks.go — ADR-072 state-transition hook dispatch.
+//
+// Implements the per-transition handler layer described in ADR-072
+// ("State-Transition Hooks for Node Lifecycle"). On every state change,
+// `transition()` invokes a per-state enter handler. Each handler:
+//
+// - Runs the minimum-viable per-ADR work inline (small, bounded).
+// - Dispatches any matching declarative StateHook definitions loaded from
+// `.cog/hooks/transitions/*.yaml`. Only the `shell:` form is implemented
+// at this revision — agent-form hooks (ADR-072 Phase 3) are loaded and
+// matched but logged as pending instead of executed.
+//
+// Non-goals of this file:
+// - Event-bus emission of transition records (owned by a sibling track).
+// - Full agent-subprocess spawning with budget/timeout (ADR-072 Phase 3).
+// - Condition evaluation beyond the scaffold (ADR-072 Phase 4).
+//
+// Concurrency: all handler bodies and hook executions run on goroutines
+// spawned by `transition()`. They must not take `p.mu`; they may read
+// immutable fields (cfg, sessionID) directly.
+package engine
+
+import (
+ "context"
+ "log/slog"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "sort"
+ "strings"
+ "sync"
+ "time"
+
+ "gopkg.in/yaml.v3"
+)
+
+// stateHook is the minimal in-memory representation of a StateHook YAML
+// definition. It covers both shell-form and agent-form hooks; only shell
+// execution is wired up at this revision.
+type stateHook struct {
+ Name string
+ From ProcessState
+ To ProcessState
+ Priority int
+ Async bool
+ Timeout time.Duration
+ Shell string // inline shell command (shell-form)
+ HasAgent bool // agent-form — loaded but not executed yet
+}
+
+// stateHookFile is the YAML wire format; see `.cog/hooks/transitions/*.yaml`.
+type stateHookFile struct {
+ Kind string `yaml:"kind"`
+ Metadata struct {
+ Name string `yaml:"name"`
+ } `yaml:"metadata"`
+ Spec struct {
+ Trigger struct {
+ From string `yaml:"from"`
+ To string `yaml:"to"`
+ } `yaml:"trigger"`
+ Priority int `yaml:"priority"`
+ Async bool `yaml:"async"`
+ Timeout string `yaml:"timeout"`
+ Shell string `yaml:"shell"`
+ Agent *struct {
+ Model string `yaml:"model"`
+ } `yaml:"agent"`
+ } `yaml:"spec"`
+}
+
+// stateHookRegistry holds the sorted list of hooks matching each (from,to) pair.
+type stateHookRegistry struct {
+ mu sync.RWMutex
+ hooks []stateHook
+}
+
+// loadStateHookRegistry loads StateHook YAML files from the given workspace.
+// Missing directory is a non-error (no hooks). Malformed files are skipped
+// with a warning; they must not block kernel startup.
+func loadStateHookRegistry(workspaceRoot string) *stateHookRegistry {
+ reg := &stateHookRegistry{}
+ if workspaceRoot == "" {
+ return reg
+ }
+ dir := filepath.Join(workspaceRoot, ".cog", "hooks", "transitions")
+ entries, err := os.ReadDir(dir)
+ if err != nil {
+ if !os.IsNotExist(err) {
+ slog.Debug("transition_hooks: registry dir read failed", "dir", dir, "err", err)
+ }
+ return reg
+ }
+ var loaded []stateHook
+ for _, e := range entries {
+ if e.IsDir() || !strings.HasSuffix(e.Name(), ".yaml") {
+ continue
+ }
+ path := filepath.Join(dir, e.Name())
+ raw, err := os.ReadFile(path)
+ if err != nil {
+ slog.Warn("transition_hooks: read failed", "file", e.Name(), "err", err)
+ continue
+ }
+ var f stateHookFile
+ if err := yaml.Unmarshal(raw, &f); err != nil {
+ slog.Warn("transition_hooks: parse failed", "file", e.Name(), "err", err)
+ continue
+ }
+ if f.Kind != "StateHook" {
+ continue
+ }
+ from, okF := parseProcessState(f.Spec.Trigger.From)
+ to, okT := parseProcessState(f.Spec.Trigger.To)
+ if !okF || !okT {
+ slog.Warn("transition_hooks: unknown trigger states", "file", e.Name(), "from", f.Spec.Trigger.From, "to", f.Spec.Trigger.To)
+ continue
+ }
+ to_ := stateHook{
+ Name: f.Metadata.Name,
+ From: from,
+ To: to,
+ Priority: f.Spec.Priority,
+ Async: f.Spec.Async,
+ Timeout: parseHookTimeout(f.Spec.Timeout),
+ Shell: strings.TrimSpace(f.Spec.Shell),
+ HasAgent: f.Spec.Agent != nil,
+ }
+ loaded = append(loaded, to_)
+ }
+ sort.SliceStable(loaded, func(i, j int) bool { return loaded[i].Priority < loaded[j].Priority })
+ reg.hooks = loaded
+ if len(loaded) > 0 {
+ slog.Info("transition_hooks: registry loaded", "count", len(loaded), "dir", dir)
+ }
+ return reg
+}
+
+func parseProcessState(s string) (ProcessState, bool) {
+ switch strings.ToLower(strings.TrimSpace(s)) {
+ case "active":
+ return StateActive, true
+ case "receptive":
+ return StateReceptive, true
+ case "consolidating":
+ return StateConsolidating, true
+ case "dormant":
+ return StateDormant, true
+ }
+ return 0, false
+}
+
+func parseHookTimeout(s string) time.Duration {
+ s = strings.TrimSpace(s)
+ if s == "" {
+ return 30 * time.Second
+ }
+ if d, err := time.ParseDuration(s); err == nil {
+ return d
+ }
+ // Accept bare integer (seconds), as ADR-072 example uses `timeout: 300`.
+ if d, err := time.ParseDuration(s + "s"); err == nil {
+ return d
+ }
+ return 30 * time.Second
+}
+
+// match returns the hooks registered for the given transition, in priority order.
+func (r *stateHookRegistry) match(from, to ProcessState) []stateHook {
+ r.mu.RLock()
+ defer r.mu.RUnlock()
+ var out []stateHook
+ for _, h := range r.hooks {
+ if h.From == from && h.To == to {
+ out = append(out, h)
+ }
+ }
+ return out
+}
+
+// runTransitionHooks executes all matching hooks for a (from,to) transition.
+// Always invoked in a goroutine from `transition()`. Honors each hook's
+// timeout; agent-form hooks are recognized but not executed at this revision
+// (see ADR-072 Phase 3).
+func (p *Process) runTransitionHooks(from, to ProcessState) {
+ if p.hookRegistry == nil {
+ return
+ }
+ hooks := p.hookRegistry.match(from, to)
+ if len(hooks) == 0 {
+ return
+ }
+ workspace := ""
+ sessionID := ""
+ if p.cfg != nil {
+ workspace = p.cfg.WorkspaceRoot
+ }
+ sessionID = p.sessionID
+ for _, h := range hooks {
+ switch {
+ case h.Shell != "":
+ p.execShellHook(h, from, to, workspace, sessionID)
+ case h.HasAgent:
+ // TODO: implement agent-subprocess spawn with budget+timeout per
+ // ADR-072 Phase 3. Until then, the declaration is honored only as
+ // telemetry so operators can see that a hook was registered.
+ slog.Info("transition_hooks: agent hook pending (ADR-072 Phase 3)",
+ "name", h.Name, "from", from, "to", to)
+ default:
+ slog.Debug("transition_hooks: hook has no executable body", "name", h.Name)
+ }
+ }
+}
+
+// execShellHook runs a `shell:` StateHook under a timeout. Environment
+// variables match the contract documented in `.cog/hooks/transitions/` YAML
+// files (COG_TRANSITION_FROM / _TO / COG_SESSION_ID / COG_WORKSPACE).
+func (p *Process) execShellHook(h stateHook, from, to ProcessState, workspace, sessionID string) {
+ timeout := h.Timeout
+ if timeout <= 0 {
+ timeout = 30 * time.Second
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), timeout)
+ defer cancel()
+ cmd := exec.CommandContext(ctx, "sh", "-c", h.Shell)
+ cmd.Env = append(os.Environ(),
+ "COG_TRANSITION_FROM="+from.String(),
+ "COG_TRANSITION_TO="+to.String(),
+ "COG_SESSION_ID="+sessionID,
+ "COG_WORKSPACE="+workspace,
+ )
+ if workspace != "" {
+ cmd.Dir = workspace
+ }
+ out, err := cmd.CombinedOutput()
+ if err != nil {
+ slog.Warn("transition_hooks: shell hook failed",
+ "name", h.Name, "err", err, "output", strings.TrimSpace(string(out)))
+ return
+ }
+ slog.Debug("transition_hooks: shell hook ok", "name", h.Name, "from", from, "to", to)
+}
+
+// ── Per-state enter handlers (ADR-072 §"Standard Hook Points") ──────────────
+//
+// Each handler runs off the main select loop on a goroutine spawned by
+// transition(). Handlers must be short (<~20 lines), non-blocking w.r.t.
+// the kernel tick cadence, and must not hold p.mu.
+//
+// The inline work done here is deliberately minimal. The bulk of per-state
+// behavior lives either (a) in the declarative StateHook YAML registry
+// dispatched above, or (b) in existing package logic that is not being
+// moved in this revision (runConsolidation remains ticker-driven until the
+// registry replaces it; see ADR-072 §"Migration Path" step 7).
+
+// enterActive fires on any → active. The kernel is processing an external
+// perturbation. Per ADR-072 "dormant → active: identity card reload, field
+// warm-up, session init". At this revision the field is kept warm by the
+// consolidation tick (runConsolidation calls p.field.Update), so no
+// additional inline work is required — matching hooks in the registry
+// (e.g., a future `identity-reload.yaml`) are dispatched by the caller.
+func (p *Process) enterActive(from ProcessState) {
+ // intentionally minimal per ADR-072 §Standard Hook Points (row: dormant→active)
+ // TODO: migrate identity-card reload here once the agent-hook executor lands
+ // (ADR-072 Phase 3). Until then, any declarative hook file in
+ // .cog/hooks/transitions/ with trigger from=* to=active fires via
+ // runTransitionHooks.
+ _ = from
+}
+
+// enterReceptive fires on any → receptive. This is the idle/alert baseline
+// state. Per ADR-072 "consolidating → receptive: light cone pruning, index
+// rebuild, ResourcePressure update". Index rebuild is already performed by
+// runConsolidation before it transitions to Receptive, so the inline body
+// here stays empty to avoid duplicate work; matching registry hooks still
+// fire.
+func (p *Process) enterReceptive(from ProcessState) {
+ // intentionally no-op per ADR-072 §"Migration Path" step 1:
+ // existing ticker logic remains authoritative until hooks replace it.
+ _ = from
+}
+
+// enterConsolidating fires on any → consolidating. Per ADR-072
+// "active → consolidating: session review, journal write, turn metric
+// aggregation". The heavyweight consolidation work (field update, index
+// rebuild, coherence check, observer cycle, consolidation CogDoc write)
+// is already performed by runConsolidation() which is invoked on the
+// consolidationTicker path; duplicating it here would double the work on
+// ticker-driven transitions. Instead the declarative hooks
+// (session-review.yaml, log-transition.yaml) carry the per-session
+// journaling, dispatched via runTransitionHooks.
+func (p *Process) enterConsolidating(from ProcessState) {
+ // intentionally minimal per ADR-072 §"Migration Path" step 7 — hook
+ // dispatch is the new trigger surface; runConsolidation() still owns
+ // the in-kernel pass until its logic is migrated into hook definitions.
+ _ = from
+}
+
+// enterDormant fires on any → dormant. Per ADR-072 "receptive → dormant:
+// deep consolidation, embedding refresh, sleep-time compute". At this
+// revision the only inline work is recording the transition timestamp as
+// the last consolidation watermark when a full consolidation has not run
+// recently, so the next heartbeat's consolidation gate triggers correctly.
+// Expensive resource-release work (model refs, embedding reloads) is
+// delegated to declarative hooks.
+func (p *Process) enterDormant(from ProcessState) {
+ // No-op inline body: heartbeat path already handles dormant cadence
+ // and consolidation gating (see emitHeartbeat). Matching registry
+ // hooks (future on-dormant.yaml) handle deep-sleep work.
+ // TODO: once ADR-072 Phase 3 lands, move expensive resource-release
+ // calls into a declarative agent hook rather than inline Go.
+ _ = from
+}
+
+// dispatchEnterHandler routes to the correct enter handler for the target
+// state. Called from transition() on a goroutine; runs both the inline
+// handler and the declarative-hook dispatch for (from,to).
+func (p *Process) dispatchEnterHandler(from, to ProcessState) {
+ switch to {
+ case StateActive:
+ p.enterActive(from)
+ case StateReceptive:
+ p.enterReceptive(from)
+ case StateConsolidating:
+ p.enterConsolidating(from)
+ case StateDormant:
+ p.enterDormant(from)
+ }
+ p.runTransitionHooks(from, to)
+}
diff --git a/internal/engine/web/dashboard.html b/internal/engine/web/dashboard.html
index a2c46fa..a2b9bac 100644
--- a/internal/engine/web/dashboard.html
+++ b/internal/engine/web/dashboard.html
@@ -332,6 +332,19 @@
}
.cogdoc-viewer-overlay.open { display: block; }
+/* ── Decompose Panel ── */
+.decomp-row {
+ padding: 6px 8px; border-radius: 4px; margin-bottom: 4px;
+ background: var(--bg-elevated); border: 1px solid var(--border);
+ font-family: var(--font-mono); font-size: 11px; line-height: 1.5;
+}
+.decomp-row .decomp-hash { color: var(--accent); }
+.decomp-row .decomp-tier { color: var(--text-dim); }
+.decomp-row .decomp-total { color: var(--text); font-weight: 600; }
+.decomp-row.ratio-high { border-left: 3px solid var(--green); }
+.decomp-row.ratio-mid { border-left: 3px solid var(--yellow); }
+.decomp-row.ratio-low { border-left: 3px solid var(--text-dim); opacity: 0.7; }
+
/* ── Proprioceptive Panel ── */
.proprio-section {
margin-bottom: 20px;
@@ -446,6 +459,7 @@ CogOS v3--
--
field: --
+ agent: --
@@ -466,6 +480,8 @@ CogOS v3Metrics
Settings
Proprioceptive
+ Decompose
+ Agent
@@ -580,6 +596,101 @@
CogOS v3
+
+
Recent Decompositions
+
+ No decompositions recorded yet
+
+
+
+
+
+
+ Agent Status
+ ▶ Trigger Cycle
+
+
+
+ Model: --
+ Uptime: --
+ Interval: --
+ Cycles: --
+
+
+
+ --
+ u=--
+
+
--
+
--
+
+
+
+
+
+
+
System Activity
+
+
+ User: --
+ Claude Code: --
+ Event delta: --
+ Hottest: --
+
+
+
+
+
+
+
+
+
+
Rolling Memory (Tier 0)
+
+ No memory entries yet
+
+
+
+
+
+
Pending Proposals
+
+ No pending proposals
+
+
+
+
+
+
Link Feed
+
+
+ Last pull: --
+ Next: --
+ Raw: --
+ Enriched: --
+ Failed: --
+ Total: --
+
+
+
+
+
+
+
+
+
Cycle Traces
+
+ No traces yet
+
+
+
CogOS v3No decompositions recorded yet
';
+ return;
+ }
+
+ let html = '';
+ for (const evt of events) {
+ const p = evt.payload || evt;
+ const hash = (p.input_hash || '--').substring(0, 10);
+ const ratio = p.compression_ratio || 0;
+ const ratioClass = ratio > 100 ? 'ratio-high' : (ratio >= 50 ? 'ratio-mid' : 'ratio-low');
+ const ts = evt.ts ? new Date(evt.ts).toLocaleTimeString() : '--';
+
+ html += ''
+ + '[' + ts + '] '
+ + '' + hash + '... '
+ + 'T0: ' + (p.tier0_tokens || 0) + 'tok ' + fmtLatency(p.tier0_latency_ms) + ' '
+ + ' | T1: ' + (p.tier1_tokens || 0) + 'tok ' + fmtLatency(p.tier1_latency_ms) + ' '
+ + ' | T2: ' + (p.tier2_tokens || 0) + 'tok ' + fmtLatency(p.tier2_latency_ms) + ' '
+ + 'Total: ' + fmtLatency(p.total_latency) + ' '
+ + (ratio > 0 ? ' | ' + Math.round(ratio) + ':1 ' : '')
+ + (p.schema_conformant === false ? ' | retry ' : '')
+ + '
';
+ }
+ container.innerHTML = html;
+}
+
+// Hook tab switching to trigger decompose/agent refresh
+document.querySelectorAll('.panel-tab').forEach(tab => {
+ tab.addEventListener('click', () => {
+ if (tab.dataset.tab === 'decompose') refreshDecompositions();
+ if (tab.dataset.tab === 'agent') refreshAgent();
+ });
+});
+
+function startDecompPolling() {
+ if (decompRefreshTimer) return;
+ decompRefreshTimer = setInterval(() => {
+ const tab = document.querySelector('.panel-tab[data-tab="decompose"]');
+ if (tab && tab.classList.contains('active')) {
+ refreshDecompositions();
+ }
+ }, 15000);
+}
+
+// ── Agent Panel ──
+const actionColors = {
+ sleep: '#4ade80', observe: '#facc15', consolidate: '#60a5fa',
+ propose: '#c084fc', repair: '#f97316', escalate: '#f87171',
+ skip: '#6b7280', error: '#ef4444'
+};
+
+let agentRefreshTimer = null;
+let urgencyHistory = [];
+let lastTraceHash = '';
+
+async function refreshAgent() {
+ try {
+ const res = await fetch(API + '/v1/agent/status');
+ if (!res.ok) return;
+ const d = await res.json();
+ renderAgentPill(d);
+ renderAgentStatus(d);
+ renderAgentActivity(d.activity);
+ renderAgentMemory(d.memory);
+ renderAgentProposals(d.proposals);
+ renderAgentInbox(d.inbox);
+ if (d.last_urgency != null && d.cycle_count > 0) {
+ urgencyHistory.push(d.last_urgency);
+ if (urgencyHistory.length > 20) urgencyHistory.shift();
+ renderUrgencySparkline();
+ }
+ // Fetch traces when Agent tab is active
+ const agentTab = document.querySelector('.panel-tab[data-tab="agent"]');
+ if (agentTab && agentTab.classList.contains('active')) {
+ refreshAgentTraces();
+ }
+ } catch {}
+}
+
+async function refreshAgentTraces() {
+ try {
+ const res = await fetch(API + '/v1/agent/traces');
+ if (!res.ok) return;
+ const traces = await res.json();
+ // Only re-render if data changed — avoids collapsing open
+ const hash = JSON.stringify(traces.map(t => t.cycle + ':' + t.action));
+ if (hash === lastTraceHash) return;
+ lastTraceHash = hash;
+ renderAgentTraces(traces);
+ } catch {}
+}
+
+function renderAgentTraces(traces) {
+ const container = document.getElementById('agent-traces');
+ if (!traces || traces.length === 0) {
+ container.innerHTML = 'No traces yet
';
+ return;
+ }
+ // Show most recent first
+ let html = '';
+ for (let i = traces.length - 1; i >= 0; i--) {
+ const t = traces[i];
+ const color = actionColors[t.action] || '#888';
+ const ago = t.timestamp ? timeSince(new Date(t.timestamp)) : '--';
+ const hasResult = t.result && t.result.length > 0;
+ const id = `trace-${t.cycle}`;
+ html += ``;
+ html += ``;
+ html += `${t.action} `;
+ html += ` u=${t.urgency.toFixed(1)} · ${ago} ago · ${t.duration_ms}ms `;
+ if (hasResult) html += ` ▸ has result `;
+ html += ` `;
+ html += ``;
+ html += `
Reason: ${esc(t.reason)}
`;
+ if (t.target) html += `
Target: ${esc(t.target)}
`;
+ if (hasResult) {
+ html += `
Execute Result:
`;
+ html += `
${esc(t.result)} `;
+ }
+ html += `
Observation (${t.observation.length} chars) `;
+ html += `${esc(t.observation)} `;
+ html += ``;
+ html += `
`;
+ }
+ container.innerHTML = html;
+}
+
+function renderAgentPill(d) {
+ const pill = document.getElementById('pill-agent');
+ if (!d.alive) {
+ pill.textContent = 'agent: --';
+ pill.className = 'pill warn';
+ return;
+ }
+ const action = d.last_action || '--';
+ const color = actionColors[action] || '#888';
+ if (d.last_cycle) {
+ const ago = timeSince(new Date(d.last_cycle));
+ pill.textContent = `▲ ${d.cycle_count} · ${ago}`;
+ pill.className = 'pill ok';
+ // Warn if stale (>2x interval)
+ const intervalSec = parseInterval(d.interval);
+ const ageSec = (Date.now() - new Date(d.last_cycle).getTime()) / 1000;
+ if (ageSec > intervalSec * 2.5) pill.className = 'pill warn';
+ } else {
+ pill.textContent = `▲ ${d.cycle_count}`;
+ pill.className = 'pill ok';
+ }
+}
+
+function renderAgentStatus(d) {
+ document.getElementById('agent-model').textContent = d.model || '--';
+ document.getElementById('agent-uptime').textContent = d.uptime || '--';
+ document.getElementById('agent-interval').textContent = d.interval || '--';
+ document.getElementById('agent-cycles').textContent = d.cycle_count || '0';
+
+ const actionEl = document.getElementById('agent-last-action');
+ const action = d.last_action || '--';
+ actionEl.textContent = action;
+ actionEl.style.color = actionColors[action] || 'var(--text)';
+
+ document.getElementById('agent-last-urgency').textContent = `u=${(d.last_urgency || 0).toFixed(1)}`;
+ document.getElementById('agent-last-reason').textContent = d.last_reason || '--';
+
+ if (d.last_cycle) {
+ const ago = timeSince(new Date(d.last_cycle));
+ document.getElementById('agent-last-time').textContent = `${ago} ago · ${d.last_duration_ms}ms`;
+ }
+}
+
+function renderAgentActivity(a) {
+ if (!a) return;
+ const userEl = document.getElementById('activity-user');
+ userEl.textContent = `${a.user_presence} (${a.user_last_event_ago || '--'} ago)`;
+ userEl.style.color = a.user_presence === 'active' ? '#4ade80' : a.user_presence === 'recent' ? '#facc15' : 'var(--text-dim)';
+
+ const ccEl = document.getElementById('activity-cc');
+ ccEl.textContent = a.claude_code_active > 0 ? `${a.claude_code_active} (${a.claude_code_events} events)` : 'none';
+
+ document.getElementById('activity-delta').textContent = `${a.total_event_delta} events`;
+ document.getElementById('activity-hottest').textContent = a.hottest_bus ? `${a.hottest_bus} (${a.hottest_delta})` : '--';
+}
+
+function renderAgentMemory(mem) {
+ const container = document.getElementById('agent-memory');
+ if (!mem || mem.length === 0) {
+ container.innerHTML = 'No memory entries yet
';
+ return;
+ }
+ let html = '';
+ for (const entry of mem) {
+ const color = actionColors[entry.action] || '#888';
+ html += ``;
+ html += `
${entry.action} `;
+ html += `
u=${entry.urgency.toFixed(1)} · ${entry.ago} ago `;
+ html += `
${esc(entry.sentence)}
`;
+ html += '
No pending proposals
';
+ return;
+ }
+ let html = '';
+ for (const p of proposals) {
+ html += ``;
+ html += `
[${esc(p.type)}] `;
+ html += `
${esc(p.title)} `;
+ html += `
urgency: ${p.urgency} · ${p.created || '--'}
`;
+ html += '
Recent Enrichments
';
+ for (const e of inbox.recent_enrichments) {
+ const connColor = e.connections > 0 ? 'var(--green)' : 'var(--text-dim)';
+ html += ``;
+ html += `${esc(e.title)} `;
+ html += ` ${e.connections} conn `;
+ html += ` ${e.ago} ago `;
+ html += '
';
+ }
+ recentEl.innerHTML = html;
+ } else {
+ recentEl.innerHTML = '';
+ }
+}
+
+function renderUrgencySparkline() {
+ const svg = document.getElementById('agent-sparkline');
+ if (!svg || urgencyHistory.length < 2) return;
+ const w = svg.clientWidth || 300;
+ const h = 40;
+ const padding = 2;
+ const points = urgencyHistory.map((u, i) => {
+ const x = padding + (i / (urgencyHistory.length - 1)) * (w - padding * 2);
+ const y = h - padding - (u * (h - padding * 2));
+ return `${x},${y}`;
+ });
+ // Color gradient based on latest urgency
+ const latest = urgencyHistory[urgencyHistory.length - 1];
+ const color = latest > 0.7 ? '#f87171' : latest > 0.3 ? '#facc15' : '#4ade80';
+ svg.innerHTML = `
+