@frankzhang2026/opencode-android-orchestrator 0.10.0 → 1.0.1

package/docs/MIGRATION.md

@@ -1,7 +1,7 @@
 # Migration guide
 
 This guide covers migration to
-`@frankzhang2026/opencode-android-orchestrator@0.10.0`. Pin the exact version and
+`@frankzhang2026/opencode-android-orchestrator@1.0.1`. Pin the exact version and
 prove the migration in a disposable clone before changing a long-lived
 repository.
 
@@ -9,13 +9,14 @@ repository.
 
 | Current state | Correct command after release | Important distinction |
 | --- | --- | --- |
-| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@0.10.0 init .` | Normal new installation; all runtime-detected Android modules and registered debug verification tasks are discovered automatically. |
+| No orchestrator files or manifest | `npx @frankzhang2026/opencode-android-orchestrator@1.0.1 init .` | Normal new installation; all runtime-detected Android modules and registered debug verification tasks are discovered automatically. |
 | Published `0.1.0` scaffold only | Remove any project-local `@0.1.0` plugin reference after review, then run `init`. | `0.1.0` did not create a usable managed installation and cannot be upgraded. |
-| `0.2.0` through `0.9.0` manifest-managed installation with intact managed/backup content | Run the `0.10.0` `upgrade`; add `--refresh-gradle-discovery` when generated module/task lists are incomplete. | Refresh replaces all derived module metadata, source paths, protected build files, and task allowlists from one Gradle runtime snapshot. Module scope, operator policies, user-owned AGENTS content, and an existing commit-prefix sidecar remain preserved. |
+| `0.2.0` through `0.10.0` manifest-managed installation with intact managed/backup content | Run the `1.0.0` `upgrade`; add `--refresh-gradle-discovery` when generated module/task lists are incomplete. | Refresh replaces all derived module metadata, source paths, protected build files, and task allowlists from one Gradle runtime snapshot. Module scope, operator policies, user-owned AGENTS content, and an existing commit-prefix sidecar remain preserved. |
+| Healthy `1.0.0` installation | Stop the queue service, finish or abort retained workspaces, then run the fixed `1.0.1` `upgrade`. | Pending inbox contracts remain durable. Restart OpenCode so Planner loads the bounded snapshot actions. |
 | Manually copied V3 files, no `.automation-plugin/manifest.json` | Finish active tasks, preserve historical evidence separately, then run `init`. | Exact files can be reused; differing managed files fail as conflicts. |
 | Healthy older manifest-managed installation | Run `doctor`, then the fixed target version's `upgrade`. | `upgrade` requires a valid installed manifest and intact original backups. |
 | Healthy current-version manifest | Run `doctor`; repeated `init` or same-version `upgrade` is verification-only and byte-idempotent. | Do not reinstall or delete the manifest. |
-| Damaged manifest, ordinary managed-content drift, or damaged backup content | Stop and investigate. | `init` and `upgrade` intentionally refuse to overwrite this state. AGENTS content outside its managed block and Unix-mode drift are handled by `0.10.0 upgrade`. |
+| Damaged manifest, ordinary managed-content drift, or damaged backup content | Stop and investigate. | `init` and `upgrade` intentionally refuse to overwrite this state. AGENTS content outside its managed block and Unix-mode drift are handled by `1.0.0 upgrade`. |
 
 `uninstall` is not an upgrade shortcut. It restores verified pre-install files,
 removes unchanged plugin-created files, and retains drift for manual review.
@@ -35,7 +36,7 @@ removes unchanged plugin-created files, and retains drift for manual review.
    support bundle.
 5. If a managed manifest already exists, the installed version's doctor may be
    used to collect read-only evidence. A mode warning/failure or an AGENTS
-   content mismatch does not by itself prevent `0.10.0 upgrade`; the target
+   content mismatch does not by itself prevent `1.0.0 upgrade`; the target
    upgrade performs its own content-safe checks. Do not edit manifest hashes to
    make doctor pass.
 6. Prove the migration in a disposable clone or temporary Android fixture
@@ -50,14 +51,14 @@ scaffold, not as an older managed installation.
 If the project OpenCode configuration contains an exact
 `@frankzhang2026/opencode-android-orchestrator@0.1.0` entry, save the file and
 remove only that obsolete entry in a reviewed Git change before running
-`0.10.0 init`. The merger deliberately rejects a different version of the same
+`1.0.0 init`. The merger deliberately rejects a different version of the same
 managed package; it will not silently replace the reference. A global npm
 installation of `0.1.0` alone does not require project-file cleanup.
 
 After release, initialize with the fixed version:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.10.0 init .
+npx @frankzhang2026/opencode-android-orchestrator@1.0.1 init .
 ```
 
 New installations default to all-module scope, so multiple application modules
@@ -105,7 +106,7 @@ Use the lifecycle command selected by the active manifest:
 
 ```sh
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@0.10.0 upgrade . --json
+  @frankzhang2026/opencode-android-orchestrator@1.0.1 upgrade . --json
 ```
 
 The command-level Registry option is useful when a company-wide npm Registry
@@ -135,7 +136,7 @@ computed includes dynamically or a company convention plugin applied
 
 ```sh
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@0.10.0 upgrade . \
+  @frankzhang2026/opencode-android-orchestrator@1.0.1 upgrade . \
   --refresh-gradle-discovery --json
 ```
 
@@ -146,7 +147,7 @@ task report. The resulting module/path/task configuration is written through
 the normal verified upgrade transaction. Omit the flag when the installed task
 matrix was intentionally supplied with `--gradle-verification-config` and must
 remain unchanged. An explicit refresh may be rerun on an already installed
-`0.10.0` after the Gradle module graph changes; if its generated resources are
+`1.0.0` after the Gradle module graph changes; if its generated resources are
 unchanged, the operation remains byte-idempotent.
 
 Upgrade also preserves an installed `longCommandTimeoutMs`. Installations from
@@ -194,12 +195,32 @@ The command refuses:
 Do not repair those conditions by editing the manifest or its hashes. Diagnose
 the source of drift and use the recorded recovery data.
 
+## Moving to the durable 1.0.0 queue
+
+Finish or explicitly abort legacy active tasks before upgrading. For an existing
+1.0.0 installation, stop its background service and complete/abort retained
+workspaces first. The upgrade lock shares queue arbitration so execution cannot
+start while resources are being replaced. Pending inbox contracts remain in the
+Git common directory through upgrade and uninstall; legacy on-disk contracts
+are not silently approved or imported.
+
+Schema V6 preserves the selected workspace strategy and defaults missing commit
+policy to `humanApproval`. Old contract approvals never acquire `autoCommit`
+from a changed global default. Queue execution requires full unit tests enabled;
+a migrated `unitTestsEnabled: false` remains preserved but blocks queue
+consumption until the operator enables and commits the setting.
+
+Restart OpenCode after upgrading so Planner loads the new bounded intake tools
+and question-receipt hooks. `/change` returns after enqueue; the background
+service owns subsequent execution. Human acceptance and isolated revalidation
+use the queue rather than the old direct Shell commands. See [Queue operation](QUEUE.md).
+
 ## Post-migration verification
 
 Run all checks from the detected Git root:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.10.0 doctor .
+npx @frankzhang2026/opencode-android-orchestrator@1.0.1 doctor .
 opencode debug config
 opencode debug skill
 opencode debug agent scheduled-planner

package/docs/QUEUE.md

@@ -0,0 +1,151 @@
+# Queue and background execution
+
+Version `1.0.1` stores proposals and approved contracts under
+`<git-common-dir>/automation-runtime/inbox/queue.json`. A contract is runnable
+only after its full plan, version, digest, target branch and commit policy are
+approved and durably recorded. Planning reads a fixed `planningHead`, so another
+Coder's active files and branch do not affect the proposal.
+
+Planner first receives compact branch and commit metadata. It discovers paths
+through bounded `list` pages and reads exact UTF-8 content through bounded
+`readChunk` pages. Every cursor is tied to the same `planningHead` and query;
+changing the commit, path, prefix or query rejects the cursor.
+
+## Normal use
+
+Start OpenCode with `scheduled-planner` and use `/change`. Approve the displayed
+proposal and the returned contract question. After enqueue, Planner returns;
+you can plan and approve B or C while A is executing or awaiting acceptance.
+Only the current task's plan and contract enter its working diff.
+
+Defaults are `inPlaceExclusive` and `humanApproval`. Human tasks stop at
+`AWAITING_HUMAN`; `/acceptance TASK-ID` presents the latest review and candidate
+and asks a new question before requesting integration. Automatic tasks must
+explicitly select `autoCommit` in their reviewed contract and proceed from
+`READY_TO_COMMIT` to local commit and integration without a final question.
+They never produce a fabricated human-acceptance record. Completion shows the
+local commit SHA, authorization source and `pushed: false` (未推送).
+
+| Workspace policy | Commit policy | When the next independent task may start |
+| --- | --- | --- |
+| `inPlaceExclusive` (default) | `humanApproval` (default) | After acceptance, local integration and directory handoff, or approved abort |
+| `inPlaceExclusive` | Explicitly sealed `autoCommit` | After build, full tests, Review, local commit/integration and handoff |
+| `isolatedWorktree` | `humanApproval` | After the worker and its children exit and its result is safely sealed |
+| `isolatedWorktree` | `autoCommit` | Rejected; fresh compatible policy approval is required |
+
+Both workspaces use one execution slot per Git common directory. A retained
+isolated candidate keeps its own directory; revalidation and integration must
+reacquire that same slot. Dependencies wait for `COMPLETED`, which means
+integrated locally. Review approval and commit creation alone do not satisfy a
+dependency. Fixed workspaces remain occupied during failures and human waiting.
+
+The worker resolves the Android SDK from `ANDROID_HOME`, `ANDROID_SDK_ROOT`,
+then the source repository's `local.properties` and passes the resolved location
+to its shell and Gradle processes. Isolated worktrees do not copy that local file.
+
+## Service and scheduling
+
+The first enqueue starts the package-owned detached service. Closing the
+Planner does not stop it. Enqueue notifications, deadlines, worker completion,
+startup recovery and periodic scans all use the same atomic reservation logic.
+Idle scans do not call a model. No launchd or external Scheduler is registered.
+The machine must be awake; a restarted service scans overdue entries once
+through normal arbitration. Recurring task-template generation is not exposed
+in this release; each approved contract has at most one initial execution.
+
+`notBefore` requires an ISO timestamp with an explicit timezone, for example
+`2026-09-14T22:00:00+08:00`. `dependsOn` contains previously approved task IDs.
+Default ordering is FIFO; priority ranges from -100 to 100, higher first, without
+preempting active work. Duplicate approval of a version returns its queue item.
+To revise an unstarted approval, cancel it and approve a new draft version.
+An executing version stays sealed; use a new task ID for later changes.
+
+```sh
+opencode-android-orchestrator queue status .
+opencode-android-orchestrator queue status . TASK-A
+opencode-android-orchestrator queue pause .
+opencode-android-orchestrator queue resume .
+opencode-android-orchestrator queue priority . TASK-B 10
+opencode-android-orchestrator queue cancel . TASK-C
+opencode-android-orchestrator queue stop .
+opencode-android-orchestrator queue start .
+```
+
+An unsuccessful OpenCode agent process pauses consumption as a shared execution
+fault; inspect its log and fix provider/environment failures before clearing it.
+
+Pause stops new reservations. Stop terminates the scheduler while preserving
+its active detached worker. Resume does not clear a fault. Notifications are
+persisted until acknowledged, so the original Planner session need not remain
+open. `queue --help` lists direct local-operator commands; interactive agents
+use bounded plugin tools and actual question receipts instead of the CLI.
+
+## Policy, capacity and verification
+
+Pause and finish/abort retained workspaces before changing repository mode:
+
+```sh
+opencode-android-orchestrator queue pause .
+opencode-android-orchestrator queue policy . isolatedWorktree humanApproval
+```
+
+Review and commit the changed `automation/config.json` before resuming. The
+queued task fixes its workspace strategy when claimed. Its commit authorization
+remains exactly the approved choice: changing a default cannot grant autoCommit
+to an older task. Direct configuration drift while a workspace is retained
+blocks scheduling; restore the recorded strategy before recovery.
+
+Schema V6 queue defaults are `scanIntervalMs: 5000`, `maxWorkspaces: 3` and
+`maxWorkspaceBytes: 21474836480`. Capacity includes retained isolated workspaces,
+including completed directories when automatic cleanup is disabled. Reaching
+count or disk limits pauses new isolated execution while still accepting intake;
+acceptance, recovery and cleanup of existing tasks remain eligible. Occupied or
+failed directories are never deleted simply to free queue capacity.
+
+Queued execution requires `unitTestsEnabled: true`. A temporary Gradle init
+script disables up-to-date and output-cache reuse only for Test tasks, records
+actual suite results and rejects missing/skipped-only evidence. The invocation
+uses `--no-configuration-cache`; compilation and build caches remain usable.
+It does not run `clean` or rerun all dependency tasks. Coder, Reviewer and local
+integration perform the configured full suite and build gates. Evidence records
+fresh-test logs, configured tasks and elapsed seconds.
+
+## Baselines and recovery
+
+Before execution, changes to contract-relevant files or execution configuration
+since planning require a revised contract and fresh approval. Planning files of
+other completed queue tasks are not treated as execution configuration changes.
+For an isolated waiting candidate whose local target advanced, request
+`revalidate`; it preserves the original evidence, rebases a nonconflicting
+uncommitted candidate in the same worktree, reruns build/full tests/Review and
+produces a new candidate ID. Conflicts or policy changes preserve the workspace
+and block progress. Old final acceptance cannot approve the new candidate.
+
+All local commits use a persisted transaction: `INTENT`, `COMMITTED`, `VERIFIED`,
+`INTEGRATED`, `COMPLETED`. Recovery checks the sealed tree, parent, target,
+authorization and local refs before reusing a commit or completing handoff.
+It never force-updates the target or pushes. A fixed directory is reusable only
+after local integration and handoff succeed.
+
+```sh
+opencode-android-orchestrator queue recover-lock .
+opencode-android-orchestrator queue recover-execution .
+opencode-android-orchestrator queue recover . TASK-A
+opencode-android-orchestrator queue clear-fault .
+```
+
+Inspect status and evidence first. Lock recovery proves the recorded owner has
+exited; a heartbeat timeout alone never steals a live lock. Execution recovery
+also checks the whole worker process group. If a reservation has no registered
+worker, stop its recorded launcher before recovering it. Unknown ownership
+retains the execution slot. `recover` is only for an existing sealed commit
+transaction; baseline/Reviewer interruptions use `/resume-task` or
+`/resume-review`. Running cancellation uses `/abort-task` and waits for a safe
+agent boundary before archival through the execution slot. A hung external
+process must be diagnosed and stopped before ownership recovery can succeed.
+
+Upgrade and uninstall require the service stopped, no active execution, and no
+retained unfinished workspace. Inbox, notifications and audit data remain in
+the Git common directory. Commit-message prefix and worktree-allowlist sidecars
+remain human-owned. See [Migration](MIGRATION.md), [Troubleshooting](TROUBLESHOOTING.md)
+and [Security](SECURITY.md) for lifecycle and trust boundaries.

package/docs/SECURITY.md

@@ -1,9 +1,9 @@
 # Security model
 
 This document describes the security properties of
-`@frankzhang2026/opencode-android-orchestrator@0.10.0`. The lifecycle foundation
+`@frankzhang2026/opencode-android-orchestrator@1.0.1`. The lifecycle foundation
 completed the real OpenCode `1.14.22` and `1.15.13` release matrix in `0.2.0`;
-`0.10.0` retains that compatibility boundary.
+`1.0.0` retains that compatibility boundary.
 
 ## Security goals and non-goals
 
@@ -38,31 +38,34 @@ perform actions outside the orchestrator's intended scope.
 
 ## Human approval boundary
 
-The normal workflow has three fresh OpenCode `question` selections: proposal,
-sealed contract, and final result. Direct chat prose, silence, a dismissed
-question, or a copied option label is not a normal-path approval. Baseline-only
-recovery and exceptional abort each have their own fresh status/question
-boundary.
-
-Approval phrases stored in `automation/config.json` are validation tokens, not
-secrets or cryptographic proof. Security depends on the scheduled planner
-showing the current review material, the user acting at that boundary, and the
-fixed Shell script independently verifying state, hashes, refs, scope, and
-leases. Anyone with direct shell and repository write access can invoke or
-modify local files; this package does not claim to protect against that actor.
-
-OpenCode permission prompts are also not semantic workflow approval. They can
-be accepted for the remainder of a session and may be auto-approved. For that
-reason `0.8.0` exposes only `android_orchestrator_status` and
-`android_orchestrator_doctor` as custom tools. State-changing wrappers remain a
-NO-GO until a one-use, non-model-forgeable receipt can bind the approval kind,
-task, session/message, sealed SHA or branch, time, and nonce.
+Proposal and contract approval always require fresh OpenCode `question`
+selections. The default `humanApproval` policy additionally requires final
+candidate acceptance. Explicit `autoCommit` authorization is sealed during
+contract approval and replaces only the final human question; build, actual
+full unit tests and independent Review remain mandatory.
+
+The plugin observes the host's question arguments and completed answer
+metadata through the common before/after hooks. Its one-use receipt binds
+session, consuming message, question call, operation, task/digest and candidate.
+Changed questions, multi-select answers, ordinary chat, copied labels, another
+session and already consumed receipts cannot authorize a tool mutation. A new
+candidate requires a new acceptance question. Receipts expire after 15 minutes
+and are lost on plugin restart; completed enqueue and consumed proof are stored
+in the durable queue. Repeated enqueue cannot create a second execution.
+
+The older mutating-wrapper NO-GO decision is superseded only by the bounded
+1.0.0 queue interfaces and these receipts. Permission prompts still do not grant
+semantic workflow approval. Direct CLI use is a trusted local-operator surface;
+Planner/Coder/Reviewer cannot call arbitrary CLI commands. An actor who can
+modify the package, host hooks, repository or runtime files remains outside
+this enforcement boundary.
 
 ## Agent and tool permissions
 
 All three installed agents start with `"*": deny` and add exact permissions.
-The planner can write only new planning artifacts and invoke the small set of
-orchestration scripts. The Coder can edit detected production/test source sets
+The Planner reads committed Git objects through snapshot and writes only
+the independent inbox through authenticated intake tools. It cannot directly
+read/edit the active working files, run Bash or call execution scripts. The Coder can edit detected production/test source sets
 but not Gradle, OpenCode, automation, or control files. Reviewer edit access is
 denied. Subagents, Scheduler/job tools, external directories, web access, push,
 merge/rebase, destructive Git commands, shell composition, and launchd are
@@ -85,7 +88,8 @@ The read-only status tool additionally:
 Doctor invokes read-only project, dependency, SDK, and installation checks and
 returns their failures instead of repairing the project.
 
-The compatible `tool.execute.before` hook may only raise the timeout argument
+The compatible `tool.execute.before` hook validates unattended shell commands,
+records approval challenges and may raise the timeout argument
 for a fixed list of direct managed long-running scripts. Its generated config
 value is an integer from `120000` through `7200000` milliseconds, defaults to
 `1800000`, never shortens a larger caller timeout, and does not rewrite the
@@ -130,13 +134,14 @@ while Gradle settings/build files and orchestration resources remain protected.
 legacy configuration with no scope field as `primary`, preventing an implicit
 permission expansion.
 
-`unitTestsEnabled`, `lintEnabled`, and `commitMessagePrefixMode` are the
-operator-editable fields in the otherwise manifest-managed
+`unitTestsEnabled`, `lintEnabled`, `commitMessagePrefixMode` and bounded
+queue/workspace policies are the operator-editable fields in the otherwise manifest-managed
 `automation/config.json`. Upgrade authenticates
 the remaining generated content before preserving those values, and doctor
 validates the resulting adaptive configuration. Task agents still cannot edit
 the protected file. Unit tests default on and lint defaults off; disabling unit
-verification does not remove the mandatory RED evidence step. Assemble, scope,
+verification blocks queue consumption and does not remove the mandatory RED
+evidence step for legacy non-queue tasks. Assemble, scope,
 evidence, and required device-test gates are unaffected.
 
 When commit prefix mode is `required`, the regular UTF-8 sidecar
@@ -191,14 +196,15 @@ the recorded before/after hashes and Git refs.
 ## Git and orchestration invariants
 
 - The source repository must have an identifiable original branch and baseline
-  HEAD. Original-branch drift blocks integration.
+  HEAD. Fixed-directory branch drift blocks integration; isolated drift
+  requires new full verification, independent Review and human acceptance.
 - The persistent repository lease prevents concurrent orchestrated tasks from
   sharing a mutable repository workspace.
 - Planning artifacts remain uncommitted until the verified product change is
   ready. Successful integration creates exactly one combined local commit.
 - Scope gates inspect tracked and untracked changes, reject protected paths and
   obvious test weakening, and bind the accepted result to a diff SHA.
-- An approved task snapshots the validated worktree allowlist. Listed local
+- Workspace preparation snapshots the validated worktree allowlist. Listed local
   changes are excluded consistently from cleanliness, scope, hashes, evidence,
   archival, and commits; explicit commit pathsets preserve allowlisted staged
   entries, and rename detection cannot hide an unlisted source path. Changing
@@ -216,8 +222,9 @@ the recorded before/after hashes and Git refs.
 - Abort rejects out-of-contract/protected paths, archives the diff, and avoids
   changing the original branch ref.
 
-Git hooks and Git configuration remain part of the host repository's trust
-surface. Review them before running a workflow in an untrusted project.
+Queue-controlled Git writes disable hooks and create local commit objects
+from a sealed tree. Git configuration and project-executed code still remain
+part of the host repository's trust surface. Review them before running a workflow in an untrusted project.
 
 ## Dependencies and network behavior
 

package/docs/TROUBLESHOOTING.md

@@ -1,7 +1,7 @@
 # Troubleshooting
 
 Use this guide for
-`@frankzhang2026/opencode-android-orchestrator@0.10.0`.
+`@frankzhang2026/opencode-android-orchestrator@1.0.1`.
 
 ## Start with read-only evidence
 
@@ -11,7 +11,7 @@ From the repository root, capture:
 git status --short --branch
 git rev-parse HEAD
 opencode --version
-npx @frankzhang2026/opencode-android-orchestrator@0.10.0 doctor . --json
+npx @frankzhang2026/opencode-android-orchestrator@1.0.1 doctor . --json
 ```
 
 If installation never completed, doctor will correctly report a missing or
@@ -39,9 +39,9 @@ command-scoped override:
 
 ```sh
 npm --registry=https://registry.npmjs.org/ view \
-  @frankzhang2026/opencode-android-orchestrator@0.10.0 version
+  @frankzhang2026/opencode-android-orchestrator@1.0.1 version
 npx --yes --registry=https://registry.npmjs.org/ \
-  @frankzhang2026/opencode-android-orchestrator@0.10.0 upgrade . --json
+  @frankzhang2026/opencode-android-orchestrator@1.0.1 upgrade . --json
 ```
 
 This leaves the company's saved npm configuration unchanged. Use the option
@@ -71,7 +71,7 @@ Git-backed Superpowers plugin at runtime.
 | Invalid `--long-command-timeout-ms` | The value is not an integer from `120000` through `7200000`. | Use the `1800000` ms default or pass an intentional bounded value to `init`/`upgrade`; do not edit the generated config directly. |
 | Android SDK failure | No valid explicit SDK, `ANDROID_HOME`, `ANDROID_SDK_ROOT`, or `local.properties` `sdk.dir` was found. | Configure one real SDK root containing `platforms/` and `build-tools/`. Do not publish `local.properties`. |
 | Missing `git`, `jq`, `rg`, `shasum`, or Java | Required deterministic command is unavailable on `PATH`. | Install or restore the missing command, record its version, and rerun the read-only checks. |
-| `Bundled Orchestrator skill is unavailable` | The installed `0.10.0` package is incomplete, damaged, or loaded from an unsupported partial copy. | Reinstall the exact package, inspect its `resources/third-party/superpowers-v6.2.0/skills/` entries, restart OpenCode, and rerun `opencode debug skill`. Do not add an external Superpowers plugin as a fallback. |
+| `Bundled Orchestrator skill is unavailable` | The installed `1.0.1` package is incomplete, damaged, or loaded from an unsupported partial copy. | Reinstall the exact package, inspect its `resources/third-party/superpowers-v6.2.0/skills/` entries, restart OpenCode, and rerun `opencode debug skill`. Do not add an external Superpowers plugin as a fallback. |
 | The exact Superpowers v6.2.0 plugin remains after upgrade | That entry existed in the verified pre-install OpenCode file and is therefore user-owned. | Leave it in place or remove it as a separate reviewed configuration change. Upgrade only removes the old Orchestrator-managed entry. |
 
 Version `0.6.0` always passes `--no-configuration-cache` to its temporary
@@ -87,7 +87,7 @@ silence of `./gradlew tasks --all --console=plain | rg ...` in a large build.
 For an existing installation, run:
 
 ```sh
-npx @frankzhang2026/opencode-android-orchestrator@0.10.0 upgrade . \
+npx @frankzhang2026/opencode-android-orchestrator@1.0.1 upgrade . \
   --refresh-gradle-discovery
 ```
 
@@ -96,7 +96,7 @@ least `1800000` milliseconds. A higher timeout already supplied by the caller
 is preserved; unrelated Bash commands are unchanged. To configure one hour,
 run `upgrade . --long-command-timeout-ms 3600000` on a healthy installation.
 If a command still reports `120000 ms`, confirm that the project manifest and
-OpenCode plugin reference are both `0.10.0`, restart the OpenCode session so the
+OpenCode plugin reference are both `1.0.1`, restart the OpenCode session so the
 plugin reloads, and rerun doctor before attempting recovery.
 
 After installation, inspect OpenCode discovery separately:
@@ -151,7 +151,7 @@ Common fail-closed codes include:
 | `PLUGIN_VERSION_CONFLICT` | The same managed package identity has another reference/version. | Review and remove or migrate only the obsolete entry; never let init silently replace it. |
 | `DUPLICATE_PLUGIN` or `DUPLICATE_PROPERTY` | Configuration identity is ambiguous. | Correct the JSON/JSONC structure without discarding unrelated fields or comments. |
 | `INVALID_JSONC` or `ROOT_NOT_OBJECT` | OpenCode configuration cannot be merged safely. | Repair the user-owned file and validate it before retrying. |
-| `AGENTS_BLOCK_CONFLICT` or `AGENTS_MARKERS_INVALID` | During `init`, the bounded block was modified; or a lifecycle command found partial, out-of-order, or duplicate markers. | Keep project-specific instructions outside one valid marker pair. `0.10.0 upgrade` preserves marker-external changes and replaces the old managed block; malformed marker structure still requires manual repair. |
+| `AGENTS_BLOCK_CONFLICT` or `AGENTS_MARKERS_INVALID` | During `init`, the bounded block was modified; or a lifecycle command found partial, out-of-order, or duplicate markers. | Keep project-specific instructions outside one valid marker pair. `1.0.0 upgrade` preserves marker-external changes and replaces the old managed block; malformed marker structure still requires manual repair. |
 | `FILE_SYMLINK`, `TARGET_SYMLINK`, or `CONFIG_SYMLINK` | A managed target or ancestor is a symbolic link. | Replace it only after understanding ownership and destination. The installer intentionally does not follow it. |
 | `PLAN_STALE` or `TARGET_MODIFIED` | A file changed between planning and application. | Stop concurrent edits, inspect the diff, and rerun from a stable state. |
 
@@ -170,8 +170,8 @@ configuration.
 | --- | --- | --- |
 | `MANIFEST_MISSING`, `MANIFEST_INVALID`, or `MANIFEST_STATE` | No trustworthy installed manifest is available. | Do not invent a manifest or copy one from another project. Determine whether this is an uninstalled/manual setup or an interrupted transaction. |
 | `EXISTING_INSTALLATION_DIFFERENT` | `init` found another installed inventory/version. | Use `upgrade` for a healthy older manifest. |
-| `EXISTING_INSTALLATION_INVALID` or `INSTALLATION_INVALID` | Manifest, installed files, or required backups failed structural or content validation. In `0.8.0`, this also reported an active manifest whose mode was not exactly `0600`. | Preserve the project and `.automation-plugin/`; use `0.10.0 upgrade` for mode-only drift, and inspect other doctor details or recovery history. |
-| `INSTALLED_FILES_MODIFIED` | Upgrade found content/existence drift in an ordinary managed file or missing/modified backup content. | Move intentional customization out of ordinary managed paths or choose manual recovery. `0.10.0` separately merges user-owned `AGENTS.md` content and does not reject mode-only drift. |
+| `EXISTING_INSTALLATION_INVALID` or `INSTALLATION_INVALID` | Manifest, installed files, or required backups failed structural or content validation. In `0.8.0`, this also reported an active manifest whose mode was not exactly `0600`. | Preserve the project and `.automation-plugin/`; use `1.0.0 upgrade` for mode-only drift, and inspect other doctor details or recovery history. |
+| `INSTALLED_FILES_MODIFIED` | Upgrade found content/existence drift in an ordinary managed file or missing/modified backup content. | Move intentional customization out of ordinary managed paths or choose manual recovery. `1.0.0` separately merges user-owned `AGENTS.md` content and does not reject mode-only drift. |
 | `VERSION_DOWNGRADE_REFUSED` | Target package is older than the installed manifest. | Use a newer fixed package version; never edit the manifest version. |
 | `UPGRADE_IN_PROGRESS` or `UNINSTALL_IN_PROGRESS` | `.automation-plugin/upgrade.json` or `uninstall.json` records an unfinished transaction. | Inspect the marker and matching recovery directory. Do not delete the marker merely to retry. |
 | `POST_UPGRADE_VERIFICATION_FAILED` | New resources failed verification. | The implementation attempts a complete old-version rollback; verify the old manifest and inspect upgrade evidence. |
@@ -182,7 +182,7 @@ configuration.
 Installer control paths are:
 
 - active manifest: `.automation-plugin/manifest.json` (new manifests are
-  written as `0600`; mode-only drift does not block `0.10.0 upgrade`);
+  written as `0600`; mode-only drift does not block `1.0.0 upgrade`);
 - first-install/original backups: `.automation-plugin/backups/<id>/`;
 - upgrade marker and snapshots: `.automation-plugin/upgrade.json` and
   `.automation-plugin/upgrades/<id>/`;
@@ -236,6 +236,29 @@ identify the state, workspace, original branch, sealed diff, and evidence.
 - `TEST_FAILED` or `NEEDS_HUMAN`: inspect the contract and evidence. Do not
   broaden scope or silently queue the same task again.
 
+## Durable queue failures in 1.0.0
+
+Start with `opencode-android-orchestrator queue status .` and the task's detailed
+status. The queue and commit transaction are authoritative; an old Planner
+session or a missing notification is not evidence that a task never started.
+
+| Symptom | Recovery |
+| --- | --- |
+| Fresh matching question receipt required | Show a new queue review/draft question and select it in the same Planner session; do not paste its approval label into chat. |
+| Waiting for human confirmation or fixed workspace | Accept the current candidate or use the approved abort workflow; further contracts may still be enqueued. |
+| Isolated capacity reached | Integrate or explicitly archive retained workspaces; do not delete failed work simply to advance the queue. |
+| Execution launch ownership unknown | Stop the recorded launcher, prove it exited, then use `queue recover-execution .`; preserve any partial workspace. |
+| Dead transaction owner | Inspect the lock record and use explicit `queue recover-lock .`; a live PID or surviving child process blocks takeover. |
+| OpenCode process failure | Inspect the current agent log, repair provider/environment access, then clear the fault while idle. Resume alone does not clear it. |
+| Local commit already exists but task is blocked | Use `queue recover . TASK-ID`; it reuses the sealed transaction instead of creating another visible commit. |
+| Target advanced for an isolated candidate | Request `revalidate`, wait for fresh full tests/Review, and confirm the new candidate. |
+| Upgrade/uninstall reports a retained workspace | Stop scheduling and finish or approve abort before replacing runtime resources. |
+
+The service launches the packaged queue entry with Node.js, independently of the
+OpenCode/Bun executable. Ensure `node` is on the service's inherited `PATH`.
+There is no model polling while idle and no launchd registration. After reboot,
+start the service or enqueue a contract to resume durable scanning.
+
 ## Actions to avoid
 
 Never use a troubleshooting shortcut that destroys the evidence needed to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frankzhang2026/opencode-android-orchestrator",
-  "version": "0.10.0",
+  "version": "1.0.1",
   "description": "Reusable OpenCode orchestration for Android projects",
   "license": "MIT",
   "author": "frankzhang2026",