Development preview 0.1.12 · November 3, 2026
This manual covers the local Cohandry desktop application and its persistent project workspace. Examples use a small coding project called Task Garden. The public website manages signup and downloads; its login is separate from the model connections inside the app.
Cohandry coordinates AI roles around a project. You supply the project context, configure the team and its tools, give it a bounded objective, and review what it produces. A lead can create assignments for other agents when you explicitly give it that authority. Implementation agents can change project files through configured execution hosts. Reviewers inspect submissions and record decisions against a particular revision.
The local coordinator stores projects, assignments, messages, decisions and checkpoints. A worker is a process that carries out work on a configured computer. An agent is a role with instructions and a model connection; it is not itself a computer. One host may serve multiple roles, subject to concurrency and resource rules.
A useful first cycle is: describe → configure → assign → inspect → review → integrate. Begin with one small feature and a clear stopping point. Add automation after that cycle works.
Demo mode lets you learn the controls without calling models or executing tools. To implement real code, configure a real connection and a trusted file-capable worker. Merely choosing a software or game template does not install tools or grant access to an editor.
The current public Mac build targets Apple Silicon. Do not assume it is an Intel-native build.
Windows x64 is available from the website after email verification and a short project answer. Download the single Cohandry-Setup-VERSION-x64-COMMIT.exe installer and run it; you do not need to extract a ZIP. It installs for the current user and creates shortcuts and an uninstaller. The app's supporting files stay in its installation directory rather than a loose Downloads folder.
To update an installed Windows preview, quit Cohandry and run the newer installer over the existing installation. You normally do not uninstall first. Back up project records and working folders before upgrading; the installer preserves application data. Earlier portable previews are separate: close the old portable copy and use the installed shortcut afterward. Updates are announced in the app; installation is initiated by you.
Use Cohandry → Check for updates… or App settings → Application updates. Automatic checks run at startup and once daily while the app is running. You can turn automatic checks off and still check manually. The app contacts cohandry.com for public version metadata without sending project contents or signup credentials. Existing versions through 0.1.10 need one manual download to install the first checker-enabled release.
When a newer version is available for your platform, the header shows Update available. Open it to view release notes or download through the website's normal verification flow. Finish running work, back up project data and working folders, and quit before installing. The Windows installer refuses to proceed while Cohandry is running. Run the newer installer over the existing installation; app data is preserved. On Mac, quit and replace the app bundle. The preview is not Developer ID signed or notarized.
Checks use only releases promoted through the deployment pipeline. A failed network check does not interrupt your work; retry later. The installed version and last successful check appear in App settings. There is no automatic installation or forced restart. Read current release notes.
Developers can use the repository with the Node version in .node-version (currently 24.22.2):
npm ci
npm startEnd users should open the installed Cohandry desktop app. Its local service address is an internal implementation detail, not a separately offered browser edition. Developers working from source can use npm start; development-server instructions belong to the repository guide.
Pause new work, finish or inspect running operations, create a coordinator backup and back up working project folders. Quit Cohandry, replace the application, then reopen it. Inspect project and worker state before resuming. The app checks for update notifications; installation is initiated by you. Remote worker installations must be updated separately.
The desktop menu Cohandry → Open application data folder locates local state. Earlier Orqelune installations may reuse the older profile location for compatibility; the old folder name does not mean the app was not renamed. Do not delete or rename that data as part of a cosmetic cleanup.
| Area | Use it for |
|---|---|
| Projects | Create, search, open, archive and restore persistent projects. |
| Templates | Reusable teams, agent definitions and project starting packs. |
| Accounts & API keys | Reusable model authorization and provider keys. New-project defaults and backups are in App settings. |
| Help | Built-in help and supporting references. |
| Work, inside a project | Assignments, queue reasons, progress and owner attention. |
| Deliverables | Received files, evidence and previews. |
| Team | Agent responsibilities, hosts, tools and review authority. |
| Resources | Imported reference documents and shared project knowledge. |
| More | Setup, Conversation, Activity history, Automation, Checkpoints and Project settings. |
Some older guides call Projects the Coordinator, Resources Sources, and Deliverables Artifacts. Those terms describe the same underlying records. Some dialog labels still use the older terms.
At the project header, New work offers Team objective and Direct task. Start new work / Pause new work controls dispatch. Opening a project or viewing its history does not start assignments.
Help includes the quick start, complete manual and coding tutorial offline. Search by feature or task, use Open feature to navigate to the related screen, or choose Help with this screen from your current screen/dialog. Help opens separately from an unfinished form; Return to work preserves its entries. Feature navigation asks you to finish or close an existing form first. Online editions and the practice-kit download are linked explicitly.
Use the project selector to switch projects. Workstream, agent and status filters narrow the visible history; a filtered-out task has not been deleted. Refresh retrieves current coordinator state.
Enter each fact in the narrowest place where it belongs. A project describes the enduring purpose, an agent describes a reusable responsibility, and a task describes the work to perform now. Supporting documents belong in Resources. Success criteria explain how you will judge the result.
| Field | Enter | Task Garden example |
|---|---|---|
| Project name | Short recognizable name. | Task Garden |
| Project context / brief | Background, audience, overall outcome and constraints shared by assignments. | A small local task board for personal use. Keep data in the browser. Use the existing JavaScript app and avoid accounts or a backend for this prototype. |
| Agent name | A recognizable team member label. | Implementation agent |
| Responsibilities | Ongoing duties across assignments. | Implement scoped features, run relevant checks and submit measured changed files with a concise report. |
| Role label | Optional short role description. | Frontend developer |
| Additional guidance | Enduring instructions that add to responsibilities. | Preserve keyboard access; explain tradeoffs before adding a dependency. |
| Team objective | This milestone's outcome, delegation scope and stopping point. | Deliver the first approved add-task feature, have the reviewer inspect it, then stop before adding filters. |
| Task name | A short label for lists. | Add a task from the keyboard |
| Assignment / What should this agent do? | Concrete work, allowed scope and actions to avoid. | Implement adding a task with Enter. Trim whitespace and ignore empty input. Modify only the relevant UI and tests. Stop after submitting evidence. |
| Success criteria | Observable results and evidence needed for acceptance. | Enter adds one task; whitespace-only input adds none; existing behavior still passes tests; report changed files and test results. |
| Resource document | Longer reference material, supplied once. | PRODUCT-BRIEF.md or the feature acceptance specification. |
| Shared record key | Stable identifier for a decision or fact. | storage-policy |
| Shared record content | The decision and its scope/source. | Approved: browser-local storage for milestone 1. Source: product brief revision 1. |
| Workstream | A separate authorized area of work. | Frontend implementation |
| Workflow run input | The current subject and run-specific limits for a saved workflow. | Evaluate the add-task feature against acceptance criterion 1 only. |
| Execution folder | Existing absolute folder on the worker computer. | /Users/you/Projects/task-garden |
| Repository URL | HTTPS URL of the initialized GitHub repository. | https://github.com/YOUR-ACCOUNT/task-garden |
| Model ID | Exact identifier accepted by the selected provider. | Copy it from that provider's available model catalog; do not guess. |
Avoid duplication: put the no-backend constraint in project context, implementation standards in agent responsibilities, and the add-task requirement in the assignment. The task can refer to an imported specification instead of pasting its entire text. Put the pass/fail checks in success criteria, rather than repeating the assignment word for word.
Short placeholders are hints. Use the ? icon beside a field for its explanation and a detailed neutral-project example. Hover or focus the icon, or tap/click it; press Escape or click elsewhere to dismiss. These examples use a small Python task list or a website, never building Cohandry itself. Help content is not submitted; enter your own instructions in the field. Optional blank fields can be left blank. A blank override generally inherits the project setting; check the displayed connection summary.
Project context is copied into newly queued assignments. Editing it later does not rewrite an existing task or an active attempt. If a requirement changes, inspect existing assignments and create a deliberate correction or replacement.
If a setup stage fails after the project is saved, you can go back and edit its name, context or connection, then retry without creating a second project. Successful imports and repository connections are retained. An installed starting team and a connected repository are fixed during recovery; manage them in the saved project. Previously imported documents remain in Resources even if you change subsequent selections. Closing the wizard does not delete a project already created. If a network response is lost, inspect the project and Resources before retrying.
| Connection | Meaning |
|---|---|
| Demo | Simulated text; no model or project tool execution. |
| Account · ChatGPT | Authorized local ChatGPT account and available model access. |
| Provider API | A separately billed key for OpenAI, Anthropic, xAI or OpenRouter. |
| Project tool adapter | A locally configured custom execution harness, for advanced host setups. |
In Accounts & API keys, authorize the intended account or select an API provider, enter its key and choose Save key (or Update key). You can also save the key beside the model in the project connection editor. Save or clear a typed key before saving the project connection. Keys for different providers remain independent. Account authorization alone does not prove that a model can respond; run the connection test or a small task.
Choose defaults for new projects and save them. Existing projects retain their own settings: use Project settings → Connection & billing to change those. An agent can inherit the project default or override its connection/provider/model in Team → Configure.
Direct providers use their own native model IDs. OpenRouter uses its routed catalog IDs. When changing providers, supply a model available from the new provider. An override does not reliably carry a different provider's model choice with it. Tool work also requires a tool-capable model and a configured worker.
Keys entered in local settings stay in coordinator process memory until restart. They are not included in workspace exports or ordinary project records. A blank key field preserves a configured key; Clear session key removes the selected provider's in-memory key. Host environment variables can supply persistent host-managed keys. Clearing an in-memory key does not remove a host environment key.
ChatGPT credentials are stored locally by the authorization runtime. Do not put credentials in objectives, documents, terminal arguments or bug reports. Model requests can contain relevant project context and tool results; choose what you import and submit accordingly.
Fallback from account usage limits to a provider API is opt-in. Configure the fallback provider/model and a project-wide daily request cap. It applies only to the supported account quota-exhaustion error, not to arbitrary network, permission or authentication failures. Agents can inherit, allow or disable fallback under the project cap.
The cap counts fallback requests, not dollars. Direct API-mode requests are separately billed and are not covered by that fallback request count. A failed reserved request can still count toward the cap. Use provider-side spending controls for monetary limits. Begin with a small task before a large workflow.
Open Team → Configure for each project agent.
A simple coding team has a lead that plans and assigns, an implementation agent that changes code, and a reviewer that checks the submission. A lead's prose saying it delegated work is not evidence that an assignment exists; look for real child tasks in Work.
Use the same optional Shared resource lock for agents sharing an editor or scene. This serializes participating tasks within that project's resource scope; it does not lock out your editor or other programs. Required capability names must match the execution host's capabilities.
Archiving an agent retains history. A running agent cannot be archived; work queued for an unavailable agent waits. Review authority and assignment authority are separate permissions. Giving a model a goal does not grant either automatically.
Configured file workers support bounded listing, text reads, hash-checked text writes and measured evidence publishing. Common private/configuration paths are excluded. A folder boundary in the file tools does not turn an allowed external tool into an operating-system sandbox.
MCP servers give workers specific tools. Unity, Blender and other applications need an installed server/harness on the execution computer, an available project, and an explicit allowlist. Selecting a game pack does not install those tools. A connected GitHub repository does not automatically give an agent VS Code control.
Server executable paths, arguments, working directories and tool permissions are host configuration. Do not paste them into an objective as a substitute for configuration. Start with a read-only tool test. Some editors bind to one open project; automatic Git task-worktree mode currently rejects fixed Unity/Blender MCP sessions that cannot safely follow the isolated path.
Pair a worker in the project and store the once-shown worker token privately on that host. Configure the coordinator URL and token, then start the worker process. A registered host is offline until its process connects. Revocation invalidates its access and leases.
Remote workers connect outward. Configure a private network or HTTPS owner/worker gateway for cross-machine use; the default local service is loopback-only. Keep one authoritative coordinator database. Do not run two coordinators against the same live database or synchronize an active SQLite database through a shared drive.
Advanced worker configuration and protocol details are in COORDINATOR-GUIDE.md and AGENT-RUNTIME.md. Remote updates and local tool installation remain the host owner's responsibility.
Import supported text documents in Resources. One import supports up to 50 documents, each at most 30,000 characters. Supported text sources include Markdown, plain text, JSON, CSV, C# and Python. PDF/Word extraction is not included; supply a text version or split a long document into named sections.
Use Link repository files to browse a GitHub repository and select supported text paths. Each saved Resource identifies its repository, branch, path, exact commit and content fingerprint. It is a snapshot, rather than a live file. GitHub CLI must be authenticated on the coordinator with read access to that repository; a working clone is unnecessary for documentation-only access.
For a linked Resource, Check for updates reads its tracked branch without changing the saved snapshot. If content changed, review the new content and commit, then explicitly Refresh Resource. Refresh preserves the previous revision and applies to future assignments; it does not rewrite existing attempt context. Linked snapshots cannot be manually edited as ordinary notes. Uploads and ordinary project notes remain editable. Symlinks, hidden paths, oversized and non-text files are not imported; very large or incomplete repository trees are rejected.
Resources are references. Use a versioned shared record for an approved decision, naming the source and revision that controls it. For example, import a product brief once, then record that milestone 1 uses local storage and excludes accounts. Editing a record preserves history; it does not silently rewrite prior attempt context.
Create workstreams for areas such as frontend, tests and documentation. Give each an authorized scope and stopping point. Workstreams separate histories and agent checkpoints; they do not grant new filesystem permissions or automatically create Git branches.
Context is bounded. The worker may receive selected records, relevant source sections, prior outputs and checkpoints rather than every document in full. Keep authoritative direction concise and reference large artifacts by path/commit. If a source conflicts with the current approved scope, resolve it explicitly before proceeding.
Use New work → Team objective, select the lead and workstream, and enter a bounded milestone. Example:
Implement only Task Garden's first add-task feature from the imported acceptance specification. Delegate implementation to the configured developer and require the configured reviewer to inspect the submitted files and test evidence. Ask me if requirements conflict. Stop after the first approved submission; do not add filters, publish or begin the next milestone.
The lead can create real assignments only within its configured authority. Configure downstream reviewers before dispatch. A good objective names the outcome, constraints, deliverables, evidence, reviewer and stopping point.
Use New work → Direct task when one agent should perform one assignment. Select the agent, enter a short task name, assignment and success criteria. Choose relevant dependencies, workstream and review/evidence options. Reference the resource that defines the requirement.
A text planning task can run without file tools. A task that says “implement” needs a real file-capable worker. Demo output cannot demonstrate that code was changed.
Choose Start new work when configuration is ready. A queued task starts only when its agent, host, connection, dependencies and resource locks permit it. Read the queue explanation rather than repeatedly creating new copies.
Sequential assignments wait for their prerequisites. Independent parallel work should edit separate areas or use suitable isolated workspaces. A reviewed Git submission can still block dependent tasks until its integration is verified.
The Work view shows what is running, what should happen next and what needs your attention. Inspect a task for its assignment, success criteria, saved project context, result, evidence, command activity and history.
| State | What to do |
|---|---|
| Queued | Read the waiting reason: pause, dependencies, offline host, permissions or resource lock. |
| Running | Follow reported activity; inspect commands and messages as needed. |
| Review | Inspect the exact submission; complete the required review stage. |
| Completed | Read the accepted result; verify Git integration separately when applicable. |
| Needs attention | Inspect the error, recorded actions and external effects before recovery. |
| Rejected / changes requested | Read feedback and follow the correction assignment or deliberate retry path. |
| Cancelled | Check whether external work already occurred before starting replacement work. |
Use Message an agent or a task's message control to ask for an update, provide feedback or clarify instructions. Choose the recipient and optionally the assignment. Messages persist with delivery states such as Queued, Received by executor, Replied and Reply failed.
Received means the executor accepted a message, not that the model has already obeyed it. Workers receive updates at supported model-turn boundaries; a message cannot retract an external operation already sent. Separate read-only replies use saved project state and can incur model usage. Use task controls to cancel or approve; a message is not a substitute.
Answer blocking owner questions in the project's attention/question controls. An answer does not grant new tool permissions. Use workstream and agent filters to find a specific conversation. Activity history records durable actions rather than private model reasoning.
Open Deliverables and inspect the relevant task submission. Received artifacts include measured paths, byte counts and SHA-256 hashes. Compare actual files and previews with the success criteria. For code, inspect the diff and test evidence; a confident report alone is insufficient.
Text previews and supported images can be inspected directly. Other binary files require an appropriate external viewer or exported preview. A model cannot establish the visual quality of a Blender scene merely by reading its filename.
Approval is bound to a revision and, for measured work, its evidence digest. Later external edits need fresh measurement. Current transfer limits are 64 files and 128 MB per assignment, with 32 MB per file. Model inspection has smaller limits: complete UTF-8 text up to 40 KB; images up to 1 MB each, with bounded inspection counts. Supply focused evidence when a project is larger.
Policies may require an authorized reviewer, the owner, or reviewers followed by the owner. All required reviewers must approve the current revision. An agent-only policy does not expose manual approval as a bypass. Approve revision accepts that submission; Request changes should state concrete failed criteria and desired corrections. A completed review assignment is not itself proof that a decision was recorded.
A correction can create a separate assignment. Follow the linked correction rather than approving the rejected ancestor. A dependent task waits until its configured approval and integration gates pass. Review approval does not automatically merge a GitHub pull request or publish a release.
Create a GitHub repository for Task Garden, initialize it with a commit, and place the starter application in it. Use the downloadable tutorial for the full exercise. On the coordinator, install and authenticate GitHub CLI (gh) with access to that repository. On execution hosts, clone the same repository and verify Git authentication for push.
Connect the repository from the new-project wizard or Project settings → Repository actions. Connect repository verifies access and updates its connection status immediately. Use Check connection for an optional later recheck. Saved repository metadata or a previously successful check does not establish current access. The repository card identifies the base branch and last verification.
The worker fetches the base, prepares a task branch and isolated worktree, performs file work there, measures evidence, commits the submitted files and pushes the submission branch. Dirty interrupted work stops for inspection. Git worktrees isolate checkouts, not the host's operating-system privileges.
This configuration authorizes task-branch work and push. PR publication and merging remain separate owner actions. Fixed editor/MCP sessions that cannot follow a task worktree are not supported in this automatic mode.
Cohandry's merge control checks the expected head, PR readiness, conflicts, review state and successful CI/check evidence. It does not bypass repository protections. A moving base or substantive conflict needs a deliberate correction. It does not force-push to erase the problem.
While dispatch is active, bounded monitoring refreshes approved published submissions and verifies integration. It does not automatically merge or create corrections. Squash merges need the recorded PR to establish the integrated commit. Keep the original PR history for traceability.
An application-project Git workflow and Cohandry's own product release pipelines are different layers: this section describes your project; the separate Repository and Pipeline Guide describes releasing Cohandry itself.
Enable project commands on a trusted managed host under Team & tools → Command permissions. Existing hosts keep commands disabled until deliberately enabled. Select Request approval for every command and save when no task is running on that host.
When an agent requests a command, inspect its executable, argument list, directory, purpose and timeout in Inspect task → Console / Checks. Choose Approve once or Deny. Approval is scoped to that task execution and expires after five minutes. A denial returns information to the agent; it is not an approval of an alternate command.
Output streams to the task activity and records an exit status. Failed checks can be returned to the agent for a correction and rerun. Cancel command targets the running process tree. A stopped connection or worker crash can leave uncertain effects; inspect before replaying it.
Commands run on the assigned machine using that account's permissions. Shell syntax is not implicitly interpreted in an executable/argument-array request. Explicit shells need their own reviewed command. Windows .cmd/.bat wrappers are not directly launched by the command tool; npm may need Node plus its npm CLI script path, or a deliberately approved shell.
Commands have 1-second to 10-minute timeouts, up to 40 records per task and one active command per execution. Captured output is bounded at 1 MiB per command, with smaller UI/model excerpts. Truncation is disclosed. Unresolved commands block completion. Subsequent modifications can mark earlier checks stale; rerun relevant tests on final files.
Open Inspect task → Owner shell → Start shell. The task needs a trusted locally managed host and a project folder. A Git task opens its existing task worktree; it must already exist. Remote/manual hosts and the remote owner gateway are not supported by this shell.
Check the displayed folder and shell before starting. Mac uses zsh without user startup files. Windows uses Command Prompt (cmd.exe /d), so use cmd syntax rather than PowerShell syntax.
Type commands, use arrow keys and Tab, paste text, and interrupt foreground commands with Ctrl-C. The terminal uses a real PTY and resizes with the panel. Switching task tabs preserves the session and unsent owner-message draft. Choose Stop to end it. Closing the task dialog, navigating away or quitting ends it; loss of browser polling expires it after approximately two minutes. It is not a persistent background dev-server manager.
This shell is for you. Its keystrokes are not sent to the model, and opening it does not approve agent commands. Stop/pause competing work before editing the same files. Shell start/exit marks task checks potentially stale; rerun checks and republish measured evidence after your changes.
The shell runs with your account privileges and can change directories, access the network and invoke installed programs. Cohandry filters inherited environment variables, but programs can still access account files and their own credentials. Cohandry records start/exit events rather than shell input/output; other programs may keep their own history. Up to four sessions are supported, with bounded in-memory output.
Automation rules respond to future project events, such as a worker submission needing review or a rejection requiring correction. Configure the target agent, event filters and generation/firing limits. Review authority must still be explicitly granted. Rules do not make a future project stage approved just because a document mentions it.
Rules deduplicate handled events and bound chains. If dispatch fails, repair the target or permissions and use the retry control. Do not create repeated copies of the same rule to get past an error.
Checkpoints summarize completed work, decisions, next steps and artifact references for an agent/workstream. Start fresh session preserves the checkpoint and increments the session generation; a running agent cannot rotate its session. A checkpoint is a summary, not an unlimited provider conversation or hidden reasoning archive.
The system bounds assignments, generations, model turns, tool calls, runtime and context. Current root coordination limits include 40 child assignments, 12 generations and 100 aggregate model turns. These prevent runaway loops; they are not a dollar budget. Reaching a limit means inspect and deliberately scope the next stage.
Use Project settings → Slack to configure a dedicated Slack app with Socket Mode, a bot token, app-level token, channel and allowed approver member IDs. The repository's integrations/slack-manifest.json and SLACK-SETUP.md supply the detailed setup. Enter tokens only in the credential fields.
Leave notifications disabled until the route and authorized members are correct. Enabling sends project task names, statuses and task links; it does not automatically upload all project files. Use a dashboard URL reachable by your devices. A localhost link points to the device opening it.
Slack actions are checked against the configured user, channel, task revision, review policy and evidence. Old or unauthorized actions cannot approve current work. Test with a synthetic task before relying on it. Live delivery with your workspace requires validation even though mocked protocol tests pass. Disconnect clears locally stored tokens; revoke the Slack app separately if necessary.
Templates are reusable definitions, not persistent project history. Create/edit agent templates with reusable duties, then arrange team tasks, expected outputs, ordering and review gates. Sequential tasks receive prior results; independent parallel tasks begin with their own instructions and the shared input. Use run input for the current subject rather than rewriting fixed template instructions.
Launching a team into a selected project queues persistent work there. Legacy template-run history may still appear separately; it is not the persistent project history.
Template JSON exports contain reusable templates, legacy runs and saved defaults. Export before importing a replacement. Importing replaces that template data, not persistent projects. Keys are excluded. Use the coordinator backup for project records and history, and back up working folders separately.
Standalone Python workflow export uses Python 3.10+ and OpenRouter via an environment key. It is a separate terminal runner, not an export of every coordinator feature. Direct-provider export is blocked instead of silently rerouting providers. It does not carry credentials or recreate project files, workers, the coordinator database or all tool integrations.
| Information | Backup method |
|---|---|
| Persistent coordinator projects/history | App settings backup control, or the project settings shortcut to backups. Keep the SQLite backup, adjacent manifest, and its .artifacts/.commands sidecar folders together. |
| Working repositories and assets | Git plus a separate file/asset backup. A coordinator backup is not a clone of the working project. |
| Host configuration, journals and credentials | Private host backup under your control. Do not share it as a public app/tutorial package. |
The coordinator uses SQLite's backup API, not a casual copy of an active database. Backups are placed under the coordinator data directory's backups folder and include an integrity/hash manifest. Preserve the entire backup set, including the adjacent .artifacts and .commands directories when present; the manifest validates their contents during restore. Current coordinator backup handling also captures submitted artifacts and command-log sidecars; worker journals and original project folders require separate handling. Template JSON exports are a separate backup for templates and legacy runs.
Advanced restore uses the source CLI:
node scripts/backup.mjs restore /absolute/path/to/backup.sqlite.json /absolute/path/to/new-dataThe destination must not exist. The tool verifies the backup, then applies safe defaults: projects paused, previous workers revoked, unfinished work marked for attention. Stop old coordinators/workers before switching COHANDRY_DATA_DIR to the restored folder. Re-pair workers, restore project files/journals and reconnect credentials as needed. Do not run the old and restored coordinators as competing authorities.
Open the task's Recover interrupted run action. Inspect recorded operations, submitted files, pending tool calls and active child tasks. Inspect external files/editors/repositories too: a missing result does not prove an operation never happened. Resolve active child tasks before replaying a lead. Enter a recovery note and confirm only after checking that retry will not duplicate effects.
For paired workers, owner-confirmed recovery authorizes only the next attempt on that task and host. The prior execution journal is archived before new work starts; old tool calls are not replayed. Resolve pending or running commands before retrying. Provider failures show an application-authored diagnostic, including the upstream HTTP status when available; private provider response bodies are never displayed.
A recovery action records the decision and queues a retry; a paused project stays paused. Runtime journals can require separate host inspection. Creating another task is not a safe shortcut around an unresolved external operation.
Pause stops new claims while already running work may finish. Cancel/stop does not undo accepted model calls or external changes. Archive requires no running tasks, preserves history and stops new work. Restoring an archived project leaves it paused.
| Symptom | Check |
|---|---|
| Task stays queued | Dispatch pause, dependencies, assigned agent enabled, host online, capabilities and resource locks; read its queue explanation. |
| Task says it changed files but no files exist | Demo/text-only route, actual execution host and evidence transfer. Inspect measured deliverables, not just prose. |
| API key connected but task fails | Selected provider/model, current account access, host environment vs in-memory key, tool capability and actual small-task result. |
| Model key disappears after restart | In-memory keys are intentionally session-scoped; reconnect or configure the host environment privately. |
| New default does not affect a project | Existing projects and agent overrides keep their settings. Open Connection & billing and agent Configure. |
| Required review never starts | Reviewer enabled, correct review authority, connection and dispatch status; repair then Retry review dispatch. |
| Owner approval unavailable | The policy may require reviewer approval first or require agent-only approval. Inspect the current revision and policy. |
| Approved Git task still blocks the next task | Approval and base-branch integration differ. Refresh PR delivery and verify merged submission. |
| Git task stops on dirty/conflicting files | Inspect its worktree and external changes. Do not discard or force-push simply to clear the error. |
| Owner shell unavailable | Trusted local managed host, configured folder, existing Git worktree and current task scope. Remote gateway is unsupported. |
| Tests passed before an owner edit | They may now be stale. Rerun checks and remeasure the submitted files. |
| App fails to start after extraction | Confirm complete extraction, correct platform/architecture and port availability; use the exact error in a private bug report. |
| Data seems missing | Check app/profile/address and selected project/filters. Inspect the application data folder before deleting or recreating anything. |
When reporting a bug, include app version, operating system/architecture, the action attempted, expected/actual result and reproducible steps. Add task/revision and a sanitized screenshot when useful. Exclude API keys, authorization URLs/tokens, private source contents and raw databases unless you deliberately choose a private support transfer.
This manual is based on the current source and native CI results. Some older supporting documents contain historical verification notes; the current release has passed native Mac and Windows CI, while live provider accounts, individual MCP servers, remote hosts and real project outcomes still need validation in your installation.