@moretea-labs/forge 1.5.1 → 1.6.0

package/docs/architecture/current/system-overview.md

@@ -1,10 +1,35 @@
 # Controller Runtime System Overview
 
 > Status: **Runtime Authority**
+>
+> Control convergence: ChatGPT/human Controller owns semantic understanding and commits Direct/Process/Durable Work/Plan only after sufficient context; Forge does not classify every request at ingress. `RouteDecision` owns execution mechanics after that commitment, while unrelated Work/Plan state never upgrades or blocks ordinary Direct execution. Semantic ownership, execution depth, and resource placement stay independent. CodeGraph/lexical/Forge relations are bounded impact evidence, not another decision authority.
 
 ## 1. System Definition
 
-Forge Controller Runtime is an Agent Engineering Control Plane for one or more local Git repositories. ChatGPT, Local UI, CLI and optional GitHub integrations submit decisions and commands. The runtime persists accepted work, schedules it under repository-owned conflict rules, executes it outside the Gateway process and records evidence for recovery, acceptance and release.
+Forge Controller Runtime is an Agent Engineering Control Plane for one or more local Git repositories. ChatGPT is the primary semantic Controller: it may inspect first, then choose whether a request needs only a Direct action, a Process, finite durable Work, a Plan, or a Workflow. Local UI, CLI and integrations can submit the same explicit decisions and commands. Forge supplies bounded context, hard policy/resource constraints, persistence, execution and machine evidence; it does not replace the Controller with prompt classifiers or Plan/Work ceremony.
+
+### 1.1 End-to-end authority map
+
+```text
+User request
+  -> ChatGPT / human Controller
+       -> Explore when needed: rh_context + raw reads + CodeGraph/Runtime/history evidence
+       -> semantic commitment: answer | Direct | Process | finite Work | Plan | Workflow
+  -> Forge execution boundary
+       -> hard policy / authorization / claims / leases / fencing
+       -> placement and executor mechanics; no semantic reinterpretation
+  -> execution
+       -> Direct mutation: SafePatch -> EditSession -> MutationGate
+       -> command/check: Unified Process Runtime
+       -> durable responsibility: finite Work using the same execution primitives
+       -> recurrence: Workflow/Schedule -> bounded Occurrence -> Controller decision
+  -> machine evidence
+       -> diff / Process receipt / check / delivery / cleanup facts
+  -> ChatGPT / user acceptance
+       -> accept, continue, replan, or close the semantic goal
+```
+
+Authority rule: Context providers return evidence, RoutePolicy selects mechanics from a Controller commitment, Plan/Requirement/Work persist explicitly chosen durable semantics, and Process/EditSession/Evidence record execution facts. None of those layers may infer that a missing Plan/Work makes ordinary implementation unauthorized, or that a successful/failed cleanup receipt by itself proves the user's goal accepted/rejected.
 
 ## 2. Canonical Runtime Topology
 

package/docs/architecture/current/thin-harness-v1.md

@@ -174,6 +174,16 @@ bounded child process (process group) / yielded search
 - Timeout/cancel: SIGTERM process group → grace → SIGKILL via `terminateProcessTree`.
 - stdout/stderr collectors cap while streaming.
 
+## MCP tool-surface freshness
+
+The Canonical Runtime `tools/list` schema fingerprint is the tool-surface identity. Release identity alone does not invalidate a session, while any exposed schema change does.
+
+HTTP MCP sessions capture the exact Canonical Runtime fingerprint and tool names at initialize time. The Gateway also observes the existing atomic `runtime/status.json` publication; when its published tool-surface fingerprint changes, it sends the standard MCP `notifications/tools/list_changed` notification to connected sessions whose captured fingerprint is stale. This is event-driven over the existing Runtime status publication—there is no schema poller, refresh daemon, or extra control-plane entity.
+
+The notification is an optimization hint, not authority. It never rewrites a session's captured fingerprint. Until the client re-runs discovery/reinitializes, the existing per-request fingerprint fence still rejects stale-schema execution. A lost notification therefore cannot make an obsolete tool call valid; it only risks falling back to the deterministic reinitialize path.
+
+This removes the normal stale-tool extra round trip for clients that honor standard MCP list-changed notifications while retaining the same fail-closed schema fence for clients that do not.
+
 ## Process output confidentiality
 
 Process Runtime applies one shared bounded redaction policy before stdout/stderr

package/docs/operations/chatgpt-personal-assistant-runtime.md

@@ -54,7 +54,15 @@ A routine stores the user's natural-language goal rather than a traditional GUI
 }
 ```
 
-The first version stores the routine and can run it on demand. Automatic time-based scheduling should attach this store to the existing schedule engine in a later iteration.
+Routine execution and long-lived goal continuation use the existing Schedule Engine rather than a second assistant daemon. Semantic/model-backed routine logic remains external-controller-owned; the Kernel does not execute an unbounded model loop on a timer.
+
+For an accepted non-terminal Work, ChatGPT can create a bounded `rh_work.schedule_create` policy in one of three modes:
+
+- `continuation` — wake the bound ChatGPT/Codex/Claude/Grok Controller at the configured trigger;
+- `browser_watch` — silently refresh/read an allowed browser target, fingerprint a deterministic text projection, and wake the bound Controller only when the observation changes;
+- `browser_keepalive` — silently refresh an authenticated browser target and wake only when configured login markers indicate that user authentication is required.
+
+The first `browser_watch` observation is a silent baseline by default. Unchanged observations do not create a ChatGPT conversation turn. When the bound Work becomes terminal, Forge disables the Schedule before performing another external probe, so temporary watchers naturally disappear with the Goal they serve.
 
 ## Policy defaults
 
@@ -76,8 +84,10 @@ Requires human approval:
 
 ## Assistant Inbox
 
-Assistant Inbox is the user-facing result surface for routine outputs and intent execution records. ChatGPT can read it and then present the result conversationally, for example: "今天助理整理了什么？"
+Assistant Inbox is the user-facing result surface for meaningful routine outputs, approval/authentication needs, and intent execution records. A successful scheduled probe with no external change should remain silent rather than generating a daily "completed" notification. ChatGPT can read meaningful items and then present the result conversationally, for example: "今天助理整理了什么？"
 
 ## Current limitation
 
 The runtime does not embed a full NLP model. ChatGPT Actions should provide structure when precision matters. The local runtime includes conservative intent inference only for routine creation, reminders, and immediate mail-summary collection.
+
+`browser_watch` is a fallback observation source for services without a usable API or webhook; it depends on a live authenticated browser session and caller-supplied selectors/terms when the page contains unrelated or volatile content. Browser refresh can reduce inactivity-related logout but cannot override a provider's absolute session lifetime, security checks, or MFA policy. Provider-native APIs/events should replace browser probes when they are available and more reliable.

package/docs/operations/controller-browser-plugin.md

@@ -48,7 +48,7 @@ Session metadata is reusable across actions via `session_id`. Any action that re
 - Artifacts stay under `.forge/browser/**` (not arbitrary local paths).
 - CDP attach is bounded to configured loopback endpoints only; the plugin does not scan arbitrary ports or remote hosts. Native discovery checks only the configured Chrome/Vivaldi candidates and does not launch them.
 - CDP browsers are disconnected after the action; Apple Events keeps plugin-owned session tabs open until `close_session`/`close_page` while preserving user-owned tabs; managed contexts are closed after the action. Standard native DOM reads/interactions do not foreground the owned tab and return DOM evidence instead of attempting a screenshot.
-- Health `userFacingStatus` reports `ready`, `domain restricted`, `session active`, or setup states.
+- Health `userFacingStatus` reports `ready`, `session active`, or setup states.
 
 ## Configuration
 
@@ -67,12 +67,11 @@ Example:
   "nativeBrowserCandidates": ["vivaldi", "chrome"],
   "cdpAttachFallback": "managed_persistent",
   "browserChannel": "chromium",
-  "defaultTimeoutMs": 30000,
-  "allowedDomains": ["example.com", "docs.example.com"]
+  "defaultTimeoutMs": 30000
 }
 ```
 
-`allowedDomains` is the safety boundary. If it is empty, the plugin can target any HTTP(S) host. If it is set, the plugin accepts only exact hosts or subdomains of those entries.
+Browser URLs are open by default across hosts. The URL boundary is scheme-based: top-level navigation accepts absolute `http://` and `https://` URLs and rejects `file://`, `data:`, browser-internal pages, and custom schemes. Interaction risk and authorization are enforced by the typed action policy rather than a domain grant.
 
 Additional browser/profile fields:
 
@@ -131,8 +130,7 @@ Example custom Chrome automation-profile binding:
   "browserChannel": "chrome",
   "cdpEndpoint": "http://127.0.0.1:9222",
   "cdpAttachFallback": "fail_closed",
-  "defaultTimeoutMs": 30000,
-  "allowedDomains": ["appstoreconnect.apple.com"]
+  "defaultTimeoutMs": 30000
 }
 ```
 
@@ -152,12 +150,11 @@ Use native attachment when the target session is already logged in:
   "browserMode": "attach_preferred",
   "nativeAttachMode": "auto",
   "nativeBrowserCandidates": ["vivaldi", "chrome"],
-  "cdpAttachFallback": "managed_persistent",
-  "allowedDomains": ["chatgpt.com", "example.com"]
+  "cdpAttachFallback": "managed_persistent"
 }
 ```
 
-The attach order is CDP, then Apple Events, then managed fallback. macOS may require Automation permission for the controller/Node process to control Vivaldi or Google Chrome. The browser must also permit JavaScript from Apple Events for DOM extraction and interaction. If either permission is unavailable or the browser has no window, the attempt is recorded and fallback policy applies. The provider uses the active browser only for discovery, then operates on a plugin-owned tab identified by stable window/tab metadata. It does not read cookies or storage and re-checks the target URL against `allowedDomains` before and after actions.
+The attach order is CDP, then Apple Events, then managed fallback. macOS may require Automation permission for the controller/Node process to control Vivaldi or Google Chrome. The browser must also permit JavaScript from Apple Events for DOM extraction and interaction. If either permission is unavailable or the browser has no window, the attempt is recorded and fallback policy applies. The provider uses the active browser only for discovery, then operates on a plugin-owned tab identified by stable window/tab metadata. It does not read cookies or storage. Top-level Browser actions accept any absolute HTTP(S) URL; non-HTTP(S) schemes fail before launch.
 
 Native limitations are explicit: console/network event capture is unavailable and native file-input/download semantics are not equivalent to Playwright. A screenshot of a plugin-owned background tab fails closed with `PLUGIN_BROWSER_FOREGROUND_REQUIRED`; Forge does not silently activate the tab just to capture evidence. Use explicit foreground/human handoff, CDP, or a managed context for workflows that require screenshots or capabilities not available through background DOM automation.
 
@@ -219,15 +216,14 @@ Risk levels:
 - `click`, `type`, `press` use `risk=remote_write`
 - `wait_for_selector` uses `risk=workspace_write`
 
-## Allowed-domain enforcement
-
-The plugin enforces `allowedDomains` in three places:
+## URL scheme boundary
 
-1. It validates the explicit `url` before opening a page.
-2. It validates any saved `session_id` target before interaction.
-3. It re-checks the resulting page URL after the action and rejects the result if navigation leaves the allowed set.
+Browser no longer maintains per-domain grants or a host allowlist. Any absolute HTTP(S) URL may be opened, redirected to, or reached by an interaction. This avoids configuration churn for normal browsing while preserving the actual trust boundaries:
 
-The plugin does not intentionally provide any action that can bypass this boundary.
+1. top-level Browser targets must use `http:` or `https:`;
+2. local files, browser-internal URLs, `data:` URLs, and custom schemes are rejected as Browser targets;
+3. action risk and confirmation still govern remote writes and interactive operations;
+4. silent native automation stays on plugin-owned background tabs unless an explicit human handoff requires foreground presentation.
 
 ## Dependency requirement
 

package/docs/operations/features.md

@@ -24,7 +24,7 @@ These features are part of the default local setup:
 | Codex / Claude | Delegated implementation for work too large for Direct Edit | Install and authenticate the corresponding CLI; explicitly enable the dev runner. |
 | GitHub | Issue/Project synchronization, PR workflows, cloud-agent sessions | Authenticated `gh` and repository permission. |
 | Tailscale / Cloudflare | Stable HTTPS endpoint for ChatGPT MCP | Tunnel client and appropriate account/domain configuration. |
-| Browser | Playwright navigation, screenshots, and bounded browser evidence | Browser binaries and allowed domains. |
+| Browser | Playwright navigation, screenshots, and bounded browser evidence | Browser binaries and HTTP(S) URL scheme validation. |
 | CodeGraph | Additional code relationships and impact navigation | CodeGraph CLI; native Windows automatic setup is not yet enabled. |
 | Google Workspace | Gmail and Calendar assistant actions | Explicit OAuth setup and plugin permission. |
 | Schedules and findings | Supervised recurring checks and candidate findings | Canonical Forge Runtime running; live actions remain policy-gated. |

package/docs/operations/homebrew.md

@@ -6,8 +6,8 @@ Homebrew is planned as a convenience layer after the first stable npm/GitHub rel
 
 Do not publish a formula until all of the following are true:
 
-- `@moretea-labs/forge@1.5.1` exists on npm;
-- Git tag and GitHub Release `v1.5.1` exist and point to the tested commit;
+- `@moretea-labs/forge@1.6.0` exists on npm;
+- Git tag and GitHub Release `v1.6.0` exist and point to the tested commit;
 - the npm tarball has an immutable checksum;
 - macOS installation and `forge --version` / `forge doctor` tests pass;
 - upgrade and uninstall behavior is documented.

package/docs/tutorials/01-install-and-start.md

@@ -34,7 +34,7 @@ For Forge source development only:
 ```bash
 git clone https://github.com/moretea-labs/forge.git
 cd forge
-npm ci --ignore-scripts --no-audit --no-fund
+bun install --frozen-lockfile
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 

package/docs/tutorials/01-install-and-start.zh-CN.md

@@ -34,7 +34,7 @@ forge --version
 ```bash
 git clone https://github.com/moretea-labs/forge.git
 cd forge
-npm ci --ignore-scripts --no-audit --no-fund
+bun install --frozen-lockfile
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 

package/docs/wiki/Installation.md

@@ -7,7 +7,7 @@
 This is the verified path while `@moretea-labs/forge` remains unpublished:
 
 ```bash
-npm ci --ignore-scripts --no-audit --no-fund
+bun install --frozen-lockfile
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 

package/docs/wiki/Quick-Start.md

@@ -7,7 +7,7 @@ Until the npm RC is publicly available, use the verified source path:
 ```bash
 git clone https://github.com/moretea-labs/forge.git
 cd forge
-npm ci --ignore-scripts --no-audit --no-fund
+bun install --frozen-lockfile
 npm install -g . --omit=optional --no-audit --no-fund
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moretea-labs/forge",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Local-first action assistant for software work with resumable execution, bounded tools, and reviewable evidence",
   "license": "MIT",
   "author": "Moretea Labs contributors",

package/scripts/check-public-docs.sh

@@ -72,9 +72,22 @@ grep -q "$README_CHANNEL_EN" README.md || { echo "[public-docs] English README m
 grep -q "$README_CHANNEL_ZH" README.zh-CN.md || { echo "[public-docs] Chinese README must state the npm channel for $PACKAGE_VERSION" >&2; exit 1; }
 grep -q 'See \[README.md\](README.md)' README.en.md || { echo "[public-docs] README.en.md must point to the maintained English README" >&2; exit 1; }
 
+source_install_docs=(
+  README.md README.zh-CN.md
+  docs/tutorials/01-install-and-start.md docs/tutorials/01-install-and-start.zh-CN.md
+  docs/wiki/Quick-Start.md docs/wiki/Installation.md
+)
+for path in "${source_install_docs[@]}"; do
+  grep -q 'bun install --frozen-lockfile' "$path" || { echo "[public-docs] source checkout must use the CI-authoritative Bun frozen lock: $path" >&2; exit 1; }
+  grep -q 'npm install -g \.' "$path" || { echo "[public-docs] missing source package install: $path" >&2; exit 1; }
+done
+if git grep -n 'npm ci --ignore-scripts --no-audit --no-fund' -- "${source_install_docs[@]}" >/dev/null; then
+  echo "[public-docs] generic npm ci must not be advertised for Forge source checkouts" >&2
+  exit 1
+fi
+
 for path in docs/tutorials/01-install-and-start.md docs/tutorials/01-install-and-start.zh-CN.md; do
   grep -q 'Node.js 20.10' "$path" || { echo "[public-docs] missing Node baseline: $path" >&2; exit 1; }
-  grep -q 'npm install -g \.' "$path" || { echo "[public-docs] missing source install: $path" >&2; exit 1; }
   grep -q "$INSTALL_SPEC" "$path" || { echo "[public-docs] missing package command for $PACKAGE_VERSION: $path" >&2; exit 1; }
 done
 

package/scripts/migrate-chatgpt-automation-schedules.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env bun
+import { mkdirSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { resolveRepoPreferredControllerHome } from '../src/cli/repositories/controller-home';
+import { listRepositories } from '../src/cli/repositories/registry';
+import { migrateChatgptAutomationSchedule } from '../src/runtime/workflow/schedules/chatgpt-automation-migration';
+import { listSchedules, saveSchedule } from '../src/runtime/workflow/schedules/store';
+import type { RepositorySchedule } from '../src/runtime/workflow/schedules/types';
+
+interface Args { controllerHome?: string; apply: boolean; json: boolean; }
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = { apply: false, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === '--apply') args.apply = true;
+    else if (value === '--json') args.json = true;
+    else if (value === '--controller-home') args.controllerHome = resolve(argv[++index] ?? '');
+    else throw new Error(`unknown argument: ${value}`);
+  }
+  return args;
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const controllerHome = resolveRepoPreferredControllerHome(process.cwd(), args.controllerHome);
+  const repositories = listRepositories(controllerHome, { includeRemoved: true });
+  const candidates: Array<{ repositoryName: string; original: RepositorySchedule; migrated: RepositorySchedule }> = [];
+  for (const repository of repositories) {
+    for (const schedule of listSchedules(controllerHome, repository.repoId)) {
+      const result = migrateChatgptAutomationSchedule(schedule);
+      if (result.changed) candidates.push({ repositoryName: repository.displayName, original: schedule, migrated: result.schedule });
+    }
+  }
+
+  let backupPath: string | undefined;
+  if (args.apply && candidates.length > 0) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    backupPath = join(controllerHome, 'backups', `chatgpt-automation-schedules-${stamp}.json`);
+    mkdirSync(dirname(backupPath), { recursive: true });
+    writeFileSync(backupPath, `${JSON.stringify({ schemaVersion: 1, createdAt: new Date().toISOString(), schedules: candidates.map((item) => item.original) }, null, 2)}\n`);
+    for (const candidate of candidates) saveSchedule(controllerHome, candidate.migrated);
+  }
+
+  const output = {
+    schemaVersion: 1,
+    controllerHome,
+    repositoryCount: repositories.length,
+    migratedCount: candidates.length,
+    writesApplied: args.apply,
+    backupPath,
+    schedules: candidates.map((item) => ({ repoId: item.original.repoId, repositoryName: item.repositoryName, scheduleId: item.original.scheduleId, name: item.original.name })),
+  };
+  if (args.json) console.log(JSON.stringify(output, null, 2));
+  else {
+    console.log(`[chatgpt-automation-migration] ${candidates.length} schedule(s) eligible across ${repositories.length} repository record(s).`);
+    console.log(args.apply ? `[chatgpt-automation-migration] Applied. Backup: ${backupPath ?? 'not needed'}` : '[chatgpt-automation-migration] Preview only; pass --apply after the new Runtime baseline is active.');
+  }
+}
+
+try { main(); } catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/scripts/sprint-backlog.sh

@@ -21,7 +21,7 @@ Usage:
 
 Program-level sprint backlog helper. PRDs live in plans/prds/ as the upper
 planning layer; sprints live in plans/sprints/ as ordered execution backlogs.
-Each backlog row is expanded with $think before the existing plan -> contract
+Each backlog row is expanded with /plan before the existing plan -> contract
 -> worktree flow. tasks/todos.md stays the deferred-goal ledger.
 
 start-task reserves the next (or named) pending backlog row and can capture a

package/src/cli/commands/chatgpt.ts

@@ -13,7 +13,11 @@ import {
 } from '../chatgpt-browser/engine';
 import type { BrowserProviderName, BrowserSessionStatus, NativeBrowserChannel, ThinkingLevel } from '../chatgpt-browser/types';
 import { durableControllerHome } from '../repositories/controller-home';
-import { runWorkChatgptContinuation } from '../../runtime/control-plane/launcher/chatgpt-work-continuation';
+import {
+  runWorkChatgptContinuation,
+  type ChatgptAutomationReasoning,
+  type ChatgptAutomationTabPolicy,
+} from '../../runtime/control-plane/launcher/chatgpt-work-continuation';
 
 interface BrowserCommonOptions {
   repo?: string;
@@ -84,6 +88,9 @@ interface WorkChatgptContinueOptions extends BrowserCommonOptions {
   title?: string;
   session?: string;
   conversationUrl?: string;
+  model?: string;
+  reasoning?: string;
+  tabPolicy?: string;
   timeoutMs?: string;
 }
 
@@ -109,6 +116,18 @@ interface BrowserFollowupOptions extends BrowserCommonOptions {
   oracleBin?: string;
 }
 
+function parseAutomationReasoning(value?: string): ChatgptAutomationReasoning | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'medium' || value === 'high' || value === 'xhigh') return value;
+  throw new Error(`invalid --reasoning "${value}" (expected: medium, high, xhigh)`);
+}
+
+function parseAutomationTabPolicy(value?: string): ChatgptAutomationTabPolicy | undefined {
+  if (value === undefined) return undefined;
+  if (value === 'auto' || value === 'reuse' || value === 'new') return value;
+  throw new Error(`invalid --tab-policy "${value}" (expected: auto, reuse, new)`);
+}
+
 function parseProvider(value?: string): BrowserProviderName {
   if (value === undefined || value === 'oracle') return 'oracle';
   if (value === 'native') return 'native';
@@ -384,8 +403,11 @@ export function buildChatgptCommand(): Command {
     .requiredOption('--work-id <work-id>', 'Stable Forge Work id')
     .requiredOption('--prompt <text>', 'Bounded continuation prompt')
     .option('--title <title>', 'Human-readable local conversation alias')
-    .option('--session <session-id>', 'Legacy saved browser session to seed the binding')
+    .option('--session <session-id>', 'Saved browser session to seed or resume the Work binding')
     .option('--conversation-url <url>', 'Explicit ChatGPT conversation URL to seed the binding')
+    .option('--model <label>', 'Requested ChatGPT automation model', 'gpt-5.6')
+    .option('--reasoning <level>', 'Reasoning level: medium|high|xhigh', 'high')
+    .option('--tab-policy <policy>', 'Browser tab policy: auto|reuse|new', 'auto')
     .option('--timeout-ms <ms>', 'Assistant timeout in milliseconds')
     .action((rawOpts: WorkChatgptContinueOptions) => {
       void runChatgptAction(async () => {
@@ -398,6 +420,9 @@ export function buildChatgptCommand(): Command {
           title: rawOpts.title,
           browserSessionId: rawOpts.session,
           conversationUrl: rawOpts.conversationUrl,
+          model: rawOpts.model,
+          reasoning: parseAutomationReasoning(rawOpts.reasoning),
+          tabPolicy: parseAutomationTabPolicy(rawOpts.tabPolicy),
           timeoutMs: parsePositiveInteger('timeout-ms', rawOpts.timeoutMs),
         });
         console.log(JSON.stringify({
@@ -408,6 +433,10 @@ export function buildChatgptCommand(): Command {
           conversationId: result.conversationId,
           localAlias: result.localAlias,
           resumedFromBinding: result.resumedFromBinding,
+          model: result.model,
+          reasoning: result.reasoning,
+          tabPolicy: result.tabPolicy,
+          executionPreferenceVerified: result.executionPreferenceVerified,
           error: result.error,
         }, null, 2));
       });

package/src/cli/commands/plugin.ts

@@ -5,11 +5,11 @@ import { dirname, isAbsolute, join, resolve, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { Command } from 'commander';
 import { resolveControllerHome, controllerSystemRoot } from '../repositories/controller-home';
-import { installExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistrationInput } from '../../runtime/plugins/external-registration';
+import { installExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistration, type ExternalPluginRegistrationInput } from '../../runtime/plugins/external-registration';
 import { createDesktopOperatorRegistrationInput } from '../../runtime/plugins/desktop-operator-registration';
 import { controllerPluginRepository, getAssistantPluginManifest, syncAssistantPluginRegistry } from '../../runtime/plugins/store';
 
-interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer:string; platforms:NodeJS.Platform[]; }
+export interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer:string; providerVersion?:string; protocolVersion?:string; platforms:NodeJS.Platform[]; }
 interface Registry { schemaVersion:1; plugins:RegistryEntry[]; }
 interface CliOptions { json?:boolean; controllerHome?:string; refresh?:boolean; }
 const packageRoot=resolve(dirname(fileURLToPath(import.meta.url)),'../../..');
@@ -24,11 +24,26 @@ function registry():Registry{
     if(!plugin.repository.startsWith('https://github.com/moretea-labs/')||!plugin.repository.endsWith('.git'))throw new Error(`PLUGIN_CATALOG_UNTRUSTED_REPOSITORY: ${plugin.id}`);
     if(!/^v\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(plugin.ref))throw new Error(`PLUGIN_CATALOG_UNPINNED_REF: ${plugin.id}`);
     if(plugin.installer!=='forge-plugin-install.mjs')throw new Error(`PLUGIN_CATALOG_INSTALLER_INVALID: ${plugin.id}`);
+    if(plugin.providerVersion!==undefined&&!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(plugin.providerVersion))throw new Error(`PLUGIN_CATALOG_PROVIDER_VERSION_INVALID: ${plugin.id}`);
+    if(plugin.protocolVersion!==undefined&&!/^\d+\.\d+$/.test(plugin.protocolVersion))throw new Error(`PLUGIN_CATALOG_PROTOCOL_VERSION_INVALID: ${plugin.id}`);
     ids.add(plugin.id);
   }
   return value;
 }
 function within(root:string,relative:string):string{const target=resolve(root,relative);const base=`${resolve(root)}${sep}`;if(target!==resolve(root)&&!target.startsWith(base))throw new Error('PLUGIN_INSTALL_PATH_ESCAPE');return target;}
+export function pluginCatalogCompatibility(entry:RegistryEntry,platform:NodeJS.Platform=process.platform):{compatible:boolean;reason?:string}{
+  if(!entry.platforms.includes(platform))return{compatible:false,reason:`unsupported platform: ${platform}`};
+  if(entry.providerVersion&&entry.providerVersion!==entry.version)return{compatible:false,reason:`catalog version ${entry.version} does not match pinned provider version ${entry.providerVersion}`};
+  return{compatible:true};
+}
+export function officialPluginCatalogItems(platform:NodeJS.Platform=process.platform){return registry().plugins.map(entry=>({...entry,...pluginCatalogCompatibility(entry,platform)}));}
+export function externalPluginListItem(controllerHome:string,registration:ExternalPluginRegistration){
+  const base={pluginId:registration.pluginId,version:registration.pluginVersion,provider:registration.provider,enabled:registration.enabled,scope:registration.scope,transport:registration.transport.kind};
+  if(registration.scope==='repository')return{...base,healthScope:'repository_context_required' as const};
+  const repository=controllerPluginRepository(controllerHome);
+  try{return{...base,health:getAssistantPluginManifest(controllerHome,repository,registration.pluginId).health};}
+  catch(error){return{...base,health:{state:'error',message:error instanceof Error?error.message:String(error)}};}
+}
 function run(command:string,args:string[],cwd:string,timeoutMs=120000):string{
   const result=spawnSync(command,args,{cwd,encoding:'utf8',timeout:timeoutMs,maxBuffer:32*1024*1024,shell:false,windowsHide:true});
   if(result.error)throw new Error(`PLUGIN_INSTALL_COMMAND_FAILED: ${result.error.message}`);
@@ -40,17 +55,29 @@ function installerJson(stdout:string):Record<string,unknown>{
   for(let i=lines.length-1;i>=0;i--){try{const x=JSON.parse(lines[i]);if(x&&typeof x==='object'&&!Array.isArray(x)&&x.schemaVersion===1)return x;}catch{}}
   throw new Error('PLUGIN_INSTALLER_OUTPUT_INVALID');
 }
+export function installerNextSteps(result:Record<string,unknown>):string[]{
+  if(!Array.isArray(result.nextSteps))return[];
+  return result.nextSteps
+    .filter((value):value is string=>typeof value==='string')
+    .map(value=>value.replace(/[\u0000-\u001F\u007F]/g,' ').trim().slice(0,1000))
+    .filter(Boolean)
+    .slice(0,10);
+}
 function registrationFrom(result:Record<string,unknown>,entry:RegistryEntry):ExternalPluginRegistrationInput{
   if(result.registration){const input=result.registration as ExternalPluginRegistrationInput;if(input.pluginId!==entry.id)throw new Error('PLUGIN_INSTALLER_ID_MISMATCH');if(input.pluginVersion!==entry.version)throw new Error('PLUGIN_INSTALLER_VERSION_MISMATCH');return input;}
   const facts=result.providerInstall as Record<string,unknown>|undefined;
   if(!facts||facts.kind!=='desktop_operator'||entry.id!=='desktop_operator')throw new Error('PLUGIN_INSTALLER_REGISTRATION_MISSING');
-  if(facts.pluginVersion!==entry.version||facts.protocolVersion!=='1.0')throw new Error('PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH');
+  const expectedProviderVersion=entry.providerVersion??entry.version;
+  const expectedProtocolVersion=entry.protocolVersion??'1.0';
+  if(facts.pluginVersion!==expectedProviderVersion)throw new Error(`PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH: expected ${expectedProviderVersion} for ${entry.id}@${entry.version}, actual ${String(facts.pluginVersion??'missing')}`);
+  if(facts.protocolVersion!==expectedProtocolVersion)throw new Error(`PLUGIN_INSTALLER_PROTOCOL_VERSION_MISMATCH: expected ${expectedProtocolVersion} for ${entry.id}@${entry.version}, actual ${String(facts.protocolVersion??'missing')}`);
   const socketPath=typeof facts.socketPath==='string'?facts.socketPath:'';const launchAgentLabel=typeof facts.launchAgentLabel==='string'?facts.launchAgentLabel:'';const expectedProgramContains=typeof facts.expectedProgramContains==='string'?facts.expectedProgramContains:'';
   if(!isAbsolute(socketPath)||!launchAgentLabel||!expectedProgramContains)throw new Error('PLUGIN_INSTALLER_PROVIDER_FACTS_INVALID');
-  return createDesktopOperatorRegistrationInput({socketPath,launchAgentLabel,expectedProgramContains,pluginVersion:entry.version,protocolVersion:'1.0'});
+  return createDesktopOperatorRegistrationInput({socketPath,launchAgentLabel,expectedProgramContains,pluginVersion:expectedProviderVersion,protocolVersion:expectedProtocolVersion});
 }
 function install(entry:RegistryEntry,controllerHome:string):Record<string,unknown>{
-  if(!entry.platforms.includes(process.platform))throw new Error(`PLUGIN_PLATFORM_UNSUPPORTED: ${entry.id}/${process.platform}`);
+  const compatibility=pluginCatalogCompatibility(entry,process.platform);
+  if(!compatibility.compatible)throw new Error(`PLUGIN_CATALOG_INCOMPATIBLE: ${entry.id}@${entry.version}: ${compatibility.reason}`);
   const packagesRoot=join(controllerSystemRoot(controllerHome),'plugins','packages');mkdirSync(packagesRoot,{recursive:true,mode:0o700});
   const finalRoot=join(packagesRoot,entry.id),stage=join(packagesRoot,`.${entry.id}.${randomUUID()}.staging`),backup=join(packagesRoot,`.${entry.id}.${randomUUID()}.backup`);let backed=false;
   try{
@@ -62,13 +89,13 @@ function install(entry:RegistryEntry,controllerHome:string):Record<string,unknow
     const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry));
     const repository=controllerPluginRepository(controllerHome);syncAssistantPluginRegistry(controllerHome,repository);const plugin=getAssistantPluginManifest(controllerHome,repository,entry.id);
     if(backed)rmSync(backup,{recursive:true,force:true});
-    return{pluginId:entry.id,version:entry.version,packageRoot:finalRoot,registrationRevision:installed.revision,enabled:plugin.enabled,health:plugin.health};
+    return{pluginId:entry.id,version:entry.version,packageRoot:finalRoot,registrationRevision:installed.revision,enabled:plugin.enabled,health:plugin.health,nextSteps:installerNextSteps(result)};
   }catch(error){rmSync(stage,{recursive:true,force:true});if(backed&&existsSync(finalRoot))rmSync(finalRoot,{recursive:true,force:true});if(backed&&existsSync(backup))renameSync(backup,finalRoot);throw error;}
 }
 export function buildPluginCommand():Command{
   const root=new Command('plugin').description('Discover and install trusted Forge plugins');
-  root.command('catalog').description('List official plugins').option('--json','Output JSON').action((o:CliOptions)=>{const items=registry().plugins.map(x=>({...x,compatible:x.platforms.includes(process.platform)}));if(o.json)console.log(JSON.stringify({schemaVersion:1,platform:process.platform,plugins:items},null,2));else items.forEach(x=>console.log(`${x.id}\t${x.version}\t${x.compatible?'compatible':'unsupported'}\t${x.name}`));});
-  root.command('list').description('List installed external plugins').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--refresh','Probe providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome),repo=controllerPluginRepository(home);if(o.refresh)syncAssistantPluginRegistry(home,repo);const items=listExternalPluginRegistrations(home).map(r=>{let health:unknown;try{health=getAssistantPluginManifest(home,repo,r.pluginId).health;}catch(e){health={state:'error',message:e instanceof Error?e.message:String(e)};}return{pluginId:r.pluginId,version:r.pluginVersion,provider:r.provider,enabled:r.enabled,transport:r.transport.kind,health};});if(o.json)console.log(JSON.stringify({schemaVersion:1,plugins:items},null,2));else if(!items.length)console.log('No external Forge plugins installed.');else items.forEach(x=>console.log(`${x.pluginId}\t${x.version}\t${x.enabled?'enabled':'disabled'}\t${(x.health as {state?:string})?.state??'unknown'}`));});
-  root.command('install <plugin-id>').description('Install/update an official plugin from a pinned public release').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').action((id:string,o:CliOptions)=>{const entry=registry().plugins.find(x=>x.id===id);if(!entry)throw new Error(`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${id}`);const result=install(entry,resolveControllerHome(o.controllerHome));if(o.json)console.log(JSON.stringify(result,null,2));else console.log(`Installed ${entry.name} ${entry.version} (${(result.health as {state?:string})?.state??'unknown'}).`);});
+  root.command('catalog').description('List official plugins').option('--json','Output JSON').action((o:CliOptions)=>{const items=officialPluginCatalogItems();if(o.json)console.log(JSON.stringify({schemaVersion:1,platform:process.platform,plugins:items},null,2));else items.forEach(x=>console.log(`${x.id}\t${x.version}\t${x.compatible?'compatible':`incompatible (${x.reason})`}\t${x.name}`));});
+  root.command('list').description('List installed external plugins').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--refresh','Probe controller-scoped providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome),repo=controllerPluginRepository(home);if(o.refresh)syncAssistantPluginRegistry(home,repo);const items=listExternalPluginRegistrations(home).map(r=>externalPluginListItem(home,r));if(o.json)console.log(JSON.stringify({schemaVersion:1,plugins:items},null,2));else if(!items.length)console.log('No external Forge plugins installed.');else items.forEach(x=>console.log(`${x.pluginId}\t${x.version}\t${x.enabled?'enabled':'disabled'}\t${'healthScope' in x?'repository-context-required':((x.health as {state?:string})?.state??'unknown')}`));});
+  root.command('install <plugin-id>').description('Install/update an official plugin from a pinned public release').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').action((id:string,o:CliOptions)=>{const entry=registry().plugins.find(x=>x.id===id);if(!entry)throw new Error(`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${id}`);const result=install(entry,resolveControllerHome(o.controllerHome));if(o.json)console.log(JSON.stringify(result,null,2));else{console.log(`Installed ${entry.name} ${entry.version} (${(result.health as {state?:string})?.state??'unknown'}).`);for(const step of (result.nextSteps as string[]|undefined)??[])console.log(`- ${step}`);}});
   return root;
 }