fix(flow): release safe home startup in 10.0.3

.agents/plans/06-patch-release/README.md

@@ -26,6 +26,30 @@ semantic judgment from a path or a patch version. A content change invalidates
 that approval. This is a maintainer review control, not a sandbox against someone
 who can rewrite the policy and its approvals together.
 
+## Reviewed home-startup exception
+
+The operator authorized a release without new model qualification for the
+home-startup defect on 2026-10-29. Exact 10.0.3 may use fully qualified 10.0.2's
+OpenAI-only baseline. This does not change full-matrix profiles or admit later
+runtime patches automatically.
+
+An optional `startup` approval binds before/after SHA-256 hashes for exactly
+`src/infrastructure/fs/workspace-paths.ts` and
+`src/platform/opencode/plugin-composition.ts`, both regular non-executable files.
+The sole package-script change appends the provider-free startup test to
+`smoke:live`. Other metadata, runtime files, guides, dependencies and build inputs
+remain protected. Missing approvals, changed content, other baselines/versions,
+extra runtime paths or weakened smoke commands fail.
+
+Review must confirm that only home-directory setup becomes inactive, preserving
+mutable-state rejection, project registration and every workflow gate. Linux
+packed startup must cover home, Git and non-Git folders without a model call.
+The baseline is reverified by its original released-tag authority in a temporary
+worktree with the unchanged dependencies. This avoids resealing historical
+evidence merely because the candidate runtime/version changed. No credentials
+are inherited and no model calls occur. The patch has no new model measurements
+or canary. Publication still checks exact candidate package bytes.
+
 ## Evidence
 
 A record at evals/qualification/patches/VERSION.json uses schemaVersion 1 and kind
@@ -34,10 +58,10 @@ manifest hashes, its version, the baseline artifact identity, tag commit, canary
 path and regraded bundle hash, approvedBy, rationale, and any guidance approval.
 The PatchReleaseSchema in scripts/patch-release.ts is the executable format.
 
-The baseline must independently pass the full verifier at release time. Existing
-seven-day campaign and 72-hour canary limits remain unchanged. A patch record
-cannot stand in for a fully qualified baseline, extend freshness, or invent runs.
-An expired baseline blocks; it never starts a paid campaign automatically.
+The baseline must independently pass the full verifier as retained evidence at
+release time. Its prior campaign and canary are historical, not fresh candidate
+measurements. A patch record cannot become a fully qualified baseline or invent
+runs. Verification never starts a paid campaign.
 
 The candidate has no new model eval or live model canary. Required assurance is
 clean source, strict diff eligibility, matching package bytes, review of the

.agents/plans/23-home-startup-patch/README.md

@@ -0,0 +1,40 @@
+# Flow 10.0.3 home-startup patch
+
+The operator requested a new release without new model qualification on
+2026-10-29, and explicitly invoked full-stop: prepare an open, reviewed PR; do
+not merge or publish from that task.
+
+The published 10.0.2 package fails plugin setup when OpenCode loads its global
+configuration at home. A workspace safety guard is correct for mutation but was
+also used as a fatal startup precondition. The patch handles that precise error
+as an inactive plugin location with an actionable warning. It does not create
+home state or weaken root, missing-directory, validation or review guards.
+
+## Release assurance
+
+Use the existing baseline-qualified-patch route with an exact-version reviewed
+startup exception. Compare directly against measured source `fdd11b7d` and the
+published `v10.0.2` tag at `a920f737`. The patch record binds candidate package
+bytes and both changed runtime files. The 10.0.2 matrix (80/81 under unchanged
+thresholds) and native canary (6/6) remain historical. No model evaluation or
+model canary is measured for 10.0.3. Full-matrix two-provider policy is unchanged.
+
+The provider-free native regression must reject the published artifact and pass
+the patch at home, in a Git project and in a non-Git folder. CI also runs full
+checks, replay, package smoke and strict baseline/patch verification. Changes to
+approved code require refreshed hashes and review; no skip flag is added.
+
+Dependabot PRs #213 and #214 remain separate: dependencies and lockfiles stay
+identical to the measured baseline for this narrowly reviewed patch.
+
+## Linux installation after publication
+
+```sh
+opencode2 plugin add opencode-plugin-flow@10.0.3
+cd /path/to/your/project
+opencode2
+```
+
+An exact existing 10.0.2 pin does not update itself. No software was installed on
+the user's Linux laptop by this work. Publication needs a merged commit and its
+annotated version tag; the existing workflow owns npm and GitHub publication.

.github/workflows/release.yml

@@ -244,7 +244,7 @@ jobs:
                 "opencode-plugin-flow-${version}.tgz" "$sealed" "$digest"
             fi
           fi
-          if node -e 'process.exit(Number(process.argv[1].split(".")[0]) >= 10 ? 0 : 1)' "$version"; then
+          if node -e 'process.exit(Number(process.argv[1].split(".")[0]) >= 10 ? 0 : 1)' "$version" && [[ ! -f "evals/qualification/patches/${version}.json" && ! -f "evals/qualification/features/${version}.json" ]]; then
             qualified="$(bun scripts/materialize-qualification.ts --descriptor "evals/qualification/archives/${version}.json" --out "${RUNNER_TEMP}/flow-qualified-${version}")"
             bun run scripts/restore-exact-release-artifact.ts \
               "opencode-plugin-flow-${version}.tgz" --bundle "$qualified" "$version"

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [10.0.3]
+
+- Start OpenCode safely from home after a global installation. Flow stays
+  inactive there and explains how to open a project, instead of failing the
+  server plugin. Project state and source scans remain excluded from home.
+- Add a provider-free packed startup check for home, Git projects and ordinary
+  folders to CI and release smoke. Session v5 schema, permissions, validation, review,
+  continuation and closure requirements are unchanged.
+- Use the reviewed baseline-qualified patch route against 10.0.2. No new live
+  model qualification or model canary was run for 10.0.3; 10.0.2's 80/81 matrix
+  and 6/6 canary are historical evidence, not measurements of this patch.
+
+Upgrade with `opencode2 plugin add opencode-plugin-flow@10.0.3`, then start
+`opencode2` inside your project folder.
+
 ## [10.0.2]
 
 - Put ordinary Flow execution before recovery details, share goal-alignment and

README.md

@@ -43,21 +43,27 @@ Install OpenCode v2 and the exact Flow release:
 ```sh
 npm install -g @opencode/cli@2.1.4
 opencode2 --version
-opencode2 plugin add opencode-plugin-flow@10.0.2
+opencode2 plugin add opencode-plugin-flow@10.0.3
 ```
 
-The version command must report `opencode v2.1.4` or a later tested 2.x version.
-Flow selects HTTP transport for provider, model, and variant settings while loaded.
-This keeps model requests observable for continuation and validation attribution.
-The v2 package provides both `opencode` and `opencode2`. Use `opencode2` when an
-older `opencode` executable remains on your PATH. The plugin command installs
-Flow globally. Exact pins stay fixed until you install another version.
+`opencode2 --version` must report `opencode v2.1.4` or a later tested 2.x version.
+Use `opencode2` to avoid an older `opencode` on PATH. The install is global;
+start inside a project:
+
+```sh
+cd /path/to/your/project
+opencode2
+```
+
+Flow keeps state in `<project>/.flow/` and refuses the home directory itself.
+Exact pins stay fixed. Flow uses HTTP transport for provider, model, and variant
+settings to observe continuation and validation.
 
 For project scope, add this entry to the project's `opencode.json`:
 
 ```json
 {
-  "plugins": ["opencode-plugin-flow@10.0.2"]
+  "plugins": ["opencode-plugin-flow@10.0.3"]
 }
 ```
 
@@ -74,7 +80,7 @@ Set plugin defaults:
 ```json
 {
   "plugins": [{
-    "package": "opencode-plugin-flow@10.0.2",
+    "package": "opencode-plugin-flow@10.0.3",
     "options": {
       "reviewer": { "model": "provider/model", "steps": 80 },
       "typesafeApiKeyEnv": "MY_TYPESAFE_KEY"

docs/quickstart.md

@@ -5,9 +5,9 @@ consequential change. Read the plan and the review before accepting the result.
 
 ## Install Flow
 
-Install the exact release shown in the [README installation section](../README.md#install).
-Use OpenCode v2 with the tested minimum from the README. Finish or explicitly
-close active Flow sessions before upgrading, then restart OpenCode.
+Install the exact release and start OpenCode inside your project as shown in the
+[README installation section](../README.md#install). Finish or explicitly close
+active Flow sessions before upgrading, then restart OpenCode.
 
 ## Select Flow models
 

docs/release-qualification.md

@@ -35,11 +35,12 @@ Verifier fixes may reuse runs for unchanged package bytes and case policy.
 Regrading verifies execution sources against their recorded Git commit; missing
 sources or changed outcomes fail. Canary retries keep manager/reviewer identity.
 
-Reviewed offline exceptions cover [narrow patches](../.agents/plans/06-patch-release/README.md)
-and [frozen features](../.agents/plans/09-planning-models/README.md). They measure
-against the last fully qualified release, never another offline one. Baseline
-citations are historical evidence at their recorded source. Only the candidate
-needs a fresh canary; historical reconstruction measures nothing new.
+Reviewed offline paths cover [narrow patches](../.agents/plans/06-patch-release/README.md)
+and [frozen features](../.agents/plans/09-planning-models/README.md), always against
+a fully qualified baseline. Exact 10.0.3's reviewed home-startup patch uses
+10.0.2's released-tag evidence plus Linux startup tests, without new model calls or
+canary. Other runtime changes retain full qualification. Prior passes never
+become candidate measurements.
 
 New scenarios need a policy decision. Missing required cases fail qualification.
 
@@ -106,8 +107,7 @@ on the canonical Linux host. The v2 profile uses HTTP transport with ambient
 OpenCode configuration disabled. Run a fresh canary against its exact `artifact.tgz`,
 seal/regrade the bundle, and commit only evidence without changing measured inputs.
 Recheck final main CI and exact artifact identity before tagging `v<package-version>`.
-For 9.4.0, use
-`bun scripts/prepare-qualified-release-940.ts --out opencode-plugin-flow-9.4.0.tgz`.
+Historical artifact reconstruction follows the versioned release workflow.
 
 Authorize dispatches using the [paid-run budget](../.agents/plans/05-release-simplification/README.md#authorize-paid-work).
 Keep that ledger across retries. Budget-stopped campaigns cannot qualify.

docs/troubleshooting.md

@@ -1,15 +1,17 @@
 # Troubleshooting
 
-## Flow commands are missing
+## Home-directory startup error
+
+OpenCode started in `~`. Run `cd /path/to/project && opencode2`.
+Flow protects home from state and source scans; no reinstall is needed.
 
-Rerun the exact-version plugin command from the
-[README installation section](../README.md#install), or confirm that the
-relevant `opencode.json` holds that same exact entry.
+## Flow commands are missing
 
-Restart OpenCode and inspect its plugin-loading logs. Flow has no installer,
-cache cleaner, or configuration-repair CLI. Follow the official
-[OpenCode plugin documentation](https://opencode.ai/v2/docs/plugins/) for npm or
-configuration failures.
+In a project folder, confirm the exact [README plugin entry](../README.md#install)
+in `opencode.json`, restart OpenCode, and inspect plugin-loading logs. Flow does
+not repair host configuration or caches. See the official
+[OpenCode plugin documentation](https://opencode.ai/v2/docs/plugins/) for
+installation or configuration failures.
 
 ## Reviewer model looks shared
 

evals/qualification/patches/10.0.3.json

@@ -0,0 +1,40 @@
+{
+	"schemaVersion": 1,
+	"kind": "baseline-qualified-patch",
+	"version": "10.0.3",
+	"baseline": {
+		"commit": "a920f7375d2bd5262e7fc5c272f5cac55c6b3b4b",
+		"artifact": {
+			"packageVersion": "10.0.2",
+			"sourceCommit": "fdd11b7dea1e95a87d781bdee89ed84aea8a29e7",
+			"sourceTreeSha256": "sha256:5ca3dc21436044f8a4d3b0c92f160d3cb90a7af422cfed8dd252846a818eccc9",
+			"tarballSha256": "sha256:6d8345ea7968799778fa4dc9c818ab37449b70c16a08a7eedba48f8c24c8f5a4",
+			"unpackedManifestSha256": "sha256:cf68469968b148aac2ccf30d6e0d22460079597d59ff6662ec39907362842153"
+		},
+		"canary": "evals/canary/10.0.2.json",
+		"bundleSha256": "sha256:89b32228d6651737152a616dea44439b1d8acd23037c1f6123f91c2e920674ed"
+	},
+	"artifact": {
+		"packageVersion": "10.0.3",
+		"tarballSha256": "sha256:74294e90f7ff9e9500fab1ee4b896273bca9848815eab6a494c55a7bf75b1399",
+		"unpackedManifestSha256": "sha256:c136169692af6ef0dd95b1d6e73e3942b60588c91dbae8b202785cc428c6ee49"
+	},
+	"guidance": [],
+	"approvedBy": "Maintainer approval in this T3 Code thread on 2026-10-29: release the home-startup fix without a new model qualification; full-stop requires reviewed PR handoff before merge.",
+	"rationale": "Exact-version home-startup compatibility patch. Only the two reviewed runtime files and the declared smoke command may change. Retain 10.0.2 historical matrix/canary evidence; candidate assurance is deterministic checks, Linux packed startup, replay and independent review, not a new model measurement.",
+	"startup": {
+		"kind": "home-directory-startup-10.0.3",
+		"files": [
+			{
+				"path": "src/infrastructure/fs/workspace-paths.ts",
+				"baselineSha256": "sha256:f49ac543d8253e868aafd885feaced8214b0e3704815d606477ab3ab45c1e1fa",
+				"sha256": "sha256:fd146e0a680bd9d879292b6e3c88e853527d3354e1db842e13934b835c1b80c2"
+			},
+			{
+				"path": "src/platform/opencode/plugin-composition.ts",
+				"baselineSha256": "sha256:26ffd9677ca07b4ab5f8f7297ecabc10cdf7df1feae0a2b8471490b5ca3ee214",
+				"sha256": "sha256:9e164e3a31464e8cfee7b860d6b707ae18e6418762c5647c0a05acba65556986"
+			}
+		]
+	}
+}

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-plugin-flow",
-	"version": "10.0.2",
+	"version": "10.0.3",
 	"description": "Durable planning, validation, and independent review for OpenCode v2",
 	"type": "module",
 	"repository": {
@@ -55,7 +55,7 @@
 		"replay": "bun run evals/replay-run.ts",
 		"triage": "bun run scripts/triage-report.ts",
 		"release:monitor": "node scripts/release-monitor.mjs",
-		"smoke:live": "FLOW_LIVE_SMOKE=1 bun test tests/live-opencode-smoke.test.ts",
+		"smoke:live": "FLOW_LIVE_SMOKE=1 bun test tests/live-opencode-smoke.test.ts tests/plugin-startup-live.test.ts",
 		"test": "bun test tests",
 		"typecheck": "tsc --noEmit",
 		"check": "bun run typecheck && bun run lint && bun run release:metadata && bun run build && bun run test"