run: guard empty text part in runAgent + drop cross-repo doc ref (gadfly #16)

Every reviewer flagged that runAgent appended llm.Text(input) unconditionally, so
an image-only run (blank prompt) emitted an empty TextPart — inconsistent with the
sibling runSession.AttachImages which guards it. Mirror that guard
(strings.TrimSpace(input) != ""). Also:
- copy opts before appending (variadic backing array can have spare capacity; avoid
  aliasing a caller's slice).
- reword the doc comment to drop the mort-agentexec reference (executus is a
  standalone lib; a consumer name doesn't belong in its godoc).

Tests: image+text are co-located in ONE user message; an image-only run emits no
blank TextPart.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitea/workflows/adversarial-review.yml

@@ -1,11 +1,8 @@
-# Gadfly — agentic adversarial PR reviewer (https://gitea.stevedudenhoeffer.com/steve/gadfly).
-#
-# Runs the published Gadfly image (pinned to an immutable :sha- tag — act_runner
-# caches :latest, and this build is what carries foreman provider-type support)
-# as a specialist swarm and posts
-# ONE consolidated review comment as gitea-actions. Advisory only — never blocks a
-# merge. This reviews executus PRs with 3 ollama-cloud models (3-lens suite). Gadfly
-# is a simple system — findings are advisory; always double-check before acting.
+# Gadfly adversarial review — subscribes to steve/gadfly's reusable workflow and
+# INHERITS its default swarm. This stub holds only the triggers, the actor gate,
+# secret forwarding, and the allow-list; the swarm config (models, lenses,
+# concurrency, timeouts) lives centrally in gadfly's review-reusable.yml so it is
+# tuned in ONE place. Advisory only — never blocks a merge.
 
 name: Adversarial Review (Gadfly)
 
@@ -32,48 +29,26 @@ concurrency:
 jobs:
   review:
     # Security: only trusted users may trigger a secret-bearing run via a PR
-    # comment (pull_request + workflow_dispatch are already trusted). Mirrors
-    # GADFLY_ALLOWED_USERS, the in-container belt-and-suspenders check.
+    # comment (pull_request + workflow_dispatch are already trusted). Mirrors the
+    # allowed_users input below (the in-container belt-and-suspenders check) — both
+    # lists must stay in sync; a workflow if: can't read a workflow_call input.
     if: >-
       github.event_name != 'issue_comment'
       || (github.event.issue.pull_request
           && (github.actor == 'steve'
               || github.actor == 'fizi'
               || github.actor == 'dazed'))
-    runs-on: ubuntu-latest
-    # 3 cloud models, all concurrent, 3-lens suite. ~12 min typical.
-    timeout-minutes: 30
-    steps:
-      - uses: docker://gitea.stevedudenhoeffer.com/steve/gadfly:sha-d0de034
-        env:
-          GITEA_API: ${{ github.server_url }}/api/v1/repos/${{ github.repository }}
-          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
-          OLLAMA_CLOUD_API_KEY: ${{ secrets.OLLAMA_CLOUD_API_KEY }}
-          # executus uses CLOUD MODELS ONLY. The local Macs (m1/m5) were dropped:
-          # on a P2-review measurement they took 26–29 min (with lens timeouts)
-          # and contributed ZERO real findings — the two cloud models found every
-          # genuine bug in 6–12 min. Cloud-only is faster AND higher-signal.
-          # 3 cloud models. Concurrency now lives in the LENSES, not the models:
-          # one model runs at a time (PROVIDER_CONCURRENCY=1) with its 3 lenses
-          # concurrent (PROVIDER_LENS_CONCURRENCY=3). So the first model's
-          # comment lands sooner and each model finishes a bit faster, at the
-          # cost of the other two models' comments arriving in series after it.
-          GADFLY_MODELS: "minimax-m3:cloud,deepseek-v4-flash:cloud,glm-5.2:cloud"
-          GADFLY_PROVIDER_CONCURRENCY: "ollama-cloud=1"
-          GADFLY_PROVIDER_LENS_CONCURRENCY: "ollama-cloud=3"
-          # Default => the 3-lens suite (security, correctness, error-handling).
-          # Set the repo var GADFLY_SPECIALISTS to override (csv / "all" / "auto").
-          GADFLY_SPECIALISTS: ${{ vars.GADFLY_SPECIALISTS || 'security,correctness,error-handling' }}
-          # Per-lens deadline + bounded steps so the slow local models stay sane.
-          GADFLY_TIMEOUT_SECS: "600"
-          GADFLY_MAX_STEPS: "14"
-          # Allow-list for the comment trigger (mirrors the job-level if: guard).
-          GADFLY_ALLOWED_USERS: "steve,fizi,dazed"
-          # --- event context (leave as-is) ---
-          EVENT_NAME: ${{ github.event_name }}
-          PR: ${{ github.event.pull_request.number || github.event.issue.number || github.event.inputs.pr_number }}
-          PR_BRANCH: ${{ github.head_ref }}
-          IS_DRAFT: ${{ github.event.pull_request.draft }}
-          COMMENT_BODY: ${{ github.event.comment.body }}
-          COMMENT_ID: ${{ github.event.comment.id }}
-          ACTOR: ${{ github.actor }}
+    # Tracks gadfly's v1 release tag — a curated pointer re-moved on each release
+    # (unlike @main, which moves on every push). Central swarm tuning propagates
+    # here automatically; the tradeoff vs a full sha pin is that v1 is mutable.
+    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@v1
+    # Least privilege: forward only the review secrets (not `secrets: inherit`,
+    # which would expose every repo secret). GITEA_TOKEN is the automatic token.
+    secrets:
+      OLLAMA_CLOUD_API_KEY:    ${{ secrets.OLLAMA_CLOUD_API_KEY }}
+      CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+      GADFLY_FINDINGS_URL:     ${{ secrets.GADFLY_FINDINGS_URL }}
+      GADFLY_FINDINGS_TOKEN:   ${{ secrets.GADFLY_FINDINGS_TOKEN }}
+    with:
+      # Consumer-specific allow-list; everything else is inherited.
+      allowed_users: "steve,fizi,dazed"

.gitea/workflows/ci.yml

@@ -103,3 +103,26 @@ jobs:
             exit 1
           fi
           echo "OK: core go.sum is free of host/DB dependencies."
+
+      - name: Light-tier canary imports no battery
+        run: |
+          # examples/reviewer is gadfly's shape on the CORE only. If it ever
+          # pulls in a battery (audit/budget/persona/skill/critic/schedule/
+          # checkpoint/contrib), the light path has regressed.
+          LEAK=$(go list -deps ./examples/reviewer/... | grep -E 'executus/(audit|budget|persona|skill|critic|schedule|checkpoint|contrib)' || true)
+          if [ -n "$LEAK" ]; then
+            echo "ERROR: light-tier canary pulled in a battery:"; echo "$LEAK"; exit 1
+          fi
+          echo "OK: examples/reviewer is core-only."
+
+      - name: contrib/store (nested SQLite module — isolated from core)
+        run: |
+          # contrib/store is a SEPARATE module carrying modernc.org/sqlite; the
+          # core's `go test ./...` doesn't reach it. Build + test it on its own,
+          # and confirm it DOES carry the driver the core forbids (proof the
+          # split works: persistence lives here, not in the core go.sum).
+          cd contrib/store
+          go build ./...
+          go test -race -count=1 -timeout 5m ./...
+          grep -qE 'modernc.org/sqlite' go.sum || { echo "ERROR: contrib/store should carry the sqlite driver"; exit 1; }
+          echo "OK: contrib/store builds, tests pass, and owns the SQLite dep."

CLAUDE.md

@@ -47,9 +47,10 @@ CORE (majordomo + stdlib):
             toolbox + majordomo loop + compaction +
             run-bounding (V10 detached timeout) + step/
             audit observers + Budget gate; RunnableAgent
-            DTO + nil-safe run.Ports. Follow-ups: wire
-            Critic/Checkpointer/PaletteSource/Delivery,
-            Phases, and the no-tools direct path         [P2]
+            DTO + nil-safe run.Ports. Palette delegation +
+            Critic (monitor/deadline/steer) + Delivery
+            WIRED. Follow-ups: Checkpointer (needs a
+            majordomo msg-history hook), Phases           [C0c]
   dispatchguard/  loop/depth/fan-out caps                [P0 ✓]
   pendingattach/  attachment dedupe                      [P0 ✓]
   tool/     registry + 3-stage permissions + ssrf        [P1 ✓]
@@ -58,30 +59,42 @@ CORE (majordomo + stdlib):
              structured output — no separate structured/ pkg)
   llmmeta/  shared meta-LLM helper over model/            [P1 ✓]
   compact/  context compactor (WithCompactor hook)       [P2 ✓]
-  tools/    generic tool library: Register (think/now/    [P3 wip]
+  tools/    generic tool library: Register (think/now/    [P3 ✓]
             cite, zero-config) + RegisterMeta (classify/
             extract_entities/summarize) + RegisterStore
             (kv_*/file_*, default static quota); seams in
             research_providers.go/file_storage.go/
             kv_storage.go/quota_provider.go. End-to-end
-            "agent calls a tool" test green. Remaining:
-            web/net/compose groups + default backends     [P3]
+            "agent calls a tool" test green. Remaining
+            (deferred): web/net/compose groups + backends
 
 BATTERIES (opt-in siblings, each nil-safe + a default):
-  persona/   Agent noun + Storage seam + builtin loader [P4 ~]
+  persona/   Agent noun + Storage seam + builtin loader [P4 ✓]
              + ToRunnable() bridge to run.RunnableAgent +
              Memory default (host: chatbot/commands/personalization)
-  skill/     rich Skill + SkillStore seam + toml loader  [P4]
+  skill/     Skill noun + LEAN SkillStore (lifecycle/    [P4 ✓]
+             versions/schedule, NOT mort's 60-method
+             monster) + ToRunnable + Memory default
   audit/     run.Audit Sink + Writer + queryable Memory  [P4 ✓]
              default (skillaudit Storage iface; GORM stays in mort)
-  critic/    two-tier timeout state machine + Escalator  [P4]
-  schedule/  cron runner cores                           [P4]
-  checkpoint/ durable resume seam                        [P4]
+  critic/    two-tier timeout watchdog (run.Critic) +    [P4 ✓]
+             Escalator policy seam + ExtendOnce default
+  schedule/  generic cron Runner (Tick/Loop over a wired [P4 ✓]
+             Due/Run/Mark/Next; no cron grammar of its own)
+  checkpoint/ CheckpointStore + run.Checkpointer handle  [P4 ✓]
+             (throttled Save/Complete/Fail) + Memory
   budget/    DBBudget rolling-7d + NoOp (run.Budget);    [P4 ✓]
              BudgetStorage iface + Memory default
 
-contrib/store/   SECOND module (+ modernc.org/sqlite):   [P4]
-  in-memory + pure-Go SQLite impls of every *Store seam
+contrib/store/   SECOND module (+ modernc.org/sqlite):   [P4 ✓]
+  pure-Go SQLite impls of ALL store seams: budget +
+  persona + skill + audit (JSON-blob+indexed cols,
+  round-trip tested). CI proves the driver lands HERE,
+  not in the core go.sum.
+
+NOTE: critic/checkpoint executor wiring (run.Ports.Critic /
+.Checkpointer call sites) is a P2 follow-up — the batteries +
+defaults exist ahead of that wiring.
 ```
 
 ### The one architectural move
@@ -103,7 +116,7 @@ repackaging.
 
 P0 module + zero-coupling moves + core seams (this) → P1 tool registry + model →
 P2 run kernel + Ports inversion → P3 generic tools + defaults → P4 persona/skill
-redesign + batteries + SQLite store → P5 gadfly on core (light-tier canary) → P6
+redesign + batteries + SQLite store → P5 gadfly-on-core canary (examples/reviewer ✓) → P6
 rewire mort + tag v0.1.0. The mort-side rewrite reuses mort's existing
 `mort_*_adapters.go` wall as the host adapter layer.
 

README.md

@@ -48,6 +48,9 @@ bot) — mort and gadfly are the first two consumers (heavy and light). See
 - `config/`, `deliver/`, `identity/` — host seams (config / output / identity),
   each with a shipped default.
 - `dispatchguard/`, `pendingattach/` — run-safety primitives.
+- `examples/reviewer` — a **gadfly-shaped PR reviewer on the core only** (env-config
+  model fleet → `fanout` N×M swarm → `model.GenerateWith[T]` structured findings →
+  consolidation), the light-tier canary; CI asserts it pulls in no battery.
 
 ## Design
 

checkpoint/checkpoint.go

@@ -0,0 +1,50 @@
+// Package checkpoint is the durable-resume battery: it persists a run's
+// resumable progress so a run interrupted by a shutdown can be recovered and
+// continued on the next boot, rather than silently lost. It plugs into
+// run.Ports.Checkpointer.
+//
+// Mort backs CheckpointStore with its durable-job table; Memory() is the
+// zero-dependency default; contrib/store can add a SQLite one. NOTE: the
+// executor's call into run.Ports.Checkpointer is a P2 follow-up — this battery
+// provides the seam + impls ahead of that wiring.
+package checkpoint
+
+import (
+	"context"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// RunCheckpointMeta is the run attribution needed to resume a run from scratch
+// (mirrors mort's agentexec.RunCheckpointMeta).
+type RunCheckpointMeta struct {
+	RunID       string
+	AgentID     string
+	AgentName   string
+	CallerID    string
+	ChannelID   string
+	GuildID     string
+	Prompt      string
+	ModelTier   string
+	ParentRunID string
+}
+
+// RunCheckpoint is one persisted snapshot of a run's resumable progress.
+type RunCheckpoint struct {
+	Meta        RunCheckpointMeta
+	Messages    []llm.Message // conversation so far
+	Iteration   int           // completed agent-loop iterations
+	ActivePhase string        // current phase name (multi-phase agents); "" otherwise
+	UpdatedAt   time.Time
+}
+
+// CheckpointStore persists run checkpoints keyed by run id. A live checkpoint
+// means "this run was in flight and not cleanly finished"; Complete/Fail delete
+// it. ListInterrupted returns every surviving checkpoint at boot for recovery.
+type CheckpointStore interface {
+	Save(ctx context.Context, cp RunCheckpoint) error
+	Load(ctx context.Context, runID string) (*RunCheckpoint, error)
+	Delete(ctx context.Context, runID string) error
+	ListInterrupted(ctx context.Context) ([]RunCheckpoint, error)
+}

checkpoint/checkpoint_test.go

@@ -0,0 +1,64 @@
+package checkpoint
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+func TestHandleSaveCompleteDelete(t *testing.T) {
+	ctx := context.Background()
+	mem := NewMemory()
+	meta := RunCheckpointMeta{RunID: "r1", AgentID: "a1", CallerID: "c1"}
+	cp := New(mem, meta, 0, nil) // throttle 0 = save every call
+
+	if err := cp.Save(ctx, run.RunCheckpointState{Messages: []llm.Message{{Role: "user"}}, Iteration: 2}); err != nil {
+		t.Fatal(err)
+	}
+	got, _ := mem.Load(ctx, "r1")
+	if got == nil || got.Iteration != 2 || got.Meta.AgentID != "a1" {
+		t.Fatalf("checkpoint not persisted: %+v", got)
+	}
+	if il, _ := mem.ListInterrupted(ctx); len(il) != 1 {
+		t.Errorf("ListInterrupted = %d, want 1 (in-flight)", len(il))
+	}
+	// Complete clears it (no longer a recovery candidate).
+	if err := cp.Complete(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if il, _ := mem.ListInterrupted(ctx); len(il) != 0 {
+		t.Errorf("after Complete, ListInterrupted = %d, want 0", len(il))
+	}
+}
+
+func TestHandleThrottle(t *testing.T) {
+	ctx := context.Background()
+	mem := NewMemory()
+	now := time.Now()
+	cp := New(mem, RunCheckpointMeta{RunID: "r"}, time.Minute, func() time.Time { return now })
+
+	cp.Save(ctx, run.RunCheckpointState{Iteration: 1})
+	now = now.Add(10 * time.Second) // within throttle window
+	cp.Save(ctx, run.RunCheckpointState{Iteration: 2})
+	if got, _ := mem.Load(ctx, "r"); got.Iteration != 1 {
+		t.Errorf("throttled save should keep iteration 1, got %d", got.Iteration)
+	}
+	now = now.Add(time.Minute) // past throttle
+	cp.Save(ctx, run.RunCheckpointState{Iteration: 3})
+	if got, _ := mem.Load(ctx, "r"); got.Iteration != 3 {
+		t.Errorf("post-throttle save should land iteration 3, got %d", got.Iteration)
+	}
+}
+
+func TestNilStoreNoop(t *testing.T) {
+	cp := New(nil, RunCheckpointMeta{RunID: "r"}, 0, nil)
+	if err := cp.Save(context.Background(), run.RunCheckpointState{}); err != nil {
+		t.Errorf("nil-store Save should be a no-op, got %v", err)
+	}
+	if err := cp.Complete(context.Background()); err != nil {
+		t.Error(err)
+	}
+}

checkpoint/handle.go

@@ -0,0 +1,83 @@
+package checkpoint
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+)
+
+// handle is a per-run run.Checkpointer bound to one run's id + meta. Save writes
+// a fresh snapshot (throttled), Complete/Fail delete the checkpoint (a cleanly
+// finished or terminally failed run is NOT a recovery candidate). A run
+// interrupted by shutdown never calls Complete/Fail, so its checkpoint survives
+// for ListInterrupted at boot.
+type handle struct {
+	store    CheckpointStore
+	meta     RunCheckpointMeta
+	throttle time.Duration
+	now      func() time.Time
+
+	mu       sync.Mutex
+	lastSave time.Time
+}
+
+var _ run.Checkpointer = (*handle)(nil)
+
+// New returns a run.Checkpointer that persists snapshots of the run identified
+// by meta.RunID to store, no more often than throttle (Save calls inside the
+// window are skipped). A nil store yields a no-op Checkpointer. throttle <= 0
+// saves every call; now defaults to time.Now.
+func New(store CheckpointStore, meta RunCheckpointMeta, throttle time.Duration, now func() time.Time) run.Checkpointer {
+	if store == nil {
+		return noop{}
+	}
+	if now == nil {
+		now = time.Now
+	}
+	return &handle{store: store, meta: meta, throttle: throttle, now: now}
+}
+
+func (h *handle) Save(ctx context.Context, st run.RunCheckpointState) error {
+	h.mu.Lock()
+	now := h.now()
+	if h.throttle > 0 && !h.lastSave.IsZero() && now.Sub(h.lastSave) < h.throttle {
+		h.mu.Unlock()
+		return nil // throttled — a more recent snapshot will land shortly
+	}
+	h.mu.Unlock()
+
+	// Advance the throttle clock only AFTER a successful persist. If the store
+	// write fails, lastSave stays put so the next Save isn't throttled away —
+	// otherwise a transient store error would silently drop the snapshot the
+	// caller believes was saved. (A run drives one Save goroutine, so the brief
+	// unguarded window here can't double-write.)
+	if err := h.store.Save(ctx, RunCheckpoint{
+		Meta:      h.meta,
+		Messages:  st.Messages,
+		Iteration: st.Iteration,
+		UpdatedAt: now,
+	}); err != nil {
+		return err
+	}
+	h.mu.Lock()
+	if now.After(h.lastSave) {
+		h.lastSave = now
+	}
+	h.mu.Unlock()
+	return nil
+}
+
+func (h *handle) Complete(ctx context.Context) error { return h.store.Delete(ctx, h.meta.RunID) }
+
+func (h *handle) Fail(ctx context.Context, _ error) error { return h.store.Delete(ctx, h.meta.RunID) }
+
+// noop is the nil-store Checkpointer: every method is a successful no-op.
+type noop struct{}
+
+var _ run.Checkpointer = noop{}
+
+func (noop) Save(context.Context, run.RunCheckpointState) error { return nil }
+func (noop) Complete(context.Context) error                     { return nil }
+func (noop) Fail(context.Context, error) error                  { return nil }

checkpoint/memory.go

@@ -0,0 +1,55 @@
+package checkpoint
+
+import (
+	"context"
+	"sync"
+)
+
+// Memory is a zero-dependency in-process CheckpointStore. NOTE: an in-memory
+// checkpoint store does NOT survive the process restart it exists to recover
+// from — it is the test/light-host default and makes ListInterrupted meaningful
+// only within a single process lifetime. A host that wants real
+// crash-recovery wires a durable CheckpointStore (mort's durable-job table).
+type Memory struct {
+	mu  sync.RWMutex
+	cps map[string]RunCheckpoint // by run id
+}
+
+// NewMemory returns an empty in-memory CheckpointStore.
+func NewMemory() *Memory { return &Memory{cps: map[string]RunCheckpoint{}} }
+
+var _ CheckpointStore = (*Memory)(nil)
+
+func (m *Memory) Save(_ context.Context, cp RunCheckpoint) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.cps[cp.Meta.RunID] = cp
+	return nil
+}
+
+func (m *Memory) Load(_ context.Context, runID string) (*RunCheckpoint, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	cp, ok := m.cps[runID]
+	if !ok {
+		return nil, nil // no checkpoint (not an error — the run finished cleanly or never started)
+	}
+	return &cp, nil
+}
+
+func (m *Memory) Delete(_ context.Context, runID string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.cps, runID)
+	return nil
+}
+
+func (m *Memory) ListInterrupted(_ context.Context) ([]RunCheckpoint, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	out := make([]RunCheckpoint, 0, len(m.cps))
+	for _, cp := range m.cps {
+		out = append(out, cp)
+	}
+	return out, nil
+}

contrib/store/audit_store.go

@@ -0,0 +1,356 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/audit"
+)
+
+// auditStore is the SQLite-backed audit.Storage: one row per run (+ a JSON
+// `inputs` blob), one row per log event. The run-list/filter/walk queries are
+// indexed on the columns they filter; the log payload is a JSON blob.
+type auditStore struct{ db *sql.DB }
+
+// Audit returns a durable audit.Storage backed by this database.
+func (d *DB) Audit() audit.Storage { return &auditStore{db: d.sql} }
+
+var _ audit.Storage = (*auditStore)(nil)
+
+func (s *auditStore) Initialize(ctx context.Context) error {
+	_, err := s.db.ExecContext(ctx, `
+CREATE TABLE IF NOT EXISTS skill_runs (
+	id                    TEXT PRIMARY KEY,
+	skill_id              TEXT NOT NULL DEFAULT '',
+	caller_id             TEXT NOT NULL DEFAULT '',
+	channel_id            TEXT NOT NULL DEFAULT '',
+	parent_run_id         TEXT NOT NULL DEFAULT '',
+	inputs                TEXT NOT NULL DEFAULT '{}',
+	started_at            INTEGER NOT NULL DEFAULT 0,
+	finished_at           INTEGER NOT NULL DEFAULT 0, -- 0 = still running
+	status                TEXT NOT NULL DEFAULT 'running',
+	output                TEXT NOT NULL DEFAULT '',
+	error                 TEXT NOT NULL DEFAULT '',
+	tool_calls            INTEGER NOT NULL DEFAULT 0,
+	runtime_seconds       REAL NOT NULL DEFAULT 0,
+	total_input_tokens    INTEGER NOT NULL DEFAULT 0,
+	total_output_tokens   INTEGER NOT NULL DEFAULT 0,
+	total_thinking_tokens INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS idx_runs_skill   ON skill_runs(skill_id, started_at);
+CREATE INDEX IF NOT EXISTS idx_runs_caller  ON skill_runs(caller_id, started_at);
+CREATE INDEX IF NOT EXISTS idx_runs_parent  ON skill_runs(parent_run_id);
+CREATE INDEX IF NOT EXISTS idx_runs_started ON skill_runs(started_at);
+CREATE TABLE IF NOT EXISTS skill_run_logs (
+	run_id     TEXT NOT NULL,
+	seq        INTEGER NOT NULL,
+	event_type TEXT NOT NULL,
+	payload    TEXT NOT NULL DEFAULT '{}',
+	created_at INTEGER NOT NULL,
+	PRIMARY KEY (run_id, seq)
+);`)
+	if err != nil {
+		return fmt.Errorf("auditStore.Initialize: %w", err)
+	}
+	return nil
+}
+
+func unixOrZero(t time.Time) int64 {
+	if t.IsZero() {
+		return 0
+	}
+	return t.Unix()
+}
+
+func (s *auditStore) StartRun(ctx context.Context, r audit.SkillRun) error {
+	inputs, _ := json.Marshal(r.Inputs)
+	var fin int64
+	if r.FinishedAt != nil {
+		fin = unixOrZero(*r.FinishedAt)
+	}
+	status := r.Status
+	if status == "" {
+		status = "running"
+	}
+	_, err := s.db.ExecContext(ctx, `
+INSERT INTO skill_runs (id, skill_id, caller_id, channel_id, parent_run_id, inputs, started_at, finished_at,
+	status, output, error, tool_calls, runtime_seconds, total_input_tokens, total_output_tokens, total_thinking_tokens)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET
+	skill_id=excluded.skill_id, caller_id=excluded.caller_id, channel_id=excluded.channel_id,
+	parent_run_id=excluded.parent_run_id, inputs=excluded.inputs, started_at=excluded.started_at`,
+		r.ID, r.SkillID, r.CallerID, r.ChannelID, r.ParentRunID, string(inputs), unixOrZero(r.StartedAt), fin,
+		status, r.Output, r.Error, r.ToolCallsCount, r.RuntimeSeconds,
+		r.TotalInputTokens, r.TotalOutputTokens, r.TotalThinkingTokens)
+	if err != nil {
+		return fmt.Errorf("auditStore.StartRun: %w", err)
+	}
+	return nil
+}
+
+func (s *auditStore) FinishRun(ctx context.Context, runID string, st audit.RunStats) error {
+	res, err := s.db.ExecContext(ctx, `
+UPDATE skill_runs SET finished_at=?, status=?, output=?, error=?, tool_calls=?, runtime_seconds=?,
+	total_input_tokens=?, total_output_tokens=?, total_thinking_tokens=? WHERE id=?`,
+		time.Now().Unix(), st.Status, st.Output, st.Error, st.ToolCalls, st.RuntimeSeconds,
+		st.InputTokens, st.OutputTokens, st.ThinkingTokens, runID)
+	if err != nil {
+		return fmt.Errorf("auditStore.FinishRun: %w", err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return audit.ErrNotFound
+	}
+	return nil
+}
+
+func (s *auditStore) AppendLog(ctx context.Context, l audit.SkillRunLog) error {
+	payload, _ := json.Marshal(l.Payload)
+	created := unixOrZero(l.CreatedAt)
+	if created == 0 {
+		created = time.Now().Unix()
+	}
+	_, err := s.db.ExecContext(ctx,
+		`INSERT OR REPLACE INTO skill_run_logs (run_id, seq, event_type, payload, created_at) VALUES (?, ?, ?, ?, ?)`,
+		l.RunID, l.Sequence, l.EventType, string(payload), created)
+	if err != nil {
+		return fmt.Errorf("auditStore.AppendLog: %w", err)
+	}
+	return nil
+}
+
+// runCols is the SELECT column list matching scanRun.
+const runCols = `id, skill_id, caller_id, channel_id, parent_run_id, inputs, started_at, finished_at,
+	status, output, error, tool_calls, runtime_seconds, total_input_tokens, total_output_tokens, total_thinking_tokens`
+
+func scanRun(sc interface{ Scan(...any) error }) (*audit.SkillRun, error) {
+	var r audit.SkillRun
+	var inputs string
+	var started, finished int64
+	if err := sc.Scan(&r.ID, &r.SkillID, &r.CallerID, &r.ChannelID, &r.ParentRunID, &inputs,
+		&started, &finished, &r.Status, &r.Output, &r.Error, &r.ToolCallsCount, &r.RuntimeSeconds,
+		&r.TotalInputTokens, &r.TotalOutputTokens, &r.TotalThinkingTokens); err != nil {
+		return nil, err
+	}
+	_ = json.Unmarshal([]byte(inputs), &r.Inputs)
+	r.StartedAt = time.Unix(started, 0).UTC()
+	if finished > 0 {
+		t := time.Unix(finished, 0).UTC()
+		r.FinishedAt = &t
+	}
+	return &r, nil
+}
+
+func (s *auditStore) GetRun(ctx context.Context, runID string) (*audit.SkillRun, error) {
+	row := s.db.QueryRowContext(ctx, `SELECT `+runCols+` FROM skill_runs WHERE id = ?`, runID)
+	r, err := scanRun(row)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil, audit.ErrNotFound
+	}
+	return r, err
+}
+
+func (s *auditStore) queryRuns(ctx context.Context, tail string, args ...any) ([]audit.SkillRun, error) {
+	rows, err := s.db.QueryContext(ctx, `SELECT `+runCols+` FROM skill_runs `+tail, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var out []audit.SkillRun
+	for rows.Next() {
+		r, err := scanRun(rows)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, *r)
+	}
+	return out, rows.Err()
+}
+
+func (s *auditStore) ListLogsByRun(ctx context.Context, runID string) ([]audit.SkillRunLog, error) {
+	rows, err := s.db.QueryContext(ctx,
+		`SELECT run_id, seq, event_type, payload, created_at FROM skill_run_logs WHERE run_id = ? ORDER BY seq`, runID)
+	if err != nil {
+		return nil, fmt.Errorf("auditStore.ListLogsByRun: %w", err)
+	}
+	defer rows.Close()
+	var out []audit.SkillRunLog
+	for rows.Next() {
+		var l audit.SkillRunLog
+		var payload string
+		var created int64
+		if err := rows.Scan(&l.RunID, &l.Sequence, &l.EventType, &payload, &created); err != nil {
+			return nil, err
+		}
+		_ = json.Unmarshal([]byte(payload), &l.Payload)
+		l.CreatedAt = time.Unix(created, 0).UTC()
+		out = append(out, l)
+	}
+	return out, rows.Err()
+}
+
+func (s *auditStore) ListRunsBySkill(ctx context.Context, skillID string, limit int) ([]audit.SkillRun, error) {
+	return s.ListRunsBySkillPaginated(ctx, skillID, 0, limit, false)
+}
+
+func (s *auditStore) ListRunsBySkillPaginated(ctx context.Context, skillID string, offset, limit int, includeDryRun bool) ([]audit.SkillRun, error) {
+	w := `WHERE skill_id = ?`
+	args := []any{skillID}
+	if !includeDryRun {
+		w += ` AND status != 'dry_run'`
+	}
+	return s.queryRuns(ctx, w+` ORDER BY started_at DESC `+limitOffset(limit, offset), args...)
+}
+
+func (s *auditStore) CountRunsBySkill(ctx context.Context, skillID string, includeDryRun bool) (int64, error) {
+	q := `SELECT COUNT(*) FROM skill_runs WHERE skill_id = ?`
+	if !includeDryRun {
+		q += ` AND status != 'dry_run'`
+	}
+	var n int64
+	err := s.db.QueryRowContext(ctx, q, skillID).Scan(&n)
+	return n, err
+}
+
+func (s *auditStore) ListRunsByCaller(ctx context.Context, callerID string, limit int) ([]audit.SkillRun, error) {
+	return s.queryRuns(ctx, `WHERE caller_id = ? AND status != 'dry_run' ORDER BY started_at DESC `+limitOffset(limit, 0), callerID)
+}
+
+func (s *auditStore) buildFilter(f audit.RunFilter) (string, []any) {
+	var conds []string
+	var args []any
+	if !f.IncludeDryRun {
+		conds = append(conds, `status != 'dry_run'`)
+	}
+	if f.Status != "" {
+		conds = append(conds, `status = ?`)
+		args = append(args, f.Status)
+	}
+	if f.SkillID != "" {
+		conds = append(conds, `skill_id = ?`)
+		args = append(args, f.SkillID)
+	}
+	if f.CallerID != "" {
+		conds = append(conds, `caller_id = ?`)
+		args = append(args, f.CallerID)
+	}
+	if f.ChannelID != "" {
+		conds = append(conds, `channel_id = ?`)
+		args = append(args, f.ChannelID)
+	}
+	if f.TopLevelOnly {
+		conds = append(conds, `parent_run_id = ''`)
+	}
+	if !f.Since.IsZero() {
+		conds = append(conds, `started_at >= ?`)
+		args = append(args, f.Since.Unix())
+	}
+	if !f.Until.IsZero() {
+		conds = append(conds, `started_at <= ?`)
+		args = append(args, f.Until.Unix())
+	}
+	where := ""
+	if len(conds) > 0 {
+		where = `WHERE ` + strings.Join(conds, " AND ")
+	}
+	return where, args
+}
+
+func (s *auditStore) ListRunsFiltered(ctx context.Context, f audit.RunFilter, offset, limit int) ([]audit.SkillRun, error) {
+	where, args := s.buildFilter(f)
+	return s.queryRuns(ctx, where+` ORDER BY started_at DESC `+limitOffset(limit, offset), args...)
+}
+
+func (s *auditStore) CountRunsFiltered(ctx context.Context, f audit.RunFilter) (int64, error) {
+	where, args := s.buildFilter(f)
+	var n int64
+	err := s.db.QueryRowContext(ctx, `SELECT COUNT(*) FROM skill_runs `+where, args...).Scan(&n)
+	return n, err
+}
+
+func (s *auditStore) PurgeOlderThan(ctx context.Context, t time.Time) (int64, error) {
+	res, err := s.db.ExecContext(ctx, `DELETE FROM skill_runs WHERE finished_at > 0 AND finished_at < ?`, t.Unix())
+	if err != nil {
+		return 0, fmt.Errorf("auditStore.PurgeOlderThan: %w", err)
+	}
+	n, _ := res.RowsAffected()
+	// Best-effort orphan-log cleanup.
+	_, _ = s.db.ExecContext(ctx, `DELETE FROM skill_run_logs WHERE run_id NOT IN (SELECT id FROM skill_runs)`)
+	return n, nil
+}
+
+func (s *auditStore) ListChildrenByParent(ctx context.Context, parentRunID string) ([]audit.SkillRun, error) {
+	return s.queryRuns(ctx, `WHERE parent_run_id = ? ORDER BY started_at DESC`, parentRunID)
+}
+
+func (s *auditStore) WalkParentChain(ctx context.Context, runID string) ([]audit.SkillRun, error) {
+	var chain []audit.SkillRun
+	seen := map[string]bool{}
+	for id := runID; id != ""; {
+		if seen[id] {
+			break
+		}
+		seen[id] = true
+		r, err := s.GetRun(ctx, id)
+		if errors.Is(err, audit.ErrNotFound) {
+			break
+		}
+		if err != nil {
+			return nil, err
+		}
+		chain = append(chain, *r)
+		id = r.ParentRunID
+	}
+	return chain, nil
+}
+
+func (s *auditStore) ListFinishedRunsBefore(ctx context.Context, cutoff time.Time, limit int) ([]audit.SkillRun, error) {
+	return s.queryRuns(ctx,
+		`WHERE finished_at > 0 AND finished_at < ? ORDER BY started_at DESC `+limitOffset(limit, 0), cutoff.Unix())
+}
+
+func (s *auditStore) LastRunBySkills(ctx context.Context, skillIDs []string, includeFailed bool) (map[string]time.Time, error) {
+	out := map[string]time.Time{}
+	if len(skillIDs) == 0 {
+		return out, nil
+	}
+	q := `SELECT skill_id, MAX(started_at) FROM skill_runs WHERE skill_id IN (` +
+		strings.TrimSuffix(strings.Repeat("?,", len(skillIDs)), ",") + `)`
+	args := make([]any, 0, len(skillIDs))
+	for _, id := range skillIDs {
+		args = append(args, id)
+	}
+	if !includeFailed {
+		q += ` AND status NOT IN ('error','timeout')`
+	}
+	q += ` GROUP BY skill_id`
+	rows, err := s.db.QueryContext(ctx, q, args...)
+	if err != nil {
+		return nil, fmt.Errorf("auditStore.LastRunBySkills: %w", err)
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var id string
+		var ts int64
+		if err := rows.Scan(&id, &ts); err != nil {
+			return nil, err
+		}
+		out[id] = time.Unix(ts, 0).UTC()
+	}
+	return out, rows.Err()
+}
+
+// limitOffset renders an optional LIMIT/OFFSET clause (limit<=0 = no limit).
+func limitOffset(limit, offset int) string {
+	if limit <= 0 {
+		return ""
+	}
+	if offset > 0 {
+		return fmt.Sprintf("LIMIT %d OFFSET %d", limit, offset)
+	}
+	return fmt.Sprintf("LIMIT %d", limit)
+}

contrib/store/audit_store_test.go

@@ -0,0 +1,67 @@
+package store
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/audit"
+)
+
+func TestSQLiteAuditStore(t *testing.T) {
+	ctx := context.Background()
+	db, err := Open(":memory:")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	st := db.Audit()
+	if err := st.Initialize(ctx); err != nil {
+		t.Fatal(err)
+	}
+
+	now := time.Now().UTC()
+	// parent run
+	if err := st.StartRun(ctx, audit.SkillRun{ID: "r1", SkillID: "agent-x", CallerID: "c1",
+		Inputs: map[string]any{"q": "hi"}, StartedAt: now}); err != nil {
+		t.Fatal(err)
+	}
+	// child run
+	st.StartRun(ctx, audit.SkillRun{ID: "r2", SkillID: "skill-y", CallerID: "c1", ParentRunID: "r1", StartedAt: now.Add(time.Second)})
+
+	st.AppendLog(ctx, audit.SkillRunLog{RunID: "r1", Sequence: 1, EventType: "step", Payload: map[string]any{"i": 1}, CreatedAt: now})
+	if err := st.FinishRun(ctx, "r1", audit.RunStats{Status: "ok", Output: "done", ToolCalls: 2, InputTokens: 10, OutputTokens: 5}); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := st.GetRun(ctx, "r1")
+	if err != nil || got.Status != "ok" || got.Output != "done" || got.FinishedAt == nil ||
+		got.Inputs["q"] != "hi" || got.TotalInputTokens != 10 {
+		t.Fatalf("GetRun: %v %+v", err, got)
+	}
+	if logs, _ := st.ListLogsByRun(ctx, "r1"); len(logs) != 1 || logs[0].EventType != "step" {
+		t.Errorf("ListLogsByRun = %+v", logs)
+	}
+	if kids, _ := st.ListChildrenByParent(ctx, "r1"); len(kids) != 1 || kids[0].ID != "r2" {
+		t.Errorf("ListChildrenByParent = %+v", kids)
+	}
+	if chain, _ := st.WalkParentChain(ctx, "r2"); len(chain) != 2 || chain[1].ID != "r1" {
+		t.Errorf("WalkParentChain = %+v", chain)
+	}
+	if byCaller, _ := st.ListRunsByCaller(ctx, "c1", 10); len(byCaller) != 2 {
+		t.Errorf("ListRunsByCaller = %d, want 2", len(byCaller))
+	}
+	// filter: top-level only
+	tl, _ := st.ListRunsFiltered(ctx, audit.RunFilter{TopLevelOnly: true}, 0, 10)
+	if len(tl) != 1 || tl[0].ID != "r1" {
+		t.Errorf("TopLevelOnly filter = %+v", tl)
+	}
+	// last-run map
+	last, _ := st.LastRunBySkills(ctx, []string{"agent-x", "skill-y"}, true)
+	if _, ok := last["agent-x"]; !ok {
+		t.Errorf("LastRunBySkills missing agent-x: %+v", last)
+	}
+	if n, _ := st.CountRunsBySkill(ctx, "agent-x", false); n != 1 {
+		t.Errorf("CountRunsBySkill = %d, want 1", n)
+	}
+}

contrib/store/budget_store.go

@@ -0,0 +1,105 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"math"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/budget"
+)
+
+// budgetStore is the SQLite-backed budget.BudgetStorage.
+type budgetStore struct{ db *sql.DB }
+
+// Budget returns a durable budget.BudgetStorage backed by this database.
+func (d *DB) Budget() budget.BudgetStorage { return &budgetStore{db: d.sql} }
+
+var _ budget.BudgetStorage = (*budgetStore)(nil)
+
+func (s *budgetStore) Initialize(ctx context.Context) error {
+	_, err := s.db.ExecContext(ctx, `
+CREATE TABLE IF NOT EXISTS skill_budgets (
+	user_id      TEXT PRIMARY KEY,
+	window_start INTEGER NOT NULL, -- unix seconds
+	seconds_used REAL    NOT NULL,
+	runs_count   INTEGER NOT NULL,
+	updated_at   INTEGER NOT NULL
+)`)
+	if err != nil {
+		return fmt.Errorf("budgetStore.Initialize: %w", err)
+	}
+	return nil
+}
+
+func (s *budgetStore) Get(ctx context.Context, userID string) (*budget.SkillBudget, error) {
+	row := s.db.QueryRowContext(ctx,
+		`SELECT window_start, seconds_used, runs_count, updated_at FROM skill_budgets WHERE user_id = ?`, userID)
+	var ws, ua int64
+	var used float64
+	var runs int
+	switch err := row.Scan(&ws, &used, &runs, &ua); {
+	case errors.Is(err, sql.ErrNoRows):
+		return nil, nil // no row yet — documented (nil, nil)
+	case err != nil:
+		return nil, fmt.Errorf("budgetStore.Get: %w", err)
+	}
+	return &budget.SkillBudget{
+		UserID:      userID,
+		WindowStart: time.Unix(ws, 0).UTC(),
+		SecondsUsed: used,
+		RunsCount:   runs,
+		UpdatedAt:   time.Unix(ua, 0).UTC(),
+	}, nil
+}
+
+// Add increments usage atomically, rolling the 7-day window over inside one
+// transaction so concurrent Adds can't race the read-modify-write.
+func (s *budgetStore) Add(ctx context.Context, userID string, secondsUsed float64, now time.Time) error {
+	// A NaN/Inf would poison the seconds_used column irrecoverably (NaN
+	// propagates through every later add), so reject it at the boundary.
+	if math.IsNaN(secondsUsed) || math.IsInf(secondsUsed, 0) {
+		return fmt.Errorf("budgetStore.Add: invalid secondsUsed %v", secondsUsed)
+	}
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("budgetStore.Add: begin: %w", err)
+	}
+	defer tx.Rollback() //nolint:errcheck // no-op after Commit
+
+	var ws int64
+	var used float64
+	var runs int
+	err = tx.QueryRowContext(ctx,
+		`SELECT window_start, seconds_used, runs_count FROM skill_budgets WHERE user_id = ?`, userID).
+		Scan(&ws, &used, &runs)
+	switch {
+	case errors.Is(err, sql.ErrNoRows):
+		ws, used, runs = now.Unix(), 0, 0
+	case err != nil:
+		return fmt.Errorf("budgetStore.Add: select: %w", err)
+	}
+	// Roll the window over if older than 7 days.
+	if now.Sub(time.Unix(ws, 0)) >= 7*24*time.Hour {
+		ws, used, runs = now.Unix(), 0, 0
+	}
+	used += secondsUsed
+	runs++
+	if _, err := tx.ExecContext(ctx, `
+INSERT INTO skill_budgets (user_id, window_start, seconds_used, runs_count, updated_at)
+VALUES (?, ?, ?, ?, ?)
+ON CONFLICT(user_id) DO UPDATE SET
+	window_start = excluded.window_start,
+	seconds_used = excluded.seconds_used,
+	runs_count   = excluded.runs_count,
+	updated_at   = excluded.updated_at`,
+		userID, ws, used, runs, now.Unix()); err != nil {
+		return fmt.Errorf("budgetStore.Add: upsert: %w", err)
+	}
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("budgetStore.Add: commit: %w", err)
+	}
+	return nil
+}

contrib/store/budget_store_test.go

@@ -0,0 +1,65 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/budget"
+)
+
+// TestSQLiteBudgetConformance runs the budget battery over the SQLite store and
+// asserts the same rolling-window contract the in-memory store must satisfy.
+func TestSQLiteBudgetConformance(t *testing.T) {
+	ctx := context.Background()
+	db, err := Open(":memory:")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	st := db.Budget()
+	if err := st.Initialize(ctx); err != nil {
+		t.Fatal(err)
+	}
+
+	now := time.Now().UTC()
+	b := budget.NewDBBudget(st, func() float64 { return 100 }, nil, func() time.Time { return now })
+
+	if err := b.Check(ctx, "u"); err != nil {
+		t.Fatalf("fresh caller should pass: %v", err)
+	}
+	b.Commit(ctx, "u", 60)
+	if err := b.Check(ctx, "u"); err != nil {
+		t.Fatalf("60/100 should pass: %v", err)
+	}
+	b.Commit(ctx, "u", 50) // 110 total
+	if err := b.Check(ctx, "u"); !errors.Is(err, budget.ErrBudgetExceeded) {
+		t.Fatalf("110/100 should be ErrBudgetExceeded, got %v", err)
+	}
+
+	// Direct Get reflects the persisted row.
+	row, err := st.Get(ctx, "u")
+	if err != nil || row == nil {
+		t.Fatalf("Get: %v %+v", err, row)
+	}
+	if row.SecondsUsed != 110 || row.RunsCount != 2 {
+		t.Errorf("row = %+v, want seconds=110 runs=2", row)
+	}
+
+	// Window rolls over after 7 days.
+	now = now.Add(8 * 24 * time.Hour)
+	b.Commit(ctx, "u", 1)
+	if err := b.Check(ctx, "u"); err != nil {
+		t.Fatalf("after rollover should pass: %v", err)
+	}
+	row, _ = st.Get(ctx, "u")
+	if row.SecondsUsed != 1 || row.RunsCount != 1 {
+		t.Errorf("post-rollover row = %+v, want seconds=1 runs=1", row)
+	}
+
+	// Unknown user -> (nil, nil).
+	if r, err := st.Get(ctx, "nobody"); err != nil || r != nil {
+		t.Errorf("Get(unknown) = %+v %v, want nil,nil", r, err)
+	}
+}

contrib/store/go.mod

@@ -0,0 +1,54 @@
+module gitea.stevedudenhoeffer.com/steve/executus/contrib/store
+
+go 1.26.2
+
+require (
+	gitea.stevedudenhoeffer.com/steve/executus v0.0.0
+	modernc.org/sqlite v1.34.4
+)
+
+require (
+	cloud.google.com/go v0.123.0 // indirect
+	cloud.google.com/go/auth v0.18.1 // indirect
+	cloud.google.com/go/compute/metadata v0.9.0 // indirect
+	gitea.stevedudenhoeffer.com/steve/majordomo v0.0.0-20260626223738-1fd7109a42f3 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/s2a-go v0.1.9 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.11 // indirect
+	github.com/googleapis/gax-go/v2 v2.17.0 // indirect
+	github.com/gorilla/websocket v1.5.3 // indirect
+	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/robfig/cron/v3 v3.0.1 // indirect
+	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 // indirect
+	go.opentelemetry.io/otel v1.40.0 // indirect
+	go.opentelemetry.io/otel/metric v1.40.0 // indirect
+	go.opentelemetry.io/otel/trace v1.40.0 // indirect
+	golang.org/x/crypto v0.53.0 // indirect
+	golang.org/x/net v0.55.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
+	google.golang.org/genai v1.59.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260203192932-546029d2fa20 // indirect
+	google.golang.org/grpc v1.78.0 // indirect
+	google.golang.org/protobuf v1.36.11 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 // indirect
+	modernc.org/libc v1.55.3 // indirect
+	modernc.org/mathutil v1.6.0 // indirect
+	modernc.org/memory v1.8.0 // indirect
+	modernc.org/strutil v1.2.0 // indirect
+	modernc.org/token v1.1.0 // indirect
+)
+
+// Co-developed against the local checkout; dropped (pinned) at executus v0.1.0.
+replace gitea.stevedudenhoeffer.com/steve/executus => ../../

contrib/store/go.sum

@@ -0,0 +1,105 @@
+cloud.google.com/go v0.123.0 h1:2NAUJwPR47q+E35uaJeYoNhuNEM9kM8SjgRgdeOJUSE=
+cloud.google.com/go v0.123.0/go.mod h1:xBoMV08QcqUGuPW65Qfm1o9Y4zKZBpGS+7bImXLTAZU=
+cloud.google.com/go/auth v0.18.1 h1:IwTEx92GFUo2pJ6Qea0EU3zYvKnTAeRCODxfA/G5UWs=
+cloud.google.com/go/auth v0.18.1/go.mod h1:GfTYoS9G3CWpRA3Va9doKN9mjPGRS+v41jmZAhBzbrA=
+cloud.google.com/go/compute/metadata v0.9.0 h1:pDUj4QMoPejqq20dK0Pg2N4yG9zIkYGdBtwLoEkH9Zs=
+cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCBSM6qQI1yTBdEb3C10=
+gitea.stevedudenhoeffer.com/steve/majordomo v0.0.0-20260626223738-1fd7109a42f3 h1:KYKIFFRsXzbbBJVDa99+Fhy0zxl9G0xV/MCrLipsLL4=
+gitea.stevedudenhoeffer.com/steve/majordomo v0.0.0-20260626223738-1fd7109a42f3/go.mod h1:UZLveG17SmENt4sne2RSLIbioix30RZbRIQUzBAnOyY=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd h1:gbpYu9NMq8jhDVbvlGkMFWCjLFlqqEZjEmObmhUy6Vo=
+github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd/go.mod h1:kf6iHlnVGwgKolg33glAes7Yg/8iWP8ukqeldJSO7jw=
+github.com/google/s2a-go v0.1.9 h1:LGD7gtMgezd8a/Xak7mEWL0PjoTQFvpRudN895yqKW0=
+github.com/google/s2a-go v0.1.9/go.mod h1:YA0Ei2ZQL3acow2O62kdp9UlnvMmU7kA6Eutn0dXayM=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/googleapis/enterprise-certificate-proxy v0.3.11 h1:vAe81Msw+8tKUxi2Dqh/NZMz7475yUvmRIkXr4oN2ao=
+github.com/googleapis/enterprise-certificate-proxy v0.3.11/go.mod h1:RFV7MUdlb7AgEq2v7FmMCfeSMCllAzWxFgRdusoGks8=
+github.com/googleapis/gax-go/v2 v2.17.0 h1:RksgfBpxqff0EZkDWYuz9q/uWsTVz+kf43LsZ1J6SMc=
+github.com/googleapis/gax-go/v2 v2.17.0/go.mod h1:mzaqghpQp4JDh3HvADwrat+6M3MOIDp5YKHhb9PAgDY=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
+github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
+github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
+github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0 h1:7iP2uCb7sGddAr30RRS6xjKy7AZ2JtTOPA3oolgVSw8=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.65.0/go.mod h1:c7hN3ddxs/z6q9xwvfLPk+UHlWRQyaeR1LdgfL/66l0=
+go.opentelemetry.io/otel v1.40.0 h1:oA5YeOcpRTXq6NN7frwmwFR0Cn3RhTVZvXsP4duvCms=
+go.opentelemetry.io/otel v1.40.0/go.mod h1:IMb+uXZUKkMXdPddhwAHm6UfOwJyh4ct1ybIlV14J0g=
+go.opentelemetry.io/otel/metric v1.40.0 h1:rcZe317KPftE2rstWIBitCdVp89A2HqjkxR3c11+p9g=
+go.opentelemetry.io/otel/metric v1.40.0/go.mod h1:ib/crwQH7N3r5kfiBZQbwrTge743UDc7DTFVZrrXnqc=
+go.opentelemetry.io/otel/trace v1.40.0 h1:WA4etStDttCSYuhwvEa8OP8I5EWu24lkOzp+ZYblVjw=
+go.opentelemetry.io/otel/trace v1.40.0/go.mod h1:zeAhriXecNGP/s2SEG3+Y8X9ujcJOTqQ5RgdEJcawiA=
+golang.org/x/crypto v0.53.0 h1:QZ4Muo8THX6CizN2vPPd5fBGHyogrdK9fG4wLPFUsto=
+golang.org/x/crypto v0.53.0/go.mod h1:DNLU434OwVakk9PzuwV8w62mAJpRJL3vsgcfp4Qnsio=
+golang.org/x/mod v0.16.0 h1:QX4fJ0Rr5cPQCF7O9lh9Se4pmwfwskqZfq5moyldzic=
+golang.org/x/mod v0.16.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.46.0 h1:noSf2Fq6F8DBgS+LysIkx7rIExoNHJsxOAtPp4rthXw=
+golang.org/x/sys v0.46.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
+golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
+golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
+golang.org/x/tools v0.19.0 h1:tfGCXNR1OsFG+sVdLAitlpjAvD/I6dHDKnYrpEZUHkw=
+golang.org/x/tools v0.19.0/go.mod h1:qoJWxmGSIBmAeriMx19ogtrEPrGtDbPK634QFIcLAhc=
+google.golang.org/genai v1.59.0 h1:xp+ydkJFW8hO0hTUaAkr8TrLM9HFP3NYAwFhPd0nDqA=
+google.golang.org/genai v1.59.0/go.mod h1:mDdPDFXo1Ats7f1WXVyZgWb/CkMzFWTWJruIMy7hGIU=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260203192932-546029d2fa20 h1:Jr5R2J6F6qWyzINc+4AM8t5pfUz6beZpHp678GNrMbE=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260203192932-546029d2fa20/go.mod h1:j9x/tPzZkyxcgEFkiKEEGxfvyumM01BEtsW8xzOahRQ=
+google.golang.org/grpc v1.78.0 h1:K1XZG/yGDJnzMdd/uZHAkVqJE+xIDOcmdSFZkBUicNc=
+google.golang.org/grpc v1.78.0/go.mod h1:I47qjTo4OKbMkjA/aOOwxDIiPSBofUtQUI5EfpWvW7U=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+modernc.org/cc/v4 v4.21.4 h1:3Be/Rdo1fpr8GrQ7IVw9OHtplU4gWbb+wNgeoBMmGLQ=
+modernc.org/cc/v4 v4.21.4/go.mod h1:HM7VJTZbUCR3rV8EYBi9wxnJ0ZBRiGE5OeGXNA0IsLQ=
+modernc.org/ccgo/v4 v4.19.2 h1:lwQZgvboKD0jBwdaeVCTouxhxAyN6iawF3STraAal8Y=
+modernc.org/ccgo/v4 v4.19.2/go.mod h1:ysS3mxiMV38XGRTTcgo0DQTeTmAO4oCmJl1nX9VFI3s=
+modernc.org/fileutil v1.3.0 h1:gQ5SIzK3H9kdfai/5x41oQiKValumqNTDXMvKo62HvE=
+modernc.org/fileutil v1.3.0/go.mod h1:XatxS8fZi3pS8/hKG2GH/ArUogfxjpEKs3Ku3aK4JyQ=
+modernc.org/gc/v2 v2.4.1 h1:9cNzOqPyMJBvrUipmynX0ZohMhcxPtMccYgGOJdOiBw=
+modernc.org/gc/v2 v2.4.1/go.mod h1:wzN5dK1AzVGoH6XOzc3YZ+ey/jPgYHLuVckd62P0GYU=
+modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6 h1:5D53IMaUuA5InSeMu9eJtlQXS2NxAhyWQvkKEgXZhHI=
+modernc.org/gc/v3 v3.0.0-20240107210532-573471604cb6/go.mod h1:Qz0X07sNOR1jWYCrJMEnbW/X55x206Q7Vt4mz6/wHp4=
+modernc.org/libc v1.55.3 h1:AzcW1mhlPNrRtjS5sS+eW2ISCgSOLLNyFzRh/V3Qj/U=
+modernc.org/libc v1.55.3/go.mod h1:qFXepLhz+JjFThQ4kzwzOjA/y/artDeg+pcYnY+Q83w=
+modernc.org/mathutil v1.6.0 h1:fRe9+AmYlaej+64JsEEhoWuAYBkOtQiMEU7n/XgfYi4=
+modernc.org/mathutil v1.6.0/go.mod h1:Ui5Q9q1TR2gFm0AQRqQUaBWFLAhQpCwNcuhBOSedWPo=
+modernc.org/memory v1.8.0 h1:IqGTL6eFMaDZZhEWwcREgeMXYwmW83LYW8cROZYkg+E=
+modernc.org/memory v1.8.0/go.mod h1:XPZ936zp5OMKGWPqbD3JShgd/ZoQ7899TUuQqxY+peU=
+modernc.org/opt v0.1.3 h1:3XOZf2yznlhC+ibLltsDGzABUGVx8J6pnFMS3E4dcq4=
+modernc.org/opt v0.1.3/go.mod h1:WdSiB5evDcignE70guQKxYUl14mgWtbClRi5wmkkTX0=
+modernc.org/sortutil v1.2.0 h1:jQiD3PfS2REGJNzNCMMaLSp/wdMNieTbKX920Cqdgqc=
+modernc.org/sortutil v1.2.0/go.mod h1:TKU2s7kJMf1AE84OoiGppNHJwvB753OYfNl2WRb++Ss=
+modernc.org/sqlite v1.34.4 h1:sjdARozcL5KJBvYQvLlZEmctRgW9xqIZc2ncN7PU0P8=
+modernc.org/sqlite v1.34.4/go.mod h1:3QQFCG2SEMtc2nv+Wq4cQCH7Hjcg+p/RMlS1XK+zwbk=
+modernc.org/strutil v1.2.0 h1:agBi9dp1I+eOnxXeiZawM8F4LawKv4NzGWSaLfyeNZA=
+modernc.org/strutil v1.2.0/go.mod h1:/mdcBmfOibveCTBxUl5B5l6W+TTH1FXPLHZE6bTosX0=
+modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
+modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=

contrib/store/persona_store.go

@@ -0,0 +1,174 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/persona"
+)
+
+// personaStore is the SQLite-backed persona.Storage. It stores each Agent as a
+// JSON blob in `data` with a handful of extracted, indexed columns for the
+// query methods — so the FULL struct round-trips (no domain↔GORM↔DB field-loss
+// footgun) while owner/name/webhook/schedule lookups stay indexable.
+type personaStore struct{ db *sql.DB }
+
+// Personas returns a durable persona.Storage backed by this database.
+func (d *DB) Personas() persona.Storage { return &personaStore{db: d.sql} }
+
+var _ persona.Storage = (*personaStore)(nil)
+
+func (s *personaStore) InitializeAgentStorage(ctx context.Context) error {
+	_, err := s.db.ExecContext(ctx, `
+CREATE TABLE IF NOT EXISTS agents (
+	id                     TEXT PRIMARY KEY,
+	owner_id               TEXT NOT NULL DEFAULT '',
+	name                   TEXT NOT NULL DEFAULT '',
+	webhook_secret         TEXT NOT NULL DEFAULT '',
+	chatbot_channel_filter TEXT NOT NULL DEFAULT '',
+	schedule               TEXT NOT NULL DEFAULT '',
+	next_run_at            INTEGER NOT NULL DEFAULT 0, -- unix seconds; 0 = unset
+	data                   TEXT NOT NULL              -- full Agent as JSON
+);
+CREATE INDEX IF NOT EXISTS idx_agents_owner ON agents(owner_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agents_owner_name ON agents(owner_id, name);
+CREATE INDEX IF NOT EXISTS idx_agents_sched ON agents(schedule, next_run_at);`)
+	if err != nil {
+		return fmt.Errorf("personaStore.Initialize: %w", err)
+	}
+	return nil
+}
+
+func (s *personaStore) SaveAgent(ctx context.Context, a *persona.Agent) error {
+	blob, err := json.Marshal(a)
+	if err != nil {
+		return fmt.Errorf("personaStore.SaveAgent: marshal: %w", err)
+	}
+	var next int64
+	if a.NextRunAt != nil && !a.NextRunAt.IsZero() {
+		next = a.NextRunAt.Unix()
+	}
+	_, err = s.db.ExecContext(ctx, `
+INSERT INTO agents (id, owner_id, name, webhook_secret, chatbot_channel_filter, schedule, next_run_at, data)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET
+	owner_id=excluded.owner_id, name=excluded.name, webhook_secret=excluded.webhook_secret,
+	chatbot_channel_filter=excluded.chatbot_channel_filter, schedule=excluded.schedule,
+	next_run_at=excluded.next_run_at, data=excluded.data`,
+		a.ID, a.OwnerID, a.Name, a.WebhookSecret, a.ChatbotChannelFilter, a.Schedule, next, string(blob))
+	if err != nil {
+		return fmt.Errorf("personaStore.SaveAgent: %w", err)
+	}
+	return nil
+}
+
+// scanAgents unmarshals the `data` column of every row in rows.
+func scanAgents(rows *sql.Rows) ([]*persona.Agent, error) {
+	defer rows.Close()
+	var out []*persona.Agent
+	for rows.Next() {
+		var blob string
+		if err := rows.Scan(&blob); err != nil {
+			return nil, err
+		}
+		var a persona.Agent
+		if err := json.Unmarshal([]byte(blob), &a); err != nil {
+			return nil, err
+		}
+		out = append(out, &a)
+	}
+	return out, rows.Err()
+}
+
+func (s *personaStore) getOne(ctx context.Context, where string, arg ...any) (*persona.Agent, error) {
+	var blob string
+	err := s.db.QueryRowContext(ctx, `SELECT data FROM agents WHERE `+where, arg...).Scan(&blob)
+	switch {
+	case errors.Is(err, sql.ErrNoRows):
+		return nil, persona.ErrNotFound
+	case err != nil:
+		return nil, err
+	}
+	var a persona.Agent
+	if err := json.Unmarshal([]byte(blob), &a); err != nil {
+		return nil, err
+	}
+	return &a, nil
+}
+
+func (s *personaStore) GetAgent(ctx context.Context, id string) (*persona.Agent, error) {
+	return s.getOne(ctx, "id = ?", id)
+}
+
+func (s *personaStore) GetAgentByName(ctx context.Context, ownerID, name string) (*persona.Agent, error) {
+	return s.getOne(ctx, "owner_id = ? AND name = ?", ownerID, name)
+}
+
+func (s *personaStore) GetAgentByWebhookSecret(ctx context.Context, secret string) (*persona.Agent, error) {
+	if secret == "" {
+		return nil, persona.ErrNotFound
+	}
+	return s.getOne(ctx, "webhook_secret = ?", secret)
+}
+
+func (s *personaStore) ListAgents(ctx context.Context, ownerID string) ([]*persona.Agent, error) {
+	rows, err := s.db.QueryContext(ctx, `SELECT data FROM agents WHERE owner_id = ? ORDER BY name`, ownerID)
+	if err != nil {
+		return nil, fmt.Errorf("personaStore.ListAgents: %w", err)
+	}
+	return scanAgents(rows)
+}
+
+func (s *personaStore) ListAllAgents(ctx context.Context) ([]*persona.Agent, error) {
+	rows, err := s.db.QueryContext(ctx, `SELECT data FROM agents ORDER BY name`)
+	if err != nil {
+		return nil, fmt.Errorf("personaStore.ListAllAgents: %w", err)
+	}
+	return scanAgents(rows)
+}
+
+func (s *personaStore) DeleteAgent(ctx context.Context, id string) error {
+	if _, err := s.db.ExecContext(ctx, `DELETE FROM agents WHERE id = ?`, id); err != nil {
+		return fmt.Errorf("personaStore.DeleteAgent: %w", err)
+	}
+	return nil
+}
+
+func (s *personaStore) ListAgentsByChatbotChannelFilter(ctx context.Context) ([]*persona.Agent, error) {
+	rows, err := s.db.QueryContext(ctx, `SELECT data FROM agents WHERE chatbot_channel_filter != '' ORDER BY name`)
+	if err != nil {
+		return nil, fmt.Errorf("personaStore.ListAgentsByChatbotChannelFilter: %w", err)
+	}
+	return scanAgents(rows)
+}
+
+func (s *personaStore) ListScheduledAgents(ctx context.Context, dueBefore time.Time) ([]*persona.Agent, error) {
+	rows, err := s.db.QueryContext(ctx,
+		`SELECT data FROM agents WHERE schedule != '' AND next_run_at > 0 AND next_run_at <= ? ORDER BY next_run_at`,
+		dueBefore.Unix())
+	if err != nil {
+		return nil, fmt.Errorf("personaStore.ListScheduledAgents: %w", err)
+	}
+	return scanAgents(rows)
+}
+
+func (s *personaStore) MarkAgentScheduledRun(ctx context.Context, agentID string, ranAt, nextAt time.Time) error {
+	// Single atomic statement, not Get→mutate→Save: closes the lost-update
+	// window a concurrent Mark/edit would otherwise open. json_set keeps the
+	// blob's *time.Time fields consistent with the next_run_at column (Go
+	// encodes time.Time as RFC3339Nano, so it round-trips through GetAgent).
+	res, err := s.db.ExecContext(ctx,
+		`UPDATE agents SET next_run_at=?, data=json_set(data,'$.NextRunAt',?,'$.LastScheduledRunAt',?) WHERE id=?`,
+		nextAt.Unix(), nextAt.Format(time.RFC3339Nano), ranAt.Format(time.RFC3339Nano), agentID)
+	if err != nil {
+		return fmt.Errorf("personaStore.MarkAgentScheduledRun: %w", err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return persona.ErrNotFound
+	}
+	return nil
+}

contrib/store/persona_store_test.go

@@ -0,0 +1,106 @@
+package store
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/persona"
+)
+
+func TestSQLitePersonaStore(t *testing.T) {
+	ctx := context.Background()
+	db, err := Open(":memory:")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	st := db.Personas()
+	if err := st.InitializeAgentStorage(ctx); err != nil {
+		t.Fatal(err)
+	}
+
+	// Full struct round-trips through the JSON blob (incl. nested + map fields).
+	a := &persona.Agent{
+		ID: "a1", Name: "helper", OwnerID: "o1", SystemPrompt: "be nice",
+		ModelTier: "fast", SkillPalette: []string{"animate"},
+		StateReactEmoji:      map[string]string{"running": "⏳"},
+		ChatbotChannelFilter: "general",
+	}
+	if err := st.SaveAgent(ctx, a); err != nil {
+		t.Fatal(err)
+	}
+	got, err := st.GetAgent(ctx, "a1")
+	if err != nil || got.SystemPrompt != "be nice" || len(got.SkillPalette) != 1 ||
+		got.StateReactEmoji["running"] != "⏳" {
+		t.Fatalf("round-trip lost fields: %+v (err %v)", got, err)
+	}
+	if byName, err := st.GetAgentByName(ctx, "o1", "helper"); err != nil || byName.ID != "a1" {
+		t.Fatalf("GetAgentByName: %v %+v", err, byName)
+	}
+	if cf, _ := st.ListAgentsByChatbotChannelFilter(ctx); len(cf) != 1 {
+		t.Errorf("ListAgentsByChatbotChannelFilter = %d, want 1", len(cf))
+	}
+
+	// Scheduling: due query + MarkAgentScheduledRun round-trip.
+	now := time.Now().UTC()
+	sched := &persona.Agent{ID: "s1", Name: "cron", OwnerID: "o1", Schedule: "0 * * * *"}
+	due := now.Add(-time.Minute)
+	sched.NextRunAt = &due
+	if err := st.SaveAgent(ctx, sched); err != nil {
+		t.Fatal(err)
+	}
+	dueList, _ := st.ListScheduledAgents(ctx, now)
+	if len(dueList) != 1 || dueList[0].ID != "s1" {
+		t.Fatalf("ListScheduledAgents = %+v", dueList)
+	}
+	next := now.Add(time.Hour)
+	if err := st.MarkAgentScheduledRun(ctx, "s1", now, next); err != nil {
+		t.Fatal(err)
+	}
+	if again, _ := st.ListScheduledAgents(ctx, now); len(again) != 0 {
+		t.Errorf("after MarkAgentScheduledRun, nothing should be due before now: %+v", again)
+	}
+
+	if err := st.DeleteAgent(ctx, "a1"); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := st.GetAgent(ctx, "a1"); err != persona.ErrNotFound {
+		t.Errorf("GetAgent after delete = %v, want ErrNotFound", err)
+	}
+}
+
+// TestMarkAgentScheduledRunBlobRoundTrips guards the json_set atomic update:
+// the JSON blob must stay parseable and reflect the new scheduled times.
+func TestMarkAgentScheduledRunBlobRoundTrips(t *testing.T) {
+	ctx := context.Background()
+	db, _ := Open(":memory:")
+	defer db.Close()
+	st := db.Personas()
+	st.InitializeAgentStorage(ctx)
+	start := time.Now().UTC()
+	a := &persona.Agent{ID: "m1", Name: "n", OwnerID: "o", Schedule: "0 * * * *"}
+	a.NextRunAt = &start
+	if err := st.SaveAgent(ctx, a); err != nil {
+		t.Fatal(err)
+	}
+	ran := start
+	next := start.Add(time.Hour)
+	if err := st.MarkAgentScheduledRun(ctx, "m1", ran, next); err != nil {
+		t.Fatal(err)
+	}
+	got, err := st.GetAgent(ctx, "m1") // blob must still unmarshal
+	if err != nil {
+		t.Fatalf("GetAgent after json_set Mark failed (blob corrupt?): %v", err)
+	}
+	if got.NextRunAt == nil || !got.NextRunAt.Equal(next) {
+		t.Errorf("blob NextRunAt = %v, want %v", got.NextRunAt, next)
+	}
+	if got.LastScheduledRunAt == nil || !got.LastScheduledRunAt.Equal(ran) {
+		t.Errorf("blob LastScheduledRunAt = %v, want %v", got.LastScheduledRunAt, ran)
+	}
+	// Unknown id -> ErrNotFound.
+	if err := st.MarkAgentScheduledRun(ctx, "nope", ran, next); err != persona.ErrNotFound {
+		t.Errorf("Mark(unknown) = %v, want ErrNotFound", err)
+	}
+}

contrib/store/skill_store.go

@@ -0,0 +1,280 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/skill"
+)
+
+// skillStore is the SQLite-backed skill.SkillStore. Same JSON-blob + indexed
+// columns approach as personaStore: the full Skill round-trips, lookups stay
+// indexed. Versions live in their own table (each SkillVersion embeds a full
+// Skill snapshot, stored as a JSON blob).
+type skillStore struct{ db *sql.DB }
+
+// Skills returns a durable skill.SkillStore backed by this database.
+func (d *DB) Skills() skill.SkillStore { return &skillStore{db: d.sql} }
+
+var _ skill.SkillStore = (*skillStore)(nil)
+
+func (s *skillStore) Initialize(ctx context.Context) error {
+	_, err := s.db.ExecContext(ctx, `
+CREATE TABLE IF NOT EXISTS skills (
+	id            TEXT PRIMARY KEY,
+	owner_id      TEXT NOT NULL DEFAULT '',
+	name          TEXT NOT NULL DEFAULT '',
+	source        TEXT NOT NULL DEFAULT '',
+	visibility    TEXT NOT NULL DEFAULT '',
+	chatbot       INTEGER NOT NULL DEFAULT 0, -- ExposeAsChatbotTool
+	schedule      TEXT NOT NULL DEFAULT '',
+	next_run_at   INTEGER NOT NULL DEFAULT 0,
+	data          TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_skills_owner ON skills(owner_id);
+CREATE INDEX IF NOT EXISTS idx_skills_vis ON skills(visibility);
+CREATE INDEX IF NOT EXISTS idx_skills_sched ON skills(schedule, next_run_at);
+CREATE TABLE IF NOT EXISTS skill_versions (
+	id        TEXT PRIMARY KEY,
+	skill_id  TEXT NOT NULL,
+	version   TEXT NOT NULL DEFAULT '',
+	seq       INTEGER NOT NULL,            -- append order, for newest-first
+	data      TEXT NOT NULL
+);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_skill_versions_skill ON skill_versions(skill_id, seq);`)
+	if err != nil {
+		return fmt.Errorf("skillStore.Initialize: %w", err)
+	}
+	return nil
+}
+
+func (s *skillStore) Save(ctx context.Context, sk *skill.Skill) error {
+	blob, err := json.Marshal(sk)
+	if err != nil {
+		return fmt.Errorf("skillStore.Save: marshal: %w", err)
+	}
+	var next int64
+	if !sk.NextRunAt.IsZero() {
+		next = sk.NextRunAt.Unix()
+	}
+	chatbot := 0
+	if sk.ExposeAsChatbotTool {
+		chatbot = 1
+	}
+	_, err = s.db.ExecContext(ctx, `
+INSERT INTO skills (id, owner_id, name, source, visibility, chatbot, schedule, next_run_at, data)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET
+	owner_id=excluded.owner_id, name=excluded.name, source=excluded.source,
+	visibility=excluded.visibility, chatbot=excluded.chatbot, schedule=excluded.schedule,
+	next_run_at=excluded.next_run_at, data=excluded.data`,
+		sk.ID, sk.OwnerID, sk.Name, string(sk.Source), string(sk.Visibility), chatbot,
+		sk.Schedule, next, string(blob))
+	if err != nil {
+		return fmt.Errorf("skillStore.Save: %w", err)
+	}
+	return nil
+}
+
+func scanSkills(rows *sql.Rows) ([]skill.Skill, error) {
+	defer rows.Close()
+	var out []skill.Skill
+	for rows.Next() {
+		var blob string
+		if err := rows.Scan(&blob); err != nil {
+			return nil, err
+		}
+		var sk skill.Skill
+		if err := json.Unmarshal([]byte(blob), &sk); err != nil {
+			return nil, err
+		}
+		out = append(out, sk)
+	}
+	return out, rows.Err()
+}
+
+func (s *skillStore) getOne(ctx context.Context, where string, arg ...any) (*skill.Skill, error) {
+	var blob string
+	err := s.db.QueryRowContext(ctx, `SELECT data FROM skills WHERE `+where, arg...).Scan(&blob)
+	switch {
+	case errors.Is(err, sql.ErrNoRows):
+		return nil, skill.ErrNotFound
+	case err != nil:
+		return nil, err
+	}
+	var sk skill.Skill
+	if err := json.Unmarshal([]byte(blob), &sk); err != nil {
+		return nil, err
+	}
+	return &sk, nil
+}
+
+func (s *skillStore) Get(ctx context.Context, id string) (*skill.Skill, error) {
+	return s.getOne(ctx, "id = ?", id)
+}
+
+func (s *skillStore) GetByName(ctx context.Context, ownerID, name string) (*skill.Skill, error) {
+	return s.getOne(ctx, "owner_id = ? AND name = ?", ownerID, name)
+}
+
+func (s *skillStore) ListBuiltinByName(ctx context.Context, name string) (*skill.Skill, error) {
+	return s.getOne(ctx, "source = ? AND name = ?", string(skill.SourceBuiltin), name)
+}
+
+func (s *skillStore) Delete(ctx context.Context, id string) error {
+	if _, err := s.db.ExecContext(ctx, `DELETE FROM skills WHERE id = ?`, id); err != nil {
+		return fmt.Errorf("skillStore.Delete: %w", err)
+	}
+	return nil
+}
+
+func (s *skillStore) query(ctx context.Context, where string, arg ...any) ([]skill.Skill, error) {
+	rows, err := s.db.QueryContext(ctx, `SELECT data FROM skills WHERE `+where+` ORDER BY name`, arg...)
+	if err != nil {
+		return nil, err
+	}
+	return scanSkills(rows)
+}
+
+func (s *skillStore) ListByOwner(ctx context.Context, ownerID string) ([]skill.Skill, error) {
+	return s.query(ctx, "owner_id = ?", ownerID)
+}
+
+func (s *skillStore) ListPublic(ctx context.Context) ([]skill.Skill, error) {
+	return s.query(ctx, "visibility = ?", string(skill.VisibilityPublic))
+}
+
+func (s *skillStore) ListChatbotExposed(ctx context.Context) ([]skill.Skill, error) {
+	return s.query(ctx, "chatbot = 1")
+}
+
+// ListSharedWith loads visibility=shared rows and filters SharedWith in Go (the
+// shared set per skill is small; avoids a JSON-array query).
+func (s *skillStore) ListSharedWith(ctx context.Context, memberID string) ([]skill.Skill, error) {
+	shared, err := s.query(ctx, "visibility = ?", string(skill.VisibilityShared))
+	if err != nil {
+		return nil, err
+	}
+	out := shared[:0]
+	for _, sk := range shared {
+		for _, id := range sk.SharedWith {
+			if id == memberID {
+				out = append(out, sk)
+				break
+			}
+		}
+	}
+	return out, nil
+}
+
+func (s *skillStore) ListDueScheduled(ctx context.Context, now time.Time) ([]skill.Skill, error) {
+	rows, err := s.db.QueryContext(ctx,
+		`SELECT data FROM skills WHERE schedule != '' AND next_run_at > 0 AND next_run_at <= ? ORDER BY next_run_at`,
+		now.Unix())
+	if err != nil {
+		return nil, fmt.Errorf("skillStore.ListDueScheduled: %w", err)
+	}
+	return scanSkills(rows)
+}
+
+func (s *skillStore) MarkScheduledRun(ctx context.Context, skillID string, ranAt, nextAt time.Time) error {
+	// Single atomic statement instead of Get→mutate→Save: a concurrent Mark or
+	// admin edit can't lose this update (no read-modify-write window). json_set
+	// keeps the JSON blob's NextRunAt/LastScheduledRunAt consistent with the
+	// indexed next_run_at column; RFC3339Nano matches Go's time JSON encoding so
+	// the blob still round-trips through Get.
+	var next int64
+	if !nextAt.IsZero() {
+		next = nextAt.Unix()
+	}
+	res, err := s.db.ExecContext(ctx,
+		`UPDATE skills SET next_run_at=?, data=json_set(data,'$.NextRunAt',?,'$.LastScheduledRunAt',?) WHERE id=?`,
+		next, nextAt.Format(time.RFC3339Nano), ranAt.Format(time.RFC3339Nano), skillID)
+	if err != nil {
+		return fmt.Errorf("skillStore.MarkScheduledRun: %w", err)
+	}
+	if n, _ := res.RowsAffected(); n == 0 {
+		return skill.ErrNotFound
+	}
+	return nil
+}
+
+func (s *skillStore) AppendVersion(ctx context.Context, sv skill.SkillVersion) error {
+	if sv.SkillID == "" {
+		return fmt.Errorf("skillStore.AppendVersion: skill_id is required")
+	}
+	blob, err := json.Marshal(sv)
+	if err != nil {
+		return fmt.Errorf("skillStore.AppendVersion: marshal: %w", err)
+	}
+	// seq = current max+1 for this skill (newest-first ordering key). The
+	// MAX-then-INSERT runs in ONE transaction and the (skill_id, seq) index is
+	// UNIQUE, so two concurrent appends can't both land the same seq: the loser
+	// fails loudly on commit instead of silently corrupting the ordering. The
+	// Scan error is propagated (was swallowed, leaving seq=0 on failure).
+	tx, err := s.db.BeginTx(ctx, nil)
+	if err != nil {
+		return fmt.Errorf("skillStore.AppendVersion: begin: %w", err)
+	}
+	defer tx.Rollback() //nolint:errcheck // no-op after Commit
+	var seq int64
+	if err := tx.QueryRowContext(ctx, `SELECT COALESCE(MAX(seq),0)+1 FROM skill_versions WHERE skill_id = ?`, sv.SkillID).Scan(&seq); err != nil {
+		return fmt.Errorf("skillStore.AppendVersion: seq: %w", err)
+	}
+	if _, err := tx.ExecContext(ctx,
+		`INSERT INTO skill_versions (id, skill_id, version, seq, data) VALUES (?, ?, ?, ?, ?)`,
+		sv.ID, sv.SkillID, sv.Version, seq, string(blob)); err != nil {
+		return fmt.Errorf("skillStore.AppendVersion: insert: %w", err)
+	}
+	if err := tx.Commit(); err != nil {
+		return fmt.Errorf("skillStore.AppendVersion: commit: %w", err)
+	}
+	return nil
+}
+
+func (s *skillStore) ListVersionsBySkill(ctx context.Context, skillID string, limit int) ([]skill.SkillVersion, error) {
+	q := `SELECT data FROM skill_versions WHERE skill_id = ? ORDER BY seq DESC`
+	args := []any{skillID}
+	if limit > 0 {
+		q += ` LIMIT ?`
+		args = append(args, limit)
+	}
+	rows, err := s.db.QueryContext(ctx, q, args...)
+	if err != nil {
+		return nil, fmt.Errorf("skillStore.ListVersionsBySkill: %w", err)
+	}
+	defer rows.Close()
+	var out []skill.SkillVersion
+	for rows.Next() {
+		var blob string
+		if err := rows.Scan(&blob); err != nil {
+			return nil, err
+		}
+		var sv skill.SkillVersion
+		if err := json.Unmarshal([]byte(blob), &sv); err != nil {
+			return nil, err
+		}
+		out = append(out, sv)
+	}
+	return out, rows.Err()
+}
+
+func (s *skillStore) GetVersionByID(ctx context.Context, versionID string) (*skill.SkillVersion, error) {
+	var blob string
+	err := s.db.QueryRowContext(ctx, `SELECT data FROM skill_versions WHERE id = ?`, versionID).Scan(&blob)
+	switch {
+	case errors.Is(err, sql.ErrNoRows):
+		return nil, skill.ErrNotFound
+	case err != nil:
+		return nil, err
+	}
+	var sv skill.SkillVersion
+	if err := json.Unmarshal([]byte(blob), &sv); err != nil {
+		return nil, err
+	}
+	return &sv, nil
+}

contrib/store/skill_store_test.go

@@ -0,0 +1,72 @@
+package store
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/skill"
+)
+
+func TestSQLiteSkillStore(t *testing.T) {
+	ctx := context.Background()
+	db, err := Open(":memory:")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer db.Close()
+	st := db.Skills()
+	if err := st.Initialize(ctx); err != nil {
+		t.Fatal(err)
+	}
+
+	pub := &skill.Skill{ID: "a", Name: "pub", OwnerID: "o1", Visibility: skill.VisibilityPublic,
+		Tools: []string{"summarize"}, ExposeAsChatbotTool: true}
+	shared := &skill.Skill{ID: "b", Name: "shr", OwnerID: "o1", Visibility: skill.VisibilityShared, SharedWith: []string{"bob"}}
+	if err := st.Save(ctx, pub); err != nil {
+		t.Fatal(err)
+	}
+	if err := st.Save(ctx, shared); err != nil {
+		t.Fatal(err)
+	}
+
+	got, err := st.Get(ctx, "a")
+	if err != nil || len(got.Tools) != 1 || !got.ExposeAsChatbotTool {
+		t.Fatalf("round-trip: %v %+v", err, got)
+	}
+	if ps, _ := st.ListPublic(ctx); len(ps) != 1 || ps[0].ID != "a" {
+		t.Errorf("ListPublic = %+v", ps)
+	}
+	if ss, _ := st.ListSharedWith(ctx, "bob"); len(ss) != 1 || ss[0].ID != "b" {
+		t.Errorf("ListSharedWith(bob) = %+v", ss)
+	}
+	if ss, _ := st.ListSharedWith(ctx, "carol"); len(ss) != 0 {
+		t.Errorf("ListSharedWith(carol) should be empty: %+v", ss)
+	}
+	if ce, _ := st.ListChatbotExposed(ctx); len(ce) != 1 {
+		t.Errorf("ListChatbotExposed = %d, want 1", len(ce))
+	}
+
+	// Versions newest-first + by id.
+	st.AppendVersion(ctx, skill.SkillVersion{ID: "v1", SkillID: "a", Version: "1.0.0"})
+	st.AppendVersion(ctx, skill.SkillVersion{ID: "v2", SkillID: "a", Version: "1.1.0"})
+	vs, _ := st.ListVersionsBySkill(ctx, "a", 10)
+	if len(vs) != 2 || vs[0].ID != "v2" {
+		t.Errorf("versions newest-first: %+v", vs)
+	}
+	if gv, err := st.GetVersionByID(ctx, "v1"); err != nil || gv.Version != "1.0.0" {
+		t.Errorf("GetVersionByID: %v %+v", err, gv)
+	}
+
+	// Scheduling.
+	now := time.Now().UTC()
+	cron := &skill.Skill{ID: "c", Name: "cron", OwnerID: "o1", Schedule: "0 * * * *", NextRunAt: now.Add(-time.Minute)}
+	st.Save(ctx, cron)
+	if due, _ := st.ListDueScheduled(ctx, now); len(due) != 1 || due[0].ID != "c" {
+		t.Fatalf("ListDueScheduled = %+v", due)
+	}
+	st.MarkScheduledRun(ctx, "c", now, now.Add(time.Hour))
+	if due, _ := st.ListDueScheduled(ctx, now); len(due) != 0 {
+		t.Errorf("after MarkScheduledRun nothing due: %+v", due)
+	}
+}

contrib/store/sqlite.go

@@ -0,0 +1,54 @@
+// Package store provides durable, pure-Go SQLite implementations of executus's
+// battery store seams (audit, budget, persona, skill). It is a SEPARATE nested
+// module so the SQLite driver (modernc.org/sqlite — pure Go, no cgo) never
+// enters the executus core go.sum: a static-binary host (gadfly) that imports
+// only the core stays static, while a host that wants turnkey persistence
+// imports this module and gets every *Store seam backed by one SQLite file.
+//
+//	db, _ := store.Open("file:executus.db?_pragma=busy_timeout(5000)")
+//	defer db.Close()
+//	budgetStore := db.Budget() // satisfies budget.BudgetStorage
+package store
+
+import (
+	"database/sql"
+	"fmt"
+
+	_ "modernc.org/sqlite" // pure-Go driver, registered as "sqlite"
+)
+
+// DB is a handle to one SQLite database backing the executus store seams. Each
+// accessor (Budget(), …) returns a seam implementation sharing this connection.
+// Safe for concurrent use (SQLite serializes writes; busy_timeout handles
+// contention). Construct with Open; close with Close.
+type DB struct {
+	sql *sql.DB
+}
+
+// Open opens (creating if absent) a SQLite database at dsn and returns a DB. A
+// dsn of ":memory:" yields an ephemeral in-memory database. The caller owns the
+// returned DB and must Close it.
+func Open(dsn string) (*DB, error) {
+	sqldb, err := sql.Open("sqlite", dsn)
+	if err != nil {
+		return nil, fmt.Errorf("store: open %q: %w", dsn, err)
+	}
+	// A contended writer should WAIT for the lock, not fail immediately — set a
+	// busy_timeout so concurrent stores don't see spurious SQLITE_BUSY. (The
+	// doc example advertised this; it's now actually applied for every DSN.)
+	if _, err := sqldb.Exec("PRAGMA busy_timeout=5000"); err != nil {
+		sqldb.Close()
+		return nil, fmt.Errorf("store: set busy_timeout %q: %w", dsn, err)
+	}
+	if err := sqldb.Ping(); err != nil {
+		sqldb.Close()
+		return nil, fmt.Errorf("store: ping %q: %w", dsn, err)
+	}
+	return &DB{sql: sqldb}, nil
+}
+
+// Close closes the underlying database.
+func (d *DB) Close() error { return d.sql.Close() }
+
+// SQL exposes the underlying *sql.DB for hosts that need direct access.
+func (d *DB) SQL() *sql.DB { return d.sql }

critic/critic.go

@@ -0,0 +1,302 @@
+// Package critic is the run-watchdog battery: a two-tier timeout monitor that
+// catches a run that has stopped making progress. It plugs into
+// run.Ports.Critic.
+//
+// The split of concerns is deliberate. executus owns the deterministic
+// MECHANICS — track activity, fire on a soft timeout, enforce a hard-kill
+// backstop, carry steer messages and the extendable deadline back to the
+// executor. The POLICY — what to actually do when a run stalls (nudge it,
+// extend its deadline, kill it, escalate to a human) — is the Escalator seam.
+// Mort plugs its LLM critic-agent in as an Escalator; ExtendOnce is the
+// zero-dependency default.
+//
+// The executor wires run.Ports.Critic (C0b): it feeds the handle activity,
+// binds the run context to its extendable Deadline, drains its Steer, and polls
+// MaxSteps each step so an Escalator can also raise a long run's step ceiling
+// (Decision.RaiseStepsBy).
+package critic
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"math"
+	"sync"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+)
+
+// Progress is the snapshot the critic hands an Escalator when a run stalls.
+type Progress struct {
+	Iterations   int           // completed agent-loop iterations so far
+	LastActivity time.Time     // wall-clock of the last step/tool event
+	Idle         time.Duration // now - LastActivity
+	LastTool     string        // name of the most recently started tool ("" if none)
+}
+
+// Decision is the Escalator's verdict for a stalled run. Zero value = do
+// nothing (let the hard backstop eventually kill a truly hung run).
+type Decision struct {
+	Nudge        []llm.Message // injected before the agent's next turn (a steer)
+	ExtendBy     time.Duration // push the hard deadline out by this much
+	RaiseStepsBy int           // raise the run's tool-dispatch step ceiling by this
+	Kill         bool          // cancel the run now
+	KillReason   string
+}
+
+// Escalator decides what to do when a run crosses its soft timeout. It is
+// called at most once per idle period (a fresh step/tool event re-arms it).
+type Escalator interface {
+	OnSoftTimeout(ctx context.Context, info run.RunInfo, p Progress) Decision
+}
+
+// ExtendOnce is the default Escalator: the first time a given run stalls it
+// extends that run's deadline by By (giving a slow-but-healthy run room), then
+// takes no further action for it — so a genuinely hung run is later killed by
+// the hard backstop. A nil/zero By falls back to one soft-timeout's worth.
+//
+// The one-shot is keyed PER RUN (by RunInfo.RunID): a single System shares one
+// ExtendOnce across every run it monitors, so a global flag would let only the
+// first run to stall ever get its extension. The fired set grows with the
+// number of distinct runs that stall — fine for a process's run volume; a host
+// running unboundedly long can construct a fresh System periodically.
+type ExtendOnce struct {
+	By time.Duration
+
+	mu    sync.Mutex
+	fired map[string]bool // run ids that have already had their one extension
+}
+
+// OnSoftTimeout implements Escalator.
+func (e *ExtendOnce) OnSoftTimeout(_ context.Context, info run.RunInfo, p Progress) Decision {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if e.fired[info.RunID] {
+		return Decision{}
+	}
+	if e.fired == nil {
+		e.fired = map[string]bool{}
+	}
+	e.fired[info.RunID] = true
+	by := e.By
+	if by <= 0 {
+		by = p.Idle // ~one soft timeout
+	}
+	return Decision{ExtendBy: by}
+}
+
+// System implements run.Critic. Construct with New; one System monitors many
+// runs concurrently (each Monitor returns an independent handle).
+type System struct {
+	esc           Escalator
+	backstopMul   float64 // hard deadline = softTimeout * backstopMul from start
+	checkInterval time.Duration
+	now           func() time.Time
+	logger        *slog.Logger
+}
+
+func (s *System) log() *slog.Logger {
+	if s.logger != nil {
+		return s.logger
+	}
+	return slog.Default()
+}
+
+// New builds a run.Critic. esc is the policy (nil → ExtendOnce). backstopMul is
+// the hard-kill backstop as a multiple of each run's soft timeout (<=1 → 3). A
+// nil esc + the default backstop gives a safe "extend once, then hard-kill"
+// watchdog with no host wiring.
+func New(esc Escalator, backstopMul float64) *System {
+	if esc == nil {
+		esc = &ExtendOnce{}
+	}
+	if backstopMul <= 1 {
+		backstopMul = 3
+	}
+	return &System{esc: esc, backstopMul: backstopMul, now: time.Now}
+}
+
+var _ run.Critic = (*System)(nil)
+
+// Monitor starts watching a run and returns its handle. Implements run.Critic.
+func (s *System) Monitor(ctx context.Context, info run.RunInfo, softTimeout time.Duration) run.CriticHandle {
+	if softTimeout <= 0 {
+		return run.CriticHandle(nil) // no soft timeout → not monitored
+	}
+	now := s.now()
+	check := s.checkInterval
+	if check <= 0 {
+		check = softTimeout / 2
+		if check < time.Second {
+			check = time.Second
+		}
+	}
+	h := &handle{
+		sys:          s,
+		info:         info,
+		softTimeout:  softTimeout,
+		now:          s.now,
+		lastActivity: now,
+		deadline:     now.Add(time.Duration(float64(softTimeout) * s.backstopMul)),
+		maxSteps:     info.MaxIterations, // base ceiling; an Escalator may RaiseStepsBy
+		stopCh:       make(chan struct{}),
+	}
+	go h.watch(ctx, check)
+	return h
+}
+
+// handle is one run's live critic link. Implements run.CriticHandle.
+type handle struct {
+	sys         *System
+	info        run.RunInfo
+	softTimeout time.Duration
+	now         func() time.Time
+
+	mu           sync.Mutex
+	lastActivity time.Time
+	escalatedAt  time.Time // lastActivity value we last escalated for (de-dupes per idle period)
+	deadline     time.Time
+	steer        []llm.Message
+	iterations   int
+	maxSteps     int // current tool-dispatch ceiling (base MaxIterations, raised by RaiseStepsBy)
+	lastTool     string
+	killed       bool  // sticky: once an Escalator kills, no later decision un-kills it
+	killCause    error // non-nil once killed; surfaced via KillCause for "killed" status
+	stopped      bool
+	stopCh       chan struct{}
+}
+
+func (h *handle) RecordStep(iter int, _ *llm.Response) {
+	// This battery's Progress tracks iteration count + activity, not per-step
+	// payload, so the response is unused here; a richer Escalator could record it.
+	h.mu.Lock()
+	h.iterations = iter
+	h.lastActivity = h.now()
+	h.mu.Unlock()
+}
+
+func (h *handle) RecordToolStart(name, _ string) {
+	h.mu.Lock()
+	h.lastTool = name
+	h.lastActivity = h.now()
+	h.mu.Unlock()
+}
+
+func (h *handle) Steer() []llm.Message {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if len(h.steer) == 0 {
+		return nil
+	}
+	out := h.steer
+	h.steer = nil
+	return out
+}
+
+func (h *handle) Deadline() time.Time {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return h.deadline
+}
+
+func (h *handle) MaxSteps() int {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return h.maxSteps
+}
+
+func (h *handle) KillCause() error {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return h.killCause
+}
+
+func (h *handle) Stop() {
+	h.mu.Lock()
+	if !h.stopped {
+		h.stopped = true
+		close(h.stopCh)
+	}
+	h.mu.Unlock()
+}
+
+// watch fires the Escalator once per idle period the run crosses its soft
+// timeout, and applies the returned Decision.
+func (h *handle) watch(ctx context.Context, interval time.Duration) {
+	// A misbehaving Escalator that panics must not silently kill the watch
+	// goroutine (which would leave the run unmonitored for its lifetime). Log
+	// and exit cleanly — the run falls back to the deadline already set.
+	defer func() {
+		if r := recover(); r != nil {
+			h.sys.log().Error("critic watch panicked; run is now unmonitored", "run", h.info.RunID, "panic", r)
+		}
+	}()
+	t := time.NewTicker(interval)
+	defer t.Stop()
+	for {
+		select {
+		case <-h.stopCh:
+			return
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			h.tick(ctx)
+		}
+	}
+}
+
+func (h *handle) tick(ctx context.Context) {
+	h.mu.Lock()
+	// Kill is sticky: once an Escalator has killed this run, no later tick (and
+	// no later Decision) un-collapses the deadline.
+	if h.killed {
+		h.mu.Unlock()
+		return
+	}
+	idle := h.now().Sub(h.lastActivity)
+	// Only escalate once per idle period: skip if we already escalated for this
+	// exact lastActivity (a fresh step/tool updates lastActivity and re-arms).
+	if idle < h.softTimeout || h.escalatedAt.Equal(h.lastActivity) {
+		h.mu.Unlock()
+		return
+	}
+	h.escalatedAt = h.lastActivity
+	snap := Progress{Iterations: h.iterations, LastActivity: h.lastActivity, Idle: idle, LastTool: h.lastTool}
+	h.mu.Unlock()
+
+	d := h.sys.esc.OnSoftTimeout(ctx, h.info, snap)
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.killed { // a concurrent tick may have killed while OnSoftTimeout ran
+		return
+	}
+	if d.Kill {
+		h.killed = true
+		reason := d.KillReason
+		if reason == "" {
+			reason = "critic killed the run"
+		}
+		h.killCause = errors.New(reason) // surfaced via KillCause → "killed" status
+		h.deadline = h.now()             // immediate hard deadline → executor cancels
+		return                           // ignore any Nudge/ExtendBy paired with a Kill
+	}
+	if len(d.Nudge) > 0 {
+		h.steer = append(h.steer, d.Nudge...)
+	}
+	if d.ExtendBy > 0 {
+		h.deadline = h.deadline.Add(d.ExtendBy)
+	}
+	if d.RaiseStepsBy > 0 {
+		// Overflow-safe: a buggy Escalator returning a huge delta must not wrap
+		// maxSteps negative (which the executor would read as "defer to base").
+		if d.RaiseStepsBy > math.MaxInt-h.maxSteps {
+			h.maxSteps = math.MaxInt
+		} else {
+			h.maxSteps += d.RaiseStepsBy
+		}
+	}
+}

critic/critic_test.go

@@ -0,0 +1,100 @@
+package critic
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// escFunc adapts a func to an Escalator.
+type escFunc func(context.Context, run.RunInfo, Progress) Decision
+
+func (f escFunc) OnSoftTimeout(ctx context.Context, i run.RunInfo, p Progress) Decision {
+	return f(ctx, i, p)
+}
+
+func TestMonitorEscalatesOncePerIdlePeriodAndExtends(t *testing.T) {
+	var mu sync.Mutex
+	var calls int
+	esc := escFunc(func(_ context.Context, _ run.RunInfo, p Progress) Decision {
+		mu.Lock()
+		calls++
+		mu.Unlock()
+		return Decision{ExtendBy: 50 * time.Millisecond, Nudge: []llm.Message{{Role: llm.RoleUser}}}
+	})
+	s := New(esc, 3)
+	s.checkInterval = 5 * time.Millisecond
+	h := s.Monitor(context.Background(), run.RunInfo{RunID: "r"}, 20*time.Millisecond)
+	defer h.Stop()
+
+	d0 := h.Deadline()
+	time.Sleep(60 * time.Millisecond) // cross the soft timeout with no activity
+	mu.Lock()
+	c := calls
+	mu.Unlock()
+	if c < 1 {
+		t.Fatalf("expected at least one escalation, got %d", c)
+	}
+	// Nudge was queued and is drained once.
+	if msgs := h.Steer(); len(msgs) == 0 {
+		t.Error("expected a queued steer nudge")
+	}
+	if msgs := h.Steer(); len(msgs) != 0 {
+		t.Error("steer should drain (be empty on second read)")
+	}
+	// Deadline was extended.
+	if !h.Deadline().After(d0) {
+		t.Error("deadline should have been extended past the original")
+	}
+	// A fresh step re-arms; another idle period escalates again.
+	h.RecordStep(1, nil)
+	time.Sleep(60 * time.Millisecond)
+	mu.Lock()
+	c2 := calls
+	mu.Unlock()
+	if c2 <= c {
+		t.Errorf("a re-armed idle period should escalate again (%d -> %d)", c, c2)
+	}
+}
+
+func TestKillCollapsesDeadline(t *testing.T) {
+	esc := escFunc(func(context.Context, run.RunInfo, Progress) Decision {
+		return Decision{Kill: true, KillReason: "hung"}
+	})
+	s := New(esc, 10) // big backstop so only Kill collapses it
+	s.checkInterval = 5 * time.Millisecond
+	h := s.Monitor(context.Background(), run.RunInfo{RunID: "r"}, 20*time.Millisecond)
+	defer h.Stop()
+	time.Sleep(60 * time.Millisecond)
+	if h.Deadline().After(time.Now().Add(time.Second)) {
+		t.Error("Kill should collapse the deadline to ~now")
+	}
+}
+
+func TestExtendOnceOnlyFiresOnce(t *testing.T) {
+	e := &ExtendOnce{By: time.Minute}
+	// Same run id: only the first call extends.
+	d1 := e.OnSoftTimeout(context.Background(), run.RunInfo{RunID: "r1"}, Progress{})
+	d2 := e.OnSoftTimeout(context.Background(), run.RunInfo{RunID: "r1"}, Progress{})
+	if d1.ExtendBy != time.Minute {
+		t.Errorf("first decision should extend, got %+v", d1)
+	}
+	if d2.ExtendBy != 0 || d2.Kill {
+		t.Errorf("second call for the same run should be a no-op, got %+v", d2)
+	}
+	// A DIFFERENT run still gets its own one extension (per-run, not global).
+	if d3 := e.OnSoftTimeout(context.Background(), run.RunInfo{RunID: "r2"}, Progress{}); d3.ExtendBy != time.Minute {
+		t.Errorf("a different run should get its own extension, got %+v", d3)
+	}
+}
+
+func TestZeroSoftTimeoutNotMonitored(t *testing.T) {
+	s := New(nil, 3)
+	if h := s.Monitor(context.Background(), run.RunInfo{}, 0); h != nil {
+		t.Error("zero soft timeout should return a nil handle (not monitored)")
+	}
+}

examples/reviewer/README.md

@@ -0,0 +1,38 @@
+# examples/reviewer — the light-tier canary
+
+A **gadfly-shaped adversarial PR reviewer built on the executus core only** — no
+batteries, no database, no host adapters. It exists to prove that the core is
+sufficient for a static-binary light host (gadfly's shape), and that such a host
+keeps a `go.sum` free of `gorm`/`redis`/`discordgo`/`sqlite`.
+
+What it exercises, all from core:
+
+| Concern | executus core piece |
+|---|---|
+| Env-driven model fleet + tier overrides | `config.Env` + `model.Configure` |
+| Tier resolution + failover | `model.ParseModelForContext` |
+| N models × M lenses swarm | `fanout.Run` (with `PerKey` per-provider caps) |
+| Structured findings per cell | `model.GenerateWith[T]` |
+| One report section per model, worst-verdict-led | `Consolidate` (local) |
+
+## Run
+
+```sh
+REVIEWER_MODELS=fast,thinking \
+ANTHROPIC_API_KEY=sk-... \
+go run ./examples/reviewer -diff "$(git diff HEAD~1)"
+```
+
+Config (all optional, `REVIEWER_`-prefixed env):
+
+- `REVIEWER_MODELS` — csv of tier names / `provider/model` specs (default `fast`)
+- `REVIEWER_MODEL_TIER_<NAME>` — override a tier's resolved spec
+- `REVIEWER_MAX_CONCURRENT` — total in-flight swarm cells (default 6)
+- `REVIEWER_PROVIDER_CONCURRENCY` — per-provider cap (default 3)
+
+## Test
+
+`reviewer_test.go` runs the whole swarm against majordomo's fake provider
+(hermetic, no network) and asserts the consolidated verdicts. A `go list -deps`
+check in CI confirms the package pulls in no battery and no DB driver — the
+light-tier invariant.

examples/reviewer/main.go

@@ -0,0 +1,110 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/config"
+	"gitea.stevedudenhoeffer.com/steve/executus/fanout"
+	"gitea.stevedudenhoeffer.com/steve/executus/model"
+)
+
+// DefaultLenses is the canary's review suite (mirrors gadfly's default).
+var DefaultLenses = []Lens{
+	{Name: "security", Focus: "auth, injection, secret leakage, unsafe deserialization, SSRF."},
+	{Name: "correctness", Focus: "logic errors, broken invariants, off-by-one, contract violations."},
+	{Name: "error-handling", Focus: "swallowed errors, missing timeouts, races, unhandled edge cases."},
+}
+
+// Reviewer is configured entirely from the environment (the GADFLY_*-style light
+// host): REVIEWER_MODELS (csv of tier/spec), REVIEWER_MODEL_TIER_<NAME> overrides,
+// REVIEWER_MAX_CONCURRENT, REVIEWER_PROVIDER_CONCURRENCY. The diff is read from
+// -diff or stdin.
+//
+//	REVIEWER_MODELS=fast,thinking ANTHROPIC_API_KEY=... go run ./examples/reviewer < my.diff
+func main() {
+	cfg := config.Env("REVIEWER_")
+
+	// Tier table from env, with code defaults.
+	model.Configure(cfg, map[string]string{
+		"fast":     "anthropic/claude-haiku-4-5",
+		"thinking": "anthropic/claude-opus-4-8",
+	}, 0)
+
+	fleet := splitCSV(cfg.String("models", "fast"))
+	maxConc := cfg.Int("max_concurrent", 6)
+	perProvider := cfg.Int("provider_concurrency", 3)
+
+	diffFlag := flag.String("diff", "", "diff text to review; reads stdin when empty")
+	flag.Parse()
+	diff := *diffFlag
+	if strings.TrimSpace(diff) == "" {
+		// Guard against blocking forever on an interactive TTY (no piped input).
+		if fi, _ := os.Stdin.Stat(); fi != nil && fi.Mode()&os.ModeCharDevice != 0 {
+			fmt.Fprintln(os.Stderr, "reviewer: no diff (pass -diff or pipe one on stdin)")
+			os.Exit(2)
+		}
+		b, err := io.ReadAll(os.Stdin)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "reviewer: reading stdin: %v\n", err)
+			os.Exit(2)
+		}
+		diff = string(b)
+	}
+	if strings.TrimSpace(diff) == "" {
+		fmt.Fprintln(os.Stderr, "reviewer: no diff (pass -diff or pipe one on stdin)")
+		os.Exit(2)
+	}
+
+	ctx := context.Background()
+	var models []NamedModel
+	for _, spec := range fleet {
+		_, m, err := model.ParseModelForContext(ctx, spec)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "reviewer: resolve model %q: %v\n", spec, err)
+			os.Exit(1)
+		}
+		models = append(models, NamedModel{Name: spec, Provider: providerOf(spec), Model: m})
+	}
+
+	results := Review(ctx, models, DefaultLenses, diff, fanout.Options[cell]{
+		MaxConcurrent: maxConc,
+		PerKey:        perKeyCaps(models, perProvider),
+	})
+	fmt.Print(Consolidate(results))
+}
+
+func splitCSV(s string) []string {
+	var out []string
+	for _, p := range strings.Split(s, ",") {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// providerOf returns a model spec's provider (the first path segment, e.g.
+// "anthropic/claude-…" → "anthropic"; a bare tier name → itself).
+func providerOf(spec string) string {
+	if i := strings.IndexByte(spec, '/'); i > 0 {
+		return spec[:i]
+	}
+	return spec // bare tier name → its own bucket (don't collapse distinct tiers)
+}
+
+// perKeyCaps builds the PerKey map: each distinct provider capped at perProvider.
+func perKeyCaps(models []NamedModel, perProvider int) map[string]int {
+	if perProvider <= 0 {
+		return nil
+	}
+	caps := map[string]int{}
+	for _, m := range models {
+		caps[m.Provider] = perProvider
+	}
+	return caps
+}

examples/reviewer/reviewer.go

@@ -0,0 +1,204 @@
+// Command reviewer is executus's light-tier CANARY: a gadfly-shaped adversarial
+// PR reviewer built on the executus CORE ONLY — no batteries, no DB, no host.
+// It proves the core is sufficient for a static-binary host like gadfly:
+//
+//   - config.Env            → env-driven model fleet + concurrency (GADFLY_*-style)
+//   - model.Configure/...   → tier resolution + failover over majordomo
+//   - fanout.Run            → the N-models × M-lenses swarm, with per-provider caps
+//   - model.GenerateWith[T] → structured findings per (model, lens)
+//   - consolidation         → one report section per model, worst-verdict-led
+//
+// The whole thing imports only executus core packages, so a binary built from it
+// keeps a go.sum free of gorm/redis/discordgo/sqlite — the light-tier invariant.
+//
+// See reviewer_test.go for the hermetic swarm test (majordomo's fake provider).
+package main
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/fanout"
+	"gitea.stevedudenhoeffer.com/steve/executus/model"
+)
+
+// Severity orders findings; the rank drives a model's worst-verdict header.
+type Severity string
+
+const (
+	SevTrivial  Severity = "trivial"
+	SevSmall    Severity = "small"
+	SevMedium   Severity = "medium"
+	SevHigh     Severity = "high"
+	SevCritical Severity = "critical"
+)
+
+func severityRank(s Severity) int {
+	switch s {
+	case SevCritical:
+		return 4
+	case SevHigh:
+		return 3
+	case SevMedium:
+		return 2
+	case SevSmall:
+		return 1
+	default:
+		return 0
+	}
+}
+
+// Finding is one issue a lens reports. It is the structured-output schema the
+// model must satisfy (majordomo derives the JSON schema from this struct).
+type Finding struct {
+	Severity Severity `json:"severity" jsonschema:"enum=trivial,enum=small,enum=medium,enum=high,enum=critical"`
+	Title    string   `json:"title"`
+	Detail   string   `json:"detail"`
+}
+
+// lensReport is the per-(model,lens) structured response.
+type lensReport struct {
+	Findings []Finding `json:"findings"`
+}
+
+// Lens is one review dimension (security / correctness / …).
+type Lens struct {
+	Name  string
+	Focus string // appended to the base system prompt
+}
+
+// NamedModel is a resolved model plus the label + provider used for fan-out
+// keying (per-provider concurrency) and reporting.
+type NamedModel struct {
+	Name     string // display label (the tier/spec the host configured)
+	Provider string // fan-out key for PerKey concurrency (e.g. "ollama-cloud")
+	Model    llm.Model
+}
+
+// LensResult is one swarm cell's outcome.
+type LensResult struct {
+	Model    string
+	Lens     string
+	Findings []Finding
+	Err      error
+}
+
+const baseSystemPrompt = "You are an adversarial code reviewer. Review the diff for real, verifiable problems only — no style nits. Return ONLY JSON matching the schema. Report nothing if you find nothing."
+
+// Review runs every (model × lens) cell of the swarm concurrently, bounded by
+// opts (total + per-provider caps), and returns one LensResult per cell. A cell
+// whose model call fails carries the error in LensResult.Err — one bad cell
+// never aborts the swarm (the closure embeds per-cell errors in LensResult.Err).
+func Review(ctx context.Context, models []NamedModel, lenses []Lens, diff string, opts fanout.Options[cell]) []LensResult {
+	cells := make([]cell, 0, len(models)*len(lenses))
+	for _, m := range models {
+		for _, l := range lenses {
+			cells = append(cells, cell{model: m, lens: l})
+		}
+	}
+	// Key each cell by its provider so PerKey throttles per backend (the
+	// GADFLY_PROVIDER_CONCURRENCY analogue).
+	if opts.Key == nil {
+		opts.Key = func(c cell) string { return c.model.Provider }
+	}
+	results := fanout.Run(ctx, cells, opts, func(ctx context.Context, c cell) (LensResult, error) {
+		sys := baseSystemPrompt
+		if c.lens.Focus != "" {
+			sys += "\n\nLens — " + c.lens.Name + ": " + c.lens.Focus
+		}
+		msgs := []llm.Message{{Role: llm.RoleUser, Parts: []llm.Part{llm.Text("Diff under review:\n" + diff)}}}
+		rep, err := model.GenerateWith[lensReport](ctx, c.model.Model, sys, msgs)
+		lr := LensResult{Model: c.model.Name, Lens: c.lens.Name, Findings: rep.Findings, Err: err}
+		// Return the value either way (err embedded) so every cell reports.
+		return lr, nil
+	})
+	out := make([]LensResult, 0, len(results))
+	for _, r := range results {
+		if r.Err != nil { // a swarm-level error (ctx cancel) with no value
+			out = append(out, LensResult{Err: r.Err})
+			continue
+		}
+		out = append(out, r.Value)
+	}
+	return out
+}
+
+// cell is one (model, lens) swarm task.
+type cell struct {
+	model NamedModel
+	lens  Lens
+}
+
+// Consolidate renders the swarm's results into one report: a section per model,
+// each led by that model's worst finding severity, mirroring gadfly's
+// one-comment-per-model output.
+func Consolidate(results []LensResult) string {
+	byModel := map[string][]LensResult{}
+	var order []string
+	aborted := 0 // cells dropped before running (swarm cancelled) — no model attribution
+	for _, r := range results {
+		if r.Model == "" {
+			if r.Err != nil {
+				aborted++
+			}
+			continue
+		}
+		if _, ok := byModel[r.Model]; !ok {
+			order = append(order, r.Model)
+		}
+		byModel[r.Model] = append(byModel[r.Model], r)
+	}
+	sort.Strings(order)
+
+	var b strings.Builder
+	if aborted > 0 {
+		fmt.Fprintf(&b, "> ⚠ swarm cancelled — %d cell(s) did not run; results below are partial.\n\n", aborted)
+	}
+	for _, m := range order {
+		rs := byModel[m]
+		var all []Finding
+		worst := -1
+		errored := 0
+		for _, r := range rs {
+			if r.Err != nil {
+				errored++
+				continue
+			}
+			all = append(all, r.Findings...)
+			for _, f := range r.Findings {
+				if severityRank(f.Severity) > worst {
+					worst = severityRank(f.Severity)
+				}
+			}
+		}
+		// A model whose every lens errored produced NO data — saying "no issues
+		// found" would be misleading, so it gets its own verdict.
+		successful := len(rs) - errored
+		verdict := "no issues found"
+		switch {
+		case successful == 0 && errored > 0:
+			verdict = "review incomplete"
+		case worst >= severityRank(SevHigh):
+			verdict = "blocking issues found"
+		case worst >= 0:
+			verdict = "minor issues"
+		}
+		fmt.Fprintf(&b, "## %s — %s", m, verdict)
+		if errored > 0 {
+			fmt.Fprintf(&b, " (⚠ %d lens(es) errored)", errored)
+		}
+		b.WriteString("\n")
+		sort.SliceStable(all, func(i, j int) bool {
+			return severityRank(all[i].Severity) > severityRank(all[j].Severity)
+		})
+		for _, f := range all {
+			fmt.Fprintf(&b, "- [%s] %s — %s\n", f.Severity, f.Title, f.Detail)
+		}
+		b.WriteString("\n")
+	}
+	return b.String()
+}

examples/reviewer/reviewer_test.go

@@ -0,0 +1,128 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/fanout"
+)
+
+// TestReviewSwarm proves the light-tier path end-to-end against the fake
+// provider: a 2-model × 3-lens swarm runs, structured findings parse, and
+// consolidation produces one verdict-led section per model — no batteries, no
+// network.
+func TestReviewSwarm(t *testing.T) {
+	fp := fake.New("fakeprov")
+
+	// Model "hot" reports a high-severity finding on every lens; "cold" reports
+	// nothing. Each model is called once per lens (3×), so enqueue 3 each.
+	hot := `{"findings":[{"severity":"high","title":"SQL injection","detail":"unsanitized id in query"}]}`
+	cold := `{"findings":[]}`
+	for i := 0; i < 3; i++ {
+		fp.Enqueue("hot", fake.Reply(hot))
+		fp.Enqueue("cold", fake.Reply(cold))
+	}
+	hotM, err := fp.Model("hot")
+	if err != nil {
+		t.Fatal(err)
+	}
+	coldM, err := fp.Model("cold")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	models := []NamedModel{
+		{Name: "hot", Provider: "fakeprov", Model: hotM},
+		{Name: "cold", Provider: "fakeprov", Model: coldM},
+	}
+	lenses := []Lens{{Name: "security"}, {Name: "correctness"}, {Name: "error-handling"}}
+
+	results := Review(context.Background(), models, lenses, "some diff",
+		fanout.Options[cell]{MaxConcurrent: 6, PerKey: map[string]int{"fakeprov": 3}})
+
+	// 2 models × 3 lenses = 6 cells, all successful.
+	if len(results) != 6 {
+		t.Fatalf("got %d cells, want 6", len(results))
+	}
+	var hotFindings, coldFindings, errs int
+	for _, r := range results {
+		if r.Err != nil {
+			errs++
+			continue
+		}
+		switch r.Model {
+		case "hot":
+			hotFindings += len(r.Findings)
+		case "cold":
+			coldFindings += len(r.Findings)
+		}
+	}
+	if errs != 0 {
+		t.Errorf("expected no cell errors, got %d", errs)
+	}
+	if hotFindings != 3 { // one per lens
+		t.Errorf("hot model findings = %d, want 3", hotFindings)
+	}
+	if coldFindings != 0 {
+		t.Errorf("cold model findings = %d, want 0", coldFindings)
+	}
+
+	report := Consolidate(results)
+	if !strings.Contains(report, "hot — blocking issues found") {
+		t.Errorf("hot section should lead with a blocking verdict:\n%s", report)
+	}
+	if !strings.Contains(report, "cold — no issues found") {
+		t.Errorf("cold section should report no issues:\n%s", report)
+	}
+	if !strings.Contains(report, "SQL injection") {
+		t.Errorf("report should surface the finding:\n%s", report)
+	}
+}
+
+// TestConsolidateVerdicts checks the worst-severity-led header logic.
+func TestConsolidateVerdicts(t *testing.T) {
+	got := Consolidate([]LensResult{
+		{Model: "m", Lens: "a", Findings: []Finding{{Severity: SevSmall, Title: "x"}}},
+		{Model: "m", Lens: "b", Findings: []Finding{{Severity: SevMedium, Title: "y"}}},
+	})
+	if !strings.Contains(got, "m — minor issues") {
+		t.Errorf("medium-max should be 'minor issues', got:\n%s", got)
+	}
+	// An errored lens is surfaced in the header.
+	got = Consolidate([]LensResult{
+		{Model: "m", Lens: "a", Findings: []Finding{{Severity: SevCritical, Title: "boom"}}},
+		{Model: "m", Lens: "b", Err: context.DeadlineExceeded},
+	})
+	if !strings.Contains(got, "blocking issues found") || !strings.Contains(got, "errored") {
+		t.Errorf("critical + errored lens header wrong:\n%s", got)
+	}
+}
+
+// TestConsolidateAllErrored: a model whose every lens errored must NOT be
+// labelled "no issues found" (the gadfly P5 finding).
+func TestConsolidateAllErrored(t *testing.T) {
+	got := Consolidate([]LensResult{
+		{Model: "m", Lens: "a", Err: context.DeadlineExceeded},
+		{Model: "m", Lens: "b", Err: context.DeadlineExceeded},
+	})
+	if !strings.Contains(got, "m — review incomplete") {
+		t.Errorf("all-errored model should be 'review incomplete', got:\n%s", got)
+	}
+	if strings.Contains(got, "no issues found") {
+		t.Errorf("all-errored model must not say 'no issues found':\n%s", got)
+	}
+}
+
+// TestConsolidateSwarmCancelled: dropped (unattributed) cells surface a banner.
+func TestConsolidateSwarmCancelled(t *testing.T) {
+	got := Consolidate([]LensResult{
+		{Err: context.Canceled}, // dropped cell, no model
+		{Model: "m", Lens: "a", Findings: []Finding{{Severity: SevSmall, Title: "x"}}},
+	})
+	if !strings.Contains(got, "swarm cancelled") {
+		t.Errorf("dropped cells should surface a cancellation banner:\n%s", got)
+	}
+}

go.mod

@@ -5,6 +5,7 @@ go 1.26.2
 require (
 	gitea.stevedudenhoeffer.com/steve/majordomo v0.0.0-20260626223738-1fd7109a42f3
 	github.com/google/uuid v1.6.0
+	github.com/robfig/cron/v3 v3.0.1
 	golang.org/x/crypto v0.53.0
 	gopkg.in/yaml.v3 v3.0.1
 )

go.sum

@@ -50,6 +50,8 @@ github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aN
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/robfig/cron/v3 v3.0.1 h1:WdRxkvbJztn8LMz/QEvLN5sBU+xKpSqwwUO1Pjr4qDs=
+github.com/robfig/cron/v3 v3.0.1/go.mod h1:eQICP3HwyT7UooqI/z+Ov+PtYAWygg1TEWWzGIFLtro=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
@@ -123,6 +125,7 @@ google.golang.org/protobuf v1.23.1-0.20200526195155-81db48ad09cc/go.mod h1:EGpAD
 google.golang.org/protobuf v1.25.0/go.mod h1:9JNX74DMeImyA3h4bdi1ymwjUzf21/xIlbajtzgsN7c=
 google.golang.org/protobuf v1.34.2 h1:6xV6lTsCfpGD21XK49h7MhtcApnLqkfYgPcdHftf6hg=
 google.golang.org/protobuf v1.34.2/go.mod h1:qYOHts0dSfpeUzUFpOMr/WGzszTmLH+DiWniOlNbLDw=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=

run/critic.go

@@ -0,0 +1,124 @@
+package run
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/agent"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// criticDeadlineCheck is how often the deadline-watch goroutine polls the
+// critic's hard deadline. Small relative to any realistic soft timeout.
+const criticDeadlineCheck = time.Second
+
+// criticBinding wires a CriticHandle into a run: the executor forwards activity
+// (steps + tool starts) to it, binds the run's hard cancellation to the critic's
+// extendable deadline, and exposes the critic's Steer messages as an agent
+// RunOption. All methods are nil-safe so the executor can call them
+// unconditionally when no critic is configured.
+type criticBinding struct {
+	h CriticHandle
+}
+
+// startCritic begins critic monitoring for this run when one is configured and
+// the agent enables it. It launches a goroutine that cancels runCtx (via
+// cancelCause) the moment the critic's hard deadline passes — the critic may
+// extend that deadline, so a healthy-but-slow run is given room while a hung one
+// is killed. When the deadline passes because the critic KILLED the run
+// (KillCause() != nil), the cancellation cause is ErrCriticKill (→ status
+// "killed"); when the backstop simply expired, it is context.DeadlineExceeded (→
+// "timeout"). Returns (nil, no-op stop) when there is no critic. The caller MUST
+// defer the returned stop.
+func (e *Executor) startCritic(runCtx context.Context, cancelCause context.CancelCauseFunc, ra RunnableAgent, info RunInfo) (*criticBinding, func()) {
+	noop := func() {}
+	if e.cfg.Ports.Critic == nil || !ra.Critic.Enabled {
+		return nil, noop
+	}
+	soft := e.cfg.Defaults.CriticSoftTimeout
+	if soft <= 0 {
+		soft = 90 * time.Second // defensive: withFallbacks normally guarantees >0
+	}
+	h := e.cfg.Ports.Critic.Monitor(runCtx, info, soft)
+	if h == nil {
+		return nil, noop
+	}
+	done := make(chan struct{})
+	go func() {
+		// A host CriticHandle.Deadline() that panics must not crash the process
+		// (this runs on its own goroutine, so the executor's top-level recover
+		// can't catch it). Log-free best-effort: just stop watching.
+		defer func() { _ = recover() }()
+		t := time.NewTicker(criticDeadlineCheck)
+		defer t.Stop()
+		for {
+			select {
+			case <-done:
+				return
+			case <-runCtx.Done():
+				return
+			case <-t.C:
+				// A zero deadline = no hard cap (not yet set); otherwise cancel
+				// once we're at or past it, distinguishing an explicit kill from a
+				// natural backstop expiry so the run gets the right status.
+				if d := h.Deadline(); !d.IsZero() && !time.Now().Before(d) {
+					if cause := h.KillCause(); cause != nil {
+						cancelCause(fmt.Errorf("%w: %s", ErrCriticKill, cause.Error()))
+					} else {
+						cancelCause(context.DeadlineExceeded)
+					}
+					return
+				}
+			}
+		}
+	}()
+	return &criticBinding{h: h}, func() {
+		close(done)
+		h.Stop()
+	}
+}
+
+func (b *criticBinding) recordStep(iter int, resp *llm.Response) {
+	if b != nil {
+		b.h.RecordStep(iter, resp)
+	}
+}
+
+// recordToolStart forwards a tool call to the critic. NOTE: majordomo's step
+// observer only fires AFTER an iteration completes, so this currently lands
+// post-tool, not at dispatch — the activity clock is refreshed once per
+// iteration, not mid-tool. A single very long tool call (e.g. a 30-min render)
+// therefore won't refresh the clock until it returns; a host that runs such
+// tools should feed interim progress to its Critic (mort's InstallProgressBridge
+// pattern). A true pre-dispatch refresh needs a majordomo hook (follow-up).
+func (b *criticBinding) recordToolStart(name, args string) {
+	if b != nil {
+		b.h.RecordToolStart(name, args)
+	}
+}
+
+// maxStepsOption returns the agent step-ceiling Option. With no critic it's a
+// fixed WithMaxSteps(base); with a critic it's a DYNAMIC WithMaxStepsFunc that
+// polls the handle each step (so the critic can raise a long run's budget),
+// falling back to base when the handle defers (MaxSteps() <= 0).
+func (b *criticBinding) maxStepsOption(base int) agent.Option {
+	if b == nil {
+		return agent.WithMaxSteps(base)
+	}
+	return agent.WithMaxStepsFunc(func() int {
+		if n := b.h.MaxSteps(); n > 0 {
+			return n
+		}
+		return base
+	})
+}
+
+// drainSteer returns the critic's queued steer messages (nil-safe), so the
+// executor can merge them with the session steer mailbox into one WithSteer.
+func (b *criticBinding) drainSteer() []llm.Message {
+	if b == nil {
+		return nil
+	}
+	return b.h.Steer()
+}

run/critic_test.go

@@ -0,0 +1,128 @@
+package run_test
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+type fakeCritic struct{ h *fakeCriticHandle }
+
+func (c *fakeCritic) Monitor(_ context.Context, _ run.RunInfo, _ time.Duration) run.CriticHandle {
+	return c.h
+}
+
+type fakeCriticHandle struct {
+	mu                  sync.Mutex
+	steps, tools, stops int
+	steered             int
+	maxSteps            int   // 0 => defer to the run's base MaxIterations
+	killCause           error // non-nil simulates a critic kill
+}
+
+func (h *fakeCriticHandle) RecordStep(int, *llm.Response) { h.mu.Lock(); h.steps++; h.mu.Unlock() }
+func (h *fakeCriticHandle) KillCause() error {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	return h.killCause
+}
+func (h *fakeCriticHandle) RecordToolStart(string, string) {
+	h.mu.Lock()
+	h.tools++
+	h.mu.Unlock()
+}
+func (h *fakeCriticHandle) Steer() []llm.Message { h.mu.Lock(); h.steered++; h.mu.Unlock(); return nil }
+func (h *fakeCriticHandle) Deadline() time.Time  { return time.Time{} } // no hard deadline
+func (h *fakeCriticHandle) MaxSteps() int        { h.mu.Lock(); defer h.mu.Unlock(); return h.maxSteps }
+func (h *fakeCriticHandle) Stop()                { h.mu.Lock(); h.stops++; h.mu.Unlock() }
+
+// TestCriticRaisesStepCeiling: a critic returning a higher MaxSteps lets the agent
+// run PAST its base MaxIterations (the dynamic step ceiling). With base=1 and no
+// critic the run would hit ErrMaxSteps after the first tool-dispatch step; the
+// critic raises it to 5 so the run completes.
+func TestCriticRaisesStepCeiling(t *testing.T) {
+	h := &fakeCriticHandle{maxSteps: 5}
+	fp := fake.New("fake")
+	fp.Enqueue("m",
+		// two tool-call steps (unknown tool → tolerated error results), then answer
+		fake.ReplyWith(llm.Response{ToolCalls: []llm.ToolCall{{ID: "c1", Name: "noop", Arguments: []byte(`{}`)}}}),
+		fake.ReplyWith(llm.Response{ToolCalls: []llm.ToolCall{{ID: "c2", Name: "noop", Arguments: []byte(`{}`)}}}),
+		fake.Reply("done after 2 tool steps"),
+	)
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Critic: &fakeCritic{h: h}},
+		// large soft timeout so the deadline-watch never interferes in the test
+		Defaults: run.Defaults{CriticSoftTimeout: time.Hour},
+	})
+	res := ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m", MaxIterations: 1, Critic: run.CriticConfig{Enabled: true}},
+		tool.Invocation{RunID: "r"}, "go")
+	if res.Err != nil {
+		t.Fatalf("critic raised the ceiling to 5, run should complete past base=1: %v", res.Err)
+	}
+	if res.Output != "done after 2 tool steps" {
+		t.Errorf("output = %q", res.Output)
+	}
+}
+
+// TestCriticWired: an agent with Critic.Enabled gets monitored — Monitor returns
+// a handle the executor feeds (RecordStep), drains (Steer), and stops.
+func TestCriticWired(t *testing.T) {
+	h := &fakeCriticHandle{}
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("done"))
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Critic: &fakeCritic{h: h}},
+	})
+	res := ex.Run(context.Background(),
+		run.RunnableAgent{Name: "watched", ModelTier: "m", Critic: run.CriticConfig{Enabled: true}},
+		tool.Invocation{RunID: "r"}, "go")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.steps < 1 {
+		t.Errorf("critic should have seen >=1 step, got %d", h.steps)
+	}
+	if h.steered < 1 {
+		t.Errorf("critic Steer should be drained at least once, got %d", h.steered)
+	}
+	if h.stops != 1 {
+		t.Errorf("critic Stop should be called exactly once, got %d", h.stops)
+	}
+}
+
+// TestCriticDisabledNotMonitored: Critic.Enabled=false → Monitor never called.
+func TestCriticDisabledNotMonitored(t *testing.T) {
+	h := &fakeCriticHandle{}
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("done"))
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Critic: &fakeCritic{h: h}},
+	})
+	ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m"}, // Critic.Enabled=false
+		tool.Invocation{RunID: "r"}, "go")
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	if h.stops != 0 || h.steps != 0 {
+		t.Errorf("disabled critic should not be monitored: steps=%d stops=%d", h.steps, h.stops)
+	}
+}

run/delivery_test.go

@@ -0,0 +1,114 @@
+package run_test
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/deliver"
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+type recordingDelivery struct {
+	target   deliver.Target
+	output   string
+	errored  error
+	delivers int
+}
+
+func (d *recordingDelivery) Deliver(_ context.Context, t deliver.Target, output string, _ []deliver.Artifact) (string, error) {
+	d.target, d.output, d.delivers = t, output, d.delivers+1
+	return "msg-1", nil
+}
+func (d *recordingDelivery) DeliverError(_ context.Context, t deliver.Target, e error) error {
+	d.target, d.errored = t, e
+	return nil
+}
+
+func TestDeliveryWired(t *testing.T) {
+	d := &recordingDelivery{}
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("the output"))
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Delivery: d},
+	})
+	// With a delivery target, the executor posts the output.
+	ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m"},
+		tool.Invocation{RunID: "r", DeliveryKind: "channel", DeliveryID: "chan-9"}, "go")
+	if d.delivers != 1 || d.output != "the output" || d.target.ID != "chan-9" || d.target.Kind != "channel" {
+		t.Fatalf("delivery wrong: %+v out=%q", d.target, d.output)
+	}
+}
+
+func TestNoDeliveryWithoutTarget(t *testing.T) {
+	d := &recordingDelivery{}
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("x"))
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Delivery: d},
+	})
+	// No DeliveryID → executor delivers nothing (caller reads Result.Output).
+	ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m"},
+		tool.Invocation{RunID: "r"}, "go")
+	if d.delivers != 0 {
+		t.Errorf("no target should mean no delivery, got %d", d.delivers)
+	}
+}
+
+// TestNoDeliveryOnEarlyResolveError: an error BEFORE the run starts (model
+// resolve) returns before delivery is reached — neither Deliver nor DeliverError
+// fires. (Delivery covers run OUTCOMES, not pre-run setup failures.)
+func TestNoDeliveryOnEarlyResolveError(t *testing.T) {
+	d := &recordingDelivery{}
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models: func(ctx context.Context, _ string) (context.Context, llm.Model, error) {
+			return ctx, nil, errors.New("resolve boom")
+		},
+		Ports: run.Ports{Delivery: d},
+	})
+	ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m"},
+		tool.Invocation{RunID: "r", DeliveryKind: "channel", DeliveryID: "chan-9"}, "go")
+	if d.delivers != 0 || d.errored != nil {
+		t.Errorf("early resolve failure should neither Deliver nor DeliverError: delivers=%d errored=%v", d.delivers, d.errored)
+	}
+}
+
+// TestDeliverErrorOnRunFailure: an in-loop run failure (the model errors) routes
+// through DeliverError with the run error.
+func TestDeliverErrorOnRunFailure(t *testing.T) {
+	d := &recordingDelivery{}
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Step{Err: errors.New("model boom")}) // model errors mid-run
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Delivery: d},
+	})
+	res := ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m"},
+		tool.Invocation{RunID: "r", DeliveryKind: "channel", DeliveryID: "chan-9"}, "go")
+	if res.Err == nil {
+		t.Fatal("expected a run error")
+	}
+	if d.delivers != 0 {
+		t.Errorf("a failed run should not Deliver (success path), got %d", d.delivers)
+	}
+	if d.errored == nil || d.target.ID != "chan-9" {
+		t.Errorf("a failed run with a target should DeliverError to chan-9, got errored=%v target=%+v", d.errored, d.target)
+	}
+}

run/executor.go

@@ -4,12 +4,14 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"gitea.stevedudenhoeffer.com/steve/majordomo/agent"
 	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
 
 	"gitea.stevedudenhoeffer.com/steve/executus/compact"
+	"gitea.stevedudenhoeffer.com/steve/executus/deliver"
 	"gitea.stevedudenhoeffer.com/steve/executus/tool"
 )
 
@@ -27,6 +29,7 @@ type Defaults struct {
 	MaxConsecutiveToolErrors int           // loop guard; default 3
 	MaxSameToolCallRepeats   int           // retry-storm guard; default 3
 	CompactionThresholdRatio float64       // fraction of model context to compact at; default 0.7
+	CriticSoftTimeout        time.Duration // idle window before the critic wakes; default 90s
 }
 
 func (d Defaults) withFallbacks() Defaults {
@@ -48,6 +51,9 @@ func (d Defaults) withFallbacks() Defaults {
 	if d.CompactionThresholdRatio <= 0 {
 		d.CompactionThresholdRatio = 0.7
 	}
+	if d.CriticSoftTimeout <= 0 {
+		d.CriticSoftTimeout = 90 * time.Second
+	}
 	return d
 }
 
@@ -96,13 +102,26 @@ type Result struct {
 	Steps  []tool.Step
 	Usage  llm.Usage
 	Err    error
+	// PostRunResult carries artifacts produced by a SessionToolFactory's PostRun
+	// hook (rendered images, files). nil when no factory was set or PostRun
+	// returned nil. The host delivers these (e.g. mort's chat API / Discord).
+	PostRunResult *tool.PostRunResult
 }
 
 // Run executes ra with the given invocation + input and returns the Result. It
-// never propagates a panic; failures surface in Result.Err.
-func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocation, input string) Result {
+// never propagates a panic; failures surface in Result.Err (a top-level recover
+// converts any panic — including from a host Port — into a run error).
+func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocation, input string) (res Result) {
 	started := time.Now()
-	res := Result{RunID: inv.RunID}
+	res = Result{RunID: inv.RunID}
+	// Enforce the no-panic contract: a panic anywhere in the run (incl. a host
+	// Critic/Audit/Palette callback on the main goroutine) becomes Result.Err
+	// rather than unwinding into the caller.
+	defer func() {
+		if r := recover(); r != nil {
+			res.Err = fmt.Errorf("run.Executor: recovered panic: %v", r)
+		}
+	}()
 
 	tier := ra.ModelTier
 	if tier == "" {
@@ -141,25 +160,33 @@ func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocatio
 
 	// Audit start (optional). The recorder satisfies RunTally; stamp it on the
 	// invocation so a self-status tool can read live progress.
+	info := RunInfo{
+		RunID:         inv.RunID,
+		SubjectID:     ra.ID,
+		Name:          ra.Name,
+		CallerID:      inv.CallerID,
+		ChannelID:     inv.ChannelID,
+		ParentRunID:   inv.ParentRunID,
+		Inputs:        inv.SkillInputs,
+		StartedAt:     started,
+		MaxIterations: maxIter,
+	}
 	var rec RunRecorder
 	var stateAcc *RunStateAccessor
 	if e.cfg.Ports.Audit != nil {
-		rec = e.cfg.Ports.Audit.StartRun(ctx, RunInfo{
-			RunID:       inv.RunID,
-			SubjectID:   ra.ID,
-			Name:        ra.Name,
-			CallerID:    inv.CallerID,
-			ChannelID:   inv.ChannelID,
-			ParentRunID: inv.ParentRunID,
-			Inputs:      inv.SkillInputs,
-			StartedAt:   started,
-		})
+		rec = e.cfg.Ports.Audit.StartRun(ctx, info)
 	}
 	if rec != nil {
 		stateAcc = NewRunStateAccessor(rec, maxIter, 0, started)
 		inv.RunState = stateAcc
 	}
 
+	// Steer mailbox: lets session tools (via inv.AttachImages) feed multimodal
+	// messages into the running conversation before its next step. Created BEFORE
+	// the toolbox build so any tool's handler captures the live AttachImages seam.
+	mailbox := &steerMailbox{}
+	inv.AttachImages = (&runSession{mailbox: mailbox}).AttachImages
+
 	// Build the toolbox from the agent's low-level tools.
 	toolbox, err := e.cfg.Registry.Build(ra.LowLevelTools, inv, tool.Visibility("private"), nil)
 	if err != nil {
@@ -168,16 +195,66 @@ func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocatio
 		return res
 	}
 
+	// Add skill__/agent__ delegation tools from the agent's palette (nil-safe:
+	// no PaletteSource or empty palette → no delegation tools).
+	if err := addDelegationTools(toolbox, ra, inv, e.cfg.Ports.Palette); err != nil {
+		res.Err = fmt.Errorf("build delegation tools: %w", err)
+		e.finishAudit(ctx, rec, "error", res, started, res.Err)
+		return res
+	}
+
+	// Per-invocation ExtraTools + a SessionToolFactory's per-run tools, added on
+	// top of the agent's palette. The factory closes over the live session (the
+	// AttachImages mailbox); its PostRun hook (held for after the run) produces
+	// artifacts attached to res.PostRunResult, and its Cleanup is deferred. All
+	// nil-safe.
+	for _, t := range inv.ExtraTools {
+		if err := toolbox.Add(t); err != nil {
+			res.Err = fmt.Errorf("add extra tool: %w", err)
+			e.finishAudit(ctx, rec, "error", res, started, res.Err)
+			return res
+		}
+	}
+	var postRun func(ctx context.Context, transcript []llm.Message, output string, runErr error) *tool.PostRunResult
+	if inv.SessionToolFactory != nil {
+		st := inv.SessionToolFactory(&runSession{mailbox: mailbox})
+		if st.Cleanup != nil {
+			defer safeCleanup(st.Cleanup) // panic-isolated, like runPostRun
+		}
+		for _, t := range st.Tools {
+			if err := toolbox.Add(t); err != nil {
+				res.Err = fmt.Errorf("add session tool: %w", err)
+				e.finishAudit(ctx, rec, "error", res, started, res.Err)
+				return res
+			}
+		}
+		postRun = st.PostRun
+	}
+
 	// Run context: bound by MaxRuntime, detached from the caller's deadline so a
 	// lane/queue wait doesn't eat the run budget (mort's V10 lesson). Caller
 	// cancellation still propagates via MergeCancellation. Created BEFORE the
 	// step observer so the observer forwards the merged run context (not a
 	// possibly-cancelled caller ctx) to OnStep consumers.
-	runCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), maxRuntime)
-	defer cancel()
+	// MaxRuntime stays a WithTimeout so its DeadlineExceeded propagates through the
+	// child chain (→ "timeout"), preserving the run's-own-timeout vs caller-cancel
+	// distinction. A NESTED cause-carrying layer lets a critic kill surface as a
+	// distinct "killed" without disturbing that: only an ErrCriticKill cause is
+	// consulted in statusFor; a generic run error or a caller cancel is classified
+	// by the run error itself.
+	timeoutCtx, cancelTimeout := context.WithTimeout(context.WithoutCancel(ctx), maxRuntime)
+	defer cancelTimeout()
+	runCtx, cancelCause := context.WithCancelCause(timeoutCtx)
+	defer cancelCause(nil)
 	runCtx, mergeCancel := MergeCancellation(runCtx, ctx)
 	defer mergeCancel()
 
+	// Critic (optional): monitors the run for a stall, can nudge/extend/kill via
+	// its host Escalator. Its hard deadline is bound to runCtx (cancel on pass).
+	// nil-safe: no-op when no critic is configured or the agent doesn't enable it.
+	critic, stopCritic := e.startCritic(runCtx, cancelCause, ra, info)
+	defer stopCritic()
+
 	// Step instrumentation: accumulate Result.Steps + fire inv.OnStep, feed the
 	// audit recorder, and keep the live iteration counter fresh. majordomo's
 	// step observer hands us each completed iteration; we zip the model's tool
@@ -192,6 +269,7 @@ func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocatio
 		if rec != nil {
 			rec.OnStep(s.Index, s.Response)
 		}
+		critic.recordStep(s.Index, s.Response) // keep the critic's activity clock fresh + carry the step payload
 		var calls []llm.ToolCall
 		if s.Response != nil {
 			calls = s.Response.ToolCalls
@@ -202,6 +280,7 @@ func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocatio
 		}
 		for i := 0; i < n; i++ {
 			call, r := calls[i], s.Results[i]
+			critic.recordToolStart(call.Name, string(call.Arguments))
 			emitter.toolStart(runCtx, call.Name, call.Arguments)
 			emitter.toolEnd(runCtx, call, r.Content, r.IsError)
 			if rec != nil {
@@ -212,7 +291,10 @@ func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocatio
 
 	opts := []agent.Option{
 		agent.WithToolbox(toolbox),
-		agent.WithMaxSteps(maxIter),
+		// Step ceiling: a fixed WithMaxSteps(maxIter) normally, but when a critic is
+		// active it owns a DYNAMIC ceiling (WithMaxStepsFunc) so it can raise a
+		// healthy-but-long run's budget mid-flight. Falls back to maxIter.
+		critic.maxStepsOption(maxIter),
 		agent.WithToolErrorLimits(e.cfg.Defaults.MaxConsecutiveToolErrors, e.cfg.Defaults.MaxSameToolCallRepeats),
 		agent.WithStepObserver(stepObserver),
 	}
@@ -236,9 +318,12 @@ func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocatio
 	}
 
 	ag := agent.New(model, e.systemPrompt(ra), opts...)
-	runRes, runErr := ag.Run(runCtx, input)
+	// One WithSteer drains BOTH the session mailbox (a tool's AttachImages) and
+	// the critic's nudges before each step.
+	steer := func() []llm.Message { return append(mailbox.drain(), critic.drainSteer()...) }
+	runRes, runErr := runAgent(runCtx, ag, input, inv.Images, agent.WithSteer(steer))
 
-	status := statusFor(runErr)
+	status := statusFor(runCtx, runErr)
 	if runRes != nil {
 		res.Output = runRes.Output
 		res.Usage = runRes.Usage
@@ -246,20 +331,43 @@ func (e *Executor) Run(ctx context.Context, ra RunnableAgent, inv tool.Invocatio
 	res.Steps = emitter.snapshot()
 	res.Err = runErr
 
+	// PostRun: hand the SessionToolFactory's hook the full transcript (populated
+	// even on partial results) so it can produce artifacts. Best-effort +
+	// panic-isolated — a PostRun failure never fails an otherwise-successful run.
+	if postRun != nil {
+		var transcript []llm.Message
+		if runRes != nil {
+			transcript = runRes.Messages
+		}
+		// Detach from the caller's ctx: a finished/cancelled caller must not abort
+		// artifact production (the hook owns its own bounding, per its contract).
+		res.PostRunResult = runPostRun(detach(ctx), postRun, transcript, res.Output, runErr)
+	}
+
 	e.finishAudit(ctx, rec, status, res, started, runErr)
 	if e.cfg.Ports.Budget != nil {
 		e.cfg.Ports.Budget.Commit(detach(ctx), inv.CallerID, time.Since(started).Seconds())
 	}
+	e.deliver(ctx, inv, res, runErr)
 	return res
 }
 
-// statusFor maps a run error to a RunStats.Status, distinguishing a deadline
-// (timeout) and a cancellation (cancelled — caller cancel or shutdown) from a
-// generic error so audit consumers can tell them apart.
-func statusFor(runErr error) string {
+// statusFor maps a run error to a RunStats.Status, distinguishing a critic kill
+// (killed), a deadline (timeout), and a cancellation (cancelled — caller cancel
+// or shutdown) from a generic error so audit consumers can tell them apart. The
+// run context's cancellation cause carries the distinction (ErrCriticKill /
+// DeadlineExceeded), since ctx.Err() alone only reports Canceled.
+func statusFor(runCtx context.Context, runErr error) string {
 	switch {
 	case runErr == nil:
 		return "ok"
+	// Only the kill is recovered from the cancellation cause — a critic kill
+	// surfaces as a plain Canceled run error, so without this it'd read as
+	// "cancelled". Everything else is classified by the run error itself, so a
+	// genuine run error is never relabeled just because the context was later
+	// cancelled, and a caller cancel/deadline stays "cancelled" (not "timeout").
+	case errors.Is(context.Cause(runCtx), ErrCriticKill):
+		return "killed"
 	case errors.Is(runErr, context.DeadlineExceeded):
 		return "timeout"
 	case errors.Is(runErr, context.Canceled):
@@ -308,6 +416,23 @@ func (e *Executor) compactionThreshold(tier string) int {
 	return int(float64(max) * e.cfg.Defaults.CompactionThresholdRatio)
 }
 
+// deliver posts the run's output (or error) via run.Ports.Delivery when both a
+// Delivery and a target (inv.DeliveryID) are set. No target = the caller reads
+// Result.Output itself (the synchronous default). Best-effort + detached: a
+// delivery failure must not change the run's outcome.
+func (e *Executor) deliver(ctx context.Context, inv tool.Invocation, res Result, runErr error) {
+	if e.cfg.Ports.Delivery == nil || inv.DeliveryID == "" {
+		return
+	}
+	target := deliver.Target{Kind: inv.DeliveryKind, ID: inv.DeliveryID}
+	dctx := detach(ctx)
+	if runErr != nil {
+		_ = e.cfg.Ports.Delivery.DeliverError(dctx, target, runErr)
+		return
+	}
+	_, _ = e.cfg.Ports.Delivery.Deliver(dctx, target, res.Output, nil)
+}
+
 // detach derives a bounded cleanup context off ctx, detached from its
 // cancellation, for post-run writes. The cancel is intentionally not returned;
 // CleanupContextTimeout bounds the lifetime.
@@ -316,3 +441,28 @@ func detach(ctx context.Context) context.Context {
 	_ = cancel // bounded by the timeout; nothing to cancel early
 	return c
 }
+
+// runAgent dispatches the majordomo agent loop. majordomo's Run takes a text-only
+// input arg, so when the invocation carries images they're folded into the first
+// user message (text + image parts) via WithHistory and Run is called with an
+// empty input — the model then sees a multimodal opening turn. The image-less path
+// passes the prompt straight through.
+//
+// The text part is omitted when input is blank (image-only run), matching
+// runSession.AttachImages so no empty TextPart is sent.
+func runAgent(ctx context.Context, ag *agent.Agent, input string, images []llm.ImagePart, opts ...agent.RunOption) (*agent.Result, error) {
+	if len(images) == 0 {
+		return ag.Run(ctx, input, opts...)
+	}
+	parts := make([]llm.Part, 0, len(images)+1)
+	if strings.TrimSpace(input) != "" {
+		parts = append(parts, llm.Text(input))
+	}
+	for _, img := range images {
+		parts = append(parts, img)
+	}
+	// Copy opts before appending so a caller-supplied backing array is never
+	// mutated/aliased (the variadic slice can have spare capacity).
+	opts = append(opts[:len(opts):len(opts)], agent.WithHistory([]llm.Message{llm.UserParts(parts...)}))
+	return ag.Run(ctx, "", opts...)
+}

run/executor_test.go

@@ -148,20 +148,33 @@ func TestExecutorNilModelNoPanic(t *testing.T) {
 	}
 }
 
-// TestStatusFor maps run errors to RunStats.Status (gadfly F3).
+// TestStatusFor maps run errors + cancellation cause to RunStats.Status (gadfly F3).
 func TestStatusFor(t *testing.T) {
+	bg := context.Background()
+	// A context cancelled with the critic-kill cause: ctx.Err() is Canceled, but
+	// context.Cause carries ErrCriticKill → "killed".
+	killCtx, killCancel := context.WithCancelCause(context.Background())
+	killCancel(fmt.Errorf("%w: hung", ErrCriticKill))
+	// A context cancelled with a non-kill cause must NOT relabel a genuine run
+	// error: a real error stays "error" even though the ctx was later cancelled.
+	cancelledCtx, cc := context.WithCancelCause(context.Background())
+	cc(context.DeadlineExceeded)
 	cases := []struct {
+		ctx  context.Context
 		err  error
 		want string
 	}{
-		{nil, "ok"},
-		{context.DeadlineExceeded, "timeout"},
-		{context.Canceled, "cancelled"},
-		{fmt.Errorf("wrapped: %w", context.DeadlineExceeded), "timeout"},
-		{errors.New("boom"), "error"},
+		{bg, nil, "ok"},
+		{bg, context.DeadlineExceeded, "timeout"},
+		{bg, context.Canceled, "cancelled"},
+		{bg, fmt.Errorf("wrapped: %w", context.DeadlineExceeded), "timeout"},
+		{bg, errors.New("boom"), "error"},
+		{killCtx, context.Canceled, "killed"},
+		{cancelledCtx, errors.New("boom"), "error"},   // generic error not relabeled by cause
+		{cancelledCtx, context.Canceled, "cancelled"}, // caller cancel stays cancelled, not timeout
 	}
 	for _, c := range cases {
-		if got := statusFor(c.err); got != c.want {
+		if got := statusFor(c.ctx, c.err); got != c.want {
 			t.Errorf("statusFor(%v) = %q, want %q", c.err, got, c.want)
 		}
 	}

run/images_test.go

@@ -0,0 +1,121 @@
+package run_test
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+// TestExecutorFoldsInitialImages: when the invocation carries Images, they're
+// folded into the first user message (alongside the prompt text) instead of being
+// dropped — majordomo's Run input arg is text-only, so the executor seeds the
+// multimodal opening turn via history.
+func TestExecutorFoldsInitialImages(t *testing.T) {
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("saw the image"))
+	m, _ := fp.Model("m")
+
+	img := llm.ImagePart{MIME: "image/png", Data: []byte("PNGDATA")}
+	inv := tool.Invocation{RunID: "r1", Images: []llm.ImagePart{img}}
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+	})
+	res := ex.Run(context.Background(), run.RunnableAgent{ModelTier: "m"}, inv, "describe this")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+
+	calls := fp.Calls()
+	if len(calls) == 0 {
+		t.Fatal("no model calls recorded")
+	}
+	// The text + image must be CO-LOCATED in a single user message (not split
+	// across two), so the model reads them as one multimodal turn.
+	coLocated := false
+	for _, msg := range calls[0].Request.Messages {
+		sawImage, sawText := false, false
+		for _, p := range msg.Parts {
+			switch pp := p.(type) {
+			case llm.ImagePart:
+				if string(pp.Data) == "PNGDATA" {
+					sawImage = true
+				}
+			case llm.TextPart:
+				if strings.Contains(pp.Text, "describe this") {
+					sawText = true
+				}
+			}
+		}
+		if sawImage && sawText {
+			coLocated = true
+		}
+	}
+	if !coLocated {
+		t.Error("image + prompt text were not folded into the SAME user message")
+	}
+}
+
+// TestExecutorImageOnlyNoBlankText: an image-only run (blank prompt) must NOT emit
+// an empty TextPart — the message carries just the image, matching
+// runSession.AttachImages's guard.
+func TestExecutorImageOnlyNoBlankText(t *testing.T) {
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("saw it"))
+	m, _ := fp.Model("m")
+
+	inv := tool.Invocation{RunID: "r3", Images: []llm.ImagePart{{MIME: "image/png", Data: []byte("IMG")}}}
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+	})
+	res := ex.Run(context.Background(), run.RunnableAgent{ModelTier: "m"}, inv, "   ")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+	for _, msg := range fp.Calls()[0].Request.Messages {
+		for _, p := range msg.Parts {
+			if tp, ok := p.(llm.TextPart); ok && strings.TrimSpace(tp.Text) == "" {
+				t.Error("image-only run emitted a blank TextPart")
+			}
+		}
+	}
+}
+
+// TestExecutorTextOnlyUnchanged: with no Images, the prompt flows through as the
+// text input (regression guard that the fold path didn't break the common case).
+func TestExecutorTextOnlyUnchanged(t *testing.T) {
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("ok"))
+	m, _ := fp.Model("m")
+
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+	})
+	res := ex.Run(context.Background(), run.RunnableAgent{ModelTier: "m"}, tool.Invocation{RunID: "r2"}, "plain prompt")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+	calls := fp.Calls()
+	if len(calls) == 0 {
+		t.Fatal("no model calls recorded")
+	}
+	sawText := false
+	for _, msg := range calls[0].Request.Messages {
+		for _, p := range msg.Parts {
+			if tp, ok := p.(llm.TextPart); ok && strings.Contains(tp.Text, "plain prompt") {
+				sawText = true
+			}
+		}
+	}
+	if !sawText {
+		t.Error("text-only prompt did not reach the model")
+	}
+}

run/palette.go

@@ -0,0 +1,102 @@
+package run
+
+import (
+	"context"
+	"fmt"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+// addDelegationTools adds a delegation tool to the toolbox for each
+// SkillPalette / SubAgentPalette entry, backed by the PaletteSource:
+//
+//   - skill__<name> invokes the named saved skill with structured inputs.
+//   - agent__<name> invokes the named sub-agent with a prompt.
+//
+// Each delegated call runs as a CHILD of the current run (parentRunID =
+// inv.RunID), inheriting the caller + channel. No-op when palette is nil or both
+// palettes are empty — so an agent with no palette (or a host with no
+// PaletteSource) simply has no delegation tools, exactly as before.
+func addDelegationTools(box *llm.Toolbox, ra RunnableAgent, inv tool.Invocation, palette PaletteSource) error {
+	if palette == nil {
+		return nil
+	}
+	seen := map[string]bool{} // dedupe across both palettes by final tool name
+	for _, name := range ra.SkillPalette {
+		name := name // capture
+		toolName := "skill__" + name
+		if name == "" || seen[toolName] { // skip empty / duplicate palette entries
+			continue
+		}
+		seen[toolName] = true
+		t := llm.DefineTool(
+			toolName,
+			fmt.Sprintf("Delegate the task to the %q skill. Provide its declared inputs.", name),
+			func(ctx context.Context, args skillDelegateArgs) (any, error) {
+				out, _, status, err := palette.InvokeSkill(ctx, inv.CallerID, inv.ChannelID, name, args.Inputs, inv.RunID)
+				if err != nil {
+					return nil, delegationErr("skill", name, out, err)
+				}
+				return delegationResult(name, "skill", out, status), nil
+			},
+		)
+		if err := box.Add(t); err != nil {
+			return fmt.Errorf("add %s: %w", toolName, err)
+		}
+	}
+	for _, name := range ra.SubAgentPalette {
+		name := name // capture
+		toolName := "agent__" + name
+		if name == "" || seen[toolName] {
+			continue
+		}
+		seen[toolName] = true
+		t := llm.DefineTool(
+			toolName,
+			fmt.Sprintf("Delegate the task to the %q sub-agent with a natural-language prompt.", name),
+			func(ctx context.Context, args agentDelegateArgs) (any, error) {
+				out, _, status, err := palette.InvokeAgent(ctx, inv.CallerID, inv.ChannelID, name, args.Prompt, inv.RunID, "", "", nil, nil)
+				if err != nil {
+					return nil, delegationErr("agent", name, out, err)
+				}
+				return delegationResult(name, "agent", out, status), nil
+			},
+		)
+		if err := box.Add(t); err != nil {
+			return fmt.Errorf("add %s: %w", toolName, err)
+		}
+	}
+	return nil
+}
+
+// delegationResult surfaces a non-ok child status to the parent agent (so it can
+// react to a timeout/cancel/budget stop) while still passing the partial output.
+func delegationResult(name, kind, out, status string) string {
+	if status != "" && status != "ok" {
+		header := fmt.Sprintf("[%s %q ended with status %q]", kind, name, status)
+		if out == "" { // no trailing blank line when there's no body
+			return header
+		}
+		return header + "\n" + out
+	}
+	return out
+}
+
+// delegationErr wraps a hard delegation failure, folding in any partial output
+// the child produced before failing (so it isn't silently lost).
+func delegationErr(kind, name, partial string, err error) error {
+	if partial != "" {
+		return fmt.Errorf("%s %q failed (partial output: %q): %w", kind, name, partial, err)
+	}
+	return fmt.Errorf("%s %q failed: %w", kind, name, err)
+}
+
+type skillDelegateArgs struct {
+	Inputs map[string]any `json:"inputs" description:"Inputs for the skill, matching its declared input schema."`
+}
+
+type agentDelegateArgs struct {
+	Prompt string `json:"prompt" description:"The task/prompt to hand the sub-agent."`
+}

run/palette_test.go

@@ -0,0 +1,125 @@
+package run_test
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+// recordingPalette captures the delegation call it received.
+type recordingPalette struct {
+	gotName, gotCaller, gotParent string
+	gotInputs                     map[string]any
+}
+
+func (p *recordingPalette) ResolveSkill(context.Context, string, string) (string, error) {
+	return "", nil
+}
+func (p *recordingPalette) InvokeSkill(_ context.Context, callerID, _, name string, inputs map[string]any, parentRunID string) (string, string, string, error) {
+	p.gotName, p.gotCaller, p.gotParent, p.gotInputs = name, callerID, parentRunID, inputs
+	return "the skill output", "child-run-1", "ok", nil
+}
+func (p *recordingPalette) ResolveAgent(context.Context, string, string) (string, error) {
+	return "", nil
+}
+func (p *recordingPalette) InvokeAgent(context.Context, string, string, string, string, string, string, string, []string, func(context.Context, string, string)) (string, string, string, error) {
+	return "", "", "ok", nil
+}
+
+// TestPaletteDelegation: an agent with a SkillPalette gets a skill__<name> tool;
+// the model calls it, the executor routes it through run.Ports.Palette as a
+// child of the current run, and the result flows back into the loop.
+func TestPaletteDelegation(t *testing.T) {
+	pal := &recordingPalette{}
+
+	fp := fake.New("fake")
+	fp.Enqueue("m",
+		fake.ReplyWith(llm.Response{ToolCalls: []llm.ToolCall{{
+			ID:        "c1",
+			Name:      "skill__helper",
+			Arguments: json.RawMessage(`{"inputs":{"q":"hi"}}`),
+		}}}),
+		fake.Reply("delegated and done"),
+	)
+	m, err := fp.Model("m")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Palette: pal},
+	})
+
+	res := ex.Run(context.Background(),
+		run.RunnableAgent{ID: "a1", Name: "boss", ModelTier: "m", SkillPalette: []string{"helper"}},
+		tool.Invocation{RunID: "parent-run", CallerID: "caller-7", ChannelID: "chan"},
+		"delegate please")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+	if res.Output != "delegated and done" {
+		t.Errorf("output = %q", res.Output)
+	}
+	if pal.gotName != "helper" {
+		t.Errorf("InvokeSkill name = %q, want helper", pal.gotName)
+	}
+	if pal.gotCaller != "caller-7" {
+		t.Errorf("InvokeSkill caller = %q, want caller-7", pal.gotCaller)
+	}
+	if pal.gotParent != "parent-run" {
+		t.Errorf("InvokeSkill parentRunID = %q, want parent-run (child of the current run)", pal.gotParent)
+	}
+	if pal.gotInputs["q"] != "hi" {
+		t.Errorf("InvokeSkill inputs = %+v, want q=hi", pal.gotInputs)
+	}
+}
+
+// TestNoPaletteNoDelegationTools: nil PaletteSource → no delegation tools, run
+// still works (the agent just has no skill__/agent__ tools).
+func TestNoPaletteNoDelegationTools(t *testing.T) {
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("ok"))
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+	})
+	res := ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m", SkillPalette: []string{"helper"}},
+		tool.Invocation{RunID: "r"}, "hi")
+	if res.Err != nil || res.Output != "ok" {
+		t.Fatalf("nil-palette run failed: %v / %q", res.Err, res.Output)
+	}
+}
+
+// TestDelegationDedupeAndEmptySkip: empty + duplicate palette names are skipped,
+// not turned into "skill__"/duplicate tools that error at box.Add (gadfly C0).
+func TestDelegationDedupeAndEmptySkip(t *testing.T) {
+	pal := &recordingPalette{}
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("ok"))
+	m, _ := fp.Model("m")
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+		Ports:    run.Ports{Palette: pal},
+	})
+	// "" (empty) and a duplicate "helper" must not break the build.
+	res := ex.Run(context.Background(),
+		run.RunnableAgent{Name: "x", ModelTier: "m", SkillPalette: []string{"helper", "", "helper"}},
+		tool.Invocation{RunID: "r"}, "hi")
+	if res.Err != nil {
+		t.Fatalf("empty/duplicate palette names should be skipped, not error: %v", res.Err)
+	}
+	if res.Output != "ok" {
+		t.Fatalf("output = %q", res.Output)
+	}
+}

run/ports.go

@@ -2,6 +2,7 @@ package run
 
 import (
 	"context"
+	"errors"
 	"time"
 
 	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
@@ -9,6 +10,12 @@ import (
 	"gitea.stevedudenhoeffer.com/steve/executus/deliver"
 )
 
+// ErrCriticKill is the cancellation cause the executor stamps on a run the
+// critic kills, so a critic kill surfaces as a distinct "killed" status (vs a
+// backstop "timeout" or a caller "cancelled"). A host CriticHandle signals a
+// kill via KillCause(); the executor wraps that reason with this sentinel.
+var ErrCriticKill = errors.New("run: critic killed the run")
+
 // Ports are the host seams the run executor consumes. Every field is nil-safe:
 // a light host passes the zero Ports and gets a bounded, in-memory run with no
 // persistence, audit, budget, critic, delegation, or delivery — which is
@@ -48,6 +55,9 @@ type RunInfo struct {
 	ParentRunID string
 	Inputs      map[string]any
 	StartedAt   time.Time
+	// MaxIterations is the run's base tool-dispatch step ceiling, so a critic can
+	// raise it relative to the baseline (see CriticHandle.MaxSteps).
+	MaxIterations int
 }
 
 // RunStats is the terminal roll-up a recorder's Close writes. Mirrors mort's
@@ -113,10 +123,17 @@ type Critic interface {
 }
 
 // CriticHandle is the executor's live link to a run's critic.
+//
+// Concurrency: the executor calls RecordStep/RecordToolStart/Steer from the run
+// goroutine while a separate watch goroutine polls Deadline() and the run's end
+// calls Stop() — so implementations MUST be safe for concurrent use across these
+// methods (the critic battery's handle guards its state with a mutex).
 type CriticHandle interface {
 	// RecordStep / RecordToolStart keep the critic's activity clock fresh so a
-	// healthy-but-slow run is not mistaken for a hang.
-	RecordStep(iter int)
+	// healthy-but-slow run is not mistaken for a hang. RecordStep also carries the
+	// completed step's model response (nil-safe) so the critic's Trace can show
+	// what the agent actually produced, not just an iteration count.
+	RecordStep(iter int, resp *llm.Response)
 	RecordToolStart(name, args string)
 	// Steer returns any messages the critic wants injected into the loop (a
 	// nudge), drained before each step — matches majordomo agent.WithSteer.
@@ -124,6 +141,17 @@ type CriticHandle interface {
 	// Deadline returns the current hard-kill deadline (the critic may extend
 	// it); the executor binds the run context to it. Zero = no hard deadline.
 	Deadline() time.Time
+	// MaxSteps returns the current tool-dispatch step ceiling, polled by the
+	// executor each step (via majordomo WithMaxStepsFunc) so a critic can raise a
+	// healthy-but-long run's iteration budget mid-flight. Return <= 0 to defer to
+	// the run's base MaxIterations.
+	MaxSteps() int
+	// KillCause returns a non-nil reason iff the critic has decided to KILL this
+	// run (as opposed to letting the hard-deadline backstop expire). The executor
+	// reads it when the deadline passes: non-nil → cancel the run with
+	// ErrCriticKill (status "killed"); nil → the backstop expired naturally
+	// (status "timeout"). Hosts that never distinguish the two may return nil.
+	KillCause() error
 	// Stop ends monitoring when the run finishes.
 	Stop()
 }

run/session.go

@@ -0,0 +1,88 @@
+package run
+
+import (
+	"context"
+	"log/slog"
+	"strings"
+	"sync"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+// runPostRun invokes a SessionToolFactory's PostRun hook with panic isolation:
+// a PostRun panic (or a slow artifact build that the hook mishandles) must not
+// fail an otherwise-successful run — artifacts are best-effort, the agent's text
+// output is the source of truth.
+func runPostRun(ctx context.Context,
+	hook func(context.Context, []llm.Message, string, error) *tool.PostRunResult,
+	transcript []llm.Message, output string, runErr error) (prr *tool.PostRunResult) {
+	defer func() {
+		if r := recover(); r != nil {
+			slog.Error("run: PostRun hook panicked; no artifacts produced", "panic", r)
+			prr = nil
+		}
+	}()
+	return hook(ctx, transcript, output, runErr)
+}
+
+// steerMailbox is a thread-safe queue of messages a session tool (via
+// tool.Invocation.AttachImages) wants injected into the agent loop before its
+// next step — the same WithSteer mechanism the critic uses for nudges, exposed
+// to ordinary tools so they can show the model content (e.g. a rendered
+// preview) it must SEE, not just be told about.
+type steerMailbox struct {
+	mu   sync.Mutex
+	msgs []llm.Message
+}
+
+func (m *steerMailbox) push(msg llm.Message) {
+	m.mu.Lock()
+	m.msgs = append(m.msgs, msg)
+	m.mu.Unlock()
+}
+
+// drain returns and clears the queued messages (nil when empty).
+func (m *steerMailbox) drain() []llm.Message {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if len(m.msgs) == 0 {
+		return nil
+	}
+	out := m.msgs
+	m.msgs = nil
+	return out
+}
+
+// runSession implements tool.AgentSession over a steer mailbox: AttachImages
+// queues a user-role multimodal message the agent loop injects before its next
+// step. Replaces legacy agentkit's Agent.AttachImages — majordomo's *agent.Agent
+// is immutable mid-run, so mutation flows through the run-scoped steer mailbox.
+type runSession struct{ mailbox *steerMailbox }
+
+func (s *runSession) AttachImages(text string, images ...llm.ImagePart) {
+	parts := make([]llm.Part, 0, len(images)+1)
+	if strings.TrimSpace(text) != "" {
+		parts = append(parts, llm.Text(text))
+	}
+	for _, img := range images {
+		parts = append(parts, img)
+	}
+	if len(parts) == 0 {
+		return
+	}
+	s.mailbox.push(llm.UserParts(parts...))
+}
+
+// safeCleanup runs a SessionTools.Cleanup with panic isolation, so a misbehaving
+// teardown (temp-dir removal, handle close) can't clobber an otherwise-successful
+// run via the executor's top-level recover.
+func safeCleanup(fn func()) {
+	defer func() {
+		if r := recover(); r != nil {
+			slog.Error("run: session Cleanup panicked", "panic", r)
+		}
+	}()
+	fn()
+}

run/session_test.go

@@ -0,0 +1,94 @@
+package run_test
+
+import (
+	"context"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/provider/fake"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+	"gitea.stevedudenhoeffer.com/steve/executus/tool"
+)
+
+// TestSessionToolFactoryPostRun: a SessionToolFactory's PostRun hook produces an
+// artifact (from the run output + transcript) that lands on Result.PostRunResult,
+// and its Cleanup is deferred.
+func TestSessionToolFactoryPostRun(t *testing.T) {
+	fp := fake.New("fake")
+	fp.Enqueue("m", fake.Reply("hello artifacts"))
+	m, _ := fp.Model("m")
+
+	cleanupCalled := false
+	inv := tool.Invocation{
+		RunID: "r1",
+		SessionToolFactory: func(_ tool.AgentSession) tool.SessionTools {
+			return tool.SessionTools{
+				PostRun: func(_ context.Context, transcript []llm.Message, output string, _ error) *tool.PostRunResult {
+					return &tool.PostRunResult{
+						Artifacts: []tool.Artifact{{Name: "out.txt", MimeType: "text/plain", Data: []byte(output)}},
+						Metadata:  map[string]any{"transcript_len": len(transcript)},
+					}
+				},
+				Cleanup: func() { cleanupCalled = true },
+			}
+		},
+	}
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+	})
+	res := ex.Run(context.Background(), run.RunnableAgent{ModelTier: "m"}, inv, "go")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+	if res.PostRunResult == nil {
+		t.Fatal("Result.PostRunResult is nil — PostRun hook not invoked / not attached")
+	}
+	if n := len(res.PostRunResult.Artifacts); n != 1 {
+		t.Fatalf("artifacts = %d, want 1", n)
+	}
+	a := res.PostRunResult.Artifacts[0]
+	if a.Name != "out.txt" || string(a.Data) != "hello artifacts" {
+		t.Errorf("artifact = {%q, %q}", a.Name, string(a.Data))
+	}
+	if tl, _ := res.PostRunResult.Metadata["transcript_len"].(int); tl < 1 {
+		t.Errorf("transcript not passed to PostRun (len=%d)", tl)
+	}
+	if !cleanupCalled {
+		t.Error("Cleanup was not deferred/called")
+	}
+}
+
+// TestSessionToolFactoryAddsTool: tools the factory returns join the run's
+// toolbox and are callable by the model.
+func TestSessionToolFactoryAddsTool(t *testing.T) {
+	fp := fake.New("fake")
+	fp.Enqueue("m",
+		fake.ReplyWith(llm.Response{ToolCalls: []llm.ToolCall{{ID: "c1", Name: "render", Arguments: []byte(`{}`)}}}),
+		fake.Reply("rendered"),
+	)
+	m, _ := fp.Model("m")
+
+	toolCalled := false
+	renderTool := llm.DefineTool("render", "render a preview",
+		func(_ context.Context, _ struct{}) (any, error) { toolCalled = true; return "ok", nil })
+	inv := tool.Invocation{
+		RunID: "r2",
+		SessionToolFactory: func(_ tool.AgentSession) tool.SessionTools {
+			return tool.SessionTools{Tools: []llm.Tool{renderTool}}
+		},
+	}
+	ex := run.New(run.Config{
+		Registry: tool.NewRegistry(),
+		Models:   func(ctx context.Context, _ string) (context.Context, llm.Model, error) { return ctx, m, nil },
+	})
+	res := ex.Run(context.Background(),
+		run.RunnableAgent{ModelTier: "m", MaxIterations: 5}, inv, "go")
+	if res.Err != nil {
+		t.Fatalf("run error: %v", res.Err)
+	}
+	if !toolCalled {
+		t.Error("session-factory tool was not added to the toolbox / not called")
+	}
+}

schedule/runner.go

@@ -0,0 +1,132 @@
+// Package schedule is the cron-runner battery: a generic ticker that, each
+// interval, asks a store for the jobs whose next-run time has passed, runs each
+// one, and stamps its next fire time. It is host-agnostic orchestration — the
+// host wires the store (skill.SkillStore.ListDueScheduled /
+// persona.Storage.ListScheduledAgents), the run (run.Executor), and the cron
+// "next fire" function (a cron library, or skill's schedule parser). The
+// battery owns no cron grammar of its own, so it never duplicates the parser.
+package schedule
+
+import (
+	"context"
+	"errors"
+	"log/slog"
+	"time"
+)
+
+// Due is one schedulable job: its id and its cron expression.
+type Due struct {
+	ID   string
+	Cron string
+}
+
+// Runner periodically fires due jobs. Every func field is required except Now
+// (defaults to time.Now) and Logger (defaults to slog.Default). Construct the
+// struct directly and call Loop (or Tick for a single pass / tests).
+type Runner struct {
+	// Interval is how often Loop checks for due jobs. <= 0 defaults to 1m.
+	Interval time.Duration
+	// Due lists the jobs due at now.
+	Due func(ctx context.Context, now time.Time) ([]Due, error)
+	// Run executes one job by id.
+	Run func(ctx context.Context, id string) error
+	// Mark records that a job ran at ranAt and is next due at nextAt.
+	Mark func(ctx context.Context, id string, ranAt, nextAt time.Time) error
+	// Next computes a cron expression's next fire after a given time.
+	Next func(cron string, after time.Time) (time.Time, error)
+
+	Now    func() time.Time
+	Logger *slog.Logger
+}
+
+func (r *Runner) now() time.Time {
+	if r.Now != nil {
+		return r.Now()
+	}
+	return time.Now()
+}
+
+func (r *Runner) log() *slog.Logger {
+	if r.Logger != nil {
+		return r.Logger
+	}
+	return slog.Default()
+}
+
+// Tick runs one pass: every currently-due job is run, then stamped with its
+// next fire time. A job whose Run or Next errors is logged and skipped (its
+// next-run time is left unchanged so it stays due and retries next tick) — one
+// bad job never stalls the others. Returns the error from Due (the only
+// pass-fatal step).
+func (r *Runner) Tick(ctx context.Context) error {
+	if err := r.validate(); err != nil {
+		return err
+	}
+	now := r.now()
+	due, err := r.Due(ctx, now)
+	if err != nil {
+		return err
+	}
+	for _, j := range due {
+		// Compute the next fire BEFORE running. A permanently-unparseable cron
+		// then skips the job entirely (logged) rather than running it — an
+		// unstamped job stays due, so checking Next first avoids a hot-loop of
+		// real Run executions every tick.
+		next, err := r.Next(j.Cron, now)
+		if err != nil {
+			r.log().Warn("scheduled job has an unparseable cron; skipping (not run, not rescheduled)", "job", j.ID, "cron", j.Cron, "error", err)
+			continue
+		}
+		if err := r.Run(ctx, j.ID); err != nil {
+			r.log().Warn("scheduled job failed; stays due, will retry next tick", "job", j.ID, "error", err)
+			continue
+		}
+		// A Mark failure leaves the job due, so it re-runs next tick — Run must
+		// be idempotent (there is no atomic run+stamp across two host callbacks).
+		if err := r.Mark(ctx, j.ID, now, next); err != nil {
+			r.log().Warn("failed to stamp next run; job may re-execute next tick (Run must be idempotent)", "job", j.ID, "error", err)
+		}
+	}
+	return nil
+}
+
+// validate reports a misconfigured Runner (a required callback left nil) as a
+// clear error rather than a nil-deref panic on first tick.
+func (r *Runner) validate() error {
+	if r.Due == nil || r.Run == nil || r.Mark == nil || r.Next == nil {
+		return errors.New("schedule: Runner requires non-nil Due, Run, Mark, and Next")
+	}
+	return nil
+}
+
+// Loop ticks every Interval until ctx is cancelled. A Tick error (the Due
+// lister failing) is logged and the loop continues — a transient store hiccup
+// shouldn't kill the scheduler — and a panic from any host callback is
+// recovered so one bad tick can't silently kill the scheduler goroutine.
+func (r *Runner) Loop(ctx context.Context) {
+	interval := r.Interval
+	if interval <= 0 {
+		interval = time.Minute
+	}
+	t := time.NewTicker(interval)
+	defer t.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-t.C:
+			r.safeTick(ctx)
+		}
+	}
+}
+
+func (r *Runner) safeTick(ctx context.Context) {
+	defer func() {
+		if rec := recover(); rec != nil {
+			r.log().Error("schedule tick panicked; scheduler continues", "panic", rec)
+		}
+	}()
+	if err := r.Tick(ctx); err != nil {
+		r.log().Warn("schedule tick failed", "error", err)
+	}
+}

schedule/runner_test.go

@@ -0,0 +1,111 @@
+package schedule
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestTickRunsDueAndStampsNext(t *testing.T) {
+	ctx := context.Background()
+	now := time.Date(2026, 1, 1, 12, 0, 0, 0, time.UTC)
+	var ran []string
+	marked := map[string]time.Time{}
+
+	r := &Runner{
+		Now: func() time.Time { return now },
+		Due: func(_ context.Context, _ time.Time) ([]Due, error) {
+			return []Due{{ID: "a", Cron: "hourly"}, {ID: "b", Cron: "bad"}}, nil
+		},
+		Run:  func(_ context.Context, id string) error { ran = append(ran, id); return nil },
+		Mark: func(_ context.Context, id string, _, next time.Time) error { marked[id] = next; return nil },
+		Next: func(cron string, after time.Time) (time.Time, error) {
+			if cron == "bad" {
+				return time.Time{}, errors.New("unparseable")
+			}
+			return after.Add(time.Hour), nil
+		},
+	}
+	if err := r.Tick(ctx); err != nil {
+		t.Fatal(err)
+	}
+	// Next is checked first, so the bad-cron job is skipped BEFORE Run — only
+	// the parseable job runs and gets stamped (no hot-loop of a bad-cron Run).
+	if len(ran) != 1 || ran[0] != "a" {
+		t.Errorf("ran = %v, want only [a] (bad-cron b skipped before Run)", ran)
+	}
+	if marked["a"] != now.Add(time.Hour) {
+		t.Errorf("a next = %v, want +1h", marked["a"])
+	}
+	if _, ok := marked["b"]; ok {
+		t.Errorf("b should not be stamped (bad cron), got %v", marked["b"])
+	}
+}
+
+func TestTickRunFailureDoesNotStampOrStall(t *testing.T) {
+	ctx := context.Background()
+	var ran []string
+	marked := map[string]bool{}
+	r := &Runner{
+		Due: func(_ context.Context, _ time.Time) ([]Due, error) {
+			return []Due{{ID: "x", Cron: "h"}, {ID: "y", Cron: "h"}}, nil
+		},
+		Run: func(_ context.Context, id string) error {
+			ran = append(ran, id)
+			if id == "x" {
+				return errors.New("boom")
+			}
+			return nil
+		},
+		Mark: func(_ context.Context, id string, _, _ time.Time) error { marked[id] = true; return nil },
+		Next: func(string, time.Time) (time.Time, error) { return time.Now(), nil },
+	}
+	if err := r.Tick(ctx); err != nil {
+		t.Fatal(err)
+	}
+	if len(ran) != 2 { // y still runs despite x failing
+		t.Errorf("ran = %v, want both attempted", ran)
+	}
+	if marked["x"] { // failed job NOT stamped -> stays due, retries
+		t.Error("failed job x should not be stamped")
+	}
+	if !marked["y"] {
+		t.Error("y should be stamped")
+	}
+}
+
+func TestTickDueErrorIsFatalToPass(t *testing.T) {
+	r := &Runner{
+		Due:  func(context.Context, time.Time) ([]Due, error) { return nil, errors.New("store down") },
+		Run:  func(context.Context, string) error { return nil },
+		Mark: func(context.Context, string, time.Time, time.Time) error { return nil },
+		Next: func(string, time.Time) (time.Time, error) { return time.Now(), nil },
+	}
+	if err := r.Tick(context.Background()); err == nil {
+		t.Error("Tick should surface the Due lister error")
+	}
+}
+
+func TestUnparseableCronSkipsRunEntirely(t *testing.T) {
+	var ran []string
+	r := &Runner{
+		Due:  func(context.Context, time.Time) ([]Due, error) { return []Due{{ID: "z", Cron: "bad"}}, nil },
+		Run:  func(_ context.Context, id string) error { ran = append(ran, id); return nil },
+		Mark: func(context.Context, string, time.Time, time.Time) error { return nil },
+		Next: func(string, time.Time) (time.Time, error) { return time.Time{}, errors.New("bad cron") },
+	}
+	if err := r.Tick(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	if len(ran) != 0 {
+		t.Errorf("a job with an unparseable cron must NOT be run (avoids hot-loop), ran=%v", ran)
+	}
+}
+
+func TestValidateRejectsNilCallbacks(t *testing.T) {
+	r := &Runner{Due: func(context.Context, time.Time) ([]Due, error) { return nil, nil }} // missing Run/Mark/Next
+	if err := r.Tick(context.Background()); err == nil {
+		t.Error("Tick should return a validation error for a partially-wired Runner, not panic")
+	}
+}

skill/consts.go

@@ -0,0 +1,6 @@
+package skill
+
+// DefaultChatbotInputName is the input-param name a chatbot-exposed skill
+// receives the user's message under when its schema doesn't name one. Moved
+// from mort's chatbot_provider.go (a host concern) as a host-agnostic default.
+const DefaultChatbotInputName = "request"

skill/inputs.go

@@ -0,0 +1,422 @@
+package skill
+
+import (
+	"fmt"
+	"strings"
+)
+
+// This file holds the shared input-parsing primitives used by both the
+// chatbot exposure adapter (chatbot_provider.go) and the .skill Discord
+// command handler (commands.go) to construct a SkillInputs map from
+// caller-supplied raw values. Centralising here avoids the two paths
+// drifting in their type-coercion or required-check semantics.
+//
+// Two layers:
+//
+//   - CoerceInputValue: per-param-type coercion (int/float/bool/string).
+//     Accepts loosely-typed values (LLM-stringified numbers, JSON
+//     float64s for ints) and returns a value in the target Go shape.
+//
+//   - CoerceInputs: per-skill validation. Walks the InputSchema, coerces
+//     each declared param via CoerceInputValue, drops extras silently,
+//     errors on missing required.
+//
+// Why exported (capital): both consumers live in the same package, but
+// the names are also referenced in test files and the symbols are
+// genuinely useful API for any future consumer (webui form handler,
+// scheduler in v2). Keep the surface small.
+
+// CoerceInputValue coerces a single raw value to the target InputParam
+// type. JSON numbers arrive from json.Unmarshal as float64; bools as
+// bool; strings as string. Type-mismatched strings are accepted ("3" →
+// int 3, "true" → bool true) because both LLM tool calls and Discord
+// command args frequently surface scalars as strings.
+//
+// Why: LLM tool-call args come through json.Unmarshal of a plain
+// map[string]any, which forces every JSON number into float64 and every
+// JSON string into string. Without this coerce step, an int parameter
+// would arrive in SkillInputs as a float64, a bool sent as "true" would
+// arrive as a string, etc. — confusing the skill agent's prompt
+// renderer and any tool-side logic that switches on Go type. The
+// .skill command handler benefits identically: arg tokens arrive as
+// strings, but downstream tools may expect typed values.
+//
+// Test: TestCoerceInputValue in inputs_test.go covers each branch.
+func CoerceInputValue(paramType string, v any) (any, error) {
+	switch paramType {
+	case "int":
+		switch x := v.(type) {
+		case float64:
+			return int(x), nil
+		case int:
+			return x, nil
+		case string:
+			var i int
+			if _, err := fmt.Sscanf(x, "%d", &i); err != nil {
+				return nil, fmt.Errorf("not an int: %q", x)
+			}
+			return i, nil
+		default:
+			return nil, fmt.Errorf("not an int: %T", v)
+		}
+	case "float":
+		switch x := v.(type) {
+		case float64:
+			return x, nil
+		case int:
+			return float64(x), nil
+		case string:
+			var f float64
+			if _, err := fmt.Sscanf(x, "%f", &f); err != nil {
+				return nil, fmt.Errorf("not a float: %q", x)
+			}
+			return f, nil
+		default:
+			return nil, fmt.Errorf("not a float: %T", v)
+		}
+	case "bool":
+		switch x := v.(type) {
+		case bool:
+			return x, nil
+		case string:
+			switch x {
+			case "true", "True", "TRUE", "1":
+				return true, nil
+			case "false", "False", "FALSE", "0":
+				return false, nil
+			default:
+				return nil, fmt.Errorf("not a bool: %q", x)
+			}
+		default:
+			return nil, fmt.Errorf("not a bool: %T", v)
+		}
+	default:
+		// "string", "user", "channel", "url", and unknown — coerce to
+		// string. JSON numbers/bools are stringified so the executor's
+		// validateInputs (which strips e.g. <@!123> wrappers) gets a
+		// uniform string input.
+		switch x := v.(type) {
+		case string:
+			return x, nil
+		case float64:
+			return fmt.Sprintf("%v", x), nil
+		case bool:
+			return fmt.Sprintf("%v", x), nil
+		default:
+			return fmt.Sprintf("%v", v), nil
+		}
+	}
+}
+
+// CoerceInputs validates and coerces a map of raw caller-supplied values
+// against the declared parameter set:
+//
+//   - Extra keys (not in params) are dropped silently.
+//   - Missing required keys return an error so the caller can surface
+//     usage information.
+//   - Per-param type coercion handles int/float/bool sent as strings.
+//
+// Returns a fresh map containing only declared params; never mutates the
+// input map.
+//
+// Why: see CoerceInputValue. Both callers (chatbot exposure adapter,
+// .skill command handler) need the same required-check + extra-drop
+// semantics; previously only the chatbot path implemented them, which
+// is exactly why .skill <name> <args> dropped its arguments entirely.
+//
+// Test: TestCoerceInputs in inputs_test.go.
+func CoerceInputs(params []InputParam, raw map[string]any) (map[string]any, error) {
+	out := make(map[string]any, len(params))
+	for _, p := range params {
+		v, present := raw[p.Name]
+		if !present {
+			if p.Required {
+				return nil, fmt.Errorf("missing required parameter %q", p.Name)
+			}
+			continue
+		}
+		typed, err := CoerceInputValue(p.Type, v)
+		if err != nil {
+			return nil, fmt.Errorf("parameter %q: %w", p.Name, err)
+		}
+		out[p.Name] = typed
+	}
+	return out, nil
+}
+
+// ParseCommandInputs parses a free-form command argument string into a
+// raw map[string]any keyed by InputSchema parameter names. Three modes
+// are supported, picked by the shape of `schema`:
+//
+//	CASE A — empty schema:
+//	  The whole string becomes {"request": "<rest>"}. Mirrors the
+//	  chatbot exposure default (DefaultChatbotInputName) so a skill with
+//	  no declared inputs can still receive its trigger text uniformly
+//	  across both surfaces.
+//
+//	CASE B — exactly one required param (with optional non-required
+//	tail):
+//	  If the user passed any --key=value or --key value flags they're
+//	  parsed as flags (Case C). Otherwise the WHOLE rest-of-message
+//	  becomes that single required param's value. This is the
+//	  "single-arg convenience" pattern that lets `.skill weather Boston
+//	  today` work without the user typing --city=.
+//
+//	CASE C — multiple params, OR any --flag style input:
+//	  Tokens are parsed as `--name=value` or `--name value`. Bare
+//	  positional tokens after a flag are collected as that flag's value.
+//	  Trailing positional tokens with no preceding flag are dropped
+//	  (the caller's usage string should mention the flag form).
+//
+// The returned map values are RAW strings (or bool true for
+// presence-only flags); type coercion is the caller's job via
+// CoerceInputs.
+//
+// Why this signature instead of returning the typed map directly: the
+// caller wants to distinguish "missing required" (→ usage reply) from
+// "type coercion failed" (→ explicit error). Splitting parse from
+// coerce keeps the message specific.
+func ParseCommandInputs(schema []InputParam, raw string) map[string]any {
+	out := map[string]any{}
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return out
+	}
+
+	// Detect flag-style input regardless of schema shape — even a single
+	// required-param schema may be invoked via `.skill x --name value`
+	// for forward compat.
+	hasFlag := strings.Contains(raw, "--")
+
+	switch {
+	case len(schema) == 0:
+		// Empty schema: mirror the chatbot exposure adapter's default
+		// "request" pseudo-param so executor.composePrompt can render
+		// it uniformly.
+		out[DefaultChatbotInputName] = raw
+
+	case !hasFlag && countRequired(schema) == 1:
+		// Single-required-param convenience: whole rest-of-message is the
+		// value, regardless of any other (non-required) params declared.
+		// They can be supplied via --flag form if needed.
+		req := firstRequired(schema)
+		out[req.Name] = raw
+
+	default:
+		// Flag-style parse. Walk tokens looking for --name[=value] or
+		// --name <value>.
+		parseFlagStyle(out, schema, raw)
+	}
+	return out
+}
+
+// countRequired returns the number of params marked Required.
+func countRequired(schema []InputParam) int {
+	n := 0
+	for _, p := range schema {
+		if p.Required {
+			n++
+		}
+	}
+	return n
+}
+
+// firstRequired returns the first required param. Caller must have
+// already verified at least one exists.
+func firstRequired(schema []InputParam) *InputParam {
+	for i := range schema {
+		if schema[i].Required {
+			return &schema[i]
+		}
+	}
+	return nil
+}
+
+// parseFlagStyle walks tokens for --name=value and --name value forms.
+// Unknown flags (not in schema) are still accepted into the output map
+// so the caller can detect and warn about them; CoerceInputs will drop
+// extras when constructing the final SkillInputs.
+//
+// Tokens not preceded by a --flag are dropped. v1 is intentionally
+// strict-ish here: we don't try to guess which positional token belongs
+// to which param when there are several. The single-required-param
+// convenience handles the common ambiguity-free case in the caller.
+func parseFlagStyle(out map[string]any, schema []InputParam, raw string) {
+	tokens := tokeniseCommandLine(raw)
+	declared := map[string]bool{}
+	for _, p := range schema {
+		declared[p.Name] = true
+	}
+
+	i := 0
+	for i < len(tokens) {
+		t := tokens[i]
+		if !strings.HasPrefix(t, "--") {
+			// Bare positional token outside a flag context — drop. The
+			// caller's usage string should steer users to flag form.
+			i++
+			continue
+		}
+		key := t[2:]
+		// --name=value form
+		if eq := strings.IndexByte(key, '='); eq >= 0 {
+			out[key[:eq]] = key[eq+1:]
+			i++
+			continue
+		}
+		// --name <value> form: take the next token IF it doesn't itself
+		// start with --. Otherwise treat as a presence-only boolean flag.
+		if i+1 < len(tokens) && !strings.HasPrefix(tokens[i+1], "--") {
+			out[key] = tokens[i+1]
+			i += 2
+			continue
+		}
+		out[key] = "true"
+		i++
+	}
+	_ = declared // reserved for v2 unknown-flag warnings
+}
+
+// tokeniseCommandLine splits a free-form Discord command argument
+// string into tokens. Quoted spans (single or double quotes) are kept
+// as one token so users can pass values with spaces:
+//
+//	.skill weather --city="New York"
+//	.skill summarise --text 'a long sentence here'
+//
+// Mirrors the user's intuition without introducing a full shell
+// parser. Newlines split as whitespace.
+func tokeniseCommandLine(s string) []string {
+	var out []string
+	var cur strings.Builder
+	var quote rune
+	flush := func() {
+		if cur.Len() > 0 {
+			out = append(out, cur.String())
+			cur.Reset()
+		}
+	}
+	for _, r := range s {
+		switch {
+		case quote != 0:
+			if r == quote {
+				quote = 0
+				continue
+			}
+			cur.WriteRune(r)
+		case r == '"' || r == '\'':
+			quote = r
+		case r == ' ' || r == '\t' || r == '\n':
+			flush()
+		default:
+			cur.WriteRune(r)
+		}
+	}
+	flush()
+	return out
+}
+
+// ResolveCommandInputs is the one-call helper a Discord .skill handler
+// uses to turn a free-form rest-of-message into a coerced
+// SkillInputs map ready to hand to the executor. It is the single
+// production entry point for command-side input resolution: every
+// caller must use it (do NOT chain ParseCommandInputs + CoerceInputs
+// directly).
+//
+// Why this exists as a single function: chaining
+// ParseCommandInputs + CoerceInputs at the call site is what broke
+// `.skill echo hello world` in production. ParseCommandInputs Case A
+// (empty schema) writes the user's text into out["request"], but
+// CoerceInputs(emptySchema, …) iterates the DECLARED params and
+// silently drops every key not in the schema — so "request" is
+// dropped before reaching the executor, and the agent's user-prompt
+// renders "(no input provided)". The fix is to mirror the chatbot
+// exposure adapter: derive the EFFECTIVE param set (which inflates
+// an empty schema to a single required "request" param) and coerce
+// against that, not the original empty schema.
+//
+// What:
+//   - Empty input_schema → effective params = [{request, required, string}],
+//     so ParseCommandInputs Case A's "request" key survives Coerce.
+//   - Non-empty input_schema → effective params = the schema as-is, so
+//     Case B / Case C parse-and-coerce semantics are unchanged.
+//
+// Returns the coerced SkillInputs map, or an error suitable for
+// surfacing to the user (e.g. via FormatUsage). Never mutates
+// `schema`.
+//
+// Test: TestResolveCommandInputs_* in inputs_test.go cover the three
+// cases plus the empty-schema regression.
+func ResolveCommandInputs(schema []InputParam, raw string) (map[string]any, error) {
+	rawInputs := ParseCommandInputs(schema, raw)
+	effective := effectiveCommandParams(schema)
+	return CoerceInputs(effective, rawInputs)
+}
+
+// effectiveCommandParams returns the parameter set the .skill command
+// path should use for coercion. Mirrors chatbotToolParams in
+// chatbot_provider.go: an empty input_schema is inflated to a single
+// required "request" string param so the user's free-text trigger
+// survives CoerceInputs's drop-extras semantics.
+//
+// Why a separate helper (vs reusing chatbotToolParams): keeping the
+// helper local to inputs.go avoids dragging chatbot_provider.go into
+// the .skill command path's import surface and makes the intent
+// (Discord-side parameter inflation) explicit at the call site.
+func effectiveCommandParams(schema []InputParam) []InputParam {
+	if len(schema) > 0 {
+		return schema
+	}
+	return []InputParam{{
+		Name:        DefaultChatbotInputName,
+		Description: "The user's free-text trigger.",
+		Type:        "string",
+		Required:    true,
+	}}
+}
+
+// FormatUsage renders a human-readable usage string for the .skill
+// invocation form. Used by command handlers when required params are
+// missing or coercion fails.
+//
+// Why: keep the usage message in one place so both the missing-required
+// and coercion-failed paths produce identical output.
+func FormatUsage(name string, schema []InputParam) string {
+	var sb strings.Builder
+	fmt.Fprintf(&sb, "usage: `.skill %s", name)
+	if len(schema) == 0 {
+		sb.WriteString(" <text>`")
+		return sb.String()
+	}
+	if countRequired(schema) == 1 {
+		req := firstRequired(schema)
+		fmt.Fprintf(&sb, " <%s>`", req.Name)
+		// Show optional flags (if any).
+		var optional []InputParam
+		for _, p := range schema {
+			if !p.Required {
+				optional = append(optional, p)
+			}
+		}
+		if len(optional) > 0 {
+			sb.WriteString("\n  optional:")
+			for _, p := range optional {
+				fmt.Fprintf(&sb, " --%s=<%s>", p.Name, p.Type)
+			}
+		}
+		return sb.String()
+	}
+	// Multi-param: full --flag form.
+	for _, p := range schema {
+		if p.Required {
+			fmt.Fprintf(&sb, " --%s=<%s>", p.Name, p.Type)
+		}
+	}
+	for _, p := range schema {
+		if !p.Required {
+			fmt.Fprintf(&sb, " [--%s=<%s>]", p.Name, p.Type)
+		}
+	}
+	sb.WriteString("`")
+	return sb.String()
+}

skill/memory.go

@@ -0,0 +1,169 @@
+package skill
+
+import (
+	"context"
+	"sort"
+	"sync"
+	"time"
+)
+
+// Memory is a zero-dependency in-process SkillStore — a light host or test gets
+// saved-skill persistence with no DB. Mort backs SkillStore with GORM/MySQL;
+// contrib/store adds durable SQLite.
+type Memory struct {
+	mu       sync.RWMutex
+	skills   map[string]*Skill         // by ID
+	versions map[string][]SkillVersion // by skill ID, append order
+	byVerID  map[string]SkillVersion   // by version ID
+}
+
+// NewMemory returns an empty in-memory SkillStore.
+func NewMemory() *Memory {
+	return &Memory{
+		skills:   map[string]*Skill{},
+		versions: map[string][]SkillVersion{},
+		byVerID:  map[string]SkillVersion{},
+	}
+}
+
+var _ SkillStore = (*Memory)(nil)
+
+func (m *Memory) Initialize(context.Context) error { return nil }
+
+func (m *Memory) Save(_ context.Context, s *Skill) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	cp := *s
+	m.skills[s.ID] = &cp
+	return nil
+}
+
+func (m *Memory) Get(_ context.Context, id string) (*Skill, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	s, ok := m.skills[id]
+	if !ok {
+		return nil, ErrNotFound
+	}
+	cp := *s
+	return &cp, nil
+}
+
+func (m *Memory) GetByName(_ context.Context, ownerID, name string) (*Skill, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	for _, s := range m.skills {
+		if s.OwnerID == ownerID && s.Name == name {
+			cp := *s
+			return &cp, nil
+		}
+	}
+	return nil, ErrNotFound
+}
+
+func (m *Memory) Delete(_ context.Context, id string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	delete(m.skills, id)
+	return nil
+}
+
+func (m *Memory) listWhere(keep func(*Skill) bool) []Skill {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	out := make([]Skill, 0, len(m.skills))
+	for _, s := range m.skills {
+		if keep == nil || keep(s) {
+			out = append(out, *s)
+		}
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out
+}
+
+func (m *Memory) ListByOwner(_ context.Context, ownerID string) ([]Skill, error) {
+	return m.listWhere(func(s *Skill) bool { return s.OwnerID == ownerID }), nil
+}
+
+func (m *Memory) ListPublic(context.Context) ([]Skill, error) {
+	return m.listWhere(func(s *Skill) bool { return s.Visibility == VisibilityPublic }), nil
+}
+
+func (m *Memory) ListSharedWith(_ context.Context, memberID string) ([]Skill, error) {
+	return m.listWhere(func(s *Skill) bool {
+		if s.Visibility != VisibilityShared {
+			return false
+		}
+		for _, id := range s.SharedWith {
+			if id == memberID {
+				return true
+			}
+		}
+		return false
+	}), nil
+}
+
+func (m *Memory) ListBuiltinByName(_ context.Context, name string) (*Skill, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	for _, s := range m.skills {
+		if s.Source == SourceBuiltin && s.Name == name {
+			cp := *s
+			return &cp, nil
+		}
+	}
+	return nil, ErrNotFound
+}
+
+func (m *Memory) ListChatbotExposed(context.Context) ([]Skill, error) {
+	return m.listWhere(func(s *Skill) bool { return s.ExposeAsChatbotTool }), nil
+}
+
+func (m *Memory) ListDueScheduled(_ context.Context, now time.Time) ([]Skill, error) {
+	return m.listWhere(func(s *Skill) bool { return s.DueAt(now) }), nil
+}
+
+func (m *Memory) MarkScheduledRun(_ context.Context, skillID string, ranAt, nextAt time.Time) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	s, ok := m.skills[skillID]
+	if !ok {
+		return ErrNotFound
+	}
+	s.LastScheduledRunAt = ranAt
+	s.NextRunAt = nextAt
+	return nil
+}
+
+func (m *Memory) AppendVersion(_ context.Context, sv SkillVersion) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.versions[sv.SkillID] = append(m.versions[sv.SkillID], sv)
+	m.byVerID[sv.ID] = sv
+	return nil
+}
+
+func (m *Memory) ListVersionsBySkill(_ context.Context, skillID string, limit int) ([]SkillVersion, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	all := m.versions[skillID]
+	// newest first
+	out := make([]SkillVersion, 0, len(all))
+	for i := len(all) - 1; i >= 0; i-- {
+		out = append(out, all[i])
+		if limit > 0 && len(out) >= limit {
+			break
+		}
+	}
+	return out, nil
+}
+
+func (m *Memory) GetVersionByID(_ context.Context, versionID string) (*SkillVersion, error) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+	sv, ok := m.byVerID[versionID]
+	if !ok {
+		return nil, ErrNotFound
+	}
+	return &sv, nil
+}

skill/runnable.go

@@ -0,0 +1,35 @@
+package skill
+
+import (
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/run"
+)
+
+// ToRunnable lowers a saved Skill into the kernel's run.RunnableAgent DTO, so
+// run.Executor can run a skill WITHOUT importing this battery (the inversion of
+// mort's skillexec running a skills.Skill). Maps the static shape only; the
+// skill's input schema → prompt rendering, palette resolution, audit, etc. are
+// supplied separately (the host renders inputs into the input string and wires
+// run.Ports). A skill exposes a flat tool list (no SkillPalette/SubAgentPalette
+// — composition is a host concern), so those stay empty.
+func (s *Skill) ToRunnable() run.RunnableAgent {
+	return run.RunnableAgent{
+		ID:            s.ID,
+		Name:          s.Name,
+		SystemPrompt:  s.SystemPrompt,
+		ModelTier:     s.ModelTier,
+		MaxIterations: s.MaxIterations,
+		MaxRuntime:    s.MaxRuntime,
+		LowLevelTools: s.Tools,
+	}
+}
+
+// DueAt reports whether a scheduled skill is due at now (cron empty => never).
+// Convenience for a host scheduler that doesn't want to re-parse the cron.
+func (s *Skill) DueAt(now time.Time) bool {
+	if s.Schedule == "" || s.NextRunAt.IsZero() {
+		return false
+	}
+	return !s.NextRunAt.After(now)
+}

skill/schedule.go

@@ -0,0 +1,107 @@
+package skill
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/robfig/cron/v3"
+)
+
+// scheduleParser is the cron parser shared across the skills package. It
+// accepts the standard 5-field syntax (minute hour dom month dow) plus
+// descriptors such as @daily, @hourly, etc. We do not enable the seconds
+// field — schedule cadence is governed in minutes, and a seconds field
+// would invite specs that fire below the min-interval floor without
+// surfacing as such in the spec text.
+//
+// Why standalone vs. cron.ParseStandard: ParseStandard rejects descriptors
+// (@daily, @hourly). Skills callers may want to write @daily as a
+// shorthand alongside the explicit "daily" / "weekly" forms we translate
+// below.
+var scheduleParser = cron.NewParser(
+	cron.Minute | cron.Hour | cron.Dom | cron.Month | cron.Dow | cron.Descriptor,
+)
+
+// ParseSchedule turns a user-supplied schedule expression into a
+// cron.Schedule. The empty string returns (nil, nil) — callers should
+// treat that as "on-demand only".
+//
+// Why: Skill.Schedule is a string field stored verbatim; the validator,
+// the scheduler runner, and any future tooling all need to round-trip
+// through the same parser. Centralising it here avoids drift.
+//
+// Accepted shorthands:
+//   - "daily"  → "0 0 * * *"   (midnight UTC every day)
+//   - "weekly" → "0 0 * * 0"   (midnight UTC every Sunday)
+//
+// Anything else is fed through robfig/cron/v3's standard parser
+// (descriptors enabled).
+//
+// Test: schedule_test.go covers shorthand expansion and invalid-spec
+// rejection.
+func ParseSchedule(expr string) (cron.Schedule, error) {
+	expr = strings.TrimSpace(expr)
+	if expr == "" {
+		return nil, nil
+	}
+	switch strings.ToLower(expr) {
+	case "daily":
+		expr = "0 0 * * *"
+	case "weekly":
+		expr = "0 0 * * 0"
+	}
+	sched, err := scheduleParser.Parse(expr)
+	if err != nil {
+		return nil, fmt.Errorf("invalid schedule %q: %w", expr, err)
+	}
+	return sched, nil
+}
+
+// ScheduleMinInterval returns an estimate of the smallest gap between
+// consecutive fire times for a parsed schedule. It samples the next two
+// fire times from a couple of starting points and returns the smallest
+// observed gap.
+//
+// Why: cron.Schedule does not expose a "smallest interval" API. The
+// validator needs this to enforce a per-skill min-interval floor (so an
+// admin can't accidentally register "* * * * *" and burn GPU minutes).
+// Two probe points are enough to catch irregular schedules whose tightest
+// gap appears at a particular point in the week (e.g. "0 9 * * 1,5",
+// where Mon→Fri is 4d but Fri→Mon is 3d — both sampled).
+//
+// Returns 0 if sched is nil.
+//
+// Test: schedule_test.go covers a "* * * * *" minute-interval probe and
+// the irregular Mon/Fri case.
+func ScheduleMinInterval(sched cron.Schedule) time.Duration {
+	if sched == nil {
+		return 0
+	}
+	// Probe from a fixed reference and from a midweek offset. Six fire
+	// times across two starts catches weekly irregularities (the worst
+	// case is a schedule that fires once a week — we still get one gap
+	// per probe). Using a wall-clock-independent reference keeps the
+	// test deterministic.
+	starts := []time.Time{
+		time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC),     // Monday 00:00
+		time.Date(2024, 1, 4, 12, 30, 0, 0, time.UTC),   // Thursday 12:30
+		time.Date(2024, 6, 15, 23, 59, 59, 0, time.UTC), // mid-year, late
+	}
+	var min time.Duration
+	for _, t := range starts {
+		// Sample three consecutive fires per start to capture two gaps.
+		f1 := sched.Next(t)
+		f2 := sched.Next(f1)
+		f3 := sched.Next(f2)
+		for _, gap := range []time.Duration{f2.Sub(f1), f3.Sub(f2)} {
+			if gap <= 0 {
+				continue
+			}
+			if min == 0 || gap < min {
+				min = gap
+			}
+		}
+	}
+	return min
+}

skill/skill.go

@@ -0,0 +1,424 @@
+// Package skills implements the agentic skills platform: user-creatable
+// agent definitions (system prompt + tool whitelist + I/O spec) that run
+// in-process via majordomo's agent loop.
+//
+// A Skill is a saved agent definition. It can be invoked from Discord
+// (.skill <name>), exposed to the chatbot as a tool (via the
+// SkillsToolProvider), and (in v2) scheduled. Skills compose tools from
+// the skilltools registry, gated by a three-stage permission model:
+// save-time AuthoringRequirement, share-time SafeForShare, execute-time
+// SkillNameGate.
+//
+// This file declares the domain types only. Storage lives in storage.go;
+// validation lives in validate.go. The grand storage pattern documented in
+// pkg/logic/storage/CLAUDE.md applies — when adding a field to Skill, you
+// MUST also update pkg/logic/skills/gorm_model.go (gormSkill, fromStorage,
+// toStorage) or persistence will silently break.
+package skill
+
+import "time"
+
+// Skill is the domain definition of an agentic skill.
+//
+// Why: a skill is a saved agent definition reusable across invocations
+// (Discord, chatbot tool, scheduled run in v2). The struct is intentionally
+// flat — every field lives on its own column on the skills table; there is
+// no JSON-blob spec column. This keeps queries (e.g. "list all skills with
+// chatbot exposure") indexable and avoids opaque migration headaches.
+//
+// What: identity + authoring + agent spec + visibility + chatbot exposure
+// fields, all on one struct.
+//
+// Test: see validate_test.go and integration_test.go for round-trip and
+// validation coverage.
+type Skill struct {
+	// Identity
+	ID          string // UUID
+	OwnerID     string // Discord member ID; empty for builtin
+	Name        string // unique per (owner, builtin namespace)
+	Description string
+	Source      Source // SourceBuiltin | SourceManual
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
+
+	// Authoring (copied at save time from the user)
+	AuthoredBy string // member ID at time of last edit (audit; may differ from owner over time)
+
+	// Versioning (for builtins; user skills typically stay at 1.0.0)
+	Version string // semver; used by builtin loader to decide re-seed
+
+	// Spec — agent definition
+	SystemPrompt   string
+	Tools          []string // registry tool names
+	ModelTier      string   // "fast" | "standard" | "thinking" | explicit "provider/model"
+	InputSchema    []InputParam
+	OutputTarget   OutputTarget
+	Schedule       string        // cron; empty = on-demand only; rejected in v1 (ships in v2)
+	Visibility     Visibility    // VisibilityPrivate | VisibilityShared | VisibilityPublic
+	SharedWith     []string      // member IDs for visibility=shared
+	MaxIterations  int           // 0 → use convar default
+	MaxToolCalls   int           // 0 → use convar default
+	MaxRuntime     time.Duration // 0 → use convar default
+	InitialMessage string
+
+	// Chatbot exposure (v1 — proves out the platform via mortventure)
+	ExposeAsChatbotTool    bool
+	ChatbotToolName        string
+	ChatbotToolDescription string
+	ChatbotChannelFilter   string // named filter from the channel-filter registry
+
+	// Admin gating (v2 — public scheduled channel skills require approval).
+	// DEPRECATED in v3: PinnedVersionID subsumes this flag for non-owner
+	// invocation gating. CanInvoke no longer references this column.
+	// Drop in v4.
+	PendingApproval bool
+
+	// Pinned version (v3 — admin-curated invocation gate).
+	//
+	// Why: in v3, non-owner invocation requires that an admin explicitly
+	// pin a known snapshot. This replaces v2's PendingApproval flag —
+	// pinning is the explicit "approved for general use" signal, and the
+	// pinned snapshot is what executes for non-owner callers (so an owner
+	// editing a public skill never accidentally exposes work-in-progress
+	// to other users).
+	//
+	// PinnedVersionID is the SkillVersion.ID (UUID) of the snapshot that
+	// non-owner invocations resolve to. Empty means "no pin yet" — only
+	// the owner and admins can invoke.
+	//
+	// Schema column is `pinned_version` per the design spec but the field
+	// name in the domain struct is explicit about the kind of value it
+	// holds (a snapshot row's UUID, NOT a semver string), which avoids
+	// the spec ambiguity around "pin to v1.0.5" potentially mapping to
+	// multiple snapshot rows over time.
+	PinnedVersionID string
+
+	// PinnedAt is the wall-clock time the pin was set. Zero means
+	// PinnedVersionID is empty (never pinned).
+	PinnedAt time.Time
+
+	// PinnedBy is the admin member ID who set the current pin. Empty
+	// when PinnedVersionID is empty.
+	PinnedBy string
+
+	// Scheduler bookkeeping (v2). Updated by the scheduler runner after
+	// a successful (or failed-but-counted) scheduled execution.
+	//
+	// LastScheduledRunAt records the wall-clock time of the most recent
+	// scheduled invocation; zero means "never run on schedule".
+	//
+	// NextRunAt is the precomputed wake-up time the scheduler polls for
+	// (`WHERE next_run_at <= NOW()`). It is recomputed by feeding
+	// LastScheduledRunAt (or NOW() on first scheduling) through
+	// ParseSchedule(Schedule).Next(...). Manual / on-demand invocations
+	// MUST NOT touch these fields.
+	LastScheduledRunAt time.Time
+	NextRunAt          time.Time
+
+	// ExtendedBounds, when true, lets a non-admin author save the skill
+	// with bounds (MaxIterations / MaxToolCalls / MaxRuntime) above the
+	// default tier (12/30/60s) up to the extended tier (50/150/600s).
+	// Set by an admin via `.skill admin grant-extended <name>`. Cleared
+	// by `.skill admin revoke-extended <name>`. Builtins and admin-
+	// authored skills bypass the cap entirely (the tier resolution in
+	// Validate treats AuthorIsAdmin and ExtendedBounds equivalently).
+	//
+	// Why a per-skill flag vs a per-user grant: governance is per-skill
+	// — an admin reviews a specific skill's bounds and decides those
+	// resource limits are justified for THAT skill. A user grant would
+	// blanket-allow expensive bounds on every skill they author.
+	ExtendedBounds bool
+
+	// ParallelCompositionAllowed gates whether this skill may use the
+	// skill_invoke_parallel tool. Default false.
+	//
+	// Why a per-skill admin gate: parallel fan-out multiplies blast
+	// radius (one bad skill spawns N concurrent runs). Admins approve
+	// each skill that's allowed to use parallel composition; granting
+	// is per-skill via `.skill admin grant-parallel <name>`. Builtins
+	// may set this directly in skill.yml (the loader bypasses
+	// save-time gates by design).
+	//
+	// Checked AT INVOCATION TIME (every skill_invoke_parallel call), so
+	// admins can grant or revoke without redeploying. The check lives
+	// in the tool handler (pkg/skilltools/tools/skill_invoke_parallel.go)
+	// via the SkillInvokerProvider.IsParallelAllowed extension.
+	ParallelCompositionAllowed bool
+
+	// ExecutionLane is the named lane the skill's runs are submitted to
+	// when the executor routes through pkg/lane (v6). Default
+	// "skill-default"; admin overrides per-skill via
+	// `.skill admin set-lane <name> <lane>`.
+	//
+	// Why per-skill (vs a single global skill lane): different skills
+	// have different concurrency profiles. A long-running web-research
+	// skill might warrant a dedicated 1-slot lane to avoid starving
+	// quick chatbot-exposed skills; an admin should be able to isolate
+	// it without a code change.
+	//
+	// Empty string falls through to "skill-default" at executor time
+	// — keeping the field nullable lets a future schema change
+	// distinguish "explicit skill-default" from "never set".
+	ExecutionLane string
+
+	// WebhookSecret enables inbound webhooks (v7). Empty = disabled
+	// (the default). Non-empty = the random secret URL path segment
+	// for POST /webhooks/<secret>. Generated by EnableWebhook;
+	// rotated by RegenerateWebhookSecret. Storage is varchar(64) and
+	// the secret is 32 random bytes (64 hex chars), so the column
+	// holds a fully unique secret per skill.
+	//
+	// Why store the secret directly (not a hash): the webhook handler
+	// must look up the skill by the secret on every POST, which would
+	// require comparing every stored hash against the supplied secret
+	// — a per-call O(n_skills) operation. The secret is treated as a
+	// long random URL key (like a paste UUID); compromise is mitigated
+	// via RegenerateWebhookSecret rotation, not via storage hashing.
+	WebhookSecret string
+
+	// WebhookSignatureRequired controls whether the inbound webhook
+	// handler verifies HMAC against the X-Mort-Signature header. Default
+	// true (the storage column default). Toggling to false skips HMAC
+	// verification — useful for low-stakes integrations behind an IP
+	// allowlist where the caller can't easily compute HMAC. Owners
+	// flip this on the management page; admins can also force it
+	// back on if a leaked allowlist becomes a concern.
+	WebhookSignatureRequired bool
+
+	// WebhookIPAllowlist is a newline-separated list of CIDR blocks
+	// (or bare IPs). Empty string = no allowlist (accept any source
+	// IP). The handler parses the list at request time so updates take
+	// effect immediately without a redeploy. Invalid CIDR entries
+	// are silently dropped at parse time (the management page form
+	// shows a parse-error preview before save).
+	WebhookIPAllowlist string
+
+	// EncryptionEnabled (v8) opts the skill into per-skill envelope
+	// encryption for KV values and file blob content. Default false
+	// (plaintext storage; matches the legacy default). When true, new
+	// writes go through the AES-256-GCM helpers in pkg/skilltools and
+	// the corresponding skill_kv / skill_file_blobs row stamps
+	// encryption_key_version=1; reads transparently decrypt rows whose
+	// version > 0 and pass through rows whose version == 0 (mixed
+	// storage is supported indefinitely).
+	//
+	// !!!!! OPERATIONAL WARNING !!!!! This flag is a write-side switch
+	// only. Disabling encryption for an already-encrypted skill does
+	// NOT decrypt existing rows — they remain reachable as long as
+	// the master key is intact. Losing SKILLS_ENCRYPTION_MASTER_KEY
+	// renders every encrypted row unreadable; back the master key up
+	// separately from database backups. See pkg/skilltools/encryption.go
+	// for the full operational rules.
+	EncryptionEnabled bool
+
+	// Preemptible (v9) opts the skill into preemption: when a higher-
+	// priority job arrives at a full lane, this skill's running job may
+	// be cancelled mid-flight to free a slot. Default false.
+	//
+	// !!!!! OPERATIONAL WARNING !!!!! Preemption means the skill's
+	// scaddy.Agent context is cancelled mid-step; any partial side
+	// effects (file writes, KV updates, sent emails, etc.) remain
+	// committed. Only mark a skill preemptible when it is idempotent
+	// or read-only — otherwise the user-visible state may be
+	// inconsistent with the run's "preempted" terminal status.
+	//
+	// The lane scheduler will not preempt jobs younger than
+	// `skills.lane.preemption_min_runtime_seconds` (default 30s) to
+	// prevent thrashing. The preempted run is recorded with
+	// status="preempted".
+	Preemptible bool
+
+	// DefaultPriority (v9) is the per-skill default priority used by
+	// the lane scheduler's fair-share queue ordering. Higher numbers
+	// run first within a single user's sub-queue. Default 0.
+	//
+	// Per-invocation overrides (skill_invoke priority arg, webhook
+	// X-Mort-Priority header) win over this default. Owners may set
+	// values in the range [-`skills.priority_max_per_user`,
+	// +`skills.priority_max_per_user`] (default cap 5); admins may
+	// exceed the cap.
+	DefaultPriority int
+
+	// Tags is a free-form set of short labels owners attach to a skill
+	// for organisation + discovery. The list page renders each tag as a
+	// chip and offers a dropdown filter populated from all visible
+	// skills' tags.
+	//
+	// Why a separate field (vs reusing Description / Tools): tags are a
+	// curatorial signal, not part of the agent spec — they only matter
+	// to humans browsing the list. Storing them on the skill row (vs a
+	// side table) keeps lookups index-only and matches how the rest of
+	// the skill's flat fields are persisted.
+	//
+	// Validate enforces: each tag is trimmed + lowercased; max 32 chars
+	// per tag; max 16 tags per skill; duplicates within a single skill
+	// are deduped.
+	Tags []string
+
+	// DeprecatedByAgentID is the Phase 7 soft-retire pointer: when
+	// non-empty, the Skill is "soft retired" — hidden from default
+	// listings (`.skill list`, the webui index, chatbot tool exposure)
+	// but STILL invokable via `.skill <name>` and via `skill_invoke`
+	// tool calls. The string is the agents.Agent.ID of the replacement
+	// Agent that supersedes this Skill.
+	//
+	// Why a pointer (not a bool): a future audit / migration tool needs
+	// to follow the soft-retire link back to the replacement. An admin
+	// browsing the deprecated-skills page wants to see "what should I
+	// use instead?" without a separate lookup table.
+	//
+	// Why keep the Skill row (not drop it): existing skill_invoke calls
+	// in user-authored skills, scheduled jobs, and webhook integrations
+	// would break if the row vanished. Soft-retire preserves the
+	// callable surface while signalling "this is the old name; the
+	// replacement Agent is the curated version."
+	//
+	// Set by the Phase 7 boot migration (pkg/logic/agents/migrate_phase7.go);
+	// admins may also flip it manually via storage tooling. Listing
+	// methods filter on this field by default but explicit GetByName /
+	// GetForInvocation lookups bypass the filter so direct invocation
+	// continues to work.
+	DeprecatedByAgentID string
+
+	// DefaultEmoji is an optional identity emoji for the skill, shown
+	// as the __start__ fallback when StateReactEmoji has no __start__
+	// entry. Also forwarded to the invoking Discord message when a
+	// parent agent calls this skill via skill_invoke, so the user sees
+	// the child skill's identity emoji during execution.
+	DefaultEmoji string
+
+	// StateReactEmoji maps tool names (and reserved keys "__start__",
+	// "__end__", "__error__") to Discord emoji that the bot reacts to
+	// the invoking message with as the skill progresses. Empty map
+	// (the default) disables state-react reactions for this skill.
+	//
+	// Why: the legacy `.query` agent surfaced live progress via emoji
+	// reactions on the invoking message (magnifying glass on search,
+	// page on read, …). Skills inherit the same UX without each
+	// author having to wire `update_status` for trivial signalling —
+	// the emoji map is declarative and the executor calls inv.OnEvent
+	// at the relevant boundaries. update_status remains for richer
+	// interim text; emoji reactions are an additive lightweight signal.
+	//
+	// Reserved keys:
+	//   - __start__: reacted right before agent.Run starts
+	//   - __end__:   reacted on successful completion
+	//   - __error__: reacted on terminal error
+	//
+	// Tool keys: react fires on each tool dispatch. Repeated reactions
+	// of the same emoji are no-ops at Discord (idempotent), so a skill
+	// that calls web_search 5x just leaves one 🔍.
+	//
+	// Map values are arbitrary Discord emoji strings (unicode emoji,
+	// custom emoji `<:name:id>`, animated `<a:name:id>`). Validate does
+	// not enforce a format — Discord rejects invalid emoji at react
+	// time and the executor swallows that with a log line.
+	StateReactEmoji map[string]string
+}
+
+// ThreadIDInputKey is the magic key under skilltools.Invocation.SkillInputs
+// that the v2 .skill new / .skill edit wizard handlers use to thread a
+// pre-created thread channel ID through to delivery. When
+// OutputTarget.Kind == "thread" and this key is present in
+// inv.SkillInputs, delivery posts directly to that thread channel;
+// otherwise it falls back to OutputTarget.Target / inv.ChannelID.
+//
+// Why a magic input key vs an OutputTarget override field: keeps the
+// wire shape (Skill struct) unchanged and keeps the override scoped
+// to a single invocation. Wizard commands set this immediately after
+// MessageThreadStartComplex; nothing else writes it.
+//
+// Why defined here vs in skillexec: wizard command handlers in this
+// package need to write the key, and skillexec imports skills (so
+// the reverse import would cycle). Skillexec aliases this constant.
+const ThreadIDInputKey = "__thread_id__"
+
+// Source distinguishes builtins (loaded from skills/<name>/skill.yml on
+// boot) from user-authored manual skills.
+//
+// Why: builtin skills bypass save-time authoring and share-time safety
+// checks because the loader is trusted infrastructure.
+type Source string
+
+const (
+	SourceBuiltin Source = "builtin"
+	SourceManual  Source = "manual"
+)
+
+// InputParam declares a typed input slot on a skill, populated at
+// invocation time from positional/flag args (Discord) or form fields
+// (webui).
+//
+// Why: skills are invoked from heterogeneous surfaces and need a uniform
+// schema for input collection and validation. The Type drives string→typed
+// coercion in skillexec.validateInputs; Choices restricts to an enum set.
+type InputParam struct {
+	Name        string
+	Description string
+	Type        string // "string"|"int"|"float"|"bool"|"user"|"channel"|"url"
+	Required    bool
+	Default     string // string-encoded; parsed per Type at invocation
+	Choices     []string
+}
+
+// OutputTarget controls where the executor delivers a skill's output.
+//
+// Why: skills run in many contexts and the user shouldn't have to think
+// about delivery — the spec encodes it once. The Discord delivery
+// implementation in pkg/logic/skillexec/delivery.go reads this struct.
+type OutputTarget struct {
+	Kind   string // "channel"|"dm"|"thread"|"webui_only"|"channel_with_summary"
+	Target string // channel/member/thread ID, or empty for caller-context
+}
+
+// Visibility controls who may invoke a skill.
+//
+// Why: separates *invocation* gating (this struct) from *tool authoring*
+// gating (skilltools.Permission) — they are orthogonal. A non-admin can
+// invoke an admin-authored public skill that uses db_select; the permission
+// model for the underlying tool only fires at save time, not invocation.
+type Visibility string
+
+const (
+	VisibilityPrivate Visibility = "private"
+	VisibilityShared  Visibility = "shared"
+	VisibilityPublic  Visibility = "public"
+)
+
+// IsKnownVisibility reports whether v is a recognised visibility value.
+// Used by Validate.
+func IsKnownVisibility(v Visibility) bool {
+	switch v {
+	case VisibilityPrivate, VisibilityShared, VisibilityPublic:
+		return true
+	}
+	return false
+}
+
+// IsKnownOutputKind reports whether kind is a recognised OutputTarget.Kind.
+// Used by Validate and by the Discord delivery switch.
+//
+// "channel_with_summary" is the v-research delivery kind: full output
+// posts to a configured spam channel (skills.research.spam_channel_id)
+// while a generated summary posts in the original channel as a reply
+// linking back. Falls through to plain "channel" behaviour when the
+// spam channel convar is unset or matches the invocation channel.
+// Validate accepts this kind here; the Discord delivery switch in
+// pkg/logic/skillexec/delivery_discord.go is the consumer side.
+func IsKnownOutputKind(kind string) bool {
+	switch kind {
+	case "channel", "dm", "thread", "webui_only", "channel_with_summary":
+		return true
+	}
+	return false
+}
+
+// IsKnownInputType reports whether t is a recognised InputParam.Type.
+// Used by Validate and by skillexec.validateInputs for coercion dispatch.
+func IsKnownInputType(t string) bool {
+	switch t {
+	case "string", "int", "float", "bool", "user", "channel", "url":
+		return true
+	}
+	return false
+}

skill/skill_test.go

@@ -0,0 +1,57 @@
+package skill
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestSkillToRunnable(t *testing.T) {
+	s := &Skill{
+		ID: "s1", Name: "summarizer", SystemPrompt: "summarize well", ModelTier: "fast",
+		MaxIterations: 4, MaxRuntime: 20 * time.Second, Tools: []string{"summarize", "now"},
+	}
+	r := s.ToRunnable()
+	if r.ID != "s1" || r.ModelTier != "fast" || r.MaxIterations != 4 || len(r.LowLevelTools) != 2 {
+		t.Fatalf("ToRunnable mapping wrong: %+v", r)
+	}
+	// A skill exposes a flat tool list, not a palette.
+	if len(r.SkillPalette) != 0 || len(r.SubAgentPalette) != 0 {
+		t.Errorf("skill should have empty palettes, got %+v", r)
+	}
+}
+
+func TestMemoryStoreVisibilityAndVersions(t *testing.T) {
+	ctx := context.Background()
+	m := NewMemory()
+	pub := &Skill{ID: "a", Name: "pub", OwnerID: "o1", Visibility: VisibilityPublic}
+	shared := &Skill{ID: "b", Name: "shr", OwnerID: "o1", Visibility: VisibilityShared, SharedWith: []string{"bob"}}
+	priv := &Skill{ID: "c", Name: "prv", OwnerID: "o1", Visibility: VisibilityPrivate}
+	for _, s := range []*Skill{pub, shared, priv} {
+		if err := m.Save(ctx, s); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if ps, _ := m.ListPublic(ctx); len(ps) != 1 || ps[0].ID != "a" {
+		t.Errorf("ListPublic = %+v", ps)
+	}
+	if ss, _ := m.ListSharedWith(ctx, "bob"); len(ss) != 1 || ss[0].ID != "b" {
+		t.Errorf("ListSharedWith(bob) = %+v", ss)
+	}
+	if ss, _ := m.ListSharedWith(ctx, "carol"); len(ss) != 0 {
+		t.Errorf("ListSharedWith(carol) should be empty, got %+v", ss)
+	}
+	if all, _ := m.ListByOwner(ctx, "o1"); len(all) != 3 {
+		t.Errorf("ListByOwner = %d, want 3", len(all))
+	}
+	// Versions: newest-first, fetchable by id.
+	m.AppendVersion(ctx, SkillVersion{ID: "v1", SkillID: "a", Version: "1.0.0"})
+	m.AppendVersion(ctx, SkillVersion{ID: "v2", SkillID: "a", Version: "1.1.0"})
+	vs, _ := m.ListVersionsBySkill(ctx, "a", 10)
+	if len(vs) != 2 || vs[0].ID != "v2" {
+		t.Errorf("versions newest-first wrong: %+v", vs)
+	}
+	if got, err := m.GetVersionByID(ctx, "v1"); err != nil || got.Version != "1.0.0" {
+		t.Errorf("GetVersionByID: %v %+v", err, got)
+	}
+}

skill/skill_version.go

@@ -0,0 +1,28 @@
+package skill
+
+import "time"
+
+// SkillVersion is one immutable snapshot of a Skill at the moment it
+// was saved. The skill_versions table is append-only; pruning is by
+// retention policy in PruneOldVersions.
+//
+// Why: edit history with rollback (v3) and the admin pin gate (v3 Phase 4)
+// both need a stable snapshot of the skill at a known version. The Snapshot
+// field carries the FULL Skill struct so a later restore or pin produces
+// the exact agent definition that was saved — system_prompt, tools,
+// schedule, every field — not a synthesized partial snapshot.
+//
+// What: identity (UUID per snapshot) + skill ref + version-string copy +
+// the full Skill payload + audit fields (saved_by, saved_at, edit_summary).
+//
+// Test: see skill_version_test.go for round-trip, list ordering, prune
+// retention, and version-by-number disambiguation coverage.
+type SkillVersion struct {
+	ID          string    // UUID per snapshot (NOT the skill's ID)
+	SkillID     string    // FK to skills.id (conceptually; not enforced by GORM)
+	Version     string    // Skill.Version at save time (semver)
+	Snapshot    Skill     // full Skill struct embedded; serialised as JSON
+	SavedBy     string    // caller member ID (or "" for builtin loader / pre-v3)
+	SavedAt     time.Time // wall-clock save time
+	EditSummary string    // optional human-readable note ("changed model tier", "...")
+}

skill/store.go

@@ -0,0 +1,44 @@
+package skill
+
+import (
+	"context"
+	"errors"
+	"time"
+)
+
+// ErrNotFound is returned when a skill (or version) lookup misses.
+var ErrNotFound = errors.New("skill not found")
+
+// SkillStore is the persistence seam for saved skills. This is the DELIBERATELY
+// LEAN redesign of mort's 60-method skills.Storage: it carries only skill
+// lifecycle (CRUD + visibility), versioning, and scheduling. The KV/file/quota
+// sub-stores that were fused into mort's interface are NOT here — they are the
+// tools/ store seams (KVStorage / FileStorage / QuotaProvider); email recipients
+// and channel grants stay host concerns. A host backs this with its DB; Memory()
+// is the zero-dependency default; contrib/store adds durable SQLite.
+type SkillStore interface {
+	// Initialize prepares storage (idempotent).
+	Initialize(ctx context.Context) error
+
+	// --- lifecycle ---
+	Save(ctx context.Context, s *Skill) error
+	Get(ctx context.Context, id string) (*Skill, error)
+	GetByName(ctx context.Context, ownerID, name string) (*Skill, error)
+	Delete(ctx context.Context, id string) error
+
+	// --- listing / visibility ---
+	ListByOwner(ctx context.Context, ownerID string) ([]Skill, error)
+	ListPublic(ctx context.Context) ([]Skill, error)
+	ListSharedWith(ctx context.Context, memberID string) ([]Skill, error)
+	ListBuiltinByName(ctx context.Context, name string) (*Skill, error)
+	ListChatbotExposed(ctx context.Context) ([]Skill, error)
+
+	// --- scheduling ---
+	ListDueScheduled(ctx context.Context, now time.Time) ([]Skill, error)
+	MarkScheduledRun(ctx context.Context, skillID string, ranAt, nextAt time.Time) error
+
+	// --- versioning ---
+	AppendVersion(ctx context.Context, sv SkillVersion) error
+	ListVersionsBySkill(ctx context.Context, skillID string, limit int) ([]SkillVersion, error)
+	GetVersionByID(ctx context.Context, versionID string) (*SkillVersion, error)
+}

skill/validate.go

@@ -0,0 +1,374 @@
+package skill
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"gitea.stevedudenhoeffer.com/steve/executus/model"
+)
+
+// ChannelFilterChecker is the subset of ChannelFilterRegistry used by
+// Validate to check that a skill references a registered channel filter.
+//
+// Why: kept narrow so tests can pass a tiny stub; full registry is
+// declared in channel_filters.go.
+type ChannelFilterChecker interface {
+	Has(name string) bool
+}
+
+// ModelTierChecker reports whether the given model tier or
+// "provider/model" spec is recognised. Validate uses this to reject
+// typos at save time.
+//
+// Why: tiers come from llms.tier.* convars (fast/standard/thinking by
+// default) but admins may add custom tiers; explicit "provider/model"
+// is also valid. Validate accepts anything non-empty matching either
+// pattern — finer correctness is the LLM call's job.
+type ModelTierChecker interface {
+	IsValid(spec string) bool
+}
+
+// defaultModelTierChecker accepts all registered tier names (via
+// model.IsTierName) plus any "provider/model" form (string contains "/").
+// Tests can substitute a strict checker via ValidateOpts.ModelTierChecker.
+type defaultModelTierChecker struct{}
+
+func (defaultModelTierChecker) IsValid(spec string) bool {
+	if spec == "" {
+		return false
+	}
+	if model.IsTierName(spec) {
+		return true
+	}
+	// Accept tier-with-reasoning (e.g. "thinking:high")
+	if i := strings.IndexByte(spec, ':'); i > 0 {
+		if model.IsTierName(spec[:i]) {
+			return true
+		}
+	}
+	// Accept explicit "provider/model" or "provider/model:reasoning"
+	return strings.ContainsRune(spec, '/')
+}
+
+// ValidateOpts customises what Validate accepts. All fields are optional;
+// nil checkers fall back to permissive defaults.
+//
+// Why: Validate is called from save paths (which know the registries) and
+// from tests (which want to control acceptance). Bundling the deps here
+// keeps the Skill API stable.
+type ValidateOpts struct {
+	// Filters is consulted when the skill declares a chatbot channel
+	// filter. nil → channel-filter validity is not checked (use only in
+	// tests).
+	Filters ChannelFilterChecker
+	// ModelTier checks the ModelTier spec. nil → defaultModelTierChecker.
+	ModelTier ModelTierChecker
+	// MinIntervalMinutes is the floor on the smallest gap between
+	// consecutive fires of a skill's cron schedule. Zero → use the
+	// package default (defaultMinScheduleIntervalMinutes). Tests pass an
+	// explicit value to exercise the boundary.
+	MinIntervalMinutes int
+
+	// AuthorIsAdmin tells Validate the author has admin privileges and
+	// may save with extended-tier bounds without ExtendedBounds=true.
+	// SaveUserSkill passes this from s.admin.IsAdmin(sk.AuthoredBy).
+	// Builtin loader sets this true to bypass the per-skill flag check
+	// (builtins are trusted infrastructure).
+	AuthorIsAdmin bool
+
+	// DefaultMaxIterations / DefaultMaxToolCalls / DefaultMaxRuntimeSecs
+	// override the package-default tier-1 caps. Zero → fall back to the
+	// constants below. Production wiring populates these from convars
+	// (skills.default_max_iterations etc.) so admins can adjust the
+	// default tier without a redeploy.
+	DefaultMaxIterations  int
+	DefaultMaxToolCalls   int
+	DefaultMaxRuntimeSecs int
+
+	// ExtendedMaxIterations / ExtendedMaxToolCalls / ExtendedMaxRuntimeSecs
+	// override the package-default tier-2 caps (the ceilings allowed when
+	// ExtendedBounds=true OR AuthorIsAdmin=true). Zero → fall back to the
+	// constants below.
+	ExtendedMaxIterations  int
+	ExtendedMaxToolCalls   int
+	ExtendedMaxRuntimeSecs int
+}
+
+// Tiered cap defaults. The DEFAULT tier is what a non-admin author sees
+// without an explicit grant; the EXTENDED tier is what admin authors and
+// admin-granted skills may use. Values are tuned in the v3 spec
+// "Governance: tiered resource caps" section.
+//
+// The package's existing absolute ceilings (maxIterationsLimit=50 and
+// maxRuntime=10m) act as outer floors / sanity bounds; the tier caps
+// are the active gate at save time. Extended caps respect the absolute
+// ceilings naturally (50 iter, 600s = 10min runtime).
+const (
+	// Default tier — non-admin authors of skills without ExtendedBounds.
+	DefaultMaxIterations  = 12
+	DefaultMaxToolCalls   = 30
+	DefaultMaxRuntimeSecs = 60
+
+	// Extended tier — admin authors OR ExtendedBounds=true.
+	ExtendedMaxIterations  = 50
+	ExtendedMaxToolCalls   = 150
+	ExtendedMaxRuntimeSecs = 600 // 10m
+
+	maxIterationsLimit                = 50
+	minRuntime                        = time.Second
+	maxRuntime                        = 10 * time.Minute
+	defaultMinScheduleIntervalMinutes = 30
+
+	// MaxTagsPerSkill caps the number of organisation tags any single
+	// skill may carry. Generous compared to typical taxonomies (GitHub
+	// allows ~10 topics/repo). The cap exists to prevent the list
+	// page's chip rendering from becoming unmanageable.
+	MaxTagsPerSkill = 16
+
+	// MaxTagLength is the per-tag character ceiling. Long enough for
+	// hyphenated phrases ("retro-gaming") but short enough that the
+	// list-page tag dropdown stays readable.
+	MaxTagLength = 32
+)
+
+// Validate enforces the skill spec invariants documented in the design
+// spec ("Skill domain model" section). It is called at save time; the
+// builtin loader skips authoring/share-safety checks but still runs
+// Validate, so all callers can rely on a saved skill being well-formed.
+//
+// Why: spec rules are easy to violate by hand and silently break
+// downstream (e.g. an unknown channel filter never exposes the skill to
+// the chatbot). Every rule fails loudly here.
+//
+// What: returns the first error found; callers may surface it directly to
+// users. opts may be the zero value, in which case channel-filter
+// validation is skipped (tests).
+//
+// Test: each rejection branch has a dedicated unit test in
+// validate_test.go.
+func (s *Skill) Validate(opts ValidateOpts) error {
+	if s == nil {
+		return fmt.Errorf("skill is nil")
+	}
+	if strings.TrimSpace(s.Name) == "" {
+		return fmt.Errorf("skill name is required")
+	}
+	if strings.TrimSpace(s.SystemPrompt) == "" {
+		return fmt.Errorf("skill system prompt is required")
+	}
+
+	// ModelTier
+	tierCheck := opts.ModelTier
+	if tierCheck == nil {
+		tierCheck = defaultModelTierChecker{}
+	}
+	if !tierCheck.IsValid(s.ModelTier) {
+		return fmt.Errorf("unknown model tier %q (expected a tier alias or provider/model)", s.ModelTier)
+	}
+
+	// Schedule — empty means on-demand only. A non-empty value must be
+	// a valid cron expression (or one of the "daily" / "weekly"
+	// shorthands) AND have a smallest fire-gap >= the configured
+	// min-interval floor. Both checks share the package-level
+	// ParseSchedule helper so the scheduler runner uses the same parser.
+	if expr := strings.TrimSpace(s.Schedule); expr != "" {
+		sched, err := ParseSchedule(expr)
+		if err != nil {
+			return fmt.Errorf("schedule: %w", err)
+		}
+		minMinutes := opts.MinIntervalMinutes
+		if minMinutes == 0 {
+			minMinutes = defaultMinScheduleIntervalMinutes
+		}
+		floor := time.Duration(minMinutes) * time.Minute
+		if interval := ScheduleMinInterval(sched); interval < floor {
+			return fmt.Errorf(
+				"schedule %q runs more often than the minimum (every %s, floor is %s)",
+				expr, interval.Round(time.Second), floor)
+		}
+	}
+
+	// Iteration / call / runtime budgets. Zero is allowed — the executor
+	// substitutes a convar-backed default. Negative is always wrong.
+	// The absolute ceilings (maxIterationsLimit=50, maxRuntime=10m) are
+	// outer sanity bounds; the tier caps below are the active gate.
+	//
+	// Why admin bypass on the outer ceilings: builtins are trusted
+	// infrastructure (per the v2 "Builtin loader must bypass save-time
+	// gates" lesson). The builtin loader passes AuthorIsAdmin=true so
+	// trusted skills like `deepresearch` (max_iterations=100,
+	// max_runtime=45m) and `research` (max_runtime=15m) can validate
+	// without re-tuning the package-wide outer floor for everyone.
+	// Non-admin authors still hit the original ceilings AND the
+	// tier-based cap (default 12 iter / 60s runtime, extended 50 iter /
+	// 600s runtime) — both layers stay intact for the untrusted path.
+	if s.MaxIterations < 0 {
+		return fmt.Errorf("max_iterations must be >= 0, got %d", s.MaxIterations)
+	}
+	if !opts.AuthorIsAdmin && s.MaxIterations > maxIterationsLimit {
+		return fmt.Errorf("max_iterations must be 0..%d, got %d", maxIterationsLimit, s.MaxIterations)
+	}
+	if s.MaxToolCalls < 0 {
+		return fmt.Errorf("max_tool_calls must be >= 0, got %d", s.MaxToolCalls)
+	}
+	if s.MaxRuntime < 0 {
+		return fmt.Errorf("max_runtime must be 0 or positive, got %s", s.MaxRuntime)
+	}
+	if s.MaxRuntime > 0 && s.MaxRuntime < minRuntime {
+		return fmt.Errorf("max_runtime must be 0 or >= %s, got %s", minRuntime, s.MaxRuntime)
+	}
+	if !opts.AuthorIsAdmin && s.MaxRuntime > maxRuntime {
+		return fmt.Errorf("max_runtime must be 0 or in [%s..%s], got %s", minRuntime, maxRuntime, s.MaxRuntime)
+	}
+
+	// Tiered cap resolution: a skill saved by an admin OR a skill with
+	// ExtendedBounds=true (admin-granted) may use the extended tier;
+	// everything else saturates at the default tier. Builtins go through
+	// the loader's bypass path (AuthorIsAdmin=true).
+	defIter := opts.DefaultMaxIterations
+	if defIter == 0 {
+		defIter = DefaultMaxIterations
+	}
+	defCalls := opts.DefaultMaxToolCalls
+	if defCalls == 0 {
+		defCalls = DefaultMaxToolCalls
+	}
+	defRuntime := opts.DefaultMaxRuntimeSecs
+	if defRuntime == 0 {
+		defRuntime = DefaultMaxRuntimeSecs
+	}
+	extIter := opts.ExtendedMaxIterations
+	if extIter == 0 {
+		extIter = ExtendedMaxIterations
+	}
+	extCalls := opts.ExtendedMaxToolCalls
+	if extCalls == 0 {
+		extCalls = ExtendedMaxToolCalls
+	}
+	extRuntime := opts.ExtendedMaxRuntimeSecs
+	if extRuntime == 0 {
+		extRuntime = ExtendedMaxRuntimeSecs
+	}
+	maxIter := defIter
+	maxCalls := defCalls
+	maxRuntimeSecs := defRuntime
+	tier := "default"
+	hint := "; ask an admin to grant extended_bounds for higher"
+	if s.ExtendedBounds || opts.AuthorIsAdmin {
+		maxIter = extIter
+		maxCalls = extCalls
+		maxRuntimeSecs = extRuntime
+		tier = "extended"
+		hint = "" // already at the highest tier — no upgrade path
+	}
+	// Admin bypass on the tier cap: trusted infrastructure (builtins,
+	// admin-authored skills) may exceed the extended tier. The
+	// non-admin author still hits the tier cap above. See the
+	// "trusted infrastructure" rationale on the outer-ceiling block.
+	if !opts.AuthorIsAdmin {
+		if s.MaxIterations > maxIter {
+			return fmt.Errorf("max_iterations %d exceeds %s cap (%d)%s",
+				s.MaxIterations, tier, maxIter, hint)
+		}
+		if s.MaxToolCalls > maxCalls {
+			return fmt.Errorf("max_tool_calls %d exceeds %s cap (%d)%s",
+				s.MaxToolCalls, tier, maxCalls, hint)
+		}
+		if s.MaxRuntime > 0 && s.MaxRuntime > time.Duration(maxRuntimeSecs)*time.Second {
+			return fmt.Errorf("max_runtime %s exceeds %s cap (%ds)%s",
+				s.MaxRuntime, tier, maxRuntimeSecs, hint)
+		}
+	}
+
+	// Output target
+	if !IsKnownOutputKind(s.OutputTarget.Kind) {
+		return fmt.Errorf("unknown output_target.kind %q", s.OutputTarget.Kind)
+	}
+
+	// Input schema
+	seenInput := map[string]struct{}{}
+	for i, p := range s.InputSchema {
+		if strings.TrimSpace(p.Name) == "" {
+			return fmt.Errorf("input_schema[%d]: Name is required", i)
+		}
+		if !IsKnownInputType(p.Type) {
+			return fmt.Errorf("input_schema[%d] (%q): unknown type %q", i, p.Name, p.Type)
+		}
+		if _, dup := seenInput[p.Name]; dup {
+			return fmt.Errorf("input_schema: duplicate parameter name %q", p.Name)
+		}
+		seenInput[p.Name] = struct{}{}
+	}
+
+	// Tools
+	seenTool := map[string]struct{}{}
+	for _, t := range s.Tools {
+		if strings.TrimSpace(t) == "" {
+			return fmt.Errorf("tools: empty tool name")
+		}
+		if _, dup := seenTool[t]; dup {
+			return fmt.Errorf("tools: duplicate tool name %q", t)
+		}
+		seenTool[t] = struct{}{}
+	}
+
+	// Tags — normalise + bounds-check. The caller may pass user input
+	// directly; we trim, lowercase, dedup, and bound count + per-tag
+	// length. Mutating the slice in place is intentional so callers
+	// don't need a separate normalise pass.
+	//
+	// Why caps (16 tags / 32 chars): both are generous for human-
+	// curated organisation labels (compare to GitHub's 10 topics/repo
+	// + ~50 chars). The aim is rejecting accidental data dumps and
+	// keeping the list-page chip rendering manageable, not strict
+	// taxonomy enforcement.
+	if len(s.Tags) > MaxTagsPerSkill {
+		return fmt.Errorf("tags: too many (max %d, got %d)", MaxTagsPerSkill, len(s.Tags))
+	}
+	if len(s.Tags) > 0 {
+		seenTag := map[string]struct{}{}
+		out := make([]string, 0, len(s.Tags))
+		for _, raw := range s.Tags {
+			t := strings.ToLower(strings.TrimSpace(raw))
+			if t == "" {
+				continue
+			}
+			if len(t) > MaxTagLength {
+				return fmt.Errorf("tags: %q exceeds %d chars", t, MaxTagLength)
+			}
+			if _, dup := seenTag[t]; dup {
+				continue
+			}
+			seenTag[t] = struct{}{}
+			out = append(out, t)
+		}
+		s.Tags = out
+	}
+
+	// Visibility
+	if !IsKnownVisibility(s.Visibility) {
+		return fmt.Errorf("unknown visibility %q", s.Visibility)
+	}
+	if s.Visibility == VisibilityShared && len(s.SharedWith) == 0 {
+		return fmt.Errorf("visibility=shared requires non-empty shared_with")
+	}
+
+	// Chatbot exposure
+	if s.ExposeAsChatbotTool {
+		if strings.TrimSpace(s.ChatbotToolName) == "" {
+			return fmt.Errorf("expose_as_chatbot_tool=true requires chatbot_tool_name")
+		}
+		if strings.TrimSpace(s.ChatbotToolDescription) == "" {
+			return fmt.Errorf("expose_as_chatbot_tool=true requires chatbot_tool_description")
+		}
+		if strings.TrimSpace(s.ChatbotChannelFilter) == "" {
+			return fmt.Errorf("expose_as_chatbot_tool=true requires chatbot_channel_filter")
+		}
+		if opts.Filters != nil && !opts.Filters.Has(s.ChatbotChannelFilter) {
+			return fmt.Errorf("unknown chatbot_channel_filter %q (not registered)", s.ChatbotChannelFilter)
+		}
+	}
+
+	return nil
+}

tool/registry.go

@@ -173,6 +173,13 @@ type Invocation struct {
 	CallerID  string
 	ChannelID string
 	GuildID   string
+	// DeliveryKind / DeliveryID name where the executor posts the run's output
+	// via run.Ports.Delivery — a host-interpreted Target ("channel"/"dm"/
+	// "thread"/...). An empty DeliveryID means the executor delivers nothing
+	// and the caller reads Result.Output itself (the synchronous default; the
+	// `.agent run` canary works this way).
+	DeliveryKind string
+	DeliveryID   string
 	// CallerIsAdmin is true when the caller is a mort admin (Member.Admin).
 	// Populated by the executor at run dispatch via Bot.GetMember; defaults
 	// to false on any lookup failure (member not found, DB error, empty