@monster-orange/den 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,95 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.2.2] - 2026-11-04
+
+### Added
+
+- **`<cli> service install | status | print | uninstall`**: the web UI's
+  launchd service, over `service/install.sh`, so a distribution no longer
+  wraps the script in its Makefile. The label and log directory are
+  `web.service: { label, logs }` in the org config; the defaults are the
+  script's own (`local.<distribution dir name>.web`,
+  `~/Library/Logs/<distribution dir name>`), so an existing install keeps its
+  label. A bad label, a non-path `logs` or an unknown key under `web.service`
+  is an error. `install` (which also restarts) says `running` only once
+  `/api/server-info` answers with JSON, and after 30s without an answer says
+  `installed but not answering yet: check <logs dir>` and exits 1. `print`
+  writes the plist only, on any OS. See "Running the web UI as a service" in
+  `docs/distributions.md`.
+- **`<cli> mcp --call <tool> ['<json args>']` and `<cli> mcp --list`.** One
+  tool call from a shell, through the same tool layer as the MCP server
+  (registered tools only, so actions only as named in `mcp.actions`; every
+  guard; redaction; audit headers), against the running web server. Prints
+  the tool's text to stdout and exits 1 when the tool reports an error.
+  `--list` prints the tool names.
+- **Service aliases.** `up`, `down`, `restart` and `logs` (and every caller
+  of the service resolver, so `/api/service/exec` too) accept a service's
+  manifest key or a compose stack's name, when it names exactly one service
+  in the workspace: `<cli> restart indexer` restarts the repo whose service
+  or stack is `indexer`. Repo names and listed addresses win over an alias.
+  An ambiguous alias is an error naming the candidates (`"worker" is
+  ambiguous in workspace "default": one/worker, two/worker`). See "Naming a
+  service" in `docs/distributions.md`.
+- **`validate` flags a redundant held manifest.** When a repo carries its own
+  manifest and the distribution still holds `manifests/<repo>.<name>.yml`,
+  `validate` warns (never an error) that the held file is not used and can be
+  deleted, or turned into `manifests/<repo>.override.yml`.
+
+### Fixed
+
+- **`-n`/`--dry-run` and `--plan` run nothing on every path.** Given a
+  `repo/service` address or an alias, `up` and `down` ignored them and
+  really ran the service (and its dependencies); they now print the order
+  they would run and stop. `restart` accepts `-n`/`--dry-run` too. Tested
+  for each way to name a target: the cwd repo, a repo, an address, an alias,
+  a compose stack name and an app.
+- **A dry run says what the real run does**, per target: the same command
+  lookup (own command, restart as down + up, a repo-started service's
+  repo up, nothing to stop, not found), so a dry run fails where the real
+  run would. Every dry run names its targets (`Would down: …`).
+- **`down` and `restart` on named services act on those services only.**
+  They took the services' dependencies down (or restarted them) too, even
+  ones other running services still use. `up` still starts dependencies;
+  `down <repo>` still stops the repo's closure, naming what else depends on
+  it.
+- **`down <repo>` stops that repo only.** It stopped the repo's whole
+  derived closure, so `down api` took down stacks it sits on that other
+  running systems use. `--with-deps` keeps the old behaviour (naming what
+  else uses them); `down -a` still stops everything.
+- **Plans show remote services as skipped, with the reason**
+  (`core (remote, skipped): core runs in dev; …`), and a named remote target
+  fails with the real run's reason.
+- **A compose sub-service restarts on its own**: `restart <repo>/<svc>` runs
+  `docker compose restart <svc>` in its stack (`<cli> stack restart <stack>
+  --service <svc>`): the same container and env, nothing recreated. Up and
+  down stay the stack's.
+- **A service its repo starts**: `down` on it says it is stopped by the
+  repo's down and names the command (exit 0, so a workspace Down that sends
+  every service stays clean); `restart` fails the same way, exit 1.
+- **`down` of a remote repo no longer warns about its dependents**: it stops
+  nothing, so nothing is at risk. Only targets that really stop here count.
+- **A failed or unknown target exits 1.** `up`, `down` and `restart` exited 0
+  when a named service failed or did not exist.
+- **A service with no commands of its own** (its repo's up starts it): `up`
+  runs the repo's up and says so, instead of `command "up" not found`; other
+  commands point at the repo, since they would reach its other services.
+- **`service status`** no longer prints launchctl's errors when the service
+  is not loaded.
+
+### Migrations
+
+- None required.
+- `down <repo/service>` and `restart <repo/service>` no longer touch the
+  service's dependencies; stop or restart those by name.
+- `down <repo>` (and a bare `down` in a repo) stops only that repo; add
+  `--with-deps` for its closure.
+- A Makefile target that runs `service/install.sh` with `DEN_SERVICE_LABEL`
+  and `DEN_SERVICE_LOGS` can become `<cli> service install`; put a non-default
+  label or log directory in `web.service` first, since the CLI reads the
+  config, not those env vars.
+- Delete held manifests `validate` now reports as unused.
+
 ## [0.2.1] - 2026-11-04
 
 ### Fixed

package/README.md

@@ -133,7 +133,7 @@ provider in `src/shared/auth/token-providers/`.
 
 ```bash
 den up [repo]          # start the repo's derived dependency closure (-x deps only, -n dry run)
-den down [repo]        # stop it cleanly
+den down [repo]        # stop it cleanly (--with-deps: and what it sits on)
 den status             # service health for the active workspace
 den apps               # Org > Application > Repo > Services
 den graph [repo]       # the derived dependency graph

package/docs/distributions.md

@@ -109,6 +109,23 @@ The web UI's Services cards show the layers each manifest was built from
 `manifestLayers`, e.g. `["held", "override"]`. `DEN_MANIFESTS_DIR` points the
 held and override lookup at another directory (tests use it).
 
+Once a repo carries its own manifest, a held `manifests/<repo>.acme.yml` is
+never read. `validate` says so, as a warning (not an error), naming the held
+file: delete it, or keep only what this distribution changes as
+`manifests/<repo>.override.yml`.
+
+## Naming a service
+
+`up`, `down`, `restart` and `logs` take a repo name (`shop`) or a
+`repo/service` address (`shop/api`). A service's manifest key (`api`) or a
+compose stack's name (`compose.name`, else the manifest's `name`) works too,
+when it names exactly one service in the workspace: a stack stands for its
+repo, so `<cli> restart search` restarts the repo whose stack is `search`.
+Repo names and listed addresses always win over an alias, so a catalog repo
+is never mistaken for another repo's service. An alias that names more than
+one service is an error that lists them (`"worker" is ambiguous in workspace
+"default": one/worker, two/worker`); name one of them.
+
 ## Placement
 
 Each service says where it runs, per environment: `local` (on this machine,
@@ -329,7 +346,40 @@ are the same directory.
 ## Running the web UI as a service (macOS)
 
 Den ships a launchd installer that runs the web UI at login and restarts it if
-it exits. From the distribution root:
+it exits:
+
+```bash
+./bin/acme service install     # install (or refresh) and start it
+./bin/acme service status      # launchd's view: state, pid, last exit code
+./bin/acme service print       # the LaunchAgent plist it would install; installs nothing
+./bin/acme service uninstall   # stop it and remove the LaunchAgent
+```
+
+The label and log directory come from the org config:
+
+```yaml
+web:
+  port: 7777
+  service:
+    label: local.acme.web # default: local.<distribution dir name>.web
+    logs: ~/Library/Logs/acme # default: ~/Library/Logs/<distribution dir name>
+```
+
+The defaults are the installer's own, so an install made by the script keeps
+its label. `logs` may start with `~/`; a relative path is under the
+distribution root. A label other than letters, digits, `.`, `-` and `_`, a
+`logs` that is not a path, or any other key under `web.service` is an error.
+`print` works on any OS; the rest are macOS only.
+
+`install` also restarts a service that is already installed. It says the
+service is running only once the web server answers
+`http://localhost:<web.port>/api/server-info` with JSON (a fresh server
+answers empty for a few seconds while it starts). If it has not answered
+within 30s, it says `installed but not answering yet: check <logs dir>` and
+exits 1.
+
+`<cli> service` runs the installer script below, which you can also run
+yourself, from the distribution root:
 
 ```bash
 DEN_ROOT="$PWD" DEN_SERVICE_LABEL=local.acme.web \
@@ -407,6 +457,20 @@ everyone's checkout is in the same place.
 `--port <n>` (on `mcp` or `mcp connect`) points it at a web server on another
 port.
 
+### One call from a shell
+
+```sh
+./bin/acme mcp --list                                  # the tool names this org registers
+./bin/acme mcp --call status                           # one tool; prints its text result
+./bin/acme mcp --call logs_tail '{"service":"shop/api","lines":50}'
+```
+
+`--call <tool> ['<json args>']` runs one tool through the same tool layer as
+the server: only registered tools (so actions only as named in
+`mcp.actions`), every guard, the same redaction and audit headers. It prints
+the tool's text to stdout and exits 1 when the tool reports an error (a
+refusal, a failed action, the web server down).
+
 ### Config
 
 Without an `mcp:` block in the org config (`config/<name>.yml`) only the read

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/service/install.sh

@@ -15,6 +15,9 @@
 #
 #   DEN_SERVICE_LABEL  launchd label (default local.<dist dir name>.web)
 #   DEN_SERVICE_LOGS   log directory (default ~/Library/Logs/<dist dir name>)
+#   DEN_SERVICE_READY_CHECK=external  install does not print "running": the
+#                      caller (`<cli> service install`) checks the server
+#                      answers first.
 set -euo pipefail
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
@@ -95,7 +98,11 @@ case "${1:-install}" in
     done
     [ "$loaded" = 1 ] || { echo "✗ launchctl bootstrap failed for $LABEL (plist: $PLIST)" >&2; exit 1; }
     launchctl kickstart -k "$DOMAIN/$LABEL"
-    echo "✓ $LABEL running (logs: $LOGS/web.log)"
+    if [ "${DEN_SERVICE_READY_CHECK:-}" = external ]; then
+      echo "… $LABEL started; waiting for it to answer"
+    else
+      echo "✓ $LABEL running (logs: $LOGS/web.log)"
+    fi
     ;;
   uninstall)
     launchctl bootout "$DOMAIN/$LABEL" 2>/dev/null || true
@@ -106,7 +113,12 @@ case "${1:-install}" in
     write_plist -
     ;;
   status)
-    launchctl print "$DOMAIN/$LABEL" | grep -E '^\s*(state|pid|last exit code|runs)' || echo "$LABEL is not loaded"
+    # launchctl's own "Could not find service" is noise when it isn't loaded.
+    if out="$(launchctl print "$DOMAIN/$LABEL" 2>/dev/null)"; then
+      printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs)'
+    else
+      echo "$LABEL is not loaded"
+    fi
     ;;
   *) echo "usage: $0 [install|uninstall|status|print]" >&2; exit 2 ;;
 esac

package/src/shared/den-config.ts

@@ -9,6 +9,7 @@
  */
 
 import * as fs from "fs";
+import * as os from "os";
 import * as path from "path";
 import * as yaml from "yaml";
 import type { Environment, ReleaseSourceConfig } from "./types/index.js";
@@ -238,6 +239,11 @@ export interface DenConfig {
    * only; `actions` opts in to named actions. See readMcpConfig.
    */
   mcp?: McpConfig;
+  /**
+   * The web UI: `port` (read by edge/config.ts readWebPort) and `service`,
+   * the launchd service `<cli> service` installs. See readWebServiceConfig.
+   */
+  web?: WebConfig;
   /**
    * Shared test accounts (email + secrets-backend item per role) the test
    * pillars log in as — see src/shared/auth/test-accounts.ts.
@@ -426,6 +432,7 @@ export function readDenConfig(): DenConfig {
       env_health_urls: parsed?.env_health_urls,
       security: parsed?.security,
       mcp: parsed?.mcp,
+      web: parsed?.web,
       test_accounts: parsed?.test_accounts,
       defaults: parsed?.defaults,
       secrets: parsed?.secrets,
@@ -602,6 +609,68 @@ export function readMcpConfig(
   };
 }
 
+// ── Web UI service (`<cli> service`) ──────────────────────────────────────────
+
+/** `web:` in the org config. */
+export interface WebConfig {
+  port?: number;
+  /** The launchd service that runs the web UI (`<cli> service install`). */
+  service?: { label?: string; logs?: string };
+}
+
+/** `web.service` with its defaults applied. */
+export interface ResolvedWebService {
+  /** launchd label; also the plist's name in ~/Library/LaunchAgents. */
+  label: string;
+  /** Directory the service's web.log goes to. */
+  logs: string;
+}
+
+const WEB_SERVICE_KEYS = ["label", "logs"];
+
+/**
+ * The web UI's launchd service. The defaults are service/install.sh's own
+ * (`local.<distribution dir name>.web`, `~/Library/Logs/<dir name>`), so an
+ * install made with the script keeps its label. `logs` may start with `~/`;
+ * a relative path is under the distribution root. A bad value throws.
+ */
+export function readWebServiceConfig(
+  config: DenConfig = readDenConfig(),
+  distRoot: string = ROOT,
+  home: string = os.homedir(),
+): ResolvedWebService {
+  const name = path.basename(distRoot);
+  const raw: unknown = config.web?.service;
+  if (
+    raw !== undefined &&
+    (raw === null || typeof raw !== "object" || Array.isArray(raw))
+  )
+    throw new Error("web.service must be a map: { label, logs }");
+  const svc = (raw ?? {}) as Record<string, unknown>;
+  for (const key of Object.keys(svc))
+    if (!WEB_SERVICE_KEYS.includes(key))
+      throw new Error(
+        `web.service: unknown key "${key}" (known: ${WEB_SERVICE_KEYS.join(", ")})`,
+      );
+  const label = svc.label ?? `local.${name}.web`;
+  if (typeof label !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(label))
+    throw new Error(
+      `web.service.label must be letters, digits, dots, dashes and underscores, got "${String(label)}"`,
+    );
+  const logs = svc.logs ?? path.join(home, "Library", "Logs", name);
+  if (typeof logs !== "string" || !logs.trim())
+    throw new Error(
+      `web.service.logs must be a directory path, got "${String(logs)}"`,
+    );
+  const expanded = logs.startsWith("~/")
+    ? path.join(home, logs.slice(2))
+    : logs;
+  return {
+    label,
+    logs: path.isAbsolute(expanded) ? expanded : path.join(distRoot, expanded),
+  };
+}
+
 // ── Release config (Release tab) ──────────────────────────────────────────────
 
 /**

package/src/shared/environment-manager/service-runner.ts

@@ -8,6 +8,7 @@
 
 import { hasRuntime, repoKind } from "../repo-kind.js";
 import { effectiveLocalCommands } from "../stacks/manifest-commands.js";
+import { manifestStackName } from "../stacks/config.js";
 import fs from "fs";
 import path from "path";
 import { readManifest } from "../manifest/read-manifest.js";
@@ -40,6 +41,7 @@ import {
   getActiveWorkspaces,
   getFocusedWorkspaceName,
   getWorkspaceByName,
+  parseAddress,
   resolveServiceSource,
   listWorkspaceServices,
 } from "./workspaces.js";
@@ -49,7 +51,12 @@ import {
   type ServiceHealthResult,
 } from "./health.js";
 import { EventEmitter } from "events";
-import type { CommandDef, ResolvedService } from "../types/index.js";
+import type {
+  CommandDef,
+  ResolvedService,
+  ServiceCatalog,
+  WorkspaceConfig,
+} from "../types/index.js";
 import type { ChildProcess } from "child_process";
 import { getStateDir } from "../paths.js";
 
@@ -658,7 +665,95 @@ export function resolveService(
     : getActiveWorkspace();
   if (!ws) return null;
   const catalog = readCatalog();
+  const listed = resolveListedService(address, ws, catalog);
+  if (listed || address.includes("/")) return listed;
+  // Not a repo or a listed address: a service key or a stack name, when it
+  // names exactly one service in the workspace.
+  const candidates = aliasCandidates(address, ws, catalog);
+  return candidates.length === 1
+    ? resolveListedService(candidates[0], ws, catalog)
+    : null;
+}
+
+type NamedWorkspace = { name: string; config: WorkspaceConfig };
+
+/**
+ * The addresses `alias` could mean in `ws`: every service whose manifest key
+ * is `alias`, and the repo of every compose stack named `alias` (a stack
+ * stands for its repo; when that repo also has a service named `alias`, the
+ * service is the one match). Sorted; empty for a `repo/service` address and
+ * for a catalog repo's name.
+ */
+function aliasCandidates(
+  alias: string,
+  ws: NamedWorkspace,
+  catalog: ServiceCatalog,
+): string[] {
+  // A repo name is never an alias, in the workspace or not.
+  if (alias.includes("/") || catalog[alias]) return [];
+  const services = new Set<string>();
+  const stackRepos = new Set<string>();
+  for (const s of listWorkspaceServices(ws.config, catalog, ws.name)) {
+    if (s.subsystem === alias) services.add(s.address);
+    const manifest = readManifest(s.repoPath);
+    if (manifest?.compose && manifestStackName(manifest, s.repoName) === alias)
+      stackRepos.add(s.repoName);
+  }
+  const withService = new Set(
+    [...services].map((a) => parseAddress(a, catalog).repoName),
+  );
+  return [
+    ...services,
+    ...[...stackRepos].filter((r) => !withService.has(r)),
+  ].sort();
+}
 
+function namedWorkspace(workspaceName?: string): NamedWorkspace | null {
+  return workspaceName
+    ? getWorkspaceByName(workspaceName)
+    : getActiveWorkspace();
+}
+
+/**
+ * What `alias` could address in the workspace (the focused one by default)
+ * when it is not a repo or a listed address: see resolveService.
+ */
+export function serviceAliasCandidates(
+  alias: string,
+  workspaceName?: string,
+): string[] {
+  const ws = namedWorkspace(workspaceName);
+  if (!ws) return [];
+  const catalog = readCatalog();
+  if (resolveListedService(alias, ws, catalog)) return [];
+  return aliasCandidates(alias, ws, catalog);
+}
+
+/**
+ * The address to use for what someone typed: an unambiguous alias becomes
+ * the service's own address; anything else is returned as is. An ambiguous
+ * alias throws, naming the candidates.
+ */
+export function canonicalServiceAddress(
+  address: string,
+  workspaceName?: string,
+): string {
+  const candidates = serviceAliasCandidates(address, workspaceName);
+  if (candidates.length > 1) {
+    const ws = namedWorkspace(workspaceName)?.name ?? "default";
+    throw new Error(
+      `"${address}" is ambiguous in workspace "${ws}": ${candidates.join(", ")}; name one of them`,
+    );
+  }
+  return candidates[0] ?? address;
+}
+
+/** resolveService for a repo name or a listed address (no aliases). */
+function resolveListedService(
+  address: string,
+  ws: NamedWorkspace,
+  catalog: ServiceCatalog,
+): ResolvedService | null {
   let resolved = resolveServiceSource(address, ws.name, ws.config, catalog);
 
   // Bare multi-service repo registered ONLY by subsystem (e.g. "shop/db" +
@@ -998,6 +1093,109 @@ export interface RunCommandResult {
   };
 }
 
+/**
+ * A service with no commands of its own is started by its repo's up
+ * (placement's repo-level rule). For `up` that is the repo's up (`address`
+ * set); any other command would reach the repo's other services too, so it
+ * points at the repo instead: a refusal, except that down succeeds (nothing
+ * of the service's own runs, and a workspace Down sends every service).
+ * Null when the rule does not apply.
+ */
+function repoStartedFallback(
+  resolved: ResolvedService,
+  command: string,
+  workspace: string | undefined,
+): { address?: string; note: string } | null {
+  const repoEntry = resolveService(resolved.repoName, workspace);
+  if (!repoEntry || repoEntry.subsystem === resolved.subsystem) return null;
+  const manifest = readManifest(resolved.repoPath);
+  if (!manifest) return null;
+  const repoCommands = effectiveLocalCommands(
+    manifest,
+    repoEntry.subsystem,
+    resolved.repoName,
+    workspace ?? "default",
+  );
+  if (!repoCommands["up"]) return null;
+  if (command === "up")
+    return {
+      address: resolved.repoName,
+      note: `${resolved.address} has no up of its own; running ${resolved.repoName}'s up, which starts it`,
+    };
+  return command === "down"
+    ? {
+        note:
+          `${resolved.address} has no down of its own; it is stopped by ${resolved.repoName}'s down. ` +
+          `Run \`${product().cli} down ${resolved.repoName}\` (that stops every service it starts).`,
+      }
+    : {
+        note:
+          `${resolved.address} has no ${command} of its own; it is started by ${resolved.repoName}'s up. ` +
+          `Run \`${product().cli} ${command} ${resolved.repoName}\` (that reaches every service it starts).`,
+      };
+}
+
+/** What a run of `command` on `address` would do, without running it. */
+export type ServiceCommandPreview =
+  | { kind: "run"; address: string }
+  | { kind: "via-repo"; address: string; note: string }
+  | { kind: "nothing"; address: string; note: string }
+  | { kind: "error"; address: string; note: string };
+
+/**
+ * The dry-run twin of runServiceCommand's command lookup: the same
+ * resolution, own-command, restart-synthesis and repo-started rules, so a
+ * dry run says what a real run does.
+ */
+export function previewServiceCommand(
+  address: string,
+  command: string,
+  workspace?: string,
+): ServiceCommandPreview {
+  const resolved = resolveService(address, workspace);
+  if (!resolved) {
+    const candidates = serviceAliasCandidates(address, workspace);
+    return {
+      kind: "error",
+      address,
+      note:
+        `service "${address}" not found in workspace "${workspace ?? "default"}"` +
+        (candidates.length > 1
+          ? `; it is ambiguous: ${candidates.join(", ")}`
+          : ""),
+    };
+  }
+  const manifest = readManifest(resolved.repoPath);
+  const own = manifest
+    ? effectiveLocalCommands(
+        manifest,
+        resolved.subsystem,
+        resolved.repoName,
+        workspace ?? "default",
+      )
+    : {};
+  if (own[command] || (command === "restart" && own["down"] && own["up"]))
+    return { kind: "run", address };
+  const viaRepo = repoStartedFallback(resolved, command, workspace);
+  if (viaRepo?.address)
+    return { kind: "via-repo", address: viaRepo.address, note: viaRepo.note };
+  if (viaRepo)
+    return command === "down"
+      ? { kind: "nothing", address, note: viaRepo.note }
+      : { kind: "error", address, note: viaRepo.note };
+  if (command === "down")
+    return {
+      kind: "nothing",
+      address,
+      note: "no down command: nothing to stop",
+    };
+  return {
+    kind: "error",
+    address,
+    note: `command "${command}" not found for service "${address}"`,
+  };
+}
+
 /**
  * Resolve and execute a service command.
  * Returns the spawned child process and whether it is a long-running (detachable) command.
@@ -1048,8 +1246,12 @@ export function runServiceCommand(
 
   const resolved = resolveService(address, workspace);
   if (!resolved) {
+    const candidates = serviceAliasCandidates(address, workspace);
     onLine(
-      `Error: service "${address}" not found in catalog or workspace "${workspace}"`,
+      `Error: service "${address}" not found in catalog or workspace "${workspace}"` +
+        (candidates.length > 1
+          ? `; it is ambiguous: ${candidates.join(", ")}`
+          : ""),
     );
     closeAsync(1);
     return dummy();
@@ -1281,6 +1483,16 @@ export function runServiceCommand(
   }
 
   if (!cmdDef) {
+    const viaRepo = repoStartedFallback(resolved, command, workspace);
+    if (viaRepo?.address) {
+      onLine(viaRepo.note);
+      return runServiceCommand({ ...options, address: viaRepo.address });
+    }
+    if (viaRepo) {
+      onLine(command === "down" ? viaRepo.note : `Error: ${viaRepo.note}`);
+      closeAsync(command === "down" ? 0 : 1);
+      return dummy();
+    }
     // Down is opctl-conventional: when no container is running AND the manifest
     // declares no down command, there is simply nothing to stop — that's a
     // successful down, not an error (keeps the ⋮ menu / workspace Down safe to

package/src/shared/manifest/validate-layers.ts

@@ -15,6 +15,7 @@
  */
 
 import * as fs from "fs";
+import * as path from "path";
 import { z } from "zod";
 import type { ValidationError, ValidationResult } from "../types/index.js";
 import {
@@ -24,11 +25,14 @@ import {
   type ManifestMap,
 } from "./merge-override.js";
 import {
+  heldManifestPath,
   loadManifest,
   orphanOverrideMessage,
+  overrideSuffix,
   parseManifestText,
   type ManifestLayer,
 } from "./read-manifest.js";
+import { product } from "../product.js";
 
 /** What layered validation needs from the schema module. */
 export interface SchemaTools {
@@ -170,6 +174,31 @@ function readLayer(file: string): { value: unknown } | { error: string } {
   }
 }
 
+/**
+ * A warning for a held manifest the repo's own manifest has made redundant:
+ * the repo's file always wins, so the held one is never read.
+ */
+function redundantHeldWarning(
+  heldFile: string,
+  overrideFile: string | null,
+): ValidationError {
+  const yml = product().manifestYml;
+  const name = path.basename(heldFile);
+  const key = name.endsWith(yml) ? name.slice(0, -yml.length) : name;
+  const asOverride = path.join(
+    path.dirname(heldFile),
+    `${key}${overrideSuffix()}`,
+  );
+  return {
+    path: "",
+    file: heldFile,
+    message: `${heldFile} is not used: the repo now carries its own manifest, which always wins`,
+    suggestion: overrideFile
+      ? `delete it; ${overrideFile} already layers onto the repo's manifest`
+      : `delete it, or turn it into an override (${asOverride}) that keeps only what this distribution changes`,
+  };
+}
+
 /** Validate every manifest layer of `repoPath`, then the merged result. */
 export function validateLayers(
   tools: SchemaTools,
@@ -189,10 +218,20 @@ export function validateLayers(
   }
 
   const base = readLayer(baseFile);
-  const baseResult =
+  let baseResult =
     "error" in base
       ? failure(tools.version, baseFile, base.error)
       : withFile(tools.validate(base.value), baseFile);
+  const redundantHeld =
+    baseLayer === "repo" ? heldManifestPath(repoPath) : null;
+  if (redundantHeld)
+    baseResult = {
+      ...baseResult,
+      warnings: [
+        ...baseResult.warnings,
+        redundantHeldWarning(redundantHeld, overrideFile),
+      ],
+    };
   layers.push({ layer: baseLayer, file: baseFile, result: baseResult });
 
   if (overrideFile) {