Managed workflows orchestration (feature proposal)

.agents/skills/nebula-workflow

@@ -0,0 +1 @@
+../../.claude/skills/nebula-workflow

.claude/MEMORY.md

@@ -16,6 +16,11 @@ Line shape: `- DATE · [Title](memory/entries/DATE-slug.md) · TERMS: A; B · fi
 > `.claude/MEMORY.md` was split into this index plus per-entry files on 2026-08-28.
 
 ## Index
+- 2026-09-06 · [MANAGED WORKFLOW Progress Panel And Readable Labels](memory/entries/2026-09-06-workflow-progress-panel-and-readable-labels.md) · TERMS: MANAGED WORKFLOW; WORKTREES PANEL; SESSIONS PANEL; FOOTER; PANEL WALK; WORKSPACE · files: workflows.rs; panel_layout.rs; workflow.rs; protocol.rs · gotchas: 5
+- 2026-09-06 · [Removed Global NEBULA And Kept The DEV INSTANCE](memory/entries/2026-09-06-removed-global-nebula-kept-development-instance.md) · TERMS: NEBULA; MAKE DEV; DEV INSTANCE; DATA DIR; DAEMON; VERSION SKEW · files: install.sh; paths.rs; Makefile · gotchas: 2
+- 2026-09-06 · [MANAGED WORKFLOW Skill Rename And CLI Kickoff Boundary](memory/entries/2026-09-06-workflow-skill-renamed-and-cli-kickoff-boundary.md) · TERMS: MANAGED WORKFLOW; SESSION; AGENT; ROOT WORKTREE; PROJECT; DAEMON · files: SKILL.md; workflow_cli.rs; workflow.rs; workflows.md · gotchas: 2
+- 2026-09-06 · [Named MANAGED WORKFLOWS And Reusable AGENT Definitions](memory/entries/2026-09-06-named-workflows-and-reusable-agent-definitions.md) · TERMS: MANAGED WORKFLOW; MODEL / EFFORT; SQLITE STORE; AGENT; SESSION; PROTOCOL VERSION · files: workflow_config.rs; format.rs; workflow_cli.rs; SKILL.md · gotchas: 4
+- 2026-09-06 · [Ordered AGENT Workflows Use The SQLITE STORE](memory/entries/2026-09-06-ordered-agent-workflows-use-the-sqlite-store.md) · TERMS: SQLITE STORE; DAEMON; WORKTREE; SESSION; MODEL / EFFORT; STARTING PROMPT · files: workflow.rs; watcher.rs; workflows.rs; workflow_cli.rs · gotchas: 5
 - 2026-09-05 · [Released v0.22.0 Level With `origin/main`: Nothing To Carry, 38 Commits To Explain](memory/entries/2026-09-05-released-v0-22-0-level-with-origin-nothing-to-carry.md) · TERMS: RELEASE SKILL; RELEASE NOTES; RELEASE WORKTREE; SHARED CHECKOUT; CARRY SET; PROTOCOL VERSION · files: Cargo.toml; Cargo.lock; commands.md; gotchas.md · gotchas: 3
 - 2026-09-05 · [The `for … in $(…)` GUARD HOOK Block Was Right, But Its zsh Premise Is False](memory/entries/2026-09-05-for-in-guard-block-was-right-its-zsh-premise-is-false.md) · TERMS: GUARD HOOK; SESSION; RELEASE SKILL; RELEASE WORKTREE; WORKTREE · files: guard.py; gotchas.md · gotchas: 4
 - 2026-09-05 · [A SKILL AUDIT HOOK On Stop, Housekeeping Skips For PROMPT DADDY And NEBULA-MEMORY, A Quote-Aware GUARD HOOK](memory/entries/2026-09-05-skill-audit-hook-housekeeping-skips-quote-aware-guard.md) · TERMS: SELF-IMPROVING LOOP; GUARD HOOK; PROMPT DADDY; OUTPUT DOCTOR; NEBULA-MEMORY SKILL; SCREENSHOT HARNESS · files: skill_audit.py; guard.py; shot.sh; SKILL.md · gotchas: 7
@@ -46,6 +51,7 @@ Line shape: `- DATE · [Title](memory/entries/DATE-slug.md) · TERMS: A; B · fi
 - 2026-08-30 · [A GitHub Action Archives Every Merged PR Into `.claude/memory/prs/` For Agent Context](memory/entries/2026-08-30-a-github-action-archives-every-merged-pr-for-context.md) · TERMS: PR ARCHIVE; RELEASE WORKFLOW; MEMORY LOG; MEMORY CHECK; PR ROW; RECALL HOOK · files: pr-archive.yml; pr_archive.py; AGENTS.md; check.py · gotchas: 6
 - 2026-08-30 · [Walking Onto A Live SESSION ATTACHes Without The Debounce](memory/entries/2026-08-30-walking-onto-a-live-session-attaches-without-the-debounce.md) · TERMS: ATTACH; SESSIONS PANEL; TERMINAL PANE; SESSION; IDLE REAPER · files: event_loop.rs; ui.rs · gotchas: 4
 - 2026-08-30 · [TERMINAL PANE WHEEL SCROLL Steps One Line A Notch](memory/entries/2026-08-30-terminal-wheel-scrolls-one-line-a-notch.md) · TERMS: TERMINAL PANE; WHEEL SCROLL; MOUSE MODE · files: event_loop.rs; TERMS.md · gotchas: 1
+- 2026-08-29 · [Resetting HOTKEYS By Hand-Editing CONFIG.JSON Needs A TUI Restart](memory/entries/2026-08-29-resetting-hotkeys-by-hand-editing-config-json-needs-a-tui-re.md) · TERMS: CONFIG.JSON; KEYMAP; HOTKEYS TAB; DEV INSTANCE; DATA DIR; TUI · files: config.json; keymap.rs; event_loop.rs; Makefile · gotchas: 4
 - 2026-08-29 · [Proving A SHARED CHECKOUT Reset Loses Nothing Before Running It](memory/entries/2026-08-29-proving-a-shared-checkout-reset-loses-nothing.md) · TERMS: SHARED CHECKOUT; RELEASE SKILL; MEMORY CHECK; STANDING GOTCHAS · files: gotchas.md; MEMORY.md; TERMS.md · gotchas: 3
 - 2026-08-29 · [Released v0.21.0 — `cp` What Is Strictly Ahead, Merge What Moved Both Ways](memory/entries/2026-08-29-released-v0-21-0-cp-what-is-ahead-merge-what-moved-both-ways.md) · TERMS: RELEASE SKILL; CARRY SET; RELEASE WORKTREE; SHARED CHECKOUT; QUICK PROMPT FOCUS; MEMORY CHECK · files: gotchas.md; MEMORY.md; TERMS.md; config.rs · gotchas: 6
 - 2026-08-29 · [A QUICK PROMPT Launch No Longer Steals The TERMINAL PANE](memory/entries/2026-08-29-a-quick-prompt-launch-no-longer-steals-the-terminal-pane.md) · TERMS: QUICK PROMPT; FOCUS; TERMINAL PANE; LOCKED PANE; SETTING; AGENTS TAB · files: event_loop.rs; app.rs; config.rs · gotchas: 5
@@ -192,5 +198,3 @@ Line shape: `- DATE · [Title](memory/entries/DATE-slug.md) · TERMS: A; B · fi
 - 2026-08-05 · [Project Dividers And Shift+J/K Reordering](memory/entries/2026-08-05-project-dividers-and-shift-j-k-reordering.md) · TERMS: MOVE UP / MOVE DOWN; PROJECT DIVIDERS; MOVE PROJECT; RECENCY ORDER; PROJECTS PANEL · files:  · gotchas: 2
 - 2026-08-05 · [Install Script And The Org Slug](memory/entries/2026-08-05-install-script-and-the-org-slug.md) · TERMS: INSTALL.SH; NEBULA UPGRADE; PROJECT · files: install.sh · gotchas: 1
 - 2026-08-05 · [iTerm Swallowed Option+Delete](memory/entries/2026-08-05-iterm-swallowed-option-delete.md) · TERMS: SETTING; SESSION; KITTY PROTOCOL; LOCKED PANE; DELETE / DELETE ALL · files:  · gotchas: 2
-- 2026-08-04 · [The Focus-Key Odyssey → Ctrl+Q](memory/entries/2026-08-04-the-focus-key-odyssey-ctrl-q.md) · TERMS: SESSION; FOCUS; HARDWIRED UNLOCK; ESCAPE HATCH; DRAG SELECT; KITTY PROTOCOL · files:  · gotchas: 5
-- 2026-08-04 · [Bootstrap: Daemon/TUI Split](memory/entries/2026-08-04-bootstrap-daemon-tui-split.md) · TERMS: DAEMON SOCKET; IPC CODEC; HOOK RECEIVER; STATUS MACHINE; DAEMON; TUI · files: codec.rs; ui.rs; status.rs; kitty.rs · gotchas: 0

.claude/memory/archive.md

@@ -0,0 +1,5 @@
+# Archived MEMORY LOG
+
+## Archived index
+- 2026-08-04 · [Bootstrap: Daemon/TUI Split](memory/entries/2026-08-04-bootstrap-daemon-tui-split.md) · TERMS: DAEMON SOCKET; IPC CODEC; HOOK RECEIVER; STATUS MACHINE; DAEMON; TUI · files: codec.rs; ui.rs; status.rs; kitty.rs · gotchas: 0
+- 2026-08-04 · [The Focus-Key Odyssey → Ctrl+Q](memory/entries/2026-08-04-the-focus-key-odyssey-ctrl-q.md) · TERMS: SESSION; FOCUS; HARDWIRED UNLOCK; ESCAPE HATCH; DRAG SELECT; KITTY PROTOCOL · files:  · gotchas: 5

.claude/memory/entries/2026-08-29-resetting-hotkeys-by-hand-editing-config-json-needs-a-tui-re.md

@@ -0,0 +1,30 @@
+# Resetting HOTKEYS By Hand-Editing CONFIG.JSON Needs A TUI Restart — 2026-08-29
+
+**Asked:** "Please reset my keybindings to the default"
+→ refined: Reset my HOTKEYS to the KEYMAP defaults: drop the `keybindings` SETTING from CONFIG.JSON in
+the DATA DIR (the main instance, `~/Library/Application Support/dev.nebula.nebula/config.json`), leaving
+every other SETTING untouched. Don't use the SETTINGS OVERLAY's `R` reset — that resets everything, not
+just the HOTKEYS.
+
+**Did:** No code changed. The user's four overrides (`focus_left: "]"`, `focus_right: "["`,
+`focus_terminal: "\\"`, `unlock_terminal: "ctrl+q, d"`) were not in the app-support DATA DIR at all —
+they lived in the DEV INSTANCE's, `~/.nebula-dev/nebula-d87bd951/config.json` (`Makefile:32`,
+`DEV_DATA = $(HOME)/.nebula-dev/$(notdir $(CURDIR))-$(DEV_SLOT)`). Backed that file up to
+`config.json.bak-20260829-133803` and removed the whole `keybindings` key; every other SETTING kept its
+value. The four actions go back to `h`/`←`, `l`/`→`, `Ctrl+→`, and `Ctrl+Q`/`Ctrl+Shift+H`/`Ctrl+]`/
+`Ctrl+Esc`/`Ctrl+←` (`crates/nebula-tui/src/keymap.rs:159,168,177,381`).
+
+**Gotchas:**
+- **CONFIG.JSON is *not* read fresh for HOTKEYS.** `TERMS.md`'s CONFIG.JSON row says hand edits apply
+  live, and that holds for everything the code reads through `Config::load()` — but the KEYMAP is cached
+  once into `app.keymap` at startup (`event_loop.rs:279`, field at `app.rs:2128`). A hand edit to
+  `keybindings` does nothing until the TUI restarts.
+- **Worse, the next rebind silently reverts the hand edit.** `save_keymap` (`event_loop.rs:3773`) writes
+  `app.keymap.overrides()` — the *cached* map — so one `⌫`/Enter on the HOTKEYS TAB after a hand edit
+  writes all the old overrides back. Restart before touching the tab, or skip the file entirely.
+- **The in-app equivalent needs no restart:** `⌫` on a HOTKEYS TAB row is `SettingsCmd::ResetHotkey` →
+  `Keymap::reset(index)` (`event_loop.rs:3612`, `keymap.rs:971`), per row. The overlay's `R` is
+  `PendingAction::ResetSettings` → `Config::reset_to_defaults`, which rewrites the file from `json!({})`
+  and so resets *every* SETTING, not just the HOTKEYS.
+- **Look in the DEV INSTANCE DATA DIR first on this machine.** The app-support `config.json` does not
+  exist at all here; `~/.nebula-dev/<checkout>-<slot>/` is where a nebula developer's real settings are.

.claude/memory/entries/2026-09-06-named-workflows-and-reusable-agent-definitions.md

@@ -0,0 +1,12 @@
+# Named MANAGED WORKFLOWS And Reusable AGENT Definitions - 2026-09-06
+
+**Asked:** "Recap on workflows, first test worked great, But I want to understand now how can I create multiple types of workflows ... we could have in the nebula folder an agents folder that it can pick up the agent from there like which agent to use the agent could be described in line or it's it's from one of the files ... it should be easy for us to kind of oversee the configuration"
+→ refined: Extend the working workflow prototype with multiple named definitions in `.nebula/workflows/` and reusable AGENT definitions in `.nebula/agents/`. Support referenced and inline AGENTS, configurable MODEL / EFFORT, and stage-specific instructions. Use TOML unless the existing implementation gives a stronger reason for another format. Use filenames as stable selectors, with optional display names. Update the kickoff skill to discover, inspect, and select workflows. Preserve the existing SQLITE STORE scheduling and legacy JSON definitions, and make the resolved configuration easy to review before starting a run.
+
+**Did:** Added `workflow_config.rs` and `workflow_config/format.rs` for TOML discovery, typed parsing, reference resolution, and local validation. Added `workflow catalog`, `workflow inspect`, and `start --workflow`; extracted human/JSON rendering into `workflow_cli/output.rs`. Replaced the shipped `.nebula/workflow.json` with `workflows/default.toml`, `reviewed.toml`, and `review.toml` plus three reusable AGENT files, all pinned to `claude-sonnet-5` / `medium`. The kickoff skill now chooses by selector or description and previews the resolved definition. `docs/workflows.md` and `.nebula/README.md` explain composition and precedence. PROTOCOL VERSION 40 carries the optional definition id/name; existing SQLITE STORE snapshots load without a MIGRATION. Promoted MANAGED WORKFLOW after its second task. Clippy and formatting passed; all 915 workspace tests passed with `--test-threads=1` and an isolated `CODEX_HOME`. The initial parallel run hit three existing port bind/rebind races in `browser.rs` and `tunnel.rs` (`AddrInUse`); those tests passed sequentially without code changes. TERMS CHECK and RECALL EVAL passed, and this entry ranks 2 for its own prompt. On continuation, restored the missing index line for `2026-08-29-resetting-hotkeys-by-hand-editing-config-json-needs-a-tui-re.md`, the pre-existing MEMORY CHECK failure. MEMORY CHECK (199/200 index lines), RECALL EVAL, and TERMS CHECK then passed; the restored entry ranks 1 for its own prompt. A live read-only handshake confirmed the DAEMON still uses protocol 39 despite sharing the rebuilt protocol-40 executable path; restarting that DEV INSTANCE would terminate this SESSION and must be run from a separate terminal.
+
+**Gotchas:**
+- The filename is the selector; `name` is a display label. Labels may repeat. With no selector, choose `default.toml`, then the sole TOML definition; multiple non-default files require a choice. Legacy JSON is the automatic fallback only when no TOML definitions exist. Regression tests cover selection and legacy compatibility.
+- AGENT instructions are followed by stage instructions; stage MODEL / EFFORT override the AGENT, then omitted values use NEBULA defaults. The combined prompt text must fit the existing 4,000-byte stage bound. Unknown fields, missing references, unsupported kinds, and path/symlink escapes fail before DAEMON contact.
+- File resolution happens before kickoff. The E2E test edits the referenced AGENT file and deletes the definition after start, then verifies that a later SESSION still uses the original frozen configuration across DAEMON restarts. The watcher never rereads those files.
+- `catalog` and `inspect` need no running DAEMON or AGENT id. Starting a run needs a DAEMON matching PROTOCOL VERSION 40. The previously running prototype was version 39, so configuration can be inspected immediately but execution needs a deliberate restart. No live DAEMON was restarted by this task.

.claude/memory/entries/2026-09-06-ordered-agent-workflows-use-the-sqlite-store.md

@@ -0,0 +1,21 @@
+# Ordered AGENT Workflows Use The SQLITE STORE - 2026-09-06
+
+Configuration follow-up: [named workflows and reusable AGENTS](2026-09-06-named-workflows-and-reusable-agent-definitions.md) replace the single shipped JSON definition with TOML files. The original JSON format remains supported; the DAEMON scheduling described here still applies.
+
+**Asked:** "Investigate how nebula works and all its commands. ... the idea is to build something on top of nebula to create agent workflows, so I can kick off a task that will be self executed in this order of agents we define" Follow-up: "Hey just one thing I noticed, I guess the state could be tracked inside nebula sql already instead of a .nebula folder, that could be more reliable"
+→ refined: Investigate NEBULA's commands and build a runnable prototype for ordered AGENT workflows. Start a task from `main`, create a separate WORKTREE, and run a planner followed by an implementer in NEBULA SESSIONS, with a reviewer configurable later (assuming two stages initially). Store the workflow definition under `.nebula` and durable run state in the existing SQLITE STORE, including each stage's AGENT KIND and MODEL / EFFORT. A watcher advances only after an explicit stage result. Create a kickoff skill, demonstrate the handoff, and explain limitations. "Managed workflow" has no TERM yet; record it as a candidate. (Asked: two or three stages, provider mix; no answer received. Defaulted to Claude planner, Codex implementer, NEBULA-configured MODEL / EFFORT.)
+
+**Did:** Investigated the CLI, WORKTREE/SESSION creation, STARTING PROMPTS, status hooks, and persistence. Added `workflow start/status/list/report/pause/resume`, MIGRATION 24, PROTOCOL VERSION 39, atomic workflow snapshots plus SESSION associations, and a DAEMON-owned watcher. `.nebula/workflow.json` holds only the versioned definition. Added `/workflow-prototype` under `.claude/skills` with an `.agents/skills` symlink (renamed to `/nebula-workflow` later on September 6), and `docs/workflows.md` with setup, command inventory, state transitions, and recovery. The engine is in `crates/nebula-daemon/src/workflow.rs` and `workflow/watcher.rs`; persistence is in `store/workflows.rs`. Workspace lint and 906 tests passed, including an isolated real DAEMON/WORKTREE/PTY handoff with STUB AGENTS. No real provider execution, live DAEMON restart, commit, or install. MEMORY CHECK already failed on the unrelated unindexed August 29 HOTKEYS entry before this entry was added.
+
+**Gotchas:**
+- FINISHED is a turn state, not task success. The watcher requires both an explicit completed report and FINISHED. The E2E test covers both missing-report and report-before-FINISHED ordering, wrong callers/stages, blocked-result recovery, and immutable completed results.
+- WORKTREE and provider process creation cannot share a SQLite transaction. Persist creation/launch intent first; after interruption, adopt the unique recorded-name SESSION or block for inspection. Never blindly retry an uncertain launch. DAEMON restart preserves data but does not automatically restart provider conversations.
+- A development DAEMON can be newer than `nebula` on the AGENT's PATH (installed 0.21.0 versus this checkout 0.22.0). Worker STARTING PROMPTS use the shell-quoted DAEMON executable path. The new WORKTREE starts from committed `main`, so the DAEMON supplies the frozen definition; uncommitted prototype files need not exist there.
+- STUB AGENTS replace provider argv, so these E2E checks prove orchestration and durability, not real model instruction following. Codex hook setup still touches CODEX_HOME even with a STUB AGENT; the new E2E isolates CODEX_HOME, and the full suite ran with a temporary CODEX_HOME.
+- MAKE DEV's database seed originally copied all tables except live SESSIONS. Pending workflow rows would let a development DAEMON launch copied work in the real WORKTREE. The Makefile now strips workflow rows and only publishes a cleaned seed. Three isolated runs of the actual `dev-seed` recipe passed: legacy schema, workflow schema, and failed cleanup leaving no published database; source databases remained unchanged.
+
+**Corrections:** 1
+
+Configuration follow-up: the user requested "Please set claude sonnet medium effort for planner and for implementer too, same models and effort", then "Are you sure this model namei s correct? it needs to match exactly". Both stages now declare `kind: claude`, `model: claude-sonnet-5`, and `effort: medium`; the kickoff skill and guide match. This supersedes the initial provider assumption above and applies to new runs.
+
+Verified the exact MODEL / EFFORT with the installed Claude Code 2.1.263 and the official model configuration docs (`https://code.claude.com/docs/en/model-config`): `sonnet` is an alias; the full ID pins Sonnet 5. A live, tool-free, nonpersistent request from a temporary directory using `--safe-mode --model claude-sonnet-5 --effort medium` returned `OK`, with `claude-sonnet-5` in `modelUsage` (the harness also recorded an auxiliary Haiku call). This verified model access, not a complete live workflow handoff.