@@ -0,0 +1,55 @@
+---
+"@objectstack/cli": minor
+---
+
+fix(cli): `os start` / `os dev` stop writing `OS_ARTIFACT_PATH` into the child `serve` environment — the CLI's own plumbing moves to an internal channel (#8985)
+
+`os start` and `os dev` are supervisors: each resolves an artifact, then spawns
+`os serve` to boot it. Both handed the resolved path down by writing
+**`OS_ARTIFACT_PATH`** into the child environment — the same variable an operator
+sets to name an artifact. `dev` wrote it unconditionally; `start` wrote it
+whenever it had resolved anything and no `OS_ARTIFACT_URL` was in play. Both
+writes happen **before** the downstream `objectstack.config.ts` is evaluated.
+
+So inside any config, that variable was set on **every** boot, including boots
+where no operator had ever mentioned it — measured from the shipped EE image
+with its own `ENV` deliberately deleted: `os start` still printed
+`Artifact: dist/objectstack.json` and handed that path down. A config could not
+answer *"did a human ask for this, or did the CLI put it here?"*
+
+The resolved path now travels on **`OS_INTERNAL_ARTIFACT_PATH`**, a channel the
+CLI owns both ends of (`packages/cli/src/utils/internal-artifact-channel.ts`),
+and the property downstream consumers need is restored:
+
+> **the presence of `OS_ARTIFACT_PATH` in a config's environment means an
+> operator set it.**
+
+**Nothing about resolution changed.** Each command's ladder resolves in the
+parent exactly as before, and `serve` reads the new channel strictly between the
+reference and the operator knob:
+
+```
+--artifact > OS_ARTIFACT_URL > OS_INTERNAL_ARTIFACT_PATH > OS_ARTIFACT_PATH > <cwd>/dist/objectstack.json
+```
+
+That position is what preserves today's answers in both directions. It beats
+`OS_ARTIFACT_PATH` because `os start --artifact X` run with an operator's
+`OS_ARTIFACT_PATH=Y` exported boots **X** today — the parent used to overwrite
+the variable on the way down, and now inherits it untouched. It loses to
+`OS_ARTIFACT_URL` because `os dev` writes the channel unconditionally, as it
+wrote the old variable unconditionally, and the reference has always outranked
+the path.
+
+Two further behaviours are unchanged and now pinned rather than incidental:
+`start` still refuses to set `OS_BOOT_EMPTY` when a reference is driving the
+boot (an unreachable artifact host stays a loud refusal instead of a silently
+empty platform), and a resolved-but-missing artifact is still "named" to
+`resolveDefaultArtifactPath`, so it fails loudly rather than booting empty.
+
+**If you depended on the old side effect** — a config reading
+`process.env.OS_ARTIFACT_PATH` and expecting the CLI to have populated it — set
+the variable yourself, or read the artifact from the config's own inputs.
+`OS_ARTIFACT_PATH` remains a fully supported operator knob on the exact rung it
+has always occupied; the CLI simply no longer manufactures it on your behalf.
+`OS_INTERNAL_ARTIFACT_PATH` is not a supported knob and is deliberately absent
+from the environment-variable reference.
@@ -0,0 +1,241 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Pin: **the presence of `OS_ARTIFACT_PATH` in a config's environment means an
+ * operator set it.**
+ *
+ * `os start` and `os dev` spawn `os serve`, and the downstream
+ * `objectstack.config.ts` is evaluated inside that child. While the supervisors
+ * wrote their own resolved artifact path into the child's `OS_ARTIFACT_PATH`,
+ * the variable was set on **every** boot — so a config could not tell an
+ * operator's instruction from the CLI's own plumbing, and a consumer wanting to
+ * refuse the retired knob could only do so by inspecting its *value*.
+ *
+ * The plumbing now travels on `OS_INTERNAL_ARTIFACT_PATH`
+ * (`utils/internal-artifact-channel.ts`). This file pins both halves of the
+ * property, plus the two behaviours that had to survive the move: the
+ * resolution ladder, and `start`'s deliberate refusal to declare an empty boot
+ * acceptable when a reference is driving the boot.
+ *
+ * Two kinds of assertion here, and both are needed:
+ *
+ * - **Behavioural** — over `childEnvWithResolvedArtifact`, which is the whole
+ *   of what each command contributes to its child's artifact environment.
+ * - **Structural** — a source assertion that neither command writes
+ *   `OS_ARTIFACT_PATH` into an env object at all. The behavioural pins describe
+ *   the helper; only this one refuses a future edit that re-adds the write
+ *   beside it. Both files compose their child env as
+ *   `{ ...childEnvWithResolvedArtifact(process.env, …), …other keys }`, so
+ *   "the helper is correct" plus "nothing else writes the key" is what makes
+ *   the composed env correct.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'path';
+import {
+  INTERNAL_ARTIFACT_PATH_ENV,
+  childEnvWithResolvedArtifact,
+  readInternalArtifactPath,
+} from '../utils/internal-artifact-channel.js';
+import { resolveArtifactSource } from './start.js';
+
+const ARTIFACT = '/srv/app/objectstack.json';
+
+describe('the child `serve` env — OS_ARTIFACT_PATH means an operator set it', () => {
+  it('carries NO OS_ARTIFACT_PATH when the operator did not set one', () => {
+    const parentEnv = { PATH: '/usr/bin', NODE_ENV: 'production' };
+
+    for (const decision of [
+      { kind: 'resolved', path: ARTIFACT },
+      { kind: 'reference' },
+      { kind: 'empty' },
+    ] as const) {
+      const childEnv = childEnvWithResolvedArtifact(parentEnv, decision);
+      expect(
+        Object.prototype.hasOwnProperty.call(childEnv, 'OS_ARTIFACT_PATH'),
+        `decision ${decision.kind} must not introduce OS_ARTIFACT_PATH`,
+      ).toBe(false);
+      expect(childEnv.OS_ARTIFACT_PATH).toBeUndefined();
+    }
+  });
+
+  it('still carries OS_ARTIFACT_PATH — verbatim — when the operator DID set one', () => {
+    const parentEnv = { OS_ARTIFACT_PATH: './dist/from-operator.json' };
+
+    for (const decision of [
+      { kind: 'resolved', path: '/abs/dist/from-operator.json' },
+      { kind: 'reference' },
+      { kind: 'empty' },
+    ] as const) {
+      const childEnv = childEnvWithResolvedArtifact(parentEnv, decision);
+      // Inherited untouched: the child sees exactly what the operator wrote,
+      // not an absolutised rewrite of it.
+      expect(childEnv.OS_ARTIFACT_PATH).toBe('./dist/from-operator.json');
+    }
+  });
+
+  it('hands the resolved artifact down on the internal channel instead', () => {
+    const childEnv = childEnvWithResolvedArtifact({}, { kind: 'resolved', path: ARTIFACT });
+    expect(childEnv[INTERNAL_ARTIFACT_PATH_ENV]).toBe(ARTIFACT);
+    expect(readInternalArtifactPath(childEnv)).toBe(ARTIFACT);
+  });
+
+  it('lets the parent OWN the internal channel — an inherited value never speaks for it', () => {
+    const parentEnv = { [INTERNAL_ARTIFACT_PATH_ENV]: '/stale/inherited.json' };
+
+    expect(childEnvWithResolvedArtifact(parentEnv, { kind: 'resolved', path: ARTIFACT }))
+      .toMatchObject({ [INTERNAL_ARTIFACT_PATH_ENV]: ARTIFACT });
+
+    for (const decision of [{ kind: 'reference' }, { kind: 'empty' }] as const) {
+      const childEnv = childEnvWithResolvedArtifact(parentEnv, decision);
+      expect(
+        readInternalArtifactPath(childEnv),
+        `decision ${decision.kind} resolved nothing, so the channel must be empty`,
+      ).toBeUndefined();
+      expect(Object.prototype.hasOwnProperty.call(childEnv, INTERNAL_ARTIFACT_PATH_ENV)).toBe(false);
+    }
+  });
+
+  it('reads a blank channel value as no decision at all', () => {
+    expect(readInternalArtifactPath({})).toBeUndefined();
+    expect(readInternalArtifactPath({ [INTERNAL_ARTIFACT_PATH_ENV]: '' })).toBeUndefined();
+    expect(readInternalArtifactPath({ [INTERNAL_ARTIFACT_PATH_ENV]: '   ' })).toBeUndefined();
+  });
+});
+
+describe('OS_BOOT_EMPTY — the artifact-reference refusal survives the move', () => {
+  it('is NOT set when a reference (OS_ARTIFACT_URL) is driving the boot', () => {
+    // Load-bearing: setting it here would tell `serve` that booting an app-less
+    // kernel is an acceptable outcome, turning an unreachable artifact host
+    // into a silently empty platform instead of a loud refusal.
+    const childEnv = childEnvWithResolvedArtifact({}, { kind: 'reference' });
+    expect(childEnv.OS_BOOT_EMPTY).toBeUndefined();
+    expect(readInternalArtifactPath(childEnv)).toBeUndefined();
+  });
+
+  it('is NOT set when an artifact was resolved', () => {
+    expect(childEnvWithResolvedArtifact({}, { kind: 'resolved', path: ARTIFACT }).OS_BOOT_EMPTY)
+      .toBeUndefined();
+  });
+
+  it('is set only when nothing resolved and an empty boot IS the intent', () => {
+    expect(childEnvWithResolvedArtifact({}, { kind: 'empty' }).OS_BOOT_EMPTY).toBe('1');
+  });
+
+  it('never CLEARS an operator-exported OS_BOOT_EMPTY (add-only, as before)', () => {
+    const parentEnv = { OS_BOOT_EMPTY: '1' };
+    for (const decision of [
+      { kind: 'resolved', path: ARTIFACT },
+      { kind: 'reference' },
+      { kind: 'empty' },
+    ] as const) {
+      expect(
+        childEnvWithResolvedArtifact(parentEnv, decision).OS_BOOT_EMPTY,
+        `decision ${decision.kind} must not start clearing an inherited OS_BOOT_EMPTY`,
+      ).toBe('1');
+    }
+  });
+});
+
+describe('resolveArtifactSource — the resolution ladder is unchanged', () => {
+  let cwd: string;
+  let home: string;
+
+  const write = (dir: string, rel: string) => {
+    const abs = path.join(dir, rel);
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, '{}');
+    return abs;
+  };
+
+  beforeEach(() => {
+    cwd = mkdtempSync(path.join(tmpdir(), 'os-artifact-cwd-'));
+    home = mkdtempSync(path.join(tmpdir(), 'os-artifact-home-'));
+  });
+  afterEach(() => {
+    for (const d of [cwd, home]) {
+      try { rmSync(d, { recursive: true, force: true }); } catch { /* noop */ }
+    }
+  });
+
+  it('rung 1: --artifact wins over everything, including an operator OS_ARTIFACT_PATH', () => {
+    const flagFile = write(cwd, 'build/pinned.json');
+    write(cwd, 'dist/objectstack.json');
+    write(home, 'dist/objectstack.json');
+
+    const r = resolveArtifactSource('build/pinned.json', home, {
+      cwd,
+      env: { OS_ARTIFACT_PATH: '/from/env.json' },
+    });
+    expect(r?.path).toBe(flagFile);
+  });
+
+  it('rung 1: --artifact passes an http(s) URL through untouched', () => {
+    const url = 'https://cdn.example.com/app.json';
+    expect(resolveArtifactSource(url, home, { cwd, env: {} })?.path).toBe(url);
+  });
+
+  it('rung 2: $OS_ARTIFACT_PATH wins over both auto-detected locations', () => {
+    write(cwd, 'dist/objectstack.json');
+    write(home, 'dist/objectstack.json');
+
+    const r = resolveArtifactSource(undefined, home, {
+      cwd,
+      env: { OS_ARTIFACT_PATH: 'custom/app.json' },
+    });
+    // Anchored on the cwd, exactly as before — the ladder resolves it; the
+    // variable itself is inherited by the child untouched.
+    expect(r?.path).toBe(path.join(cwd, 'custom/app.json'));
+  });
+
+  it('rung 2: $OS_ARTIFACT_PATH may itself be an http(s) URL', () => {
+    const url = 'https://cdn.example.com/env.json';
+    expect(resolveArtifactSource(undefined, home, { cwd, env: { OS_ARTIFACT_PATH: url } })?.path)
+      .toBe(url);
+  });
+
+  it('rung 3: <cwd>/dist/objectstack.json wins over <home>/dist', () => {
+    const cwdArtifact = write(cwd, 'dist/objectstack.json');
+    write(home, 'dist/objectstack.json');
+    expect(resolveArtifactSource(undefined, home, { cwd, env: {} })?.path).toBe(cwdArtifact);
+  });
+
+  it('rung 4: <home>/dist/objectstack.json is the last resort', () => {
+    const homeArtifact = write(home, 'dist/objectstack.json');
+    expect(resolveArtifactSource(undefined, home, { cwd, env: {} })?.path).toBe(homeArtifact);
+  });
+
+  it('rung 5: nothing reachable resolves to undefined', () => {
+    expect(resolveArtifactSource(undefined, home, { cwd, env: {} })).toBeUndefined();
+  });
+});
+
+describe('structural: the supervisors never write the operator knob', () => {
+  // Strip comments first — both files discuss OS_ARTIFACT_PATH at length, and
+  // the prose is exactly what this assertion must NOT read.
+  const codeOf = (file: string): string => {
+    const src = readFileSync(new URL(`./${file}`, import.meta.url), 'utf8');
+    return src
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .split('\n')
+      .map((line) => (line.trim().startsWith('//') ? '' : line.replace(/\/\/.*$/, '')))
+      .join('\n');
+  };
+
+  for (const file of ['start.ts', 'dev.ts']) {
+    it(`${file} contains no OS_ARTIFACT_PATH assignment`, () => {
+      const offenders = codeOf(file)
+        .split('\n')
+        .filter((line) => /OS_ARTIFACT_PATH\s*[:=]/.test(line));
+      expect(
+        offenders,
+        `${file} must not write OS_ARTIFACT_PATH into a child environment — the CLI's own `
+        + `resolved artifact travels on ${INTERNAL_ARTIFACT_PATH_ENV}, so that a downstream `
+        + `objectstack.config.ts seeing OS_ARTIFACT_PATH knows an operator set it. `
+        + `Reading process.env.OS_ARTIFACT_PATH (the operator's value) stays correct.`,
+      ).toEqual([]);
+    });
+  }
+});
@@ -16,6 +16,7 @@ import {
   assessArtifactStaleness,
   formatMtimeGap,
 } from '../utils/dev-restart.js';
+import { childEnvWithResolvedArtifact } from '../utils/internal-artifact-channel.js';
 import { readEnvWithDeprecation, isMcpServerEnabled } from '@objectstack/types';
 import type { ResolvedProjectDatabaseUrl } from '@objectstack/runtime';
 
@@ -327,10 +328,18 @@ export default class Dev extends Command {
         fs.mkdirSync(path.dirname(resolvedDb.url.replace(/^file:/, '')), { recursive: true });
       }
       const effectiveDb = resolvedDb.url;
+      // `dev` always has a resolved artifact by this point (it compiled one, or
+      // was handed one with `--artifact`, or is pointing at the canonical
+      // `<cwd>/dist/objectstack.json`), so the decision is unconditionally
+      // `resolved` — exactly as unconditional as the `OS_ARTIFACT_PATH` write
+      // it replaces. What changed is the channel: the resolved path travels on
+      // the CLI's own `OS_INTERNAL_ARTIFACT_PATH`, so an `OS_ARTIFACT_PATH`
+      // seen by a downstream `objectstack.config.ts` means an operator set it.
+      // The operator's own value is inherited verbatim, and `dev`'s ladder
+      // above still honours it on the rung it has always occupied.
       const localEnv: NodeJS.ProcessEnv = {
-        ...process.env,
+        ...childEnvWithResolvedArtifact(process.env, { kind: 'resolved', path: artifactPath }),
         OS_ENVIRONMENT_ID: environmentId,
-        OS_ARTIFACT_PATH: artifactPath,
         OS_SEED_ADMIN: seedAdmin ? '1' : '0',
         ...(seedAdmin && flags['admin-email'] ? { OS_SEED_ADMIN_EMAIL: flags['admin-email'] } : {}),
         ...(seedAdmin && flags['admin-password'] ? { OS_SEED_ADMIN_PASSWORD: flags['admin-password'] } : {}),
 
@@ -9,6 +9,7 @@ import { bundleRequire } from 'bundle-require';
 import { loadConfig, BUNDLE_REQUIRE_EXTERNALS } from '../utils/config.js';
 import { mergeBootConfig } from '../utils/merge-boot-config.js';
 import { isHostConfig, shouldBootWithLibrary } from '../utils/plugin-detection.js';
+import { readInternalArtifactPath } from '../utils/internal-artifact-channel.js';
 import {
   resolveDriverType,
   resolveStorageDefinition,
@@ -956,7 +957,19 @@ export default class Serve extends Command {
     // fragment. It is resolved here, before anything else looks for an
     // artifact, and it wins over every local lookup:
     //
-    //   --artifact  >  OS_ARTIFACT_URL  >  OS_ARTIFACT_PATH  >  <cwd>/dist/…
+    //   --artifact  >  OS_ARTIFACT_URL  >  OS_INTERNAL_ARTIFACT_PATH
+    //               >  OS_ARTIFACT_PATH  >  <cwd>/dist/…
+    //
+    // `OS_INTERNAL_ARTIFACT_PATH` is the CLI's private parent-to-child channel:
+    // an `os start` / `os dev` supervisor resolved an artifact through its own
+    // ladder and is handing the answer down. It sits BELOW the reference (a
+    // supervisor that saw OS_ARTIFACT_URL resolves nothing and sends nothing,
+    // and `os dev` sends its answer unconditionally, so the reference has to
+    // keep outranking it) and ABOVE the operator's OS_ARTIFACT_PATH (which the
+    // supervisor no longer overwrites on the way down, so only a higher rung
+    // keeps `--artifact` beating an exported OS_ARTIFACT_PATH the way it does
+    // today). See `utils/internal-artifact-channel.ts` for why the CLI stopped
+    // writing the operator's knob at all.
     //
     // Beating OS_ARTIFACT_PATH is not a nicety, it is the acceptance
     // criterion: the official runtime image sets
@@ -1018,7 +1031,11 @@ export default class Serve extends Command {
 
     if (configMissing && !pinnedArtifact) {
       const { resolveDefaultArtifactPath } = await import('@objectstack/runtime');
-      const artifactSource = resolveDefaultArtifactPath();
+      // A supervising `os start` / `os dev` passes its already-resolved answer
+      // as the explicit override — the same position `OS_ARTIFACT_PATH` used to
+      // occupy when the supervisor wrote it, so a named-but-missing artifact is
+      // still a loud refusal rather than a silent empty boot.
+      const artifactSource = resolveDefaultArtifactPath(readInternalArtifactPath());
       if (!artifactSource) {
         // Quick-start mode: `objectstack start` lets the user boot an
         // empty kernel with no config and no artifact, then install apps
@@ -1246,7 +1263,15 @@ export default class Serve extends Command {
             // what stops the loader from fetching the URL a second time — a pin
             // that verifies one response while a different response boots would
             // verify nothing.
-            ...(pinnedArtifact ? { artifactPath: pinnedArtifact.localPath } : {}),
+            // Same reasoning one rung down: when no reference is in play, a
+            // supervisor's resolved answer is handed over explicitly instead of
+            // being re-derived from the environment.
+            ...(pinnedArtifact
+              ? { artifactPath: pinnedArtifact.localPath }
+              : (() => {
+                const internal = readInternalArtifactPath();
+                return internal ? { artifactPath: internal } : {};
+              })()),
           });
           // [#4002] `api` merges per key — see mergeBootConfig. A shallow spread
           // let the boot builder's two scoping keys wipe the author's whole `api`
@@ -1765,7 +1790,11 @@ export default class Serve extends Command {
         if (!hasMetadataPlugin) {
           try {
             const { resolveDefaultArtifactPath } = await import('@objectstack/runtime');
-            const hmrArtifactPath = resolveDefaultArtifactPath();
+            // `os dev` is the only caller that reaches here, and it is a
+            // supervisor: read its channel, or the artifact this HMR watcher
+            // polls would silently drift to `<cwd>/dist/objectstack.json`
+            // whenever `os dev --artifact <elsewhere>` was used.
+            const hmrArtifactPath = resolveDefaultArtifactPath(readInternalArtifactPath());
             if (hmrArtifactPath && !/^https?:\/\//i.test(hmrArtifactPath)) {
               const { MetadataPlugin } = await import('@objectstack/metadata');
               // Mirror the standalone stack's dev config exactly