refactor(cmdline)!: an app's entrypoint provides values its rows read

Replaces the patch round trip. An app's entrypoint resolves the command
line into a service, and the rows it configures read that service from
their own config — port: !!js ctx.get('webStartup')?.port ?? 3080 — so the
resolved value beats the value written beside it and nothing is written
back into a row or handed to the launcher.

A bundle names the entrypoint row in its manifest (dsh.bundle.entrypoint),
which is what lets the boot mount in two passes: entrypoints alone, then
the whole composition. That ordering is required, not cosmetic — a row's
config expressions are evaluated when the include applies the row, and a
strict ctx.get only answers for a service whose providing fiber is already
active.

What this removes: ctx.appPatches and the launcher-owned patch layer, the
disable/re-enable recycle and its in-flight-mount barrier, overrideConfig,
and the reload hazard they existed for. A live config edit now re-applies
the second pass against services that are still up, so a served port
survives by construction.

What it adds: ctx.appReady, because Loader settlement no longer means the
app is up — a row mounted in the second pass can observe a settled tree
while that pass is still running, or already rolling back. The web URL line
waits for it, so a boot that fails in the second pass announces nothing.

packages/boot/app-boot/src/index.ts

@@ -39,6 +39,7 @@ export {
   PROFILES_DIR,
   readProfileManifest,
   resolveBundleDir,
+  resolveEntrypoints,
   resolveProfileDir,
   writeProfileManifest,
   type DshBundleManifest,
@@ -527,6 +528,31 @@ export async function mountRootInclude(
   return entry
 }
 
+/**
+ * Re-apply the root include's patch list on a booted tree, and wait for the
+ * result to settle.
+ *
+ * This is how a boot mounts its composition in phases: an app's entrypoint row
+ * resolves what the rest of the tree reads (`!!js ctx.get('webStartup')?.port`),
+ * and a row's config expressions are evaluated when the include applies them —
+ * so the rest of the composition must be applied after the entrypoints are
+ * active, not before.
+ * @param ctx - the booted context whose root include to re-apply.
+ * @param patches - the full patch list for this generation.
+ * @returns nothing once the new generation has settled; a disposed tree is a no-op.
+ * @throws when the tree was booted without the root include.
+ */
+export async function applyRootPatches(ctx: Context, patches: readonly PatchOptions[]): Promise<void> {
+  const entry = bootstrapIncludes.get(ctx)
+  if (entry === undefined) throw new Error('dsh: applying root patches requires the root Include entry')
+  // A surface can dispose the whole tree while an entrypoint is still parsing
+  // (`--help`, or an early SIGTERM); there is then nothing left to mount.
+  if (ctx.get('loader') === undefined) return
+  const { patches: _previous, ...includeConfig } = entry.options.config as Include.Config
+  await entry.update({ config: { ...includeConfig, patches: [...patches] } })
+  await ctx.get('loader')?.await()
+}
+
 /**
  * The slice of `process` {@link installFailLoud} needs — injectable so tests
  * exercise the handler without registering on (or exiting) the real process.

packages/boot/app-boot/src/profile.ts

@@ -42,6 +42,16 @@ export const PROFILE_PATCH_FILENAME = 'cordis.patch.yml'
 export interface DshBundleManifest {
   /** The patch layer this bundle exports, relative to its package root. */
   patch: string
+  /**
+   * Id of the row in that patch which must run before every other row of the
+   * composition — the app's entrypoint.
+   *
+   * An entrypoint resolves what the rest of the tree needs in order to be
+   * configured at all (the command line an app was invoked with), and provides
+   * it as a service. The boot mounts entrypoints alone first, so by the time
+   * any other row's config is resolved, `ctx.get('<service>')` answers.
+   */
+  entrypoint?: string
 }
 
 /** The profile half of the `dsh` manifest section: what a profile directory composes. */
@@ -79,6 +89,37 @@ export interface ProfileLayer {
   patchPath: string
   /** The parsed patch list. */
   patches: PatchOptions[]
+  /** Row id this bundle declares as its entrypoint, when it has one. */
+  entrypoint?: string
+}
+
+/**
+ * The composition's entrypoint row ids, in bundle order.
+ * @param binName - the diagnostic prefix on the thrown error.
+ * @param profile - the loaded profile.
+ * @param rows - the composed rows, so an entrypoint a later layer removed or
+ *   disabled is not mounted (the one-shot bundle takes over the web one this way).
+ * @returns the row ids to mount before the rest of the tree.
+ * @throws when a bundle declares an entrypoint its own patch never inserts.
+ */
+export function resolveEntrypoints(
+  binName: string,
+  profile: Profile,
+  rows: readonly { id?: string; disabled?: boolean | null }[],
+): string[] {
+  const entrypoints: string[] = []
+  for (const layer of profile.layers) {
+    if (layer.entrypoint === undefined) continue
+    const row = rows.find(candidate => candidate.id === layer.entrypoint)
+    if (row === undefined) {
+      throw new Error(
+        `${binName}: bundle ${JSON.stringify(layer.packageName)} declares entrypoint ${JSON.stringify(layer.entrypoint)}, `
+        + 'which the composed tree has no row for',
+      )
+    }
+    if (row.disabled !== true) entrypoints.push(layer.entrypoint)
+  }
+  return entrypoints
 }
 
 /** A loaded profile: resolved bundle layers plus the user's own patch layer. */
@@ -391,7 +432,14 @@ export function loadProfile(
       throw new Error(`${binName}: profile bundle ${JSON.stringify(packageName)} declares no dsh.bundle in its package.json`)
     }
     const patchPath = join(packageDir, declared)
-    return { packageName, packageDir, patchPath, patches: loadOverlayPatches(binName, patchPath) }
+    const entrypoint = bundleManifest.dsh?.bundle?.entrypoint
+    return {
+      packageName,
+      packageDir,
+      patchPath,
+      patches: loadOverlayPatches(binName, patchPath),
+      ...entrypoint === undefined ? {} : { entrypoint },
+    }
   })
   const patchPath = join(dir, PROFILE_PATCH_FILENAME)
   const patches = options.userLayer !== false && existsSync(patchPath)

packages/boot/app-boot/tests/profile.spec.ts

@@ -17,6 +17,7 @@ import {
   PROFILE_TEMPLATES,
   readProfileManifest,
   resolveBundleDir,
+  resolveEntrypoints,
   resolveProfileDir,
   writeProfileManifest,
 } from '../src/index.ts'
@@ -197,6 +198,37 @@ describe('loadProfile', () => {
   })
 })
 
+describe('resolveEntrypoints', () => {
+  const profile = (layers: { packageName: string; entrypoint?: string }[]): Parameters<typeof resolveEntrypoints>[1] => ({
+    name: 'p',
+    dir: '/p',
+    patchPath: '/p/cordis.patch.yml',
+    patches: [],
+    layers: layers.map(layer => ({ ...layer, packageDir: '/b', patchPath: '/b/cordis.patch.yml', patches: [] })),
+  })
+
+  it('names each bundle entrypoint in bundle order', () => {
+    expect(resolveEntrypoints(
+      'dsh',
+      profile([{ packageName: 'a' }, { packageName: 'b', entrypoint: 'b-startup' }, { packageName: 'c', entrypoint: 'c-startup' }]),
+      [{ id: 'b-startup' }, { id: 'c-startup' }, { id: 'other' }],
+    )).toEqual(['b-startup', 'c-startup'])
+  })
+
+  it('skips an entrypoint a later layer disabled, which is how one app takes over another', () => {
+    expect(resolveEntrypoints(
+      'dsh',
+      profile([{ packageName: 'web', entrypoint: 'web-startup' }, { packageName: 'one-shot', entrypoint: 'one-shot-startup' }]),
+      [{ id: 'web-startup', disabled: true }, { id: 'one-shot-startup' }],
+    )).toEqual(['one-shot-startup'])
+  })
+
+  it('fails loud when a bundle declares an entrypoint its patch never inserts', () => {
+    expect(() => resolveEntrypoints('dsh', profile([{ packageName: 'b', entrypoint: 'absent' }]), [{ id: 'other' }]))
+      .toThrow('declares entrypoint "absent", which the composed tree has no row for')
+  })
+})
+
 describe('composeEntries', () => {
   it('applies layers over an empty root and reports skipped patches', () => {
     const warnings: string[] = []

packages/boot/app-boot/tests/user-patches.spec.ts

@@ -13,7 +13,9 @@ import { Context } from '@deepseek-ai/cordis'
 import Hmr from '@deepseek-ai/cordis-plugin-hmr'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import Timer from '@deepseek-ai/cordis-plugin-timer'
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import {
+  applyRootPatches,
   boot,
   loadOptionalPatches,
   PROFILE_PATCH_FILENAME,
@@ -92,23 +94,81 @@ describe('loadOptionalPatches', () => {
   })
 })
 
-describe('boot with user patches', () => {
-  function writeTree(dir: string): string {
-    writeFileSync(join(dir, 'noop.mjs'), [
-      'export const name = "noop"',
-      'export function apply(_ctx, config = {}) {',
-      '  if (config.fail) throw new Error("candidate config failed")',
-      '}',
+function writeTree(dir: string): string {
+  writeFileSync(join(dir, 'noop.mjs'), [
+    'export const name = "noop"',
+    'export function apply(_ctx, config = {}) {',
+    '  if (config.fail) throw new Error("candidate config failed")',
+    '}',
+    '',
+  ].join('\n'))
+  writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
+  return join(dir, 'cordis.yml')
+}
+
+function entryConfig(ctx: Context, id: string): unknown {
+  return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
+}
+
+describe('applyRootPatches', () => {
+  it('mounts a later phase whose rows read what the first phase provided', async () => {
+    // The phased boot in one test: a row's `!!js` config is evaluated when the
+    // include applies it, so a value an earlier phase provided is what a later
+    // phase's rows read.
+    const dir = tmp()
+    writeFileSync(join(dir, 'provider.mjs'), [
+      'export const name = "provider"',
+      'export function apply(ctx) { ctx.provide("phaseOne", { value: "resolved" }) }',
       '',
     ].join('\n'))
-    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
-    return join(dir, 'cordis.yml')
-  }
+    writeFileSync(join(dir, 'reader.mjs'), [
+      'export const name = "reader"',
+      'export const inject = ["phaseOne"]',
+      'export function apply() {}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'cordis.yml'), '[]\n')
+    const composition: PatchOptions[] = [{
+      insert: [
+        { id: 'provider', name: './provider.mjs' },
+        {
+          id: 'reader',
+          name: './reader.mjs',
+          inject: ['phaseOne'],
+          config: { value: { __jsExpr: "ctx.get('phaseOne')?.value ?? 'fallback'" } },
+        },
+      ],
+    }]
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'), [
+      ...structuredClone(composition),
+      { id: 'reader', disabled: true },
+    ])
+    try {
+      // Phase one leaves the reader disabled, so the plugin never ran.
+      const reader = [...ctx.loader.entries()].find(entry => entry.options.id === 'reader')
+      expect(reader?.fiber).toBeUndefined()
+      await applyRootPatches(ctx, structuredClone(composition))
+      // Phase two evaluates its config expression against the provided value.
+      expect(entryConfig(ctx, 'reader')).toEqual({ value: 'resolved' })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
 
-  function entryConfig(ctx: Context, id: string): unknown {
-    return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
-  }
+  it('does nothing on a tree that was already disposed', async () => {
+    const dir = tmp()
+    const ctx = await boot(NAME, writeTree(dir))
+    await ctx.fiber.dispose()
+    await expect(applyRootPatches(ctx, [])).resolves.toBeUndefined()
+  })
 
+  it('fails loud when the tree was booted without the root include', async () => {
+    const ctx = new Context()
+    await expect(applyRootPatches(ctx, [])).rejects.toThrow('requires the root Include entry')
+  })
+})
+
+describe('boot with user patches', () => {
   it('applies id-targeted overrides, inserts, and interpolates !!js from the environment', async () => {
     const dir = tmp()
     const userDir = tmp()