fix(tui): register pinned package entry

Author: osovv

.grace/context/requirements.xml

@@ -184,7 +184,7 @@
     <Constraint>vvoc-managed config may be global under $XDG_CONFIG_HOME/vvoc/ or project-local under .vvoc/, depending on selected scope and command semantics.</Constraint>
     <Constraint>Project-scope writes must stay inside project-local .opencode/ and .vvoc/ paths.</Constraint>
     <Constraint>Dedicated OpenCode TUI config uses tui.json(c); project scope stores it inside .opencode and conservative mutation preserves unrelated settings and plugin tuple options.</Constraint>
-    <Constraint>The public TUI entry targets OpenCode 1.18.2 or newer and is registered explicitly through tui.json(c).</Constraint>
+    <Constraint>The public TUI entry targets OpenCode 1.18.2 or newer; tui.json(c) registers the pinned base package specifier and OpenCode selects its ./tui export.</Constraint>
     <Constraint>Persisted vvoc data must live under $XDG_DATA_HOME/vvoc/.</Constraint>
     <Constraint>Config writes must be conservative, idempotent, and strict about current schema validity before mutation.</Constraint>
     <Constraint>Role resolution must fail loudly for unknown or invalid semantic role references.</Constraint>

.grace/context/technology.xml

@@ -98,7 +98,7 @@
     <Constraint>Use Bun commands for local project checks and bunx for grace-cli.</Constraint>
     <Constraint>Do not edit generated dist output manually.</Constraint>
     <Constraint>Root package exports and plugin subpath exports must stay valid unless an explicit breaking change is approved.</Constraint>
-    <Constraint>OpenCode TUI integration requires OpenCode 1.18.2 or newer and must use a default TuiPluginModule export registered in tui.json(c).</Constraint>
+    <Constraint>OpenCode TUI integration requires OpenCode 1.18.2 or newer and a default TuiPluginModule export selected from the pinned base package registered in tui.json(c).</Constraint>
     <Constraint>Publishing remains manual from terminal with npm publish; normal branch pushes must not publish the package.</Constraint>
     <Constraint>README, .grace/graph, and .grace/verification must be updated with behavior, public API, setup, command, flow, or verification changes as applicable.</Constraint>
   </OperationalConstraints>

.grace/graph/main.xml

@@ -4,13 +4,13 @@
     <Annotation>Portable OpenCode workflow package with server and TUI plugins, a Bun CLI, semantic model roles, context inspection, hashline editing, explicit work items, and managed agent workflows.</Annotation>
       <M-MODEL-ROLES><Name>ModelRoles</Name><Type>CORE_LOGIC</Type><Status>implemented</Status><Purpose>Define built-in role IDs, vv-role:* syntax, model-selection parsing, role normalization, resolution helpers, and built-in agent role bindings.</Purpose><Paths>src/lib/model-roles.ts</Paths><Depends>none</Depends><Verification>V-M-MODEL-ROLES</Verification></M-MODEL-ROLES>
       <M-CONFIG-LAYERS><Name>ConfigLayers</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Resolve vvoc, OpenCode runtime, and dedicated OpenCode TUI config sources across env, project, global, and defaults plus project/global write targets.</Purpose><Paths>src/lib/config-layers.ts, src/lib/vvoc-paths.ts</Paths><Depends>none</Depends><Verification>V-M-CONFIG-LAYERS</Verification></M-CONFIG-LAYERS>
-      <M-CLI-CONFIG><Name>OpenCodeConfigTools</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Mutate OpenCode runtime/TUI and vvoc config conservatively, pin package registrations, preserve TUI tuple options, write managed agent/skill registrations, render strict schema v3, and inspect installation state.</Purpose><Paths>src/lib/opencode.ts, src/lib/package.ts, src/lib/vvoc-config.ts, src/lib/model-roles.ts, src/lib/vvoc-paths.ts, schemas/vvoc/v3.json</Paths><Depends>M-CONFIG-LAYERS, M-MODEL-ROLES, M-VVOC-PRESET-REGISTRY, M-CLI-MANAGED-AGENTS, M-CLI-MANAGED-SKILLS, M-CLI-AGENT-MODELS</Depends><Verification>V-M-CLI-CONFIG</Verification></M-CLI-CONFIG>
+      <M-CLI-CONFIG><Name>OpenCodeConfigTools</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Mutate OpenCode runtime/TUI and vvoc config conservatively, pin base package registrations, migrate legacy TUI subpath specs, preserve tuple options, inspect OpenCode host compatibility, write managed agent/skill registrations, and render strict schema v3.</Purpose><Paths>src/lib/opencode.ts, src/lib/package.ts, src/lib/vvoc-config.ts, src/lib/model-roles.ts, src/lib/vvoc-paths.ts, schemas/vvoc/v3.json</Paths><Depends>M-CONFIG-LAYERS, M-MODEL-ROLES, M-VVOC-PRESET-REGISTRY, M-CLI-MANAGED-AGENTS, M-CLI-MANAGED-SKILLS, M-CLI-AGENT-MODELS</Depends><Verification>V-M-CLI-CONFIG</Verification></M-CLI-CONFIG>
       <M-RELEASE-AUTOMATION><Name>ReleaseAutomation</Name><Type>SCRIPT</Type><Status>implemented</Status><Purpose>Guard package exports and releases with source-path checks, local version bumping, AI changelog summary generation, schema id consistency, release checks, and tag-gated publish workflow.</Purpose><Paths>scripts/check-exports.ts, scripts/release-bump.ts, scripts/release-check.ts, scripts/release-summary.ts, .github/workflows/publish.yml, schemas/vvoc/v3.json</Paths><Depends>M-CLI-CONFIG</Depends><Verification>V-M-RELEASE-AUTOMATION</Verification></M-RELEASE-AUTOMATION>
       <M-CLI-MANAGED-AGENTS><Name>ManagedAgents</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Define bundled vv-controller, enhancer, guardian, investigator, vv-implementer, vv-spec-reviewer, and vv-code-reviewer templates and load managed prompt text.</Purpose><Paths>src/lib/managed-agents.ts, templates/agents/*.md</Paths><Depends>M-CLI-CONFIG</Depends><Verification>V-M-CLI-MANAGED-AGENTS</Verification></M-CLI-MANAGED-AGENTS>
       <M-CLI-MANAGED-SKILLS><Name>ManagedSkills</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Define bundled vv-spec, vv-plan, vv-review, vv-execute, vv-reflect, and vv-handoff skill templates and reference loading.</Purpose><Paths>src/lib/managed-skills.ts, templates/skills/**/SKILL.md</Paths><Depends>M-CLI-CONFIG</Depends><Verification>V-M-CLI-MANAGED-SKILLS</Verification></M-CLI-MANAGED-SKILLS>
       <M-CLI-AGENT-MODELS><Name>AgentModels</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Define supported vvoc model target IDs and shared model override validation helpers retained for current command and config compatibility.</Purpose><Paths>src/lib/agent-models.ts</Paths><Depends>M-CLI-MANAGED-AGENTS</Depends><Verification>V-M-CLI-AGENT-MODELS</Verification></M-CLI-AGENT-MODELS>
       <M-PLUGIN-TOGGLE-CONFIG><Name>PluginToggleConfig</Name><Type>UTILITY</Type><Status>implemented</Status><Purpose>Define vvoc-managed server and TUI plugin toggle names, default all-true config, and pure isPluginEnabled helper.</Purpose><Paths>src/lib/plugin-toggle-config.ts</Paths><Depends>none</Depends><Verification>V-M-PLUGIN-TOGGLE-CONFIG</Verification></M-PLUGIN-TOGGLE-CONFIG>
-      <M-CLI-COMMANDS><Name>VVOCCommands</Name><Type>ENTRY_POINT</Type><Status>implemented</Status><Purpose>Compose the vvoc CLI and expose init, install, sync, launch, status, doctor, version, role, preset, plugin, config, patch-provider, completion, guardian config, and upgrade commands, including managed TUI registration and diagnostics.</Purpose><Paths>src/cli.ts, src/commands/*.ts</Paths><Depends>M-CONFIG-LAYERS, M-CLI-CONFIG</Depends><Verification>V-M-CLI-COMMANDS</Verification></M-CLI-COMMANDS>
+      <M-CLI-COMMANDS><Name>VVOCCommands</Name><Type>ENTRY_POINT</Type><Status>implemented</Status><Purpose>Compose the vvoc CLI and expose init, install, sync, launch, status, doctor, version, role, preset, plugin, config, patch-provider, completion, guardian config, and upgrade commands, including managed TUI registration and OpenCode host compatibility diagnostics.</Purpose><Paths>src/cli.ts, src/commands/*.ts</Paths><Depends>M-CONFIG-LAYERS, M-CLI-CONFIG</Depends><Verification>V-M-CLI-COMMANDS</Verification></M-CLI-COMMANDS>
       <M-PLUGIN-MODEL-ROLES><Name>ModelRolesPlugin</Name><Type>INTEGRATION</Type><Status>implemented</Status><Purpose>Resolve vv-role:* references in supported OpenCode root, agent, and command model fields using effective vvoc config source precedence.</Purpose><Paths>src/plugins/model-roles/index.ts</Paths><Depends>M-CONFIG-LAYERS, M-MODEL-ROLES, M-CLI-CONFIG, M-PLUGIN-TOGGLE-CONFIG</Depends><Verification>V-M-PLUGIN-MODEL-ROLES</Verification></M-PLUGIN-MODEL-ROLES>
       <M-CLI-ROLE><Name>RoleCommand</Name><Type>ENTRY_POINT</Type><Status>implemented</Status><Purpose>List, set, and unset semantic role assignments in selected vvoc config for built-in and custom roles.</Purpose><Paths>src/commands/role.ts, src/lib/model-roles.ts</Paths><Depends>M-CONFIG-LAYERS, M-CLI-CONFIG, M-MODEL-ROLES</Depends><Verification>V-M-CLI-ROLE</Verification></M-CLI-ROLE>
       <M-CLI-PRESET><Name>PresetCommand</Name><Type>ENTRY_POINT</Type><Status>implemented</Status><Purpose>List, show, and atomically apply declarative role and orchestration presets without mutating OpenCode config.</Purpose><Paths>src/commands/preset.ts, src/lib/model-roles.ts, src/lib/vvoc-preset-registry.ts</Paths><Depends>M-CONFIG-LAYERS, M-CLI-CONFIG, M-MODEL-ROLES, M-VVOC-PRESET-REGISTRY, M-ORCHESTRATION-PROFILES</Depends><Verification>V-M-CLI-PRESET</Verification></M-CLI-PRESET>
@@ -36,7 +36,7 @@
       <M-CLI-UPGRADE><Name>Upgrade</Name><Type>ENTRY_POINT</Type><Status>implemented</Status><Purpose>Check npm for newer package versions, install globally with Bun, and run follow-up sync while reporting sync failure as partial upgrade.</Purpose><Paths>src/commands/upgrade.ts</Paths><Depends>M-CLI-CONFIG</Depends><Verification>V-M-CLI-UPGRADE</Verification></M-CLI-UPGRADE>
       <M-ORCHESTRATION-PROFILES><Name>OrchestrationProfiles</Name><Type>CORE_LOGIC</Type><Status>implemented</Status><Purpose>Define profile names, backward-compatible defaults, strict parsing, and one concrete vv-controller policy per profile.</Purpose><Paths>src/lib/orchestration.ts</Paths><Depends>none</Depends><Verification>V-M-ORCHESTRATION-PROFILES</Verification></M-ORCHESTRATION-PROFILES>
       <M-CLI-ORCHESTRATION><Name>OrchestrationCommand</Name><Type>ENTRY_POINT</Type><Status>implemented</Status><Purpose>Show scoped effective profile and source without mutation; set explicit profiles with bootstrap, preservation, and restart guidance.</Purpose><Paths>src/commands/orchestration.ts</Paths><Depends>M-CONFIG-LAYERS, M-CLI-CONFIG, M-ORCHESTRATION-PROFILES</Depends><Verification>V-M-CLI-ORCHESTRATION</Verification></M-CLI-ORCHESTRATION>
-      <DF-PLUGIN-INSTALL>vvoc init or install resolves config paths, registers the pinned runtime package and TUI subpath, syncs managed agents and skills, writes canonical vvoc schema v3, and verifies status.</DF-PLUGIN-INSTALL>
+      <DF-PLUGIN-INSTALL>vvoc init or install resolves config paths, registers the pinned base package for both server and TUI loading, syncs managed agents and skills, writes canonical vvoc schema v3, and verifies status.</DF-PLUGIN-INSTALL>
       <DF-CONFIG-SYNC>vvoc sync strict-parses current vvoc config, preserves valid role/plugin values and unrelated TUI JSONC entries, refreshes managed presets/prompts/skills, and rewrites managed runtime/TUI registrations.</DF-CONFIG-SYNC>
       <DF-LAYERED-CONFIG>Commands and runtime resolve vvoc, OpenCode runtime, and OpenCode TUI env overrides, nearest project layer, global layer, then defaults where permitted.</DF-LAYERED-CONFIG>
       <DF-VVOC-LAUNCH>vvoc launch selects OpenCode runtime and vvoc config paths, conditionally pins an existing TUI config with OPENCODE_TUI_CONFIG, forwards passthrough args, and preserves child exit code.</DF-VVOC-LAUNCH>

.grace/verification/main.xml

@@ -8,7 +8,7 @@
       <FreshEvidence>Completion claims require fresh command output or documented blockers.</FreshEvidence>
     </GlobalPolicy>
     <CriticalFlows>
-      <VF-PLUGIN-INSTALL><Flow>DF-PLUGIN-INSTALL</Flow><Priority>high</Priority><Expected>Pinned runtime plugin specifier, dedicated TUI subpath registration, vv-controller default agent, managed agents/skills, tools.apply_patch false, role-reference model fields, and seeded vvoc schema v3.</Expected></VF-PLUGIN-INSTALL>
+      <VF-PLUGIN-INSTALL><Flow>DF-PLUGIN-INSTALL</Flow><Priority>high</Priority><Expected>Pinned base package specifier for server and TUI loading, legacy TUI subpath migration, vv-controller default agent, managed agents/skills, tools.apply_patch false, role-reference model fields, and seeded vvoc schema v3.</Expected></VF-PLUGIN-INSTALL>
       <VF-CONFIG-SYNC><Flow>DF-CONFIG-SYNC</Flow><Priority>high</Priority><Expected>Canonical vvoc schema v3 and managed runtime/TUI registrations are refreshed while role assignments, plugin toggles, unrelated TUI settings, and tuple options survive; invalid current configs fail before rewrite.</Expected></VF-CONFIG-SYNC>
       <VF-STRICT-CURRENT-CUTOVER><Flow>DF-CONFIG-SYNC, DF-UPGRADE, DF-GUARDIAN-REVIEW, DF-HASHLINE-EDIT</Flow><Priority>high</Priority><Expected>Old configs, SDK paths, and hash algorithms fail loudly or are ignored rather than repaired or used as compatibility fallbacks.</Expected></VF-STRICT-CURRENT-CUTOVER>
       <VF-LAYERED-CONFIG><Flow>DF-LAYERED-CONFIG</Flow><Priority>high</Priority><Expected>vvoc, runtime, and TUI reads choose env, nearest project, global, then defaults where allowed; project writes stay inside selected project root.</Expected></VF-LAYERED-CONFIG>
@@ -32,7 +32,7 @@
       <VF-ORCHESTRATION-PROFILE><Flow>DF-ORCHESTRATION-PROFILE, DF-PRESET-SWITCH, DF-SYSTEM-CONTEXT, DF-WORKFLOW-GUIDANCE</Flow><Priority>high</Priority><Expected>Effective startup config resolves one profile; vv-controller receives only its concrete policy; old v3 config defaults to balanced; preset writes are atomic; invalid explicit values fail without fallback.</Expected></VF-ORCHESTRATION-PROFILE>
       <V-M-MODEL-ROLES><TestFiles><File>src/lib/model-roles.test.ts</File></TestFiles><Checks><Command>bun test src/lib/model-roles.test.ts</Command><Command>bun x tsc --noEmit</Command></Checks></V-M-MODEL-ROLES>
       <V-M-CONFIG-LAYERS><TestFiles><File>src/lib/config-layers.test.ts</File></TestFiles><Checks><Command>bun test src/lib/config-layers.test.ts</Command><Command>bun run typecheck</Command></Checks><Expected>Global/project/effective runtime and TUI sources honor env precedence, json/jsonc selection, and project-local write boundaries.</Expected></V-M-CONFIG-LAYERS>
-      <V-M-CLI-CONFIG><TestFiles><File>src/lib/opencode.test.ts</File><File>src/lib/managed-agents.test.ts</File><File>src/commands/sync.test.ts</File></TestFiles><Checks><Command>bun test src/lib/opencode.test.ts src/commands/sync.test.ts</Command><Command>bun run lint</Command><Command>bun run fmt:check</Command></Checks><Expected>Dedicated tui.json(c) mutation preserves comments, unrelated entries, and tuple options; install/sync is idempotent and inspection reports parse and registration state.</Expected></V-M-CLI-CONFIG>
+      <V-M-CLI-CONFIG><TestFiles><File>src/lib/opencode.test.ts</File><File>src/lib/managed-agents.test.ts</File><File>src/commands/sync.test.ts</File></TestFiles><Checks><Command>bun test src/lib/opencode.test.ts src/commands/sync.test.ts</Command><Command>bun run lint</Command><Command>bun run fmt:check</Command></Checks><Expected>Dedicated tui.json(c) mutation writes the pinned base package, migrates legacy subpath specs, preserves comments, unrelated entries, and tuple options; host compatibility, install/sync idempotence, parse state, and registration state are deterministic.</Expected></V-M-CLI-CONFIG>
       <V-M-RELEASE-AUTOMATION><TestFiles><File>scripts/release-check.test.ts</File><File>scripts/release-summary.test.ts</File></TestFiles><Checks><Command>bun run scripts/check-exports.ts</Command><Command>bun run release:check</Command><Command>bun run typecheck</Command><Command>bun run fmt:check</Command><Command>bun run pack:check</Command></Checks></V-M-RELEASE-AUTOMATION>
       <V-M-CLI-MANAGED-AGENTS><TestFiles><File>src/lib/managed-agents.test.ts</File></TestFiles><Checks><Command>bun test src/lib/managed-agents.test.ts</Command><Command>bun x tsc --noEmit</Command></Checks></V-M-CLI-MANAGED-AGENTS>
       <V-M-CLI-MANAGED-SKILLS><TestFiles><File>src/lib/opencode.test.ts</File><File>src/lib/managed-skills.test.ts</File></TestFiles><Checks><Command>bun test src/lib/opencode.test.ts</Command><Command>bun test src/lib/managed-skills.test.ts</Command><Command>bun x tsc --noEmit</Command><Command>bun run lint</Command><Command>bun run fmt:check</Command></Checks></V-M-CLI-MANAGED-SKILLS>

AGENTS.md

@@ -218,8 +218,9 @@ File-local reference:
 - Canonical `vvoc.json` is strict schema v3. Invalid or old existing config must fail
   loudly instead of being silently migrated or repaired.
 - `vvoc install` must keep a pinned package specifier in the OpenCode plugin array.
-- `vvoc install`, `init`, and `sync` must keep `@osovv/vv-opencode/tui` in the TUI plugin
-  array without removing comments, unrelated settings, plugin entries, or tuple options.
+- `vvoc install`, `init`, and `sync` must keep the current pinned base package specifier in
+  the TUI plugin array so OpenCode selects its `./tui` export, migrating legacy `/tui` specs
+  without removing comments, unrelated settings, plugin entries, or tuple options.
 - Runtime plugins share the startup config snapshot; config changes require an OpenCode
   restart rather than live reload behavior.