# v0.0.7-alpha.3

## 🧰 The "Agents, Flows, and Schedules" Release

- **Release date:** 2026-04-20
- **Previous release:** `v0.0.7-alpha.2` (2026-04-14)
- **Delta:** 292 commits, 523 files changed, +49,206 / −22,930

---

### The roadmap picks up speed.

Six weeks of dogfooding turned into a massive alpha. This drop promotes **agents** and **flows** into first-class primitives you can edit in the UI, ships a **scheduler** so routine tasks fire on a cadence, lands **cloud authentication Phase 1 and 2**, introduces **host-exec mode** for container-free runs, unifies the spec and task graph into a single **Map view**, retires the bespoke **refinement pipeline** into Plan mode, and sweeps a long list of UX papercuts.

If you want a headline: **the composer no longer asks "what sandbox?" — it asks "what flow?"** Everything else follows from that.

---

## 🧬 Agents & Flows — first-class, editable, hot-reloadable

The biggest structural shift this release. Task execution is no longer "pick a sandbox and go"; it's "compose an **agent** (role + harness + prompt) into a **flow** (ordered steps with fan-out) and run it."

### The primitives
- **Agent** is the atomic unit: a role (implementation, testing, refinement, oversight, commit, title, ideation, ...) bound to a harness (`claude` or `codex`) with a pinned prompt template.
- **Flow** is a composition of agent steps with parallel-sibling fan-out — e.g. "implement, then run test + commit in parallel."
- Built-in catalogs ship with the binary; user-authored YAML under `~/.wallfacer/agents/` and `~/.wallfacer/flows/` merges in on top and **hot-reloads via fsnotify** when you edit files on disk.

### UI: Agents and Flows tabs
- New sidebar tabs for **Agents** and **Flows**, each with a split-pane editor, inline clone/edit/delete, and Wallfacer design tokens.
- The Flows tab supports **drag-and-drop step reorder**.
- Clone any built-in to start customizing; your clone lands as YAML under `~/.wallfacer/`.

### Composer migration
- The new-task composer replaces the old **Task Kind** + per-activity sandbox overrides with a single **Flow** picker. The Agent selector is gone — the harness lives on the agent a flow step references.
- `POST /api/tasks` no longer accepts `sandbox` or `sandbox_by_activity`. If you script against the API, send `flow: "<slug>"` or rely on the default flow; PATCH the task's sandbox after creation if you need an override.
- Legacy `Kind` values resolve through a `Kind→Flow` compatibility shim so old task records still open.

### Under the hood: Agent abstraction
- New `AgentRole` descriptor + `runAgent` primitive collapse seven sub-agent roles (title, oversight, commit, refinement, ideation, implementation, testing) onto one container launch path.
- `internal/agents/` extracted as its own package with headless / inspector / heavyweight classifications.
- Dispatched non-implement flows now route through the new flow engine with parallel-sibling fan-out.

---

## ⏲️ Routine tasks — cron for the board

A generic schedule primitive promoted from the old brainstorm cronjob.

- **Routines are board cards** (`Kind=routine`) with an interval, enable/disable toggle, and an inline countdown. When they fire, they spawn fresh instance tasks against a configured flow.
- **`/api/routines`** endpoints for create, trigger-now, list, patch. Routine cancellation now cascades: the routine card is stopped and all its live spawned children are cancelled too.
- **Ideation migrated** to a `system:ideation` routine — the old "Brainstorm" toggle in Automation and Settings is gone.
- System routines render calmer chrome and are hidden from the board by default; their instance tasks appear normally.
- **Routine safety:** cancelled, archived, and done/failed routines are treated as stopped, don't spawn new instances, and unregister synchronously from the scheduler.

---

## 🔐 Cloud Authentication — Phase 1 and 2 shipped

Wallfacer now has real sign-in in cloud mode.

### Phase 1 — `WALLFACER_CLOUD=true` gates everything
- New `internal/auth` package and `WALLFACER_CLOUD` env flag.
- latere.ai sign-in routes (`/login`, `/callback`, `/logout`, `/logout/notify`, `/api/auth/me`) and cloud-gated `/api/config` fields.
- **Status-bar sign-in badge**, later promoted into a proper sidebar dropdown menu with an **org switcher**.
- **Front-channel logout** via iframe so signing out propagates across tabs.

### Phase 2 — JWT principal + RBAC
- **JWT validation middleware** for cloud-mode API routes. `AUTH_JWKS_URL` and `AUTH_ISSUER` are the new cloud-mode env vars; documented in `docs/cloud/`.
- **Principal context**: `CookiePrincipal` bridges the session cookie to `auth.Claims` on the request context, which in turn gets stamped onto task events as actor attribution.
- **Data model:** `CreatedBy` and `OrgID` on `Task`, plus a `TasksForPrincipal` filter so tasks are scoped by the viewing user's org.
- **Forced login for anonymous HTML in cloud mode** — no more unauthenticated UI surface.
- **Scope + superadmin gating** (`RequireScope`, `RequireSuperadmin`). `POST /api/admin/rebuild-index` now requires the superadmin scope.
- **Org switching** via the sign-in badge with `GET /api/orgs` + `POST /api/orgs/switch`.
- **Sandbox trust-plane proxy** endpoints (`/internal/sandbox-proxy/llm/anthropic/`, `/llm/openai/`, `/github-token`) as the forward-compatibility path for agent token exchange. Disabled unless `SANDBOX_PROXY_AUTH_URL` is set.
- **Cloud docs**: new `docs/cloud/` guide; `AGENTS.md` + `CLAUDE.md` list the new env vars.

---

## 🖥️ Host-exec mode — container-free task execution

A new backend for users who don't want podman/docker.

- `wallfacer run --backend host` execs `claude` or `codex` directly on the host instead of spinning up a container.
- `make build-host` target builds a host-first binary without pulling sandbox images.
- `wallfacer doctor --backend host` checks host-mode prerequisites.
- Codex gets argv translation so it works without the container image; Claude host-mode stream buffering is fixed.
- Max-parallel caps to 1 in host mode by default (fewer isolation guarantees, don't overwhelm the laptop).
- Settings → Sandbox shows a host-mode warning banner. See `specs/shared/host-exec-mode.md` for the isolation trade-off.

---

## 🗺️ Map view — unified spec + task graph

Plan's old spec-only minimap is gone. In its place:

- A **Map** tab that renders the full spec tree and task board as a single graph with force-directed layout, drag-to-pin, focus lens, and incremental relayout.
- Straight edges, Sugiyama layering with median + neighbor-aware sweeps (kept available as a legacy mode behind a flag).
- Interactive navigation: top-bar filter routes to the active mode's dim; clicking a node focuses it in its native view (spec in Plan, task on the board).
- Spec dep graph restyled with tinted nodes and an inspector panel.

---

## 🧵 Refinement unified into Plan mode

The bespoke "Refine with AI" pipeline is retired.

- **Task Prompts explorer section** lists backlog tasks (and waiting tasks behind a toggle) in both the Plan mode spec explorer and the board explorer. Clicking opens the task's prompt in the focused markdown view and pins the chat thread to that task.
- **Send to Plan** action on task cards and the detail modal opens (or reuses) a task-mode planning thread.
- **Task-mode chat threads** pin to a task UUID; the agent's output is auto-written to `task.Prompt` at end-of-turn with a `prompt_round` event for undo and audit. **Undo** rewinds either a git commit (spec-mode) or the last `prompt_round` event (task-mode).
- `internal/handler/refine.go`, `internal/runner/refine.go`, `ui/js/refine.js`, the Refine modal, the `autorefine` config flag, and the five `/api/tasks/{id}/refine*` routes are **gone**. A guard test prevents the routes from reappearing.
- **Task movement lock**: a task pinned to an in-flight refinement turn cannot transition until the turn finishes. Leaving backlog auto-archives the thread.

---

## 🗂️ Task board and composer redesign

- **Task detail modal** gets a top-level main-tab bar, right-side summary aside, flattened surfaces, consolidated main pane, and a single modal card. Aside actions are promoted to the top and redesigned as card buttons.
- **Start task, Send to Plan, Mark as Done, Archive, Unarchive, Cancel** all live in the aside action rail with consistent chrome. Mark as Done uses a new `aside-action--success` green variant matching the card chip.
- **New-task composer** redesigned with compact, dense modern chrome and a flow picker. Composer can create either a one-off task or a routine card.
- **Empty-board composer** renders when a workspace group has zero tasks, with a Plan bridge.
- **Workspace switcher moved to the sidebar** (was in the status bar); **branch indicator** moved to the status bar.
- **Presence panel** in the sidebar for the cloud tenancy shape.
- **Paper-ink board style** with soft column trays; terminal panel gets a matching dark ink theme.

---

## 🧩 Sidebar chrome and design tokens

- **Design tokens** extracted into `tokens.css`; status bar, sidebar, and board migrated to the new variables.
- **Sidebar refresh**: brand, search, nav, collapse behavior, keyboard shortcut styling (`.kbd`), new `.sb-*` class vocabulary.
- Scrollbar gutter reserved on both column edges so layout doesn't jump when scrollbars appear.
- Terminal panel restyled with a dark ink theme; terminal colors no longer invert under dark mode.

---

## 🏗️ Workspace groups and automation

- **Per-group `MaxParallel`** override with an inline editor on the In-Progress column header.
- **Automation scoping**: autopilot, autosync, autosubmit, and autoretest toggles are scoped to the viewed workspace group and persisted per-group. Switching groups no longer resets them.

---

## 🪶 Smaller fixes and polish

- **`cmd+Enter` in the task composer used to create two identical tasks** — duplicate keydown handler removed.
- **Cancel button** state scoped per-task; cancelling task A no longer leaks "Shutting down…" into task B's modal.
- **Task Prompts explorer section** styled to match `.explorer-node` (12px rows, amber waiting-toggle pill, status badge + title + timestamp).
- **Plan button** on cards tinted amber to match other card actions, hidden on non-backlog states.
- **Plan view** fills the breadcrumb with task title/status and renders the task prompt as markdown instead of flashing empty.
- **Clicking a Task Prompts entry mid-stream** no longer kills the agent's in-flight turn (new `switchThread` path on `PlanningChat`).
- **Waiting tasks** can resume with their existing session from the detail modal aside.
- **Composer stuck visible after `hideNewTaskForm`** — fixed.
- **Empty explorer tree in Board after returning from Plan mode** — fixed.
- **Terminal colors inverting under dark mode** — fixed.
- **Sign-in menu** escapes the sidebar's `overflow: hidden` via `position: fixed` + JS anchoring; badge is a two-line trigger with balanced spacing.
- **Em-dashes** removed from agents/flows/composer copy and peer specs.

---

## 🗃️ Rename: Kanban → Board

Project-wide vocabulary cleanup. Route names, component names, sidebar labels, and docs all speak "Board" now. No functional change; the old paths redirect for one release.

---

## 🗺️ Specs organisation

- Track themes introduced: `specs/oversight/`, `specs/observability/`, `specs/intelligence/`, `specs/intent/`, `specs/identity/`, `specs/cloud/`.
- **Agent abstraction** marked complete; Option A shipped across five migration phases.
- **Routine tasks** complete; **host-exec-mode** complete; **agents-and-flows** track complete.
- **Authentication** Phase 1 complete, Phase 2 breakdown landed with subtasks (JWT middleware, data model, principal context, cloud-forced-login, scope-and-superadmin, task-event-actor-sub, org-switching) all marked complete.
- Authentication Phase 3 split into `third-party-oidc` and `remote-control` so the cloud move can proceed independently.
- **Sandbox track handed off** to `latere.ai/sandbox`; internal sandbox specs archived.
- **Refinement-into-plan** spec complete; all eight leaf tasks landed.
- **Pixel-agents** spec archived; the pixel-art office feature was retired.
- **Multi-user-collaboration** added as a cloud blocker spec.
- **Audit log** added as a future-effort shared spec.

---

## 💔 Removed

- **Pixel-art agent office.** The tile-map, sprites, path-finding, and character manager are gone. The spec is archived for reference. Design mode and the Map view replace the at-a-glance agent spatial metaphor.
- **Refinement subsystem** (see Plan section above).
- **Auto-refine toggle** and env flag.
- **`sandbox` and `sandbox_by_activity` fields on `POST /api/tasks`.**
- **Goal task field** removed; the prompt is the source of truth.
- **Task Kind picker** and per-activity sandbox overrides in the task modal — harness lives on the agent now.
- **Brainstorm toggle** in Automation and Settings — ideation is a system routine.
- **Plan minimap** — superseded by the unified Map view.

---

## 🛠️ Under the hood

- **Agent abstraction migration** across seven roles (title, oversight, commit, refinement, ideation, implementation, testing) onto the shared `runAgent` path.
- **`internal/gitutil/`** extracted as reusable git helpers; runner and planner both consume it.
- **`internal/auth/`** new package for validator, middleware, principal context, cookie bridge, RBAC wrappers.
- **Sandbox `HostBackend`** and `--backend host` wiring; ContainerSpec-to-host-path translation.
- **Scheduler engine** (`internal/routine/`) with idempotent Register and re-arm race fix.
- **`/api/agents`, `/api/flows`, `/api/routines`, `/api/orgs`** endpoint families.
- **Event schema:** new `prompt_round` and `prompt_round_revert` event types; task events carry actor attribution.
- **Store:** `Task.FlowID`, `Task.CreatedBy`, `Task.OrgID`, `TaskKindRoutine` with schedule fields.
- **go-git** bumped to v5.18.0; **vite** bumped to 7.3.2 for security fixes.
- **Windows and macOS CI** flakes fixed (container start timing, worktree cleanup, host-handle race).
- **`-ui-dir` flag** and `make server-dev` for live UI editing without rebuilds.
- **Sandbox image:** resolves the latest `latere-ai/images` tag at build time; retags local `sandbox-agents:latest` as a fallback when the resolved tag is missing. Skips the pull when the local tag already exists.

---

## 📦 Operator notes

- **API breaking:** `POST /api/tasks` and `POST /api/tasks/batch` no longer accept `sandbox` or `sandbox_by_activity`. Send `flow: "<slug>"` or rely on the default flow. PATCH the task's sandbox after creation if you need an override.
- **`autorefine` removed** from config and env. Leaving it set has no effect.
- **`Goal` field removed** from the `Task` model. Scripts reading it should fall back to `prompt`.
- **Task records** retain dormant refine fields (`RefinementSession`, `RefineSessions`, `CurrentRefinement`) for on-disk back-compat. They are read-only and will be removed in a future release via a migration pass.
- **Cloud mode:** set `WALLFACER_CLOUD=true` plus `AUTH_JWKS_URL` and `AUTH_ISSUER` to enable sign-in. Without these, the new auth middleware stays in `OptionalAuth` mode and the UI runs anonymous.
- **Host-exec mode:** `wallfacer run --backend host` is opt-in; run `wallfacer doctor --backend host` first. Max parallel defaults to 1.
- **Sandbox trust-plane proxy:** disabled unless `SANDBOX_PROXY_AUTH_URL` is set. Cloud-only, not user-facing yet.
- **Ideation:** the Brainstorm toggle is gone. A `system:ideation` routine takes its place and can be configured from the Routines view.

---

## 📥 Desktop App

- **macOS:** `Wallfacer-darwin-universal.zip` — extract and drag to Applications
- **Windows:** `Wallfacer-windows-amd64.exe` — run directly (allow in SmartScreen on first launch)
- **Linux:** `Wallfacer-linux-amd64` — `chmod +x` and run (requires WebKitGTK)

---

**292 commits. 523 files. Seven tracks closed. Agents, flows, schedules, auth, host-exec, map, plan-mode refinement, all landing in one drop.**
