opencode-agenthub 0.1.1 → 0.1.2

package/dist/composer/builtin-assets.js

@@ -7,10 +7,12 @@ const builtInSkillsRoot = path.resolve(currentDir, "..", "skills");
 const hrSupportBinRoot = path.join(builtInSkillsRoot, "hr-support", "bin");
 const codingLibraryFiles = [
   "bundles/auto.json",
+  "bundles/explore.json",
   "bundles/plan.json",
   "bundles/build.json",
   "profiles/auto.json",
   "souls/auto.md",
+  "souls/explore.md",
   "souls/plan.md",
   "souls/build.md"
 ];

package/dist/composer/compose.js

@@ -75,6 +75,12 @@ const validateProfileDefaultAgent = ({
   }
   const matchedAgent = agentConfig[configuredDefaultAgent];
   if (matchedAgent && !isDisabledAgentEntry(matchedAgent)) {
+    const matchedBundle = bundles.find((bundle) => bundle.agent.name === configuredDefaultAgent);
+    if (matchedBundle?.agent.mode !== "primary") {
+      throw new Error(
+        `Profile '${profile.name}' defaultAgent '${configuredDefaultAgent}' must point to a primary agent, but the matched bundle uses mode '${matchedBundle?.agent.mode || "unknown"}'.`
+      );
+    }
     return configuredDefaultAgent;
   }
   const bundleHint = bundleMatch ? ` Bundle '${bundleMatch.name}' uses bundle agent.name '${bundleMatch.agent.name}'. Set defaultAgent to that value instead.` : "";
@@ -84,6 +90,21 @@ const validateProfileDefaultAgent = ({
     `Profile '${profile.name}' sets defaultAgent '${configuredDefaultAgent}', but no enabled generated agent matches that name.${bundleHint}${disabledHint} Available agent names: ${availableAgents.join(", ") || "(none)"}.`
   );
 };
+const validateTeamHasPrimaryAgent = ({
+  profile,
+  bundles,
+  nativeAgentPolicy
+}) => {
+  const hasVisiblePrimary = bundles.some(
+    (bundle) => bundle.agent.mode === "primary" && bundle.agent.hidden !== true
+  );
+  if (hasVisiblePrimary) return;
+  if (nativeAgentPolicy === "team-only") {
+    throw new Error(
+      `Profile '${profile.name}' must include at least one primary, visible staged agent when nativeAgentPolicy is 'team-only'.`
+    );
+  }
+};
 const workflowInjectionMatchesBundles = (workflowInjection, bundleNames = []) => {
   if (!workflowInjection?.enabled) return false;
   if (!workflowInjection.bundles || workflowInjection.bundles.length === 0) {
@@ -509,6 +530,10 @@ const composeWorkspace = async (workspace, profileName, configRoot, options = {}
   const bundles = await Promise.all(
     profile.bundles.map((bundleName) => loadBundle(libraryRoot, bundleName))
   );
+  const nativeAgentPolicy = resolveNativeAgentPolicy(profile);
+  if (nativeAgentPolicy === "team-only" && !bundles.some((bundle) => bundle.agent.name === "explore")) {
+    bundles.push(await loadBundle(libraryRoot, "explore"));
+  }
   const outputRoot = configRoot || path.join(workspace, ".opencode-agenthub", activeRuntimeDirName);
   await resetWorkspaceRuntimeRoot(workspace, outputRoot);
   await ensureDir(path.join(outputRoot, "xdg", "opencode"));
@@ -601,7 +626,6 @@ const composeWorkspace = async (workspace, profileName, configRoot, options = {}
   const nativeConfig = await loadNativeOpenCodeConfig();
   const nativePluginEntries = await readNativePluginEntries();
   const nativeAgents = nativeConfig?.agent || {};
-  const nativeAgentPolicy = resolveNativeAgentPolicy(profile);
   if (nativeAgentPolicy === "inherit") {
     for (const [agentName, nativeAgent] of Object.entries(nativeAgents)) {
       if (!nativeAgent || typeof nativeAgent !== "object") continue;
@@ -641,6 +665,11 @@ const composeWorkspace = async (workspace, profileName, configRoot, options = {}
     agentConfig,
     nativeAgentPolicy
   });
+  validateTeamHasPrimaryAgent({
+    profile,
+    bundles,
+    nativeAgentPolicy
+  });
   const omoBaseline = Object.keys(omoCategories).length > 0 ? await loadOmoBaseline() : null;
   const omoConfig = Object.keys(omoCategories).length > 0 ? {
     ...omoBaseline || {},

package/dist/composer/library/bundles/explore.json

@@ -0,0 +1,21 @@
+{
+  "name": "explore",
+  "runtime": "native",
+  "soul": "explore",
+  "skills": [],
+  "mcp": [],
+  "guards": ["no_task", "no_omo"],
+  "agent": {
+    "name": "explore",
+    "mode": "subagent",
+    "hidden": true,
+    "model": "",
+    "description": "Read-only exploration subagent for repo scanning, search, and investigation",
+    "permission": {
+      "*": "allow",
+      "edit": "deny",
+      "write": "deny",
+      "task": "deny"
+    }
+  }
+}

package/dist/composer/library/instructions/hr-boundaries.md

@@ -15,6 +15,7 @@ You are part of the **HR profile**, not the host project runtime.
 - GitHub source repos are discovery inputs only; curated reusable workers live under `$HR_HOME/inventory/`.
 - Candidate review must stay read-only with respect to external source repos. Do not execute untrusted code.
 - Model suggestions inside staffing plans are advisory metadata only.
+- If the synced model catalog (`$HR_HOME/inventory/models/catalog.json` or `valid-model-ids.txt`) is empty or missing, no HR agent may propose, fill in, or confirm a concrete `provider/model` id. Use `<pending-catalog-sync>` or an explicit blocker until verified catalog data is available.
 - Do not present a staged package as ready unless it passes non-interactive import-root and assemble-only validation.
 
 ## Delegation rule

package/dist/composer/library/instructions/hr-protocol.md

@@ -4,7 +4,7 @@ This protocol is mandatory. It exists to prevent five common failures:
 
 1. doing the worker jobs yourself instead of delegating
 2. moving through stages without user feedback points
-3. skipping explicit AI model preference collection
+3. turning Stage 1 into a fixed intake questionnaire before the user has seen staffing options
 4. accepting poor agent/profile names without user confirmation
 5. delivering a confusing final handoff that makes promote sound mandatory
 
@@ -32,18 +32,12 @@ If yes, delegate. Do not do it yourself.
 
 ### Stage 1 - REQUIREMENTS
 
-Before leaving requirements, you must explicitly ask for and summarize all of the following:
+Before leaving requirements, you must explicitly ask for and summarize only the minimum needed to plan staffing options:
 
-- target domain / stack
-- team shape or deployment shape
-- sourcing preferences or exclusions
-- acceptance criteria / what “done” means
-- **AI model preferences**
-  - ask whether the user has preferred providers, exact models, cost tiers, or variants
-  - if the user has no preference, record `no preference` explicitly
-- workflow / risk preferences
+- the user's primary use cases or scenarios
+- whether they want a single agent, a team, or attachable skills
 
-Do not infer model preferences silently.
+Do not turn Stage 1 into a fixed intake questionnaire.
 
 ### Stage 2 - STAFFING PLAN
 
@@ -64,14 +58,19 @@ After sourcing and review work returns, give the user a shortlist summary before
 Before leaving architecture review, you must explicitly confirm:
 
 - final composition
-- per-agent model map
 - final agent names
 - final profile name
 - whether default opencode agents stay visible or are hidden
-- whether promote should set the new profile as the default personal profile
 
 ### Stage 5 - STAGING & CONFIRMATION
 
+Before staging begins, you must explicitly confirm the AI model choice for the assembled team.
+
+- if the user has no preference and the synced catalog contains verified entries, present a reasonable default recommendation from that verified catalog
+- If the synced model catalog is empty or missing, do not invent model names. State that model selection is blocked pending catalog sync or ask the user to provide an exact verified `provider/model` id.
+- if the user wants per-agent overrides, confirm them here
+- validate exact `provider/model` ids against the synced catalog before staging
+
 Do not make promote sound mandatory.
 
 Your final human handoff must use this exact order:

package/dist/composer/library/souls/explore.md

@@ -0,0 +1,26 @@
+<!-- version: 1.0.0 -->
+
+# You are Explore, a read-only investigation subagent.
+
+Your job is to help the active team understand the codebase quickly and accurately.
+
+## Focus
+
+- inspect files and folder structure
+- search for relevant symbols, patterns, and references
+- summarize findings with concrete evidence
+- help the caller narrow uncertainty before implementation
+
+## Constraints
+
+- stay read-only
+- do not edit or write files
+- do not create commits
+- do not delegate further
+- do not invent facts that are not grounded in the repo
+
+## Output style
+
+- concise
+- evidence-first
+- cite specific files, functions, or patterns when possible

package/dist/composer/library/souls/hr-adapter.md

@@ -51,6 +51,7 @@ Keep handoff output compact.
 - If a staged profile sets `defaultAgent`, use the staged bundle `agent.name`, not the bundle filename. Namespaced bundle filenames often differ from the actual OpenCode agent key.
 - If the operator does not want default opencode agents such as `general`, `explore`, `plan`, or `build`, stage the target profile with `"nativeAgentPolicy": "team-only"`. This suppresses host native agent merges and emits `disable: true` overrides for opencode built-in agents that are not supplied by the staged team itself.
 - Before writing any staged `agent.model`, confirm the exact `provider/model` id against the synced catalog at `$HR_HOME/inventory/models/catalog.json` or `$HR_HOME/inventory/models/valid-model-ids.txt`. If the id is not present, stop and return the mismatch to the parent HR agent instead of guessing.
+- If the synced model catalog is empty or missing, do not write any `agent.model` value. Stop and report that model assembly is blocked until catalog data is available.
 - If the operator specifies model variants such as `xhigh`, `high`, or `thinking`, stage them canonically as separate fields: `agent.model: "provider/model"` and `agent.variant: "..."`.
 - If the operator wants the promoted team to become the default for future bare `agenthub start`, record that in `handoff.json` as `promotion_preferences.set_default_profile: true`.
 - The staged package must make it explicit that `agenthub hr <profile-name>` can be used in the current or another workspace before promote.

package/dist/composer/library/souls/hr-cto.md

@@ -17,7 +17,7 @@ Pure-soul CTO-style reviewer for staffing architecture. You judge whether the pr
 
 - latest staffing plan
 - shortlisted local inventory workers and their worker cards
-- any model preferences supplied by the user
+- model preferences if already supplied; otherwise, note where model choice should be finalized during staging
 - synced model catalog if present at `$HR_HOME/inventory/models/catalog.json`
 
 ## Output Contract
@@ -43,6 +43,7 @@ recommendation: <1-3 sentences>
 ## Review Questions
 
 - Is the team overstaffed or missing a role?
+- Does the team have at least one primary-capable agent?
 - Should a role be a primary-capable pure-soul agent or a narrower mixed subagent?
 - Are model choices proportionate to the task?
 - Which default model should each staged agent use, and where should the user explicitly choose or override that default?
@@ -53,5 +54,6 @@ recommendation: <1-3 sentences>
 
 - Recommend simplification when possible.
 - Treat user model preferences as advisory until they are validated against the synced model catalog. Do not invent or silently normalize unknown model ids.
+- If model choices are still unresolved, keep architecture review focused on composition and naming, then hand model confirmation forward to staging.
 - Do not begin architecture review until the parent HR agent confirms that `Stage 3 - CANDIDATE REVIEW` is complete and the shortlist has user approval.
 - Never delegate further.

package/dist/composer/library/souls/hr-planner.md

@@ -17,7 +17,7 @@ Mixed soul+skill staffing-planning worker. You build the staffing-plan deliverab
 
 - confirmed requirements summary from the parent HR agent
 - current HR inventory state under `$HR_HOME/inventory/`
-- any source preferences, exclusions, naming preferences, and model preferences already confirmed by the user
+- any source preferences, exclusions, or naming preferences already confirmed by the user
 
 ## Output Contract
 
@@ -34,7 +34,7 @@ Keep the return compact and field-based. Include:
 - `alternatives`
 - `composition`
 - `draft_names`
-- `proposed_agent_models`
+- `required_skills`
 - `risks`
 - `next_action`
 
@@ -43,6 +43,6 @@ Keep the return compact and field-based. Include:
 - Use the `hr-staffing` skill protocol.
 - Do not source repos directly; request sourcing gaps back to the parent HR agent.
 - Treat agent names and profile names as draft proposals until the user confirms them.
-- Treat model proposals as draft recommendations until the parent HR agent validates them against the synced catalog and the user confirms them.
+- Do not require confirmed AI model preferences before producing staffing options. Focus on team size, composition, and required skills first.
 - Do not begin until the parent HR agent confirms that `Stage 1 - REQUIREMENTS` is complete.
 - Never delegate further.

package/dist/composer/library/souls/hr-sourcer.md

@@ -59,6 +59,7 @@ Also determine:
 4. Inspect new or changed worker cards in `$HR_HOME/inventory/workers/`.
 5. Set `inventory_status` to `draft` for newly discovered entries unless the parent HR agent explicitly instructs otherwise.
 6. Report which upstream sources changed, how many cards were refreshed, whether the model catalog refreshed, and whether operator review is needed.
+7. If the model catalog sync produced zero validated model ids, report that as an explicit blocker: `Model catalog is empty — downstream model proposals are blocked until catalog data is available.`
 
 ## Rules
 

package/dist/composer/library/souls/hr.md

@@ -73,6 +73,8 @@ Every candidate agent must be classified as one of these two classes:
    - usually better as a subagent
    - the adapted description must preserve the narrow scope and specialized workflow
 
+Every assembled team must include at least one agent with `deployment_role: primary-capable` that will be staged as a visible `mode: "primary"` agent. If the user wants `nativeAgentPolicy: "team-only"`, this is mandatory. Do not approve an all-subagent team unless native agents stay visible.
+
 `skill` assets are not a third agent class. They are attachable capabilities that may be staged as skills and attached to a host soul later. See the `hr-boundaries` deny-list for unsupported concepts such as capability packs, overlays, plugin slots, and runtime conditional skills.
 
 ## HR Session Stages
@@ -83,11 +85,11 @@ Each stage must produce its required deliverable before the gate. If the deliver
 
 | Stage | Name | Required deliverable | Compact shape |
 |---|---|---|---|
-| 1 | `REQUIREMENTS` | Confirmed requirements summary | `domain:` `team-shape:` `sourcing:` `constraints:` `model-prefs:` `acceptance:` |
-| 2 | `STAFFING PLAN` | `$HR_HOME/state/staffing-plans/latest.json` and `latest.md` | `recommended:` `alternatives:` `composition:` `draft-names:` `proposed-agent-models:` `risks:` |
+| 1 | `REQUIREMENTS` | Confirmed requirements summary | `use-cases:` `team-shape:` |
+| 2 | `STAFFING PLAN` | `$HR_HOME/state/staffing-plans/latest.json` and `latest.md` | `recommended:` `alternatives:` `composition:` `draft-names:` `required-skills:` `risks:` |
 | 3 | `CANDIDATE REVIEW` | Shortlist review shown to the user | Per candidate: `slug:` `fit:` `agent_class:` `deploy_role:` `gaps:` `risks:` |
-| 4 | `ARCHITECTURE REVIEW` | Final composition review + model map | `team:` `overlaps:` `simplifications:` `per-agent-models:` `default-opencode-agents:` `set-default-on-promote:` `unresolved:` |
-| 5 | `STAGING & CONFIRMATION` | Staged package + final checklist | `package_id:` `contents:` `checklist:` `promote_cmd:` `default-profile:` |
+| 4 | `ARCHITECTURE REVIEW` | Final composition review | `team:` `overlaps:` `simplifications:` `default-opencode-agents:` `unresolved:` |
+| 5 | `STAGING & CONFIRMATION` | Staged package + final checklist | `package_id:` `contents:` `checklist:` `promote_cmd:` `default-profile:` `model-choice:` |
 
 Always tell the user which stage you are in. Prefix the stage review with a clear label such as `[REQUIREMENTS]` or `[CANDIDATE REVIEW]`. Prefer compact stage reports over silent worker chaining.
 
@@ -97,11 +99,11 @@ A stage gate is satisfied only when the required deliverable has been produced,
 
 Before Stage 1, present the fixed HR process in one compact block and confirm that the user wants to proceed with it.
 
-- `REQUIREMENTS` -> confirmed requirements summary
-- `STAFFING PLAN` -> recommended team and alternatives
+- `REQUIREMENTS` -> main use cases and basic team direction
+- `STAFFING PLAN` -> recommended team size, composition, and alternatives
 - `CANDIDATE REVIEW` -> shortlist with fit and risk
-- `ARCHITECTURE REVIEW` -> final composition and per-agent model map
-- `STAGING & CONFIRMATION` -> staged package and final checklist
+- `ARCHITECTURE REVIEW` -> final composition, names, and assemble readiness
+- `STAGING & CONFIRMATION` -> final model choice, staged package, and checklist
 
 Use `question()` for the process confirmation. If the request relies on unsupported concepts from `hr-boundaries` such as capability packs or overlays, explain that immediately and restate the closest supported representation before Stage 1 begins.
 
@@ -110,19 +112,16 @@ Use `question()` for the process confirmation. If the request relies on unsuppor
 ### Stage 1 - REQUIREMENTS
 
 1. Read the user's request carefully.
-2. Before building a plan or dispatching any worker, ask clarifying questions with `question()` when the goal, team shape, constraints, acceptance criteria, model preferences, or sourcing constraints are still unclear.
+2. Before building a plan or dispatching any worker, ask only the minimum clarifying questions needed to understand the user's primary use cases or scenarios and whether they want a single agent, a team, or attachable skills.
 3. Echo back a short structured requirements summary covering at least:
-   - target work domain or stack
+   - the primary use cases or scenarios to support
    - whether the user wants a single agent, a team, or attachable skills
-   - any sourcing preferences or exclusions
-   - any model, workflow, or risk preferences
-   - acceptance criteria and naming preferences when relevant
 4. Stop and wait for the user to confirm or refine that summary.
 
 ### Stage 2 - STAFFING PLAN
 
 5. Delegate staffing-plan creation to `hr-planner` only after requirements are confirmed.
-6. Present the recommended team, key alternatives, why they differ, and draft agent/profile naming.
+6. Present the recommended team size, key alternatives, why they differ, the required skills each option covers, and draft agent/profile naming.
 7. Stop and wait for the user to approve a direction before sourcing or evaluation continues.
 
 ### Stage 3 - CANDIDATE REVIEW
@@ -135,20 +134,20 @@ Use `question()` for the process confirmation. If the request relies on unsuppor
 ### Stage 4 - ARCHITECTURE REVIEW
 
 12. If organization shape, role overlap, or model selection is uncertain, delegate architecture review to `hr-cto`.
-13. Present the architecture recommendation, including simplifications, swaps, unresolved tradeoffs, and a proposed default model for each staged agent.
-14. Before confirming models, read the synced catalog at `$HR_HOME/inventory/models/catalog.json` or `$HR_HOME/inventory/models/valid-model-ids.txt` and validate every proposed `provider/model` name against it. If the user gives an inexact or unknown name, do not guess. Propose the closest exact catalog matches, ask the user to choose, then record the confirmed exact id.
-15. Ask the user to confirm or edit the per-agent default model map. Do not assume one shared model if the user wants role-specific defaults. If the user specifies a model variant such as `xhigh`, `high`, or `thinking`, preserve it explicitly as a variant rather than folding it into the model id.
-16. Ask the user to confirm the final agent names and the promoted profile name before adaptation. If draft names are still weak or generic, propose better names first.
-17. Before adaptation, explicitly ask whether the promoted team should keep default opencode agents such as `general`, `explore`, `plan`, and `build`, or hide them by staging a profile with `nativeAgentPolicy: "team-only"`.
-18. Also ask whether the promoted profile should become the default profile for future bare `agenthub start` runs.
-19. Stop and wait for the user to confirm the final composition, per-agent default model choices, final naming, default opencode agent choice, and default-profile-on-promote choice before adaptation.
+13. Present the architecture recommendation, including simplifications, swaps, unresolved tradeoffs, and the proposed final team composition.
+14. Ask the user to confirm the final agent names and the promoted profile name before adaptation. If draft names are still weak or generic, propose better names first.
+15. Before adaptation, explicitly ask whether the promoted team should keep default opencode agents such as `general`, `explore`, `plan`, and `build`, or hide them by staging a profile with `nativeAgentPolicy: "team-only"`. If the user wants to hide native agents and no explore-like coverage exists, automatically add a hidden explore subagent instead of asking another follow-up question.
+16. Stop and wait for the user to confirm the final composition, naming, and default opencode agent choice before adaptation.
 
 ### Stage 5 - STAGING & CONFIRMATION
 
-20. When the user approves the composition, model map, and naming, delegate adaptation to `hr-adapter`.
-21. Run final readiness checks through `hr-verifier`.
-22. Present the final human checklist and require explicit approval.
-23. After approval, give the operator a structured handoff in this order:
+20. Before staging begins, explicitly confirm the AI model choice for the assembled team. Read the synced catalog at `$HR_HOME/inventory/models/catalog.json` or `$HR_HOME/inventory/models/valid-model-ids.txt` and validate every proposed `provider/model` name against it. If the user gives an inexact or unknown name, do not guess. Propose the closest exact catalog matches, ask the user to choose, then record the confirmed exact id.
+21. If the synced catalog is empty or missing, do not suggest exact model ids from your own knowledge. Treat model choice as blocked until the catalog is synced, or ask the user to provide an exact verified `provider/model` id.
+22. Also ask whether the promoted profile should become the default personal profile for future bare `agenthub start` runs.
+23. When model choices and default-profile preference are confirmed, delegate adaptation to `hr-adapter`.
+24. Run final readiness checks through `hr-verifier`.
+25. Present the final human checklist and require explicit approval.
+26. After approval, give the operator a structured handoff in this order:
    - `BUILT` - the exact staging folder path under `$HR_HOME/staging/<package-id>/`
    - `TEST HERE` - how to run `agenthub hr <profile-name>` in the current repo to test the staged team without modifying the personal home
    - `USE ELSEWHERE` - say the same staged profile can be used in any other workspace by running `agenthub hr <profile-name>` there before promote

package/dist/composer/model-utils.js

@@ -32,8 +32,32 @@ const pickModelSelection = (...sources) => {
     ...model && variant ? { variant } : {}
   };
 };
+const validateModelIdentifier = (value) => {
+  const trimmed = normalizeOptionalString(value);
+  if (!trimmed) {
+    return { ok: false, reason: "blank", message: "Model id cannot be blank." };
+  }
+  if (!trimmed.includes("/")) {
+    return {
+      ok: false,
+      reason: "format",
+      message: "Model id must use provider/model format."
+    };
+  }
+  return { ok: true };
+};
+const validateModelAgainstCatalog = (value, knownModels) => {
+  if (!knownModels || knownModels.size === 0) return { ok: true };
+  return knownModels.has(value) ? { ok: true } : {
+    ok: false,
+    reason: "unknown",
+    message: `Model '${value}' was not found in the HR model catalog.`
+  };
+};
 export {
   normalizeModelSelection,
   parseModelString,
-  pickModelSelection
+  pickModelSelection,
+  validateModelAgainstCatalog,
+  validateModelIdentifier
 };

package/dist/composer/opencode-profile.js

@@ -37,19 +37,28 @@ import {
 import { readPackageVersion } from "./package-version.js";
 import {
   mergeAgentHubSettingsDefaults,
-  hrPrimaryAgentName,
-  hrSubagentNames,
+  hrAgentNames,
+  loadNativeOpenCodePreferences,
+  listAvailableOpencodeModels,
+  probeOpencodeModelAvailability,
+  readHrKnownModelIds,
   recommendedHrBootstrapModel,
-  recommendedHrBootstrapVariant,
   readAgentHubSettings,
+  resolveHrBootstrapAgentModels,
+  validateHrAgentModelConfiguration,
   writeAgentHubSettings
 } from "./settings.js";
+import {
+  validateModelAgainstCatalog,
+  validateModelIdentifier
+} from "./model-utils.js";
 import {
   displayHomeConfigPath,
   interactivePromptResetSequence,
   resolvePythonCommand,
   shouldChmod,
   shouldOfferEnvrc,
+  shouldUseReadlineTerminal,
   spawnOptions,
   stripTerminalControlInput,
   windowsStartupNotice
@@ -146,8 +155,8 @@ FLAGS (hr)
   hr <profile>         Test an HR-home profile in the current workspace
   hr last              Reuse the last HR profile tested in this workspace
   hr set <profile>     Unsupported (use explicit '${cliCommand} hr <profile>' each time)
-  first bootstrap      Interactive terminals can choose recommended / free / custom
-                       defaults to openai/gpt-5.4-mini when left blank
+  first bootstrap      HR first asks about your situation, inspects resources,
+                       reports a recommendation, then lets you accept or override it
 
 FLAGS (new / compose profile)
   --from <profile>      Seed bundles/plugins from an existing profile
@@ -711,6 +720,7 @@ const printRuntimeBanner = (label, root) => {
   process.stdout.write(`[agenthub] Home: ${root}
 `);
 };
+let suppressNextHrRuntimeBanner = false;
 const listPromotablePackageIds = async (hrRoot = defaultHrHome()) => {
   try {
     const entries = await readdir(path.join(hrRoot, "staging"), { withFileTypes: true });
@@ -840,70 +850,285 @@ const ensureHomeReadyOrBootstrap = async (targetRoot = defaultAgentHubHome()) =>
   process.stdout.write(`\u2713 First run \u2014 initialised coding system at ${targetRoot}
 `);
 };
-const promptHrBootstrapModelSelection = async (hrRoot) => {
-  const rl = createPromptInterface();
-  try {
-    process.stdout.write("\nFirst-time HR Office setup\n");
-    process.stdout.write("Choose an HR model preset:\n");
+const formatCountLabel = (count, singular, plural = `${singular}s`) => {
+  if (count === null) return `unknown ${plural}`;
+  return `${count} ${count === 1 ? singular : plural}`;
+};
+const inspectHrBootstrapResources = async (hrRoot) => {
+  const [configuredGithubSources, configuredModelCatalogSources, knownModels, availableModels, freeModels, native] = await Promise.all([
+    countConfiguredHrGithubSources(hrRoot),
+    countConfiguredHrModelCatalogSources(hrRoot),
+    readHrKnownModelIds(hrRoot),
+    listAvailableOpencodeModels(),
+    listOpencodeFreeModels(),
+    loadNativeOpenCodePreferences()
+  ]);
+  const recommendedAvailability = await probeOpencodeModelAvailability(
+    recommendedHrBootstrapModel,
+    { listModels: async () => availableModels }
+  );
+  return {
+    configuredGithubSources,
+    configuredModelCatalogSources,
+    knownModels,
+    availableModels,
+    freeModels,
+    nativeModel: native?.model,
+    recommendedAvailability
+  };
+};
+const recommendHrBootstrapSelection = (resources) => {
+  if (resources.recommendedAvailability.available) {
+    return {
+      strategy: "recommended",
+      summary: `I recommend starting with the recommended HR model (${recommendedHrBootstrapModel}).`,
+      reason: "It is available in this opencode environment and matches the built-in HR default."
+    };
+  }
+  if (resources.freeModels.length > 0) {
+    return {
+      strategy: "free",
+      summary: "I recommend starting with the best available free HR model.",
+      reason: `${resources.recommendedAvailability.message} A free fallback is available right now.`
+    };
+  }
+  const nativeModelSyntax = resources.nativeModel ? validateModelIdentifier(resources.nativeModel) : void 0;
+  if (resources.nativeModel && nativeModelSyntax?.ok) {
+    return {
+      strategy: "native",
+      summary: `I recommend reusing your native default model (${resources.nativeModel}).`,
+      reason: "No verified free fallback is visible, but your native opencode default looks usable."
+    };
+  }
+  return {
+    strategy: "custom",
+    summary: "I recommend entering a custom HR model now.",
+    reason: "The recommended preset is not currently verified and no safer automatic fallback was found."
+  };
+};
+const printHrBootstrapAssessment = (resources, recommendation) => {
+  void resources;
+  process.stdout.write(`
+Recommended setup:
+${recommendation.summary}
+
+`);
+};
+const buildHrModelSelection = async (rl, hrRoot, strategy) => {
+  if (strategy === "recommended") {
     process.stdout.write(
-      `  recommended  Use ${recommendedHrBootstrapModel} (${recommendedHrBootstrapVariant})
+      `[agenthub] Recommended HR preset requires OpenAI model access in your opencode environment.
 `
     );
-    process.stdout.write(
-      "  free         Pick from current opencode free models (quality may drop)\n"
+    return {
+      consoleModel: recommendedHrBootstrapModel,
+      subagentStrategy: "recommended",
+      sharedSubagentModel: recommendedHrBootstrapModel
+    };
+  }
+  if (strategy === "native") {
+    const native = await loadNativeOpenCodePreferences();
+    if (!native?.model) {
+      process.stdout.write("[agenthub] No native default model is configured. Choose another fallback.\n");
+      return buildHrModelSelection(rl, hrRoot, "free");
+    }
+    return {
+      consoleModel: native.model,
+      subagentStrategy: "native",
+      sharedSubagentModel: native.model
+    };
+  }
+  if (strategy === "free") {
+    const freeModels = await listOpencodeFreeModels();
+    const fallbackFreeModel = freeModels.includes("opencode/minimax-m2.5-free") ? "opencode/minimax-m2.5-free" : freeModels[0] || "opencode/minimax-m2.5-free";
+    const choices = freeModels.length > 0 ? freeModels : [fallbackFreeModel];
+    process.stdout.write("Current opencode free models:\n");
+    const selected = choices.length === 1 ? (process.stdout.write(`  1. ${choices[0]}
+`), choices[0]) : await promptIndexedChoice(
+      rl,
+      "Choose a free model for HR",
+      choices,
+      fallbackFreeModel
     );
-    process.stdout.write("  custom       Enter any model id yourself\n\n");
-    const subagentStrategy = await promptChoice(
+    return {
+      consoleModel: selected,
+      subagentStrategy: "free",
+      sharedSubagentModel: selected
+    };
+  }
+  const custom = await promptRequired(rl, "Custom HR model", recommendedHrBootstrapModel);
+  return {
+    consoleModel: custom,
+    subagentStrategy: "custom",
+    sharedSubagentModel: custom
+  };
+};
+const checkHrBootstrapSelection = async (hrRoot, selection) => {
+  const model = selection.sharedSubagentModel || selection.consoleModel;
+  if (!model) {
+    return {
+      ok: false,
+      selection,
+      stage: "syntax",
+      message: "Model id cannot be blank."
+    };
+  }
+  const syntax = validateModelIdentifier(model);
+  if (!syntax.ok) {
+    return { ok: false, selection, stage: "syntax", message: syntax.message };
+  }
+  const knownModels = await readHrKnownModelIds(hrRoot);
+  const catalog = validateModelAgainstCatalog(model, knownModels);
+  if (!catalog.ok) {
+    return { ok: false, selection, stage: "catalog", message: catalog.message };
+  }
+  const availability = await probeOpencodeModelAvailability(model, {
+    listModels: listAvailableOpencodeModels
+  });
+  if (!availability.available) {
+    return {
+      ok: false,
+      selection,
+      stage: availability.reason === "probe_failed" ? "probe_failed" : "availability",
+      message: availability.message
+    };
+  }
+  return { ok: true, selection };
+};
+const promptValidatedHrModelSelection = async (rl, hrRoot, strategy) => {
+  let selection = await buildHrModelSelection(rl, hrRoot, strategy);
+  while (true) {
+    const check = await checkHrBootstrapSelection(hrRoot, selection);
+    if (check.ok) return check.selection;
+    process.stdout.write(`${check.message}
+`);
+    if (check.stage === "syntax" && selection.subagentStrategy === "custom") {
+      selection = await buildHrModelSelection(rl, hrRoot, "custom");
+      continue;
+    }
+    const action = await promptChoice(
       rl,
-      "HR model preset",
-      ["recommended", "free", "custom"],
-      "recommended"
+      check.stage === "probe_failed" ? "Model verification failed \u2014 continue or choose a fallback" : "Choose a fallback",
+      ["continue", "free", "native", "custom", "retry recommended"],
+      check.stage === "probe_failed" ? "continue" : "free"
     );
-    let sharedSubagentModel;
-    let consoleModel;
-    if (subagentStrategy === "recommended") {
-      consoleModel = recommendedHrBootstrapModel;
-      sharedSubagentModel = recommendedHrBootstrapModel;
-    }
-    if (subagentStrategy === "free") {
-      const freeModels = await listOpencodeFreeModels();
-      const fallbackFreeModel = freeModels.includes("opencode/minimax-m2.5-free") ? "opencode/minimax-m2.5-free" : freeModels[0] || "opencode/minimax-m2.5-free";
-      process.stdout.write("Current opencode free models:\n");
-      sharedSubagentModel = await promptIndexedChoice(
-        rl,
-        "Choose a free model for HR",
-        freeModels.length > 0 ? freeModels : [fallbackFreeModel],
-        fallbackFreeModel
-      );
-      consoleModel = sharedSubagentModel;
-    } else if (subagentStrategy === "custom") {
-      sharedSubagentModel = await promptRequired(
+    if (action === "continue") return selection;
+    selection = await buildHrModelSelection(
+      rl,
+      hrRoot,
+      action === "retry recommended" ? "recommended" : action
+    );
+  }
+};
+const promptHrBootstrapModelSelection = async (hrRoot) => {
+  const rl = createPromptInterface();
+  try {
+    process.stdout.write("\nFirst-time HR Office setup\n");
+    const resources = await inspectHrBootstrapResources(hrRoot);
+    const recommendation = recommendHrBootstrapSelection(resources);
+    printHrBootstrapAssessment(resources, recommendation);
+    while (true) {
+      const action = await promptChoice(
         rl,
-        "Custom HR model",
-        recommendedHrBootstrapModel
+        "Apply this recommendation now",
+        ["accept", "recommended", "free", "native", "custom"],
+        "accept"
       );
-      consoleModel = sharedSubagentModel;
+      const strategy = action === "accept" ? recommendation.strategy : action;
+      const validated = await promptValidatedHrModelSelection(rl, hrRoot, strategy);
+      const finalModel = validated.sharedSubagentModel || validated.consoleModel;
+      if (!finalModel) continue;
+      const finalSyntax = validateModelIdentifier(finalModel);
+      if (finalSyntax.ok) {
+        return validated;
+      }
     }
-    process.stdout.write(`
-[agenthub] HR settings will be written to ${path.join(hrRoot, "settings.json")}
+  } finally {
+    rl.close();
+  }
+};
+const shouldUseInteractivePrompts = () => process.env.OPENCODE_AGENTHUB_FORCE_INTERACTIVE_PROMPTS === "1" || Boolean(process.stdin.isTTY && process.stdout.isTTY);
+const applyHrModelSelection = async (targetRoot, selection) => {
+  await installHrOfficeHomeWithOptions({
+    hrRoot: targetRoot,
+    hrModelSelection: selection
+  });
+};
+const repairHrModelConfigurationIfNeeded = async (targetRoot) => {
+  const settings = await readAgentHubSettings(targetRoot);
+  if (!shouldUseInteractivePrompts()) {
+    for (const agentName of hrAgentNames) {
+      const model = settings?.agents?.[agentName]?.model;
+      if (typeof model !== "string" || model.trim().length === 0) continue;
+      const syntax = validateModelIdentifier(model);
+      if (!syntax.ok) {
+        fail(`HR model configuration needs attention. Agent '${agentName}' model '${model}' is invalid: ${syntax.message}`);
+      }
+    }
+    return;
+  }
+  const status = await validateHrAgentModelConfiguration(targetRoot, settings);
+  if (status.valid) return;
+  const rl = createPromptInterface();
+  try {
+    process.stdout.write("[agenthub] HR model configuration needs attention.\n");
+    if (status.message) process.stdout.write(`${status.message}
 `);
-    return {
-      consoleModel,
-      subagentStrategy,
-      sharedSubagentModel
+    const repair = await promptBoolean(
+      rl,
+      "Reconfigure HR models now?",
+      true
+    );
+    if (!repair) {
+      fail("Aborted before repairing invalid HR model configuration.");
+    }
+    const fallback = await promptChoice(
+      rl,
+      "Choose a fallback",
+      ["free", "native", "custom", "retry recommended"],
+      "free"
+    );
+    const validated = await promptValidatedHrModelSelection(
+      rl,
+      targetRoot,
+      fallback === "retry recommended" ? "recommended" : fallback
+    );
+    const resolved = await resolveHrBootstrapAgentModels({
+      targetRoot,
+      selection: validated
+    });
+    const merged = mergeAgentHubSettingsDefaults(settings || {});
+    merged.agents = merged.agents || {};
+    for (const agentName of hrAgentNames) {
+      const resolvedSelection = resolved.agentModels[agentName];
+      merged.agents[agentName] = {
+        ...merged.agents[agentName] || {},
+        model: resolvedSelection.model,
+        ...resolvedSelection.variant ? { variant: resolvedSelection.variant } : {}
+      };
+      if (!resolvedSelection.variant) delete merged.agents[agentName].variant;
+    }
+    merged.meta = {
+      ...merged.meta,
+      onboarding: {
+        ...merged.meta?.onboarding,
+        modelStrategy: resolved.strategy,
+        mode: merged.meta?.onboarding?.mode || "hr-office",
+        importedNativeBasics: merged.meta?.onboarding?.importedNativeBasics ?? true,
+        importedNativeAgents: merged.meta?.onboarding?.importedNativeAgents ?? true,
+        createdAt: merged.meta?.onboarding?.createdAt || (/* @__PURE__ */ new Date()).toISOString()
+      }
     };
+    await writeAgentHubSettings(targetRoot, merged);
+    process.stdout.write("[agenthub] Updated HR model configuration.\n");
   } finally {
     rl.close();
   }
 };
 const printHrModelOverrideHint = (targetRoot) => {
-  process.stdout.write(
-    [
-      `[agenthub] HR model settings: ${path.join(targetRoot, "settings.json")}`,
-      `[agenthub] Change later with: ${cliCommand} doctor --target-root ${targetRoot} --agent ${hrPrimaryAgentName} --model <model>`,
-      `[agenthub] HR subagents: ${hrSubagentNames.join(", ")} (use the same doctor command with --agent <name>)`
-    ].join("\n") + "\n"
-  );
+  void targetRoot;
+  process.stdout.write(`Tip: change HR models later with '${cliCommand} doctor'.
+`);
 };
 const countConfiguredHrGithubSources = async (targetRoot) => {
   try {
@@ -954,8 +1179,12 @@ const syncHrSourceInventoryOnFirstRun = async (targetRoot) => {
     );
   }
   const sourceLabel = sourceParts.length > 0 ? sourceParts.join(" + ") : "configured HR sources";
-  process.stdout.write(`[agenthub] First run \u2014 syncing HR inventory from ${sourceLabel}...
-`);
+  process.stdout.write(
+    `
+Step 3/3 \xB7 Sync inventory
+Sync the HR sourcer inventory from ${sourceLabel} \u2014 this may take a moment, please wait...
+`
+  );
   try {
     const pythonCommand = resolvePythonCommand();
     const scriptPath = path.join(targetRoot, "bin", "sync_sources.py");
@@ -982,12 +1211,10 @@ const syncHrSourceInventoryOnFirstRun = async (targetRoot) => {
     });
     const summary = stdout.trim();
     if (code === 0) {
-      if (summary) process.stdout.write(`${summary}
+      void summary;
+      const repoSummary = configuredSourceCount && configuredSourceCount > 0 ? `${configuredSourceCount} repo${configuredSourceCount === 1 ? "" : "s"}` : "configured sources";
+      process.stdout.write(`\u2713 HR sourcer inventory sync complete (${repoSummary}).
 `);
-      process.stdout.write(
-        `[agenthub] HR source status: ${path.join(targetRoot, "source-status.json")}
-`
-      );
       return;
     }
     process.stderr.write(
@@ -1007,18 +1234,33 @@ const syncHrSourceInventoryOnFirstRun = async (targetRoot) => {
 };
 const ensureHrOfficeReadyOrBootstrap = async (targetRoot = defaultHrHome(), options = {}) => {
   if (await hrHomeInitialized(targetRoot)) return;
-  const shouldPrompt = process.stdin.isTTY && process.stdout.isTTY;
+  const shouldPrompt = shouldUseInteractivePrompts();
+  process.stdout.write("\nHR Office \u2014 first-time setup\n\n");
+  process.stdout.write(
+    "Heads up: a full HR assemble can take about 20\u201330 minutes because AI may need time to choose and evaluate the souls and skills your agents need.\n\n"
+  );
+  process.stdout.write("This will:\n");
+  process.stdout.write("1. Choose an AI model for HR agents\n");
+  process.stdout.write("2. Create the HR Office workspace\n");
+  if (options.syncSourcesOnFirstRun ?? true) {
+    process.stdout.write("3. Sync the HR sourcer inventory (this may take a little longer)\n\n");
+  } else {
+    process.stdout.write("3. Skip inventory sync for now because you are assembling only\n\n");
+  }
   const hrModelSelection = shouldPrompt ? await promptHrBootstrapModelSelection(targetRoot) : void 0;
-  await installHrOfficeHomeWithOptions({
-    hrRoot: targetRoot,
-    hrModelSelection
-  });
-  process.stdout.write(`\u2713 First run \u2014 initialised HR Office at ${targetRoot}
+  await applyHrModelSelection(targetRoot, hrModelSelection || {});
+  process.stdout.write(`
+Step 2/3 \xB7 Create workspace
+\u2713 First run \u2014 initialised HR Office at ${targetRoot}
 `);
   printHrModelOverrideHint(targetRoot);
   if (options.syncSourcesOnFirstRun ?? true) {
     await syncHrSourceInventoryOnFirstRun(targetRoot);
   }
+  process.stdout.write(`
+\u2713 HR Office is ready.
+`);
+  suppressNextHrRuntimeBanner = true;
 };
 const isHrRuntimeSelection = (selection) => selection?.kind === "profile" && selection.profile === "hr";
 const normalizeCsv = (value) => value.split(",").map((item) => item.trim()).filter(Boolean);
@@ -1190,17 +1432,38 @@ const maybeConfigureEnvrc = async (workspace, configRoot) => {
 };
 const createPromptInterface = () => {
   const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
-  if (interactive) {
+  const terminal = interactive && shouldUseReadlineTerminal();
+  if (terminal) {
     const resetSequence = interactivePromptResetSequence();
     if (resetSequence) process.stdout.write(resetSequence);
   }
   return readline.createInterface({
     input: process.stdin,
     output: process.stdout,
-    terminal: interactive
+    terminal
   });
 };
-const askPrompt = async (rl, question) => stripTerminalControlInput(await rl.question(question));
+const scriptedPromptAnswers = (() => {
+  const raw = process.env.OPENCODE_AGENTHUB_SCRIPTED_ANSWERS;
+  if (!raw) return void 0;
+  try {
+    const parsed2 = JSON.parse(raw);
+    return Array.isArray(parsed2) ? parsed2.map((value) => typeof value === "string" ? value : String(value)) : void 0;
+  } catch {
+    return raw.split("\n");
+  }
+})();
+let scriptedPromptIndex = 0;
+const askPrompt = async (rl, question) => {
+  if (scriptedPromptAnswers && scriptedPromptIndex < scriptedPromptAnswers.length) {
+    const answer = scriptedPromptAnswers[scriptedPromptIndex++] || "";
+    const sanitized = stripTerminalControlInput(answer);
+    process.stdout.write(`${question}${sanitized}
+`);
+    return sanitized;
+  }
+  return stripTerminalControlInput(await rl.question(question));
+};
 const promptRequired = async (rl, question, defaultValue) => {
   while (true) {
     const answer = await askPrompt(
@@ -2260,6 +2523,7 @@ if (parsed.command === "hr") {
   await ensureHrOfficeReadyOrBootstrap(resolveSelectedHomeRoot(parsed), {
     syncSourcesOnFirstRun: !parsed.assembleOnly
   });
+  await repairHrModelConfigurationIfNeeded(resolveSelectedHomeRoot(parsed) || defaultHrHome());
   if (parsed.hrIntent?.kind === "office") {
     parsed.workspace = resolveSelectedHomeRoot(parsed) || defaultHrHome();
   } else if (parsed.hrIntent?.kind === "compose") {
@@ -2284,10 +2548,13 @@ if (parsed.command === "run" || parsed.command === "start" || parsed.command ===
 }
 const finalConfigRoot = resolveConfigRoot(parsed);
 const result = await composeSelection(parsed, finalConfigRoot);
-printRuntimeBanner(
-  parsed.command === "hr" ? "HR Office" : "My Team",
-  resolveSelectedHomeRoot(parsed) || defaultAgentHubHome()
-);
+if (!(parsed.command === "hr" && suppressNextHrRuntimeBanner)) {
+  printRuntimeBanner(
+    parsed.command === "hr" ? "HR Office" : "My Team",
+    resolveSelectedHomeRoot(parsed) || defaultAgentHubHome()
+  );
+}
+suppressNextHrRuntimeBanner = false;
 if (shouldChmod()) {
   await chmod(path.join(result.configRoot, "run.sh"), 493);
 }

package/dist/composer/platform.js

@@ -9,7 +9,8 @@ const csiSequencePattern = /\u001b\[[0-?]*[ -/]*[@-~]/g;
 const oscSequencePattern = /\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
 const singleEscapePattern = /\u001b[@-_]/g;
 const controlCharacterPattern = /[\u0000-\u001f\u007f]/g;
-const stripTerminalControlInput = (value) => value.replace(oscSequencePattern, "").replace(csiSequencePattern, "").replace(singleEscapePattern, "").replace(controlCharacterPattern, "");
+const degradedLeadingCsiFragmentPattern = /^(?:(?:\d{1,3};){1,10}\d{1,3}m)+/;
+const stripTerminalControlInput = (value) => value.replace(oscSequencePattern, "").replace(csiSequencePattern, "").replace(singleEscapePattern, "").replace(controlCharacterPattern, "").replace(degradedLeadingCsiFragmentPattern, "");
 const interactivePromptResetSequence = (win = detectWindows()) => isWindows(win) ? [
   "\x1B[?1000l",
   "\x1B[?1001l",
@@ -19,6 +20,7 @@ const interactivePromptResetSequence = (win = detectWindows()) => isWindows(win)
   "\x1B[?1006l",
   "\x1B[?1015l"
 ].join("") : "";
+const shouldUseReadlineTerminal = (win = detectWindows()) => !isWindows(win);
 const generateRunScript = () => `#!/usr/bin/env bash
 set -euo pipefail
 
@@ -57,6 +59,7 @@ export {
   resolvePythonCommand,
   shouldChmod,
   shouldOfferEnvrc,
+  shouldUseReadlineTerminal,
   spawnOptions,
   stripTerminalControlInput,
   symlinkType,

package/dist/composer/settings.js

@@ -1,11 +1,17 @@
 import { readdir, readFile, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { normalizeModelSelection, pickModelSelection } from "./model-utils.js";
+import { spawn } from "node:child_process";
+import {
+  normalizeModelSelection,
+  pickModelSelection,
+  validateModelAgainstCatalog,
+  validateModelIdentifier
+} from "./model-utils.js";
 import { buildBuiltinVersionManifest } from "./builtin-assets.js";
 import { getDefaultProfilePlugins } from "./defaults.js";
 import { readPackageVersion } from "./package-version.js";
-import { resolveHomeConfigRoot } from "./platform.js";
+import { resolveHomeConfigRoot, spawnOptions } from "./platform.js";
 const hrPrimaryAgentName = "hr";
 const recommendedHrBootstrapModel = "openai/gpt-5.4-mini";
 const recommendedHrBootstrapVariant = "high";
@@ -253,6 +259,97 @@ const normalizeConfiguredModel = (value) => {
   return trimmed.length > 0 ? trimmed : void 0;
 };
 const fallbackInstalledModel = (installedModels, nativeModel) => installedModels[hrPrimaryAgentName]?.model || installedModels.auto?.model || Object.values(installedModels)[0]?.model || nativeModel;
+const readHrKnownModelIds = async (targetRoot) => {
+  const filePath = path.join(targetRoot, "inventory", "models", "valid-model-ids.txt");
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const values = raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    return values.length > 0 ? new Set(values) : void 0;
+  } catch {
+    return void 0;
+  }
+};
+const listAvailableOpencodeModels = async () => new Promise((resolve) => {
+  const child = spawn("opencode", ["models"], {
+    stdio: ["ignore", "pipe", "ignore"],
+    ...spawnOptions()
+  });
+  const timeout = setTimeout(() => {
+    child.kill();
+    resolve(void 0);
+  }, 15e3);
+  let stdout = "";
+  child.stdout?.on("data", (chunk) => {
+    stdout += chunk.toString();
+  });
+  child.on("error", () => {
+    clearTimeout(timeout);
+    resolve(void 0);
+  });
+  child.on("close", () => {
+    clearTimeout(timeout);
+    const models = stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    resolve(models.length > 0 ? [...new Set(models)].sort() : void 0);
+  });
+});
+const probeOpencodeModelAvailability = async (model, options = {}) => {
+  const models = await (options.listModels ?? listAvailableOpencodeModels)();
+  if (!models) {
+    return {
+      available: false,
+      reason: "probe_failed",
+      message: "Unable to verify model availability from opencode. Continue only if you know this model works in your environment."
+    };
+  }
+  return models.includes(model) ? { available: true } : {
+    available: false,
+    reason: "unavailable",
+    message: `Model '${model}' is not available in the current opencode environment.`
+  };
+};
+const agentModelValidationMessage = (agentName, model, status) => `Agent '${agentName}' model '${model}' is invalid: ${status.message}`;
+const validateHrAgentModelConfiguration = async (targetRoot, settings, options = {}) => {
+  const currentSettings = settings ?? await readAgentHubSettings(targetRoot);
+  if (!currentSettings?.agents) return { valid: true };
+  const knownModels = await readHrKnownModelIds(targetRoot);
+  const availabilityCache = /* @__PURE__ */ new Map();
+  for (const agentName of hrAgentNames) {
+    const model = currentSettings.agents[agentName]?.model;
+    if (typeof model !== "string" || model.trim().length === 0) continue;
+    const syntax = validateModelIdentifier(model);
+    if (!syntax.ok) {
+      return {
+        valid: false,
+        agentName,
+        model,
+        syntax,
+        message: agentModelValidationMessage(agentName, model, syntax)
+      };
+    }
+    const catalog = validateModelAgainstCatalog(model, knownModels);
+    if (!catalog.ok) {
+      return {
+        valid: false,
+        agentName,
+        model,
+        catalog,
+        message: agentModelValidationMessage(agentName, model, catalog)
+      };
+    }
+    const availability = availabilityCache.get(model) || await probeOpencodeModelAvailability(model, options);
+    availabilityCache.set(model, availability);
+    if (!availability.available && availability.reason !== "probe_failed") {
+      return {
+        valid: false,
+        agentName,
+        model,
+        availability,
+        message: agentModelValidationMessage(agentName, model, availability)
+      };
+    }
+  }
+  return { valid: true };
+};
 const resolveHrBootstrapAgentModels = async ({
   targetRoot,
   selection
@@ -383,11 +480,14 @@ export {
   hrAgentNames,
   hrPrimaryAgentName,
   hrSubagentNames,
+  listAvailableOpencodeModels,
   loadNativeOpenCodeConfig,
   loadNativeOpenCodePreferences,
   mergeAgentHubSettingsDefaults,
   nativeOpenCodeConfigPath,
+  probeOpencodeModelAvailability,
   readAgentHubSettings,
+  readHrKnownModelIds,
   readNativeAgentOverrides,
   readNativePluginEntries,
   readWorkflowInjectionConfig,
@@ -395,6 +495,7 @@ export {
   recommendedHrBootstrapVariant,
   resolveHrBootstrapAgentModels,
   settingsPathForRoot,
+  validateHrAgentModelConfiguration,
   workflowInjectionPathForRoot,
   writeAgentHubSettings
 };

package/dist/skills/agenthub-doctor/diagnose.js

@@ -1,6 +1,7 @@
 import { readdir, readFile, access } from "node:fs/promises";
 import path from "node:path";
 import { readAgentHubSettings } from "../../composer/settings.js";
+import { validateModelIdentifier } from "../../composer/model-utils.js";
 const readJson = async (filePath) => {
   const content = await readFile(filePath, "utf-8");
   return JSON.parse(content);
@@ -98,8 +99,28 @@ async function runDiagnostics(targetRoot) {
   if (omoIssue) {
     report.issues.push(omoIssue);
   }
+  for (const issue of diagnoseInvalidModelSyntax(settings)) {
+    report.issues.push(issue);
+  }
   return report;
 }
+const diagnoseInvalidModelSyntax = (settings) => {
+  if (!settings?.agents) return [];
+  const issues = [];
+  for (const [agentName, agent] of Object.entries(settings.agents)) {
+    if (typeof agent.model !== "string" || agent.model.trim().length === 0) continue;
+    const syntax = validateModelIdentifier(agent.model);
+    if (!syntax.ok) {
+      issues.push({
+        type: "model_invalid_syntax",
+        severity: "error",
+        message: `Agent '${agentName}' has an invalid model override: ${syntax.message}`,
+        details: { agentName, model: agent.model }
+      });
+    }
+  }
+  return issues;
+};
 async function diagnoseMissingGuards(settings) {
   if (!settings) return REQUIRED_GUARDS;
   const existingGuards = Object.keys(settings.guards || {});

package/dist/skills/agenthub-doctor/interactive.js

@@ -3,9 +3,15 @@ import { readdir, readFile, access, writeFile } from "node:fs/promises";
 import path from "node:path";
 import {
   loadNativeOpenCodeConfig,
+  probeOpencodeModelAvailability,
+  readHrKnownModelIds,
   readAgentHubSettings,
   writeAgentHubSettings
 } from "../../composer/settings.js";
+import {
+  validateModelAgainstCatalog,
+  validateModelIdentifier
+} from "../../composer/model-utils.js";
 import {
   fixMissingGuards,
   createBundleForSoul,
@@ -686,6 +692,19 @@ async function updateAgentModelOverride(targetRoot, agentName, model) {
     await writeAgentHubSettings(targetRoot, settings);
     return `Cleared model override for '${agentName}'.`;
   }
+  const syntax = validateModelIdentifier(trimmed);
+  if (!syntax.ok) {
+    return `${syntax.message} Use provider/model format or leave blank to clear the override.`;
+  }
+  const knownModels = await readHrKnownModelIds(targetRoot);
+  const catalog = validateModelAgainstCatalog(trimmed, knownModels);
+  if (!catalog.ok) {
+    return `${catalog.message} Sync HR sources or choose a listed model, then try again.`;
+  }
+  const availability = await probeOpencodeModelAvailability(trimmed);
+  if (!availability.available) {
+    return `${availability.message} Pick another model or clear the override.`;
+  }
   settings.agents[agentName] = {
     ...existing,
     model: trimmed

package/dist/skills/hr-assembly/SKILL.md

@@ -41,7 +41,10 @@ $HR_HOME/staging/<package-id>/
 - Prefer namespaced bundle/soul/profile names for adapted teams or rewrites so the package does not overwrite shared starter assets like `plan`, `build`, or `explore` unless the human explicitly requests replacement.
 - If a staged profile sets `defaultAgent`, it must use the staged bundle's `agent.name` value, not the bundle filename. This matters when bundle filenames are namespaced but `agent.name` is shorter.
 - Before final assembly, confirm whether the operator wants to keep default opencode agents such as `general`, `explore`, `plan`, and `build`. If not, the staged profile must set `"nativeAgentPolicy": "team-only"`. This suppresses host native agent merges and emits `disable: true` overrides for default opencode agents that are not supplied by the staged team itself.
+- If `nativeAgentPolicy` is `team-only` and the staged bundle set does not already provide `explore`, automatically include the built-in hidden `explore` subagent so the team retains investigation coverage without another user prompt.
+- Before final assembly, MUST verify the staged bundle set includes at least one `agent.mode: "primary"` agent that is not hidden. If all sourced candidates are subagent-style, either add/create a primary host agent or keep native agents visible. Never stage an all-subagent team as `team-only`.
 - Before final assembly, confirm whether the promoted profile should become the default personal profile for future bare `agenthub start` runs. Record that choice in `handoff.json` under `promotion_preferences.set_default_profile`.
+- If AI models are still unresolved when final assembly begins, stop and confirm the exact model choice here before writing staged agent defaults.
 - If the operator specifies a model variant such as `xhigh`, `high`, or `thinking`, store it canonically as `agent.model: "provider/model"` plus `agent.variant: "..."`. For backward compatibility, combined strings like `"provider/model xhigh"` may still be accepted on read, but staged output should prefer the split form.
 - The package must be promotable by:
 

package/dist/skills/hr-final-check/SKILL.md

@@ -69,11 +69,12 @@ Keep `final-checklist.md` compact and explicit. Use this shape:
 | descriptions are operator-readable | pass/fail |
 | MCP registrations resolve to staged servers or blocker | pass/fail |
 | handoff clearly separates test/use/promote | pass/fail |
-| model preferences were explicitly collected | pass/fail |
+| model preferences were confirmed before assembly | pass/fail |
 | final names were user-confirmed | pass/fail |
 | specialized work was delegated | pass/fail |
 | staged model ids validated against synced catalog | pass/fail |
 | profile defaultAgent matches bundle agent.name | pass/fail |
+| team includes at least one primary, non-hidden agent | pass/fail |
 | default opencode agent policy confirmed | pass/fail |
 | default profile on promote confirmed | pass/fail |
 | no host project mutations | pass/fail |
@@ -94,5 +95,6 @@ The package cannot be marked ready unless the verifier confirms:
 7. if any bundle references MCP tools, the staged package includes the referenced `mcp/*.json` files, the required `mcp-servers/` implementation files, and `mcp-servers/package.json` when runtime dependencies are needed
 8. the handoff clearly shows how to test/use the staged profile in a workspace before promote, and promote is not described as mandatory for workspace use
 9. if a profile sets `defaultAgent`, that value exactly matches one of the staged bundles' `agent.name` values (not just the bundle filename)
+10. the staged team includes at least one non-hidden primary agent, and any `team-only` profile keeps at least one such primary agent available to the operator
 
 If bundle metadata contains fake runtime keys such as `optional_skills` or `runtime_conditional_skills`, mark the package `NOT READY` until they are removed or rewritten as plain documentation outside runtime bundle semantics.

package/dist/skills/hr-staffing/SKILL.md

@@ -37,8 +37,6 @@ Every staffing plan must include:
 - `composition`
 - `required_skills`
 - `required_tools`
-- `suggested_model_provider`
-- `proposed_agent_models` (initial proposal only; final per-agent defaults require user confirmation later)
 - `draft_names` (draft agent names and draft profile name for user review)
 - `risks`
 - `next_action`
@@ -57,8 +55,8 @@ composition:
 draft_names:
 - seat: ... | proposed_agent_name: ... | reason: ...
 - profile: ... | reason: ...
-proposed_agent_models:
-- agent: ... | model: ...
+required_skills:
+- skill: ... | why: ...
 risks:
 - ...
 next_action: ...
@@ -75,7 +73,9 @@ For each recommended entry, specify:
 
 ## Decision Rules
 
+- At least one staffing-plan entry must have `deployment_role: primary-capable`.
 - Prefer the smallest team that can cover planning, sourcing/exploration, implementation, audit, verification, and documentation.
+- When multiple candidates can cover the same seat, prefer a pure-soul agent with attached skills over a mixed soul+skill agent. Use a mixed soul+skill agent only when the specialized workflow cannot be cleanly separated, the source is tightly fused, or the user explicitly wants that mixed form.
 - Prefer local worker cards from `$HR_HOME/inventory/workers/` with `inventory_status = available`.
 - Treat `draft` worker cards as sourcing inputs that still need review or explicit operator acceptance.
 - Exclude `retired` worker cards from recommended staffing compositions.

package/dist/skills/hr-support/bin/validate_staged_package.py

@@ -168,6 +168,7 @@ def validate_profile_default_agents(import_root: Path) -> None:
             )
 
         references: list[tuple[str, str]] = []
+        primary_agent_names: set[str] = set()
         missing_bundles: list[str] = []
         for raw_bundle_name in bundle_names:
             if not isinstance(raw_bundle_name, str) or not raw_bundle_name.strip():
@@ -181,11 +182,16 @@ def validate_profile_default_agents(import_root: Path) -> None:
                 continue
             agent = bundle.get("agent", {})
             agent_name = agent.get("name") if isinstance(agent, dict) else None
+            agent_mode = agent.get("mode") if isinstance(agent, dict) else None
+            agent_hidden = agent.get("hidden") if isinstance(agent, dict) else None
             if not isinstance(agent_name, str) or not agent_name.strip():
                 raise SystemExit(
                     f"Bundle '{bundle_name}' is missing required agent.name; profile '{profile_name}' cannot use it."
                 )
-            references.append((bundle_name, agent_name.strip()))
+            normalized_agent_name = agent_name.strip()
+            references.append((bundle_name, normalized_agent_name))
+            if agent_mode == "primary" and agent_hidden is not True:
+                primary_agent_names.add(normalized_agent_name)
 
         if missing_bundles:
             detail = ", ".join(missing_bundles)
@@ -199,6 +205,10 @@ def validate_profile_default_agents(import_root: Path) -> None:
             raise SystemExit(
                 f"Profile '{profile_name}' uses nativeAgentPolicy 'team-only' and must set defaultAgent explicitly."
             )
+        if native_agent_policy == "team-only" and not primary_agent_names:
+            raise SystemExit(
+                f"Profile '{profile_name}' uses nativeAgentPolicy 'team-only' but does not include at least one primary, non-hidden agent."
+            )
         if default_agent is None:
             continue
         if not isinstance(default_agent, str) or not default_agent.strip():
@@ -224,6 +234,10 @@ def validate_profile_default_agents(import_root: Path) -> None:
 
         agent_names = {agent_name for _, agent_name in references}
         if normalized_default_agent in agent_names:
+            if normalized_default_agent not in primary_agent_names:
+                raise SystemExit(
+                    f"Profile '{profile_name}' defaultAgent '{normalized_default_agent}' must point to a primary, non-hidden agent."
+                )
             continue
 
         available = ", ".join(sorted(agent_names)) or "(none)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-agenthub",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A control plane for organizing, composing, and activating OpenCode agents, skills, profiles, and bundles.",
   "type": "module",
   "main": "./dist/plugins/opencode-agenthub.js",