[earakely-scale]

Stacked on #8934, which is stacked on #8877, #8875 and #8874. This branch contains all four. Review only c3d079754, 27617c37a, 079760fb7, 2c2a5bef7, bced17cf2, 31e4f8d7a, 11b1340ec, 57f04ffa1 and 59cdcf22a; the merge commits only bring the earlier PRs in. Once they merge, the diff shrinks to these.

Summary

An exported desktop app can now carry one task: a prompt for a computer-use agent, and declarative checks that grade the files the agent leaves in the app. An agent writes the prompt and the checks from the change the capture recorded. REA validates the task against the capture and keeps it only when its checks fail on the seed and all pass on the captured end state. The bundle then holds the task, a verifier that needs no model, and an eval that runs it.

The spec, plan and verification are in docs/specs/desktop-app-environments/tasks/, and the user guide is docs/desktop-application-tasks.md.

Problem and expected behavior

export-desktop-application gives a computer that runs the app on its seed, but nothing for an agent to do in it and nothing to grade. The change the user made during the capture is the natural task. But REA cannot turn it into a prompt: what the user meant is a judgment, and REA runs no model.

After this change:

• describe-desktop-application-task lays out the change: each owned file that differs between the capture's first and last version, with both views and the net change. It also drafts checks.
• An agent writes the prompt and keeps the checks that say what the user did.
• export-desktop-application --task task.json accepts the task only if it is a real task for this capture.

Change and scope

• Task file (src/domain/desktop/appTask.ts): {name, prompt, checks} with 1 to 32 checks of ten kinds:

  • file_present and file_absent;
  • lines_present, lines_absent and line_count (lines equal to exact or holding contains; equals, at_least or at_most);
  • value_equals and value_absent by JSON pointer;
  • row_present, row_absent and row_count on SQLite tables.

  Refused at parse time:

  • a file outside the home;
  • the empty pointer;
  • a value that looks like an ISO 8601 date and time;
  • the placeholder prompt.

• Evaluator (appTaskChecks.ts): evaluates the checks on the typed views the state view already produces.

  • An absent file reads as empty.
  • A file with no view fails every check except the presence checks.
  • A check decided by what a view leaves out fails when that view is truncated, as does value_equals of a whole object or array.
  • No regular expressions: a pattern run on agent-written text could stall the verifier, and the two evaluators would read some differently.

• Verifier (appTaskPython.ts): renders verify.py, the same evaluator in Python with the checks inlined.

  • It finds the app among the computer's child environments and calls its data/get under the run's control-token grant.
  • It raises when the app cannot be reached, so the run fails instead of scoring the agent.

• describe-desktop-application-task <capture> (new command): returns the application, its owned paths, the changed files with their net change (lines, values, keys, rows, or created, deleted, format, content, unreadable), and a draft task with suggested checks.

• export-desktop-application --task <file>:

  • The export evaluates the checks at the capture's first version of each file (the seed) and its last (the end state).
  • It refuses the task, naming the check, when every check passes on the seed or any check fails at the end. It also refuses a check outside the owned paths, a pointer into text or into namespaced XML, or a value naming the captured home.
  • A refused task writes no bundle.
  • A file present but not retained at the baseline counts as absent on the seed, since the computer starts without it.
  • An accepted task adds tasks/<name>.json, artifacts/<name>-check/verify.py and evals/<env>.toml, and the README describes the task and a solve-rate recipe.

• Not included:

  • running agents or measuring a solve rate (REA runs no model; the README and guide give the recipe);
  • more than one task per capture;
  • checks on anything but files the app's data/get serves.

Contract and boundary impact

• Semantic owner and earliest changed stage: a new describe_desktop_application_task operation (predicate type rea.desktop-application-task-draft), then the task stage of export_desktop_application.
• Contribution scope fit and linked maintainer decision: same approved desktop-environments work as feat(desktop): capture a Linux desktop application in use #8874.
• CLI and MCP/tool-catalog contract:
  • one new command, describe-desktop-application-task;
  • one new option on export-desktop-application, --task, given at most once (a second is refused);
  • the export result gains task.
• Provider, bridge, target-format, or platform compatibility: the bundle's task uses agentenv-framework 0.9.1431 task steps (deploy_env, deploy_agent, add_skills, start_computer_recording, prompt_agent, env_outcome_verifier, end_computer_recording).
• Evidence, artifact, provenance, or reconstruction contract: the draft is Evidence over the capture and its state view. The export's result names the task, its number of checks and the checks failing on the seed.
• Target selection, authority, upstream behavior, and cleanup details: unchanged. The task reads only the capture, and the verifier reads only the app's data/get.
• Generated metadata: the CLI reference and the docs navigation list the new command and guide.

Expected effects:

• Read existing files or captured data.
• Launch or attach to a process.
• Inject instrumentation or run scripts/code.
• Change process memory, registers, files, or configuration.
• Contact network services.
• Recover protected code or work around protections.
• Documentation or usability only; no target interaction.
• Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

• Tests added:

  • 68 checks covering every kind against views of every format: text, truncated text, JSON with numbers, booleans, arrays and escaped pointers, a key file, truncated XML, SQLite with truncated and unreadable tables, binary, a view error, and an absent file.
  • Each check is asserted for the TypeScript evaluator and for the rendered verify.py under python3 -I with a stub protocol client. The two agree on every result and description.
  • 19 task refusals, among them a leftover regex field.
  • Draft suggestions for text, a format rewrite, key files, SQLite rows, and created and deleted files. The draft also keeps a database whose rows changed under an unchanged hash (its -wal changed), and a file whose truncated views match while it changed. It leaves out a file with one version.
  • The export with a task, plus nine refusals, none of which writes a bundle. A task file with a byte-order mark is refused with the reader's own fix.

• Mousepad, captured fresh (~/Documents/todo.txt, "buy milk" added under "buy bread"): the draft listed the document and suggested lines_present "buy milk":

  {"name": "change", "prompt": "REPLACE: what the user asks to have done in the app, in their own words.",
   "checks": [{"id": "check-1", "kind": "lines_present", "file": "Documents/todo.txt", "lines": ["buy milk"]}]}

  A task with three checks (milk, bread, and one-milk counting exactly one "buy milk" line) was exported:

  {"name": "add-milk", "checks": 3, "failing_on_seed": ["milk", "one-milk"]}

  Tasks checking only "buy bread", or checking "buy eggs", were refused with no bundle written:

  • "Every check already passes on the seed, so the task would be done before the agent starts."
  • Check "check-1" fails on the captured end state: Documents/todo.txt has no line "buy eggs".

• LibreCAD (four holes added to a plate, which the save rewrote from DXF R12 to 2007): the draft suggested counts of SECTION, ENDSEC and CIRCLE. A task with CIRCLE equals 9 was exported: 5 on the seed and 9 at the end.

• Typora, captured fresh (a to-do "Buy trail snacks" and a table row "Sun | Lake swim" added to ~/Documents/trip.md): among about 25 changed files under .config/Typora, the draft suggested only the document's two new lines. A task checking both, with "- [ ] Book the cabin" kept, was exported with snacks and sunday failing on the seed. Tasks checking only the cabin, or a kayak to-do, were refused.

• In an agentenv computer (agentenv-framework 0.9.1431, local Docker, arm64, --no-emulate):

  • agent-env run --dry-run planned the eval's one task with Claude Code as the solver.
  • A model-free probe task (deploy_env, then the exported verifier) scored 0 on the seed. It recorded milk and one-milk false and bread true.
  • On the same computer, computer_click, computer_key and computer_type added "buy milk" in Mousepad and saved it. The exported verify.py, called under the control-token grant as the step calls it, then passed all three checks.
  • A second "buy milk" line failed only one-milk. After data/reset, the checks read as on the seed again.
  • Typora's bundle, which installs Typora from its vendor repository, ran the same way. Its probe scored 0 on the seed. The capture's input sequence, sent through the computer's tools, made all three checks pass, and data/reset restored the seed verdict.
  • Both sandboxes were torn down.

• Solve rate (the documented recipe, --agent claude-code --model anthropic/claude-sonnet-5-5, three runs per task on bundles re-exported from the final code):

  Task	Runs passed	Cost per run (USD)
  Mousepad add-milk	3 of 3	0.91, 0.39, 0.39
  Typora plan-sunday	3 of 3	0.77, 0.31, 0.43
  LibreCAD add-holes	3 of 3	0.81, 0.32, 0.34

  • Every run worked through the computer's input tools only, and passed every check. In LibreCAD, the agent typed circle commands into the app's command line.
  • The nine runs cost $4.67 in total, by Claude Code's own count.
  • Each task is one change made in one sitting, so Sonnet 5.5 solves all of them. They show the environments work end to end, not how hard a task can be.

• Recordings of the runs. These are the computer's own screen recordings (10 fps, cursor shown), with each run's segments joined and nothing else edited. Below is the first run of each task; the table links all nine.

  

  Task	MP4
  Mousepad add-milk	run 1, run 2, run 3
  Typora plan-sunday	run 1, run 2, run 3
  LibreCAD add-holes	run 1, run 2, run 3

• Remaining proof gaps:

  • The agentenv runs used the verify.py from before bced17cf2. That commit changed only line_count with contains and value_equals of whole values on truncated views, both covered by the cross-language tests.
  • SQLite and dconf checks were covered by synthetic views only.
  • The XML namespace refusal was covered by code review only.

For evidence-bearing changes:

• Observed, derived, and inferred claims remain distinguishable.
• Artifact identity, source provenance, and failed attempts remain preserved.
• Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

• npm run typecheck, lint, lint:typed, format:check, build:cached, knip, jscpd, docs:check, docs:build, verify:test-discovery and verify:architecture-guards passed. There are no lint diagnostics in the touched files.
• Desktop tests with the two Python boundary tests: 261 passed and 14 skipped on macOS, and 274 passed and 1 skipped in the Ubuntu 24.04 container.
• CLI boundary tests (cliInputSchemaRequired, cliToolCoverage, cliStartupImports) passed.
• The Mousepad, LibreCAD and Typora captures, exports and agentenv runs above.

The hand-written diff is about 1,300 lines of source, 1,400 of tests and fixtures, and 400 of docs. The task file, its evaluator, its Python rendering and the export's validation only make sense together, so this is kept as one PR.

Compatibility, safety, and release

• Breaking changes or migration steps: none. An export without --task is unchanged.
• Real Hopper/Ghidra, browser, or OS coverage: Ubuntu 24.04 arm64; Mousepad, LibreCAD and Typora; agentenv-framework 0.9.1431.
• Package or release metadata impact: none.
• Security, privacy, process, or containment review:
  • REA runs no model and no code the task author wrote. Checks are data, and verify.py is rendered from them with values inlined as JSON.
  • The verifier calls only the app's data/get, under the grant the run gives it.

Author readiness

Human owner: @earakely-scale

• I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
• I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
• I declare this PR ready for initial maintainer review.

Before merge

• This PR addresses a concrete problem or an agreed enhancement.
• Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
• The PR has one focused outcome and the title follows type(scope): outcome.
• Related issue is linked, or the reason for not linking one is stated above.
• Tests cover changed observable behavior and meaningful failure paths.
• Owning docs, contracts, and generated metadata are updated where needed.
• User-visible CLI/MCP changes include representative output.
• I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code

[greptile-apps]

Older captures expose passwords

The new credential scrub still returns raw repository.source when uri is null. Older supported captures can hold a username and password here when no sources entry matched. That password reaches export errors, or skipped and returned Evidence when another repository is usable. The no-repository error also prints raw installed.sources.

This violates the repository requirement to redact transport credentials. Normalize these older fields at the capture-reading boundary too.

How this was verified: Older source strings pass capture admission unchanged, and the raw fallback flows into export errors and Evidence without credential removal.

Context Used: AGENTS.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/domain/desktop/appExportInstall.ts
Line: 58-61

Comment:
**Older captures expose passwords**

The new credential scrub still returns raw `repository.source` when `uri` is null. Older supported captures can hold a username and password here when no sources entry matched. That password reaches export errors, or `skipped` and returned Evidence when another repository is usable. The no-repository error also prints raw `installed.sources`.

This violates the repository requirement to redact transport credentials. Normalize these older fields at the capture-reading boundary too.

**How this was verified:** Older source strings pass capture admission unchanged, and the raw fallback flows into export errors and Evidence without credential removal.

**Context Used:** AGENTS.md ([source](https://github.com/morluto/rea/blob/main/AGENTS.md))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Relative executables fail after export

resolveProgram now accepts an executable relative to the application's working folder, but export still launches the original argv. For an apt-installed app with Path=/opt/app and Exec=./app, with no extra arguments, capture succeeds. The exported launchCommand checks only arguments after the executable when deciding whether to restore that folder. It therefore runs ./app from the environment folder and never reaches ready.

Use the resolved executable for export, or account for a relative executable when restoring the working folder.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/desktop/LinuxApplicationInventory.ts
Line: 174-176

Comment:
**Relative executables fail after export**

`resolveProgram` now accepts an executable relative to the application's working folder, but export still launches the original `argv`. For an apt-installed app with `Path=/opt/app` and `Exec=./app`, with no extra arguments, capture succeeds. The exported `launchCommand` checks only arguments after the executable when deciding whether to restore that folder. It therefore runs `./app` from the environment folder and never reaches ready.

Use the resolved executable for export, or account for a relative executable when restoring the working folder.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[greptile-apps]

Snap apps become snapd

With /snap/bin/ on PATH, this join returns /snap/bin//firefox, which neither snap pattern in packageFromPath accepts. If the launcher is the standard symlink to the snapd executable, identifyPackage falls through to Debian package lookup and records snapd instead of the Firefox snap. Export can then install snapd and try to launch a missing app.

Keep the symlink-aware lookup, but make package detection accept equivalent separators and . segments without losing the snap launcher's identity.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/desktop/ProgramLookup.ts
Line: 29-32

Comment:
**Snap apps become `snapd`**

With `/snap/bin/` on `PATH`, this join returns `/snap/bin//firefox`, which neither snap pattern in `packageFromPath` accepts. If the launcher is the standard symlink to the snapd executable, `identifyPackage` falls through to Debian package lookup and records `snapd` instead of the Firefox snap. Export can then install `snapd` and try to launch a missing app.

Keep the symlink-aware lookup, but make package detection accept equivalent separators and `.` segments without losing the snap launcher's identity.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.