Goal Management

Goals transform Myrm from a chat assistant into an autonomous worker. Define an objective, set constraints, and let the agent work independently across multiple turns.

Creating a Goal

From the GUI

Toggle Goal Mode in the message input area (bottom-right toggle button)
The configuration panel expands with sections:
- Budget — Set any combination of max_tokens, max_usd, max_time_seconds, and max_turns
- Acceptance Criteria — Define shell commands and semantic checks the agent must pass
- Constraints — Rules the agent must follow during execution
- Protected Paths — Glob patterns for files the agent must not modify (e.g., *.env, migrations/**)
- Advanced — loop_on_pause, convergence_window, Pause after each step (per-todo checkpoint)
Type your objective in the message box and send — the agent begins planning and executing

From Chat

Simply describe a complex task in natural language. The agent will detect it requires sustained effort and offer to create a goal.

Goal Lifecycle

QUEUED → ACTIVE → PAUSED / WAIT / BUDGET_LIMITED / NEEDS_HUMAN_REVIEW → COMPLETE / CANCELLED
           ↑                            ↓
    PENDING_APPROVAL ←───────── (resume)

State	Description
`QUEUED`	Waiting for the current active goal to finish
`ACTIVE`	Agent is actively working toward the objective
`PENDING_APPROVAL`	Waiting for user to approve the execution plan
`PAUSED`	Temporarily halted by user or convergence detection
`WAIT`	Agent is blocked and needs user input or an external event (e.g., background job, user credentials), or the goal is determined unachievable without user guidance
`BUDGET_LIMITED`	Budget exhausted — requires user to add budget and resume
`NEEDS_HUMAN_REVIEW`	Verification failed — requires human review and feedback
`COMPLETE`	Objective met and verified
`CANCELLED`	Explicitly cancelled by user

Budget Control

Every goal has 4 budget dimensions:

Dimension	Description	Example
`max_tokens`	Maximum total tokens consumed	500,000
`max_usd`	Maximum dollar spend	$5.00
`max_time_seconds`	Maximum wall-clock time	3600 (1 hour)
`max_turns`	Maximum agent turns	30

Budget exhaustion pauses the goal with a structured summary of progress. You can resume the goal with additional budget at any time.

Acceptance Criteria

Define what “done” looks like:

All tests pass, code coverage > 80%, no new linting errors

The agent uses dual-engine verification:

Shell verification — Runs test commands (e.g., pytest, npm test) and checks results
Semantic verification — LLM-based assessment against your acceptance criteria

Both engines must agree for the goal to be marked complete.

Advanced: Logical Consistency Verification

For long document tasks, semantic verification ensures the entire output is logically consistent:

Verify all sections are logically coherent: data and claims introduced earlier are addressed in later sections with no contradictions or omissions

After the agent finishes writing, the LLM reads the full output and judges logical consistency. If it fails, the agent automatically fixes the issues (up to 3 retries, then pauses for human review).

Constraints

Hard rules the agent must follow:

Do not modify the database schema
Do not introduce new dependencies
Keep all changes backward compatible

Constraints are injected into the agent’s prompt every turn as a “CONSTRAINTS (MUST NOT VIOLATE)” block, and the semantic judge evaluates compliance during completion verification.

14-Layer Dead-Loop Shield

At the end of every turn, a 14-layer guard chain determines whether the agent should continue — preventing runaway execution, cost overruns, token waste, goal drift, and sandbox probing:

#	Guard Layer	What it does
1	User cancellation	Immediate stop via `CancellationToken`
2	4D budget limits	Tokens / USD / wall-clock time / turns — any dimension exhausted triggers pause
3	Steering token	Pauses when a new user message is pending, ensuring user input takes priority
4	Tool completion check	Detects if tools already reported the goal as done
5	Sandbox boundary HITL	3× consecutive `PERMISSION_DENIED` → graceful PAUSE (not hard crash) + red alert in GoalStatusCard for human review
6	Goal drift detection	Every 5 turns, LITE_MODEL scores trajectory drift 0–10. Score ≥3 → nudge message injected; ≥7 → PAUSE for human review. Fail-open on LLM error
7	Per-todo checkpoint	Opt-in mode: auto-PAUSE after each todo completion, waits for user confirmation before continuing. Ideal for high-risk multi-step tasks (deployments, migrations, data pipelines)
8	Semantic judge (LLM)	Evaluates whether the objective is met based on conversation context
9	Constraint compliance	Checks acceptance criteria and protected-file rules
10	Zero-progress pause	No tool calls in a turn → auto-pause to prevent “talks but does nothing”
11	Judge parse circuit-breaker	3 consecutive unparseable judge outputs → pause (saves tokens on bad models)
12	Verification fuse	3 consecutive verification failures → pause (prevents verify-retry loops)
13	Convergence detection	K turns without progress → auto-complete (`convergence_window`)
14	Graceful wrap-up	On budget exhaustion, injects a wrap-up prompt for a final summary turn — no mid-sentence cutoffs

Additionally, progressive budget degradation (WARNING → FINALIZATION) with dynamic remaining USD injection and 4-layer context-window overflow protection operate at the middleware level to catch edge cases before they reach the guard chain.

Judge Feedback Loop

When the semantic judge determines the goal is not yet complete, it provides a specific reason (e.g., “only 3 of 5 charts produced”). This reason is automatically injected into the next turn’s prompt so the agent knows exactly what gap to address — eliminating redundant re-analysis and reducing unnecessary turns.

Per-Todo Checkpoint

Enable “Pause after each step” in Advanced settings to activate per-todo checkpoint mode. When enabled, the agent automatically pauses after completing each todo item and waits for your confirmation before continuing. How it works:

Agent reports a todo item as completed via todo_write
Guard chain detects the new completion and pauses the goal
GoalStatusCard shows which step(s) just finished with a Continue button
You review the results, then click Continue to proceed to the next step

Best for:

Production deployments — Confirm each migration step before proceeding
Data pipelines — Verify data integrity at each stage
Complex refactors — Review code changes step by step
Learning — Understand what the agent does at each stage

This is opt-in and defaults to off. When disabled, the agent runs uninterrupted as usual.

Kanban Goal Mode

Goals are not limited to chat — you can enable Goal Mode on any Kanban task card for autonomous multi-turn execution:

Enabling Goal Mode

When creating a new Kanban task, toggle Goal Mode in the task creation form
Optionally set Max Turns (defaults to the system goal budget if not specified)
The task description becomes the goal objective; the agent works toward it across multiple turns

How It Works

When a Goal Mode task is dispatched:

The KanbanTaskRunner creates a GoalProvider via the GoalRegistry, reusing the full Goal engine (same infrastructure as chat goals)
The StreamExecutor drives the autonomous loop — semantic judge, 14-layer guard chain, budget control, convergence detection — all apply
On completion: GoalStatus.COMPLETE → task marked COMPLETED; budget exhaustion → task marked FAILED with structured summary

Why Use It

Scenario	Without Goal Mode	With Goal Mode
Research report	Single-turn partial output, manual re-run	Multi-turn deep research until acceptance criteria pass
Code review audit	One pass, misses follow-up items	Iterative review → fix → verify cycle
Data analysis	Incomplete if data is complex	Continues until all metrics extracted and validated

Visual Indicators

Task Card — A “Goal Mode” badge appears on cards with goal mode enabled (shows max turns if set)
Task Drawer — The details section shows Goal Mode status

Budget & Safety

All 4 budget dimensions (tokens, USD, time, turns) apply. The 14-layer dead-loop shield runs on every turn, preventing runaway execution, cost overruns, and goal drift — identical protections to chat goals.

Priority Queue

When you create multiple goals, they’re automatically queued:

The first goal runs immediately
Subsequent goals enter QUEUED state
When the active goal finishes, the next queued goal auto-starts
Drag-and-drop reordering in the GUI

Set auto_approve: true to skip the approval step for queued goals, enabling fully unattended execution of goal chains.

Saved Agent Profile on Continuation

When a goal auto-continues (queue dequeue, background WAIT resume, or loop restart), Myrm does not fall back to a generic headless agent. The continuation path loads the chat-bound Saved Agent profile and injects the same runtime context as your first turn:

Field	Why it matters
`agent_id`	Preserves the agent you selected in chat
`user_instructions`	System prompt + team Leader protocol (when `agent_type=team`) + output locale suffixes
`subagent_ids`	Keeps delegation tools bound on team leaders
`agent_skill_ids`	Keeps skill-scoped tools available
Tool mount + security	Builtin tool flags and `enable_web_fetch` follow the saved agent’s security profile

This means long-running goals keep formal tone (e.g., Korean 합니다体 via builtin-ko-office or a custom response_locale_policy), team roster text, and tool scope across every unattended turn — not just turn 1. Implementation entry point: goal_stream_trigger.py (trigger_goal_stream / _resolve_goal_stream_agent_context). Verified (Aug 2026): Goal Chrome E2E (test_goal_focus_chrome_e2e.py) passed 2/2 live runs (~3 min pytest body each) via real WebUI + MCP mux + MiniMax-M3 — confirms Goal mode stream, wait_turn_done, and persisted goal status on a private SHPOIB backend.

Adaptive Convergence & Loop-on-Pause

Goals can automatically detect when the agent has finished its work and handle continuous execution without human intervention.

Convergence Detection

When the agent goes convergence_window consecutive turns without making any tool calls, the goal is automatically marked as converged (completed). This prevents the agent from idling and wasting tokens when it has nothing left to do.

Parameter	Description	Default
`convergence_window`	Turns of no progress before auto-convergence	(disabled)

Loop-on-Pause

When enabled, a goal that pauses due to convergence will automatically restart with a fresh context, up to a configurable maximum number of restarts. This is ideal for long-running monitoring or iterative refinement tasks.

Parameter	Description	Default
`loop_on_pause`	Automatically restart after convergence pause	`false`
`max_loop_restarts`	Maximum number of automatic restarts	0

Resume Safety

When you manually resume a paused goal, all runtime counters (no_progress_streak, loop_restarts, consecutive_judge_parse_failures) are automatically reset to zero. This ensures the agent gets a fresh opportunity without triggering immediate re-convergence or false auto-pauses.

Judge Failure Circuit Breaker

If the semantic judge model returns unparseable output (not valid JSON) 3 consecutive times, the goal is automatically paused to prevent burning tokens on a misconfigured judge. This protects against:

Using a weak model that can’t follow the JSON reply contract
Temporary model degradation producing garbage output
Token budget waste from infinite retry loops

When the goal pauses due to parse failures, the reason field clearly states what happened and suggests switching to a more capable judge model. Resuming the goal resets the failure counter, so you can try again after fixing the configuration. API/network errors do not count toward this threshold — only content-level parse failures trigger the circuit breaker.

Server Restart Recovery

If the server restarts (upgrade, crash, or container reschedule) while a goal is active, the orphaned goal is automatically detected and paused with a clear reason:

On startup, the server scans for goals still marked ACTIVE with no execution engine driving them
Each orphaned goal transitions to PAUSED with the reason “Server restarted — resume when ready”
A system notification alerts you that goals were paused
Open the affected chat to see the paused status and one-click Resume when ready

This prevents silent token waste (no automatic resume without your consent) while ensuring you never lose track of interrupted work.

Frontend Status

The Goal Status Card displays differentiated states:

Converged — Goal completed via convergence detection
Restarting (#N) — Goal is restarting via loop-on-pause (showing restart count)

Global Goal Tracking

Monitor all active goals from any page without switching contexts:

NavBar Badge — A real-time badge shows the number of active goals. Updates instantly via Server-Sent Events when a goal completes or dequeues.
Background Tasks Popover — Click the badge to see all active goals across all sessions: objective, status, tokens consumed, and elapsed time.
Quick Actions — Pause, resume, or cancel any goal directly from the popover. A toast confirms the action.
Navigate — “Go to session” button jumps directly to the goal’s chat for full detail.
OS Notifications — When a goal finishes (completes, fails, or gets paused), you receive a system notification even if the browser tab is in the background.

This works across all deployment modes — local WebUI, Tauri desktop app, and cloud-hosted sandboxes.

Dynamic Subgoals

During execution, you can add new objectives without interrupting the agent:

Open the active goal’s detail panel
Add a subgoal (e.g., “Also add unit tests for the new module”)
The subgoal is injected into the agent’s context with highest priority

Subgoals are included in the semantic judge’s completion criteria.

IM Slash Commands

Manage goals entirely from any IM channel (Slack, Feishu, Telegram, WhatsApp, etc.):

Command	Description
`/goal set <objective>`	Create a new goal
`/goal status`	View active goal status, constraints, and subgoals
`/goal pause`	Pause the active goal
`/goal resume`	Resume a paused goal
`/goal clear`	Cancel and clear the active goal
`/goal budget <amount>`	Add budget to the active goal
`/goal constraint <text>`	Add a hard constraint the agent must not violate
`/goal constraint`	View all current constraints
`/goal constraint clear`	Remove all constraints
`/subgoal add <text>`	Add a dynamic subgoal
`/subgoal list`	List all subgoals
`/subgoal remove <index>`	Remove a subgoal by index
`/subgoal clear`	Clear all subgoals

Constraints added via IM are injected into the agent’s prompt as “CONSTRAINTS (MUST NOT VIOLATE)” and enforced by the semantic judge during completion verification — identical behavior to GUI-defined constraints.

Objective Hot-Edit

Change the goal’s direction mid-execution:

Open the active goal’s detail panel
Edit the objective text
The change is injected as a steering message — the agent adjusts course without losing progress

Execution Summary

After completion, every goal produces a GoalExecutionSummary with:

Files modified (with diff links)
Token usage breakdown
Cost breakdown by model
Time elapsed
Turn count
Completion reason

This summary is available in the GUI and via API.

IM Completion Notification

When a Goal is initiated from an IM channel (via /goal set), the completion result is automatically pushed back to the original conversation thread — no polling required.

Feature	Details
Thread-precise delivery	Replies land in the exact IM thread where `/goal set` was issued
Localized messages	Notification language matches the user’s locale at goal creation time (en, zh-CN, ja, zh-TW)
Deeplink button	”Continue in browser” button opens the full Goal detail in WebUI
Success & failure coverage	Both completed and failed goals trigger a notification
Consistent with `/btw`	Uses the same delivery infrastructure as background task notifications

Example

Start a Goal in Feishu:

/goal set Analyze Q3 sales data and generate a summary report

Hours later, in the same Feishu thread:

✅ Goal completed: "Analyze Q3 sales data and generate a summary report"
8 turns · 31.2 min · 3 files changed
[Continue in browser]

Deliverable Bundle

When a goal completes and has produced 2 or more artifacts (documents, spreadsheets, presentations, etc.), Myrm automatically aggregates them into a Deliverable Bundle card:

Auto-Collection — All artifacts generated during the goal’s session are collected without any manual action
One-Click ZIP Download — Download the entire bundle as a single ZIP archive
Per-File Preview — Click any individual deliverable to open it in the Artifact Portal with format-aware rendering
Filename Deduplication — If multiple artifacts share the same name, unique identifiers are appended automatically

Clickable deliverable paths in chat

Beyond the Bundle card, when the agent cites deliverables with inline code in its reply, the WebUI renders them as clickable links:

`workspace/reports/brief.md` — workspace-relative path; one tap opens Artifact Portal preview
`@file_001` — harness short file ID (same alias the agent uses internally); clickable once the artifact SSE syncs

What you get: no copying paths into Finder or Explorer. OpenWorker Cowork expects [Title](artifact:path) markdown plus a separate Right Rail; Myrm reuses the existing Portal — click the path in chat.

Note: the frozen deliverable_discipline prompt block teaches agents to write files and cite paths; file creation auto-registers artifacts and SSE may include short_file_id.

Use Case: Full-Chain Office Delivery

Use the pre-built “Office Full-Chain Delivery” agent template to generate complete document suites in one conversation:

Select the “Office Full-Chain Delivery” agent from the agent selector
Describe your deliverables (e.g., “Prepare quarterly report: Excel data + PPT presentation + Word summary”)
The agent executes with Goal mode, maintaining data consistency across all documents
On completion, the Deliverable Bundle card appears with all files ready for download

API Access

Deliverables are also available via REST API:

GET /api/goals/{goal_id}/status — Returns deliverables array with artifact IDs and filenames
POST /api/files/download-bundle — Downloads multiple artifacts as a ZIP archive

Example Workflow

User: "Migrate the API from Express to Fastify"

Goal created:
  Objective: Migrate Express → Fastify
  Criteria: All existing tests pass, no API contract changes
  Constraints: Don't modify the database layer
  Budget: max_turns=50, max_usd=$10

Agent:
  Turn 1-3: Plans migration, identifies 12 affected files
  Turn 4-15: Rewrites route handlers
  Turn 16-20: Updates middleware
  Turn 21-25: Fixes failing tests
  Turn 26: All tests pass, semantic judge confirms completion
  
Goal COMPLETED — 26 turns, $3.47 spent

Project Milestones (Cross-Session Goals)

While Goals operate within a single session, Project Milestones span across sessions. They let you define strategic objectives for an entire project, and the agent automatically stays aware of them in every conversation.

How It Works

Create milestones in the sidebar panel (within a Project)
Agent auto-injects — ProjectRoadmapMiddleware injects a compact roadmap context (~100 tokens) into every conversation in that project
Track progress — Milestones link to Kanban boards for automatic progress calculation

Creating Milestones

In the sidebar, navigate to your project and find the Milestones section:

Click the + button to add a new milestone
Each milestone has a title, optional description, and acceptance criteria
Double-click a milestone title to rename it inline
Mark milestones as completed when objectives are met

Real-Time Progress Visualization

Each milestone displays a compact progress bar showing the completion rate of linked Kanban tasks:

A 3px progress bar appears below the title when the milestone has associated tasks
Task count is shown (e.g., “6/8”) — no manual calculation needed
Progress updates automatically when tasks are completed
The batch-progress API fetches all active milestone completion rates in a single request (no N+1 queries)

Automatic Context Injection

When you chat within a project that has milestones, the agent receives context like:

Project: Q3 Product Upgrade — Complete core feature iteration
Current Focus: Finish milestone system and ship to production

Active Milestones:
  - [active] MVP Release (criteria: All core APIs pass integration tests)
  - [active] Beta Launch

Completed: Technical Research

This happens automatically — no commands needed.

Assessment Import (One-Click Report → Tasks)

When your agent produces assessment reports or review documents (as artifacts), you can convert them into milestones and tasks in one click:

Expand the Milestone panel in the sidebar
Recent candidates appear automatically — the system probes each artifact to verify it contains importable tasks (semantic validation using the same parser as the import engine). Already-imported artifacts are automatically detected via the import ledger and shown as disabled.
Click a candidate to import, or type an artifact ID manually
Instant feedback — success shows a receipt (milestones + tasks created); failure shows a clear reason (e.g., “already imported”, “no actionable tasks”)

Key guarantees:

Idempotent — the same artifact version cannot be imported twice into the same project (immutable ledger)
Atomic — if import fails midway, all partially-created milestones/tasks are rolled back
Observable — import funnel metrics (attempts, successes, failures by reason and trigger) are tracked for product analytics
Value closure — the panel shows post-import task completion rate, so you can see the real impact of imported work

Goals vs Milestones

Aspect	Goal	Milestone
Scope	Single session	Cross-session (project-level)
Lifecycle	QUEUED → ACTIVE → COMPLETE	active → completed → archived
Execution	Agent executes autonomously	Strategic direction, manual completion
Budget	Yes (tokens, cost, turns, time)	No budget — purely organizational
Use case	”Migrate API to Fastify"	"Q3: Ship v2.0 to production”

​Goal Management

​Creating a Goal

​From the GUI

​From Chat

​Goal Lifecycle

​Budget Control

​Acceptance Criteria

​Advanced: Logical Consistency Verification

​Constraints

​14-Layer Dead-Loop Shield

​Judge Feedback Loop

​Per-Todo Checkpoint

​Kanban Goal Mode

​Enabling Goal Mode

​How It Works

​Why Use It

​Visual Indicators

​Budget & Safety

​Priority Queue

​Saved Agent Profile on Continuation

​Adaptive Convergence & Loop-on-Pause

​Convergence Detection

​Loop-on-Pause

​Resume Safety

​Judge Failure Circuit Breaker

​Server Restart Recovery

​Frontend Status

​Global Goal Tracking

​Dynamic Subgoals

​IM Slash Commands

​Objective Hot-Edit

​Execution Summary

​IM Completion Notification

​Example

​Deliverable Bundle

​Clickable deliverable paths in chat

​Use Case: Full-Chain Office Delivery

​API Access

​Example Workflow

​Project Milestones (Cross-Session Goals)

​How It Works

​Creating Milestones

​Real-Time Progress Visualization

​Automatic Context Injection

​Assessment Import (One-Click Report → Tasks)

​Goals vs Milestones

Goal Management

Creating a Goal

From the GUI

From Chat

Goal Lifecycle

Budget Control

Acceptance Criteria

Advanced: Logical Consistency Verification

Constraints

14-Layer Dead-Loop Shield

Judge Feedback Loop

Per-Todo Checkpoint

Kanban Goal Mode

Enabling Goal Mode

How It Works

Why Use It

Visual Indicators

Budget & Safety

Priority Queue

Saved Agent Profile on Continuation

Adaptive Convergence & Loop-on-Pause

Convergence Detection

Loop-on-Pause

Resume Safety

Judge Failure Circuit Breaker

Server Restart Recovery

Frontend Status

Global Goal Tracking

Dynamic Subgoals

IM Slash Commands

Objective Hot-Edit

Execution Summary

IM Completion Notification

Example

Deliverable Bundle

Clickable deliverable paths in chat

Use Case: Full-Chain Office Delivery

API Access

Example Workflow

Project Milestones (Cross-Session Goals)

How It Works

Creating Milestones

Real-Time Progress Visualization

Automatic Context Injection

Assessment Import (One-Click Report → Tasks)

Goals vs Milestones