Running Tasks in the Desktop App

Manual mode: write a task directly#

Manual mode means entering an individual request in the command bar. Enactive still plans and executes the request; “manual” describes how you define and supervise the task.

Launch procedure#

1. Select the workspace. Verify the actual folder, especially when switching projects. Autonomy, worker selection, and staging preferences follow the workspace.
2. Choose a worker. Use Developer for implementation and tests, Reviewer for read-only investigation, Writer for documentation, and Ops for command-oriented diagnostics.
3. Set autonomy. Choose the level appropriate to the tools you expect to allow automatically.
4. Choose whether to stage changes. This applies to supported built-in file operations, independently of the autonomy slider.
5. Describe the outcome. Include the problem, scope, restrictions, and a way to check completion.
6. Press Run or Enter. Watch Execution and respond to decision cards when needed.
7. Inspect the result. Read the terminal outcome, review/check results, changed files, and any failures or denied operations.

Command-bar shortcuts#

Example: a focused implementation request#

Fix the failure when an empty search query is submitted.

Scope: the search service and its existing tests.
First inspect the current behavior, then make the smallest useful change.
Preserve the public API. Do not commit or push.
Run the relevant tests and report the command and result.

A test command written in a manual prompt instructs the worker. It does not create a separate deterministic success criterion in the host. Use a template with SuccessCriteria when you want the engine to run that check independently at the end.

Autonomy and approval#

The effective level is narrowed by the worker's level and any template ceiling. A worker's tool allowlist is a separate gate. Increasing autonomy cannot make an unlisted tool available to that worker.

An above-level action generally asks for one-off approval; the level is not the same as an absolute deny. A template's explicit Deny entry is absolute in the permission engine. The Suggest label also does not turn on staging: use Stage changes explicitly when you want a diff/apply workflow.

Decision cards#

Read the full action details. The card can offer a one-time approval, a session approval, or a remembered workspace approval for eligible tools. Remembered approvals are scoped to tool names, not a promise that only one particular command string will ever run.

Workspace approvals are stored in %APPDATA%\Enactive\permissions.json, keyed by workspace identity. The legacy <workspace>\.enactive\permissions.json is ignored. These desktop approvals are not imported by the current console or background decision handlers.

An MCP server can require approval for every call; those calls cannot be silently authorized through a remembered decision.

Launch a task from Templates#

1. Select the intended workspace and autonomy level.
2. Open Templates from the main window.
3. Select an entry and inspect its origin: built-in, global, or this workspace.
4. Fill the generated parameter form. Required/type errors appear before Run becomes available.
5. Read the goal and summary of restrictions, checks, and limits.
6. Press Run. The library resolves the template and starts a foreground task.

A template's WorkerId, when provided and recognized, overrides the role picker. If the template does not specify a worker, the desktop uses the selected worker. An unknown worker ID currently falls back to the host's default worker; it is not a launch validation error. Keep IDs synchronized with Team settings.

The resolved specification is recorded with the run. Editing the template later does not rewrite that historical specification.

Current limitation: the template's displayed “reviewed”/“not reviewed” metadata comes from ReviewRequired, but runtime Review is controlled by the phase binding. Configure the Review model explicitly; the template flag neither enforces nor disables it.

See Templates for authoring and scope behavior.

Staging, applying, and rejecting files#

With Stage changes enabled, supported built-in file writes become text proposals. In Artifacts, choose Diff to inspect a proposal, then Apply or Reject.

Staging is not an isolated checkout or an all-effects transaction:

• It represents text changes; operations requiring deletion or binary content may be refused.
• Shell commands and MCP tools can change real files outside staging.
• A shell build/check reads the actual filesystem and may not see unapplied proposed edits.
• Background launches with staging enabled are refused.

Use staging for document or file-edit review. For an implementation task requiring builds against changed files, account for the fact that shell verification needs those changes on disk.

With staging off, built-in writes go directly to the workspace. The artifact journal supports scoped revert/undo for tracked writes. If another step or the user changed the file afterward, revert reports the conflict instead of overwriting the newer content.

Read the execution screen#

The Routing panel is especially useful when a local worker seems unexpectedly expensive: complex steps may have been sent to Execute heavy.

Background mode#

Run in background starts command-bar work inside the desktop process and frees the foreground interface. Results and declined decisions are recorded in the workspace Inbox.

If a tool requires a decision, the background handler declines it and records the need for approval. Re-run interactively to approve; this is not a suspended conversation waiting for an Inbox answer.

Background work depends on the desktop process remaining alive. Closing to the tray keeps it alive; exiting the application ends that process. Background mode is not a durable scheduler.

The template library currently launches foreground runs. Copying a resolved goal into the command bar and using background mode does not preserve the template's checks, limits, or frozen specification.

Stop and inspect partial work#

Use Stop to request cancellation of a foreground run. Cancellation does not imply automatic rollback of every previous effect. Inspect artifacts and the final recorded events before restarting.

Retry versus Run again#

Both actions create a new attempt under the same task identity. Neither resumes execution at the last successful step.

Retry is not a bit-for-bit replay: the frozen template specification does not freeze provider settings or workspace contents. It reuses the stored permission policy, so inspect the old specification when your policy expectations have changed.

If Run again encounters a new required parameter or a now-invalid value, it reports the problem and directs you to fill the template form again. Deleting a template does not erase previous run snapshots.

Implementation references#

• Launch, approvals, staging, and replay actions
• Template launch form
• Approval persistence
• Permission engine
• Background decision handler