@event4u/agent-config 9.10.0 → 9.11.0

package/dist/agent-src/templates/scripts/work_engine/directives/ui/stack_bundles.ts

@@ -0,0 +1,179 @@
+/**
+ * Verb → skill-bundle map for the stack-dispatched UI steps.
+ *
+ * The UI steps halt with `@agent-directive: ui-apply-<stack>` (and the
+ * `ui-design-review-` / `ui-polish-` equivalents). Those names are **directive
+ * verbs, not skill paths** — the same shape as `run-tests`, `create-plan`, and
+ * `apply-plan`, which likewise resolve to no skill file. Only 2 of the engine's
+ * 11 literal verbs name a real skill, so a verb is something the agent
+ * interprets, and the mapping from verb to the skills that implement it is a
+ * separate fact that has to be written down somewhere.
+ *
+ * Before this module that mapping lived only in a prose table in
+ * `docs/contracts/ui-track-flow.md`. Nothing verified it, and two of its four
+ * rows were wrong: `vue` pointed at the directive verb itself (naming no skill
+ * at all) and `plain` — which is also the fallback for every unrecognised
+ * project — pointed at `blade-ui`, a skill whose frontmatter is
+ * `packs: [laravel]` and which a non-Laravel consumer therefore does not have
+ * installed.
+ *
+ * Keeping the map here makes it checkable: `lint_ui_stack_bundles` asserts every
+ * member resolves to a real skill, and that no lane reachable without the
+ * `laravel` pack names a `laravel`-only skill. A CI check in this repo cannot
+ * see a consumer's installed pack combination, so the second assertion is the
+ * part that actually prevents the `plain → blade-ui` class of defect.
+ */
+
+/** Skills that implement a lane, in the order the agent should load them. */
+export interface StackBundle {
+    /** Skills that build / fix UI for this lane (`apply`, `polish`). */
+    readonly build: ReadonlyArray<string>;
+    /** Skills that review UI for this lane (`review`). */
+    readonly review: ReadonlyArray<string>;
+    /**
+     * True when every skill above ships outside the framework packs, i.e. the
+     * lane is safe as a fallback for a consumer whose packs we cannot predict.
+     * Only lanes marked `pack_agnostic` may be used as `DEFAULT_*`.
+     */
+    readonly pack_agnostic: boolean;
+}
+
+/**
+ * The pack-agnostic pair. Both live in `engineering-base`, so they are present
+ * in every install; both self-describe as stack-neutral
+ * (`ui-component-architect`: "the same lens applies to Blade, Livewire, React,
+ * or Vue trees"; `tailwind-engineer`: "the **how** for any Tailwind-stack
+ * screen"). This is the honest floor for a lane with no framework-specific
+ * executor — not a claim that the lane is fully served.
+ */
+const GENERIC_BUILD: ReadonlyArray<string> = ['ui-component-architect', 'tailwind-engineer'];
+
+/** `design-review` is stack-neutral and ships in `engineering-base`. */
+const GENERIC_REVIEW: ReadonlyArray<string> = ['design-review'];
+
+/**
+ * Lane → bundle. Keys mirror `KNOWN_STACKS`; the dispatch tables in
+ * `apply` / `review` / `polish` keep their own verb strings (a tested public
+ * contract) and consume this map only to name the skills in the halt body.
+ */
+export const STACK_BUNDLES: Readonly<Record<string, StackBundle>> = {
+    'blade-livewire-flux': {
+        build: ['flux', 'livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // Livewire without Flux — the common Laravel frontend. Previously fell
+    // into `plain` because detection required Livewire AND Flux.
+    'blade-livewire': {
+        build: ['livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // Filament is Livewire + Blade + Tailwind under the hood; the same
+    // executors apply. A Filament-specific skill is gated on evidence that
+    // these produce unusable output for it, not assumed.
+    filament: {
+        build: ['livewire', 'blade-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    'react-shadcn': {
+        build: ['react-shadcn-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // React without Radix/shadcn. `react-shadcn-ui` still carries the React
+    // component idiom; the shadcn-specific parts simply do not apply.
+    react: {
+        build: ['react-shadcn-ui'],
+        review: GENERIC_REVIEW,
+        pack_agnostic: false,
+    },
+    // No Vue executor exists. The previous prose row pointed at the directive
+    // verb itself, which named nothing; the generic pair is a smaller lie and a
+    // stated one — the halt body says the lane has no Vue-specific skill.
+    vue: {
+        build: GENERIC_BUILD,
+        review: GENERIC_REVIEW,
+        pack_agnostic: true,
+    },
+    plain: {
+        build: GENERIC_BUILD,
+        review: GENERIC_REVIEW,
+        pack_agnostic: true,
+    },
+};
+
+/**
+ * Lanes served by the stack-neutral pair rather than a framework executor.
+ *
+ * `plain` and `vue` share the bundle but not the meaning, and the halt body has
+ * to say which it is. For `plain` the pair IS the right answer — there is no
+ * framework to be idiomatic about. For `vue` it is a gap: a Vue project has a
+ * definite idiom and the package has no executor for it, so the result must not
+ * read as Vue support.
+ */
+export const GENERIC_LANES: ReadonlySet<string> = new Set(['vue', 'plain']);
+
+/** Lanes where the stack-neutral pair is the correct answer, not a shortfall. */
+const NATIVELY_GENERIC_LANES: ReadonlySet<string> = new Set(['plain']);
+
+/**
+ * The label detection returns for a framework it recognises but does not
+ * model. Mirrors `stack/detect.ts::UNSUPPORTED_STACK`; duplicated as a literal
+ * because this module is import-free by design (the detector is a leaf module
+ * the directives must not depend on).
+ */
+export const UNSUPPORTED_LANE = 'unknown';
+
+/** Return the bundle for `stack`, or the `plain` bundle when unmapped. */
+export function bundle_for(stack: string): StackBundle {
+    return STACK_BUNDLES[stack] ?? (STACK_BUNDLES['plain'] as StackBundle);
+}
+
+/**
+ * Questions for the refusal halt on an unmodelled framework.
+ *
+ * Not a directive — there is nothing honest to dispatch to. The agent names
+ * the actual markers from the manifest (it has filesystem access; the engine
+ * deliberately does not carry them on `StackResult`), and the user chooses
+ * between the stack-neutral floor and stopping.
+ */
+export function unsupported_stack_questions(step: string): string[] {
+    return [
+        '> Detection found a frontend framework this package does not model, ' +
+            `so there is no \`${step}\` lane for it.`,
+        '> Name the markers you see in `composer.json` / `package.json` so the ' +
+            'choice below is made on the real stack, not on a guess.',
+        '> 1. Continue on the stack-neutral floor — `ui-component-architect` + ' +
+            '`tailwind-engineer`. Output will not be idiomatic for this ' +
+            'framework; say so in the result.',
+        '> 2. Abort — drop this UI request and add a lane first ' +
+            '(`docs/contracts/ui-stack-extension.md`).',
+    ];
+}
+
+/**
+ * Render the "load these skills" line for a dispatch halt.
+ *
+ * The engine cannot load a skill itself; naming the bundle is what stops the
+ * agent from resolving an unresolvable verb by guessing. A lane with no
+ * framework-specific executor says that outright rather than presenting the
+ * generic pair as if it were stack support.
+ */
+export function bundle_line(stack: string, role: 'build' | 'review'): string {
+    const bundle = bundle_for(stack);
+    const skills = role === 'review' ? bundle.review : bundle.build;
+    const rendered = skills.map((name) => `\`${name}\``).join(' + ');
+    if (NATIVELY_GENERIC_LANES.has(stack)) {
+        return `> Skills: ${rendered} — stack-neutral, which is what \`${stack}\` means.`;
+    }
+    if (GENERIC_LANES.has(stack)) {
+        return (
+            `> Skills: ${rendered} — there is no \`${stack}\`-specific executor, ` +
+            'so this is the stack-neutral floor, not idiomatic ' +
+            `\`${stack}\`. Say so in the result.`
+        );
+    }
+    return `> Skills: ${rendered}.`;
+}

package/dist/agent-src/templates/scripts/work_engine/stack/detect.ts

@@ -17,17 +17,35 @@
  *
  * 1. `composer.json` lists `livewire/livewire` AND `livewire/flux` →
  *    `blade-livewire-flux`
- * 2. `package.json` lists `react` AND any of `@radix-ui/*`,
+ * 2. `composer.json` lists `filament/filament` → `filament` (before bare
+ *    Livewire: Filament pulls Livewire in transitively)
+ * 3. `composer.json` lists `livewire/livewire` → `blade-livewire`
+ * 4. `package.json` lists `react` AND any of `@radix-ui/*`,
  *    `shadcn-ui` or has a `components.json` (the shadcn marker file)
  *    → `react-shadcn`
- * 3. `package.json` lists `vue` (any major) → `vue`
- * 4. Otherwise → `plain`
+ * 5. `package.json` lists `react` → `react`
+ * 6. `package.json` lists `vue` (any major) → `vue`
+ * 7. Either manifest names a recognised-but-unmodelled framework
+ *    (Svelte, Angular, Nuxt, Astro, Solid, Qwik, Inertia) → `unknown`
+ * 8. Otherwise → `plain`
+ *
+ * Rules 3, 5 and 7 exist because the earlier table sent three common
+ * shapes into `plain`: Laravel+Livewire without Flux failed rule 1's `&&`,
+ * React without Radix failed rule 4, and every unmodelled framework was
+ * indistinguishable from a genuinely plain project. `plain` now means "no
+ * frontend markers"; `unknown` means "a framework we do not model", and
+ * dispatch refuses on it rather than handing over generic tooling silently.
  *
  * Detection is filesystem-cheap: at most three small JSON reads per
  * project root. Errors (missing file, malformed JSON, missing `require`
  * section) downgrade to `plain` rather than raising — a wrong stack
  * label is recoverable (audit catches it, user can override), but a
  * crash mid-dispatch is not.
+ *
+ * Root manifests only, by design: a monorepo caller passes the workspace
+ * root that carries the manifest it cares about. Note the consequence —
+ * a caller that always passes the repository root gets `plain` for a
+ * monorepo, so the caller owns scope selection, not the detector.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -43,18 +61,59 @@ import * as path from 'node:path';
  */
 export const KNOWN_STACKS: ReadonlySet<string> = new Set([
     'blade-livewire-flux',
+    'blade-livewire',
+    'filament',
     'react-shadcn',
+    'react',
     'vue',
     'plain',
+    'unknown',
 ]);
 
-/** Fallback when no manifest signal matches. */
+/**
+ * Label for a project with no frontend markers at all.
+ *
+ * `plain` used to carry two meanings — "genuinely a plain HTML/Tailwind
+ * project" and "detection failed, here is generic tooling anyway" — which made
+ * a loud failure impossible without punishing real plain projects. The second
+ * meaning is now {@link UNSUPPORTED_STACK}.
+ */
 export const DEFAULT_STACK = 'plain';
 
+/**
+ * Label for a project whose frontend IS recognisable but is not modelled.
+ *
+ * Dispatch refuses on this label instead of degrading to generic tooling: a
+ * Filament or Svelte project silently routed to a Tailwind-only bundle is
+ * user-hostile precisely because the output looks like it worked.
+ */
+export const UNSUPPORTED_STACK = 'unknown';
+
 const _SHADCN_RADIX_PREFIX = '@radix-ui/';
 const _SHADCN_PACKAGE_NAMES: ReadonlySet<string> = new Set(['shadcn-ui', 'shadcn']);
 const _FLUX_PACKAGE = 'livewire/flux';
 const _LIVEWIRE_PACKAGE = 'livewire/livewire';
+const _FILAMENT_PACKAGE = 'filament/filament';
+
+/**
+ * Frontend markers this package recognises but does not model.
+ *
+ * One of these present means detection **succeeded** at recognising a
+ * framework and the package simply has no lane for it — the `unknown` case,
+ * not the `plain` case. Keep the list short and factual; a marker leaves it
+ * only when a real lane exists.
+ */
+const _UNMODELLED_MARKERS: ReadonlyArray<string> = [
+    'svelte',
+    '@angular/core',
+    'nuxt',
+    'astro',
+    'solid-js',
+    '@builder.io/qwik',
+    '@inertiajs/vue3',
+    '@inertiajs/react',
+    'inertiajs/inertia-laravel',
+];
 
 /**
  * A heterogeneous JSON object, mirroring a Python `dict[str, object]`.
@@ -109,14 +168,51 @@ export function detect_stack(project_root: string): StackResult {
         return new StackResult({ frontend: 'blade-livewire-flux', mtime });
     }
 
+    // Filament before bare Livewire: it pulls Livewire in transitively, so a
+    // Filament project would otherwise be labelled by its dependency rather
+    // than by the framework the developer actually works in.
+    if (_has_package(composer, ['require', 'require-dev'], _FILAMENT_PACKAGE)) {
+        return new StackResult({ frontend: 'filament', mtime });
+    }
+
+    // Livewire WITHOUT Flux is the common Laravel frontend, not an unknown
+    // one. It used to fail the `&&` above and land in `plain`.
+    if (_has_package(composer, ['require', 'require-dev'], _LIVEWIRE_PACKAGE)) {
+        return new StackResult({ frontend: 'blade-livewire', mtime });
+    }
+
     if (_is_react_shadcn(pkg, components_json)) {
         return new StackResult({ frontend: 'react-shadcn', mtime });
     }
 
+    // React without Radix/shadcn is a served stack, not an unknown one.
+    if (_has_package(pkg, _PKG_DEP_KEYS, 'react')) {
+        return new StackResult({ frontend: 'react', mtime });
+    }
+
     if (_has_vue(pkg)) {
         return new StackResult({ frontend: 'vue', mtime });
     }
 
+    // A recognised-but-unmodelled framework is NOT `plain`. Refusing here is
+    // the point: `plain` means "no frontend markers", and conflating the two
+    // is what let a Svelte or Inertia project receive Tailwind-only tooling
+    // and no warning.
+    if (_has_unmodelled_marker(composer, pkg)) {
+        return new StackResult({ frontend: UNSUPPORTED_STACK, mtime });
+    }
+
+    // Monorepo: no manifest at the root, but one sits in a workspace directory.
+    // That is a wrong-scope call, not a plain project — the caller owns scope
+    // selection, so say so instead of labelling the whole repo `plain` and
+    // dispatching generic tooling at it.
+    //
+    // A repo with no manifest ANYWHERE stays `plain`: that is greenfield, and
+    // the scaffold path depends on it.
+    if (mtime === 0.0 && _has_nested_manifest(project_root)) {
+        return new StackResult({ frontend: UNSUPPORTED_STACK, mtime });
+    }
+
     return new StackResult({ frontend: DEFAULT_STACK, mtime });
 }
 
@@ -185,6 +281,61 @@ function _all_dependencies(manifest: Manifest, ...keys: string[]): Manifest {
     return merged;
 }
 
+/** Dependency sections a `package.json` can carry. */
+const _PKG_DEP_KEYS: ReadonlyArray<string> = [
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+];
+
+/** True when `name` appears in any of `manifest`'s named dependency sections. */
+function _has_package(
+    manifest: Manifest,
+    sections: ReadonlyArray<string>,
+    name: string,
+): boolean {
+    return name in _all_dependencies(manifest, ...sections);
+}
+
+/** Workspace directories a monorepo conventionally puts its packages in. */
+const _WORKSPACE_DIRS: ReadonlyArray<string> = ['packages', 'apps', 'services', 'libs'];
+
+/**
+ * True when no root manifest exists but a workspace directory holds one.
+ *
+ * Deliberately shallow — one `readdir` per conventional workspace directory,
+ * one `stat` per child. It answers "was this called at the wrong scope?", not
+ * "where is the real project", which stays the caller's job.
+ */
+function _has_nested_manifest(project_root: string): boolean {
+    for (const dir of _WORKSPACE_DIRS) {
+        const base = path.join(project_root, dir);
+        let entries: string[];
+        try {
+            entries = fs.readdirSync(base);
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (
+                _is_file(path.join(base, entry, 'composer.json')) ||
+                _is_file(path.join(base, entry, 'package.json'))
+            ) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+/** True when either manifest names a framework we recognise but do not model. */
+function _has_unmodelled_marker(composer: Manifest, pkg: Manifest): boolean {
+    const composer_deps = _all_dependencies(composer, 'require', 'require-dev');
+    const pkg_deps = _all_dependencies(pkg, ..._PKG_DEP_KEYS);
+    return _UNMODELLED_MARKERS.some((marker) => marker in composer_deps || marker in pkg_deps);
+}
+
 function _is_blade_livewire_flux(composer: Manifest): boolean {
     const deps = _all_dependencies(composer, 'require', 'require-dev');
     return _LIVEWIRE_PACKAGE in deps && _FLUX_PACKAGE in deps;

package/dist/agent-src/templates/scripts/work_engine/state.ts

@@ -629,10 +629,12 @@ function _validate_app_spec(app_spec: JsonValue): void {
  * agent-directive that populates it. An empty dict is the in-progress
  * shape after the skill returns but before the brief lands; the gate
  * treats it the same as `null`. Once populated, `design_confirmed`
- * (when present) must be a bool. Other keys (`layout`, `components`,
- * `states`, `microcopy`, `a11y`, `reused_from_audit`) are
- * validated by the design handler against the skill contract — the
- * schema only enforces shape, not content.
+ * (when present) must be a bool, and `states` (when present and not
+ * `null`) must be an object — the design gate's per-state loop is
+ * object-guarded, so a string or list would bypass all five checks.
+ * The remaining keys (`layout`, `components`, `microcopy`, `a11y`,
+ * `reused_from_audit`) are validated by the design handler against the
+ * skill contract — the schema only enforces shape, not content.
  */
 function _validate_ui_design(ui_design: JsonValue): void {
     if (ui_design === null) {
@@ -652,6 +654,21 @@ function _validate_ui_design(ui_design: JsonValue): void {
             'state.ui_design.design_confirmed must be a boolean when present',
         );
     }
+    // `states` is shape-checked here, not left to the handler. The design
+    // gate's per-state loop was guarded on "is this an object", so a string or
+    // list silently skipped all five required-state checks — the gate passed
+    // while covering no state at all. Rejecting the wrong shape at the schema
+    // boundary means the loop can no longer be bypassed by type.
+    if (
+        'states' in ui_design &&
+        ui_design['states'] !== null &&
+        !_isDict(ui_design['states'])
+    ) {
+        throw new SchemaError(
+            'state.ui_design.states must be a JSON object (one key per ' +
+                `required state) or null; got ${pyTypeName(ui_design['states'])}`,
+        );
+    }
 }
 
 /**

package/dist/cli/initRouting.js

@@ -10,6 +10,61 @@
  * unit-testable, separate from the self-executing CLI entry point.
  */
 import { isHeadless } from './commands/uiServe.js';
+/** Flags that mean "the caller already knows what to install" → no picker. */
+const CLI_SIGNALS = new Set([
+    '--no-ui', '--tools', '--ai', '--yes', '-y', '--quiet', '-q',
+    '--dry-run', '--minimal', '--settings-only', '--list-tools',
+    '--validate-only', '--fleet', '--project',
+]);
+/** The explicit GUI opt-in documented in the README. */
+const GUI_FLAG = '--gui';
+/** `--flag=value` and `--flag value` both normalize to `--flag`. */
+function flagOf(arg) {
+    return arg.split('=', 1)[0];
+}
+/** Whether the explicit `--gui` opt-in is present in `rest`. */
+export function hasGuiFlag(rest) {
+    return rest.some((arg) => flagOf(arg) === GUI_FLAG);
+}
+/**
+ * `rest` with every `--gui` token removed. The bash installer's argument loop
+ * ends in `*) err "Unknown argument: $1"; exit 1`, so `--gui` must never reach
+ * it — `--gui` is an `init` front-end flag with no installer counterpart.
+ */
+export function withoutGuiFlag(args) {
+    return args.filter((arg) => flagOf(arg) !== GUI_FLAG);
+}
+/**
+ * The conflict, if any, between an explicit `--gui` and an opt-out that beats
+ * it — returns a one-line reason, or `null` when there is no conflict.
+ *
+ * `--gui` overrides the *capability* probes (TTY, headless) but yields to the
+ * *intent* guards (`CI`, `AGENT_CONFIG_NO_UI`, and the CLI-mode flags). When
+ * intent wins, the explicit request is never discarded silently: the caller
+ * asked for the GUI in so many words, so `init` fails loudly instead of
+ * quietly doing the opposite (AI council 2026-07-31, Q1 option B + Q2).
+ *
+ * `rest` is argv without the leading `init` token.
+ */
+export function findInitGuiConflict(rest) {
+    if (!hasGuiFlag(rest))
+        return null;
+    for (const arg of rest) {
+        const flag = flagOf(arg);
+        if (flag !== undefined && CLI_SIGNALS.has(flag)) {
+            return `--gui conflicts with ${flag}; drop one`;
+        }
+    }
+    const ci = (process.env['CI'] ?? '').trim();
+    if (ci && ci !== '0') {
+        return '--gui conflicts with CI=' + ci + ' in the environment; unset CI or drop --gui';
+    }
+    const envNoUi = (process.env['AGENT_CONFIG_NO_UI'] ?? '').trim();
+    if (envNoUi && envNoUi !== '0') {
+        return '--gui conflicts with AGENT_CONFIG_NO_UI=' + envNoUi + ' in the environment; unset it or drop --gui';
+    }
+    return null;
+}
 /**
  * Whether `init` should open the browser wizard instead of the non-interactive
  * CLI install. Returns false (→ delegate to the bash CLI install) when ANY of
@@ -22,6 +77,16 @@ import { isHeadless } from './commands/uiServe.js';
  *     --validate-only) — the caller already knows what to install and
  *     doesn't want the picker.
  *
+ * An explicit `--gui` suppresses the two *capability* probes (TTY, headless)
+ * only. It does not defeat `CI`, `AGENT_CONFIG_NO_UI`, or a CLI-mode flag —
+ * those combinations are rejected up-front by `findInitGuiConflict`, so a
+ * `--gui` that reaches here and still loses is impossible.
+ *
+ * `--gui` deliberately does NOT imply `--allow-headless`: on a headless host
+ * `runUiServe` refuses with an actionable error naming `--allow-headless`,
+ * which beats booting a server that then waits for a browser that cannot
+ * arrive (AI council 2026-07-31, Q3).
+ *
  * `rest` is argv without the leading `init` token.
  */
 export function shouldInitLaunchGui(rest) {
@@ -31,18 +96,16 @@ export function shouldInitLaunchGui(rest) {
     const envNoUi = (process.env['AGENT_CONFIG_NO_UI'] ?? '').trim();
     if (envNoUi && envNoUi !== '0')
         return false;
-    if (process.stdin.isTTY !== true || process.stdout.isTTY !== true)
-        return false;
-    if (isHeadless())
-        return false;
-    const cliSignals = new Set([
-        '--no-ui', '--tools', '--ai', '--yes', '-y', '--quiet', '-q',
-        '--dry-run', '--minimal', '--settings-only', '--list-tools',
-        '--validate-only', '--fleet', '--project',
-    ]);
+    const forced = hasGuiFlag(rest);
+    if (!forced) {
+        if (process.stdin.isTTY !== true || process.stdout.isTTY !== true)
+            return false;
+        if (isHeadless())
+            return false;
+    }
     for (const arg of rest) {
-        const flag = arg.split('=', 1)[0];
-        if (flag !== undefined && cliSignals.has(flag))
+        const flag = flagOf(arg);
+        if (flag !== undefined && CLI_SIGNALS.has(flag))
             return false;
     }
     return true;

package/dist/cli/initRouting.js.map

@@ -1 +1 @@
-{"version":3,"file":"initRouting.js","sourceRoot":"","sources":["../../src/cli/initRouting.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"initRouting.js","sourceRoot":"","sources":["../../src/cli/initRouting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAmB,MAAM,uBAAuB,CAAC;AAEpE,8EAA8E;AAC9E,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IAC7C,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI;IAC5D,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,cAAc;IAC3D,iBAAiB,EAAE,SAAS,EAAE,WAAW;CAC5C,CAAC,CAAC;AAEH,wDAAwD;AACxD,MAAM,QAAQ,GAAG,OAAO,CAAC;AAEzB,oEAAoE;AACpE,SAAS,MAAM,CAAC,GAAW;IACvB,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,IAAuB;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAuB;IAClD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,QAAQ,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACvD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9C,OAAO,wBAAwB,IAAI,YAAY,CAAC;QACpD,CAAC;IACL,CAAC;IACD,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,0BAA0B,GAAG,EAAE,GAAG,6CAA6C,CAAC;IAC3F,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,IAAI,OAAO,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;QAC7B,OAAO,0CAA0C,GAAG,OAAO,GAAG,6CAA6C,CAAC;IAChH,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACvD,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5C,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,IAAI,OAAO,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAChF,IAAI,UAAU,EAAE;YAAE,OAAO,KAAK,CAAC;IACnC,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,IAAI,KAAK,SAAS,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;IAClE,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAAuB;IAC9D,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,WAAW,CAAC,CAAC;IAC5D,OAAO,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACvD,MAAM,SAAS,GAAqC;QAChD,YAAY,EAAE,SAAS;QACvB,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,CAAC;QACd,UAAU,EAAE,SAAS;KACxB,CAAC;IACF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,GAAG,KAAK,SAAS;YAAE,SAAS;QAChC,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YACtB,SAAS,CAAC,IAAI,GAAG,KAAK,CAAC;QAC3B,CAAC;aAAM,IAAI,GAAG,KAAK,kBAAkB,EAAE,CAAC;YACpC,SAAS,CAAC,aAAa,GAAG,IAAI,CAAC;QACnC,CAAC;aAAM,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,gBAAgB,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;YAC7E,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACtB,CAAC,IAAI,CAAC,CAAC;gBACP,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;oBACnB,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;oBACrC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;wBAAE,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC;gBAC7C,CAAC;qBAAM,IAAI,GAAG,KAAK,gBAAgB,EAAE,CAAC;oBAClC,SAAS,CAAC,WAAW,GAAG,KAAK,CAAC;gBAClC,CAAC;qBAAM,CAAC;oBACJ,SAAS,CAAC,MAAM,GAAG,KAAK,CAAC;gBAC7B,CAAC;YACL,CAAC;QACL,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3D,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;gBAAE,SAAS,CAAC,IAAI,GAAG,CAAC,CAAC;QAC7C,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;YAC3C,SAAS,CAAC,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;QAChE,CAAC;aAAM,IAAI,GAAG,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;YACtC,SAAS,CAAC,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;QACtD,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC;AACrB,CAAC"}

package/dist/cli/main.js

@@ -22,7 +22,7 @@ import { runRecordTriggerEval } from './commands/recordTriggerEval.js';
 import { runDoctorShell } from './commands/doctorShell.js';
 import { runRtkDetect } from './commands/rtkDetect.js';
 import { runUiServe } from './commands/uiServe.js';
-import { shouldInitLaunchGui, buildInitGuiOptions, buildProjectInitDelegation } from './initRouting.js';
+import { shouldInitLaunchGui, buildInitGuiOptions, buildProjectInitDelegation, findInitGuiConflict, withoutGuiFlag } from './initRouting.js';
 import { maybePrintFirstRunNotice } from './firstRunNotice.js';
 import { runSettings } from './commands/settings.js';
 import { runConfig } from './commands/config.js';
@@ -354,6 +354,15 @@ async function main(rawArgv) {
     // --project` writer — never the GUI, never the global install
     // (road-to-setup-experience § Phase 1.3).
     if (head === 'init') {
+        // `--gui` is the explicit opt-in. It overrides the capability probes
+        // (TTY, headless) but never `CI` / `AGENT_CONFIG_NO_UI` / a CLI-mode
+        // flag — and an explicit request is never discarded silently, so a
+        // losing `--gui` is a hard error rather than a quiet CLI install.
+        const conflict = findInitGuiConflict(argv.slice(1));
+        if (conflict !== null) {
+            logger.error(`init: ${conflict}`);
+            return 2;
+        }
         const projectDelegation = buildProjectInitDelegation(argv.slice(1));
         if (projectDelegation !== null) {
             return delegateToBash({ args: projectDelegation });
@@ -365,8 +374,10 @@ async function main(rawArgv) {
         logger.info('Opening the browser install wizard (set AGENT_CONFIG_NO_UI=1 or pass --no-ui for the CLI install).');
         return runUiServe(buildInitGuiOptions(argv.slice(1)));
     }
-    // Everything else forwards to the Bash dispatcher verbatim.
-    return delegateToBash({ args: argv });
+    // Everything else forwards to the Bash dispatcher. `--gui` is stripped:
+    // it has no installer counterpart and the bash argument loop ends in
+    // `err "Unknown argument"`.
+    return delegateToBash({ args: withoutGuiFlag(argv) });
 }
 main(process.argv.slice(2))
     .then((code) => {