@mean-weasel/lineage 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.14
+
+- Fix isolated channel installs against npm clients that return registry integrity as a flat `dist.integrity` field, while rejecting missing or conflicting identity metadata.
+- Run promotion claim verification through an exact receipt-bound registry install, named production profile, external asset root, and managed writer.
+- Supersede the `0.1.13` candidate, whose packaged channel installer cannot bootstrap registry installs with the affected npm metadata shape.
+
+## 0.1.13
+
+- Isolate stable, preview, and checkout-only development code into attested channel-specific roots with runtime doctor and tamper detection.
+- Require fingerprint-bound named profiles, opened-handle SQLite identity checks, one managed writer, consistent database clones, and referenced-asset-only migration receipts for persistent writes.
+- Ship profile-aware managed service lifecycles, a three-runtime adversarial coexistence oracle, and an atomic version-locked Codex plugin release/install path.
+
 ## 0.1.12
 
 - Add named runtime profiles that bind environment, SQLite, media root, service origin, and expected runtime identity without allowing silent path drift.

package/README.md

@@ -4,41 +4,62 @@ Lineage is a local-first workspace for reviewing creative assets, branching vari
 
 ## Package Channels
 
-Lineage is packaged as `@mean-weasel/lineage`. Use `latest` for the stable dogfood or production install, and use `next` when you intentionally want the published preview candidate:
+Lineage is packaged as `@mean-weasel/lineage`, but stable and preview must not
+be installed into the same global npm prefix. A global `npm install -g ...@next`
+would replace the files and bins used by `latest`.
+
+Use the stable package only as a bootstrap for the channel installer, then
+resolve `latest` and `next` into separate content-addressed roots:
 
 ```bash
 npm install -g @mean-weasel/lineage@latest
-npm install -g @mean-weasel/lineage@next
+lineage-channel install stable
+lineage-channel install preview
 ```
 
-The stable, preview, and dev channels are intended to coexist conceptually:
+By default the installer writes immutable version/integrity roots beneath
+`~/Library/Application Support/Lineage/runtimes`, plus channel-qualified
+launchers in its `bin` directory. Every launcher is pinned to an absolute
+package root and install receipt; it does not select code from `PATH` at runtime.
+
+The three exact channel meanings are:
 
-- `latest` is the version you should trust for day-to-day dogfooding.
-- `next` is the published preview version to test before promotion.
-- `dev` is the local GitHub checkout or branch before publication.
-- `lineage` runs with stable runtime defaults.
-- `lineage-dev` runs with dev runtime defaults.
+- `stable` is npm `latest`, launched as `lineage-stable` from its receipt-bound root.
+- `preview` is npm `next`, launched as `lineage-preview` from a different root.
+- `dev` is the current Git checkout/worktree, launched from source with
+  `npm run lineage:dev -- <command>`.
 
-The package includes both CLI bridge bins for help and version checks:
+Verify code identity before inspecting data or starting a service:
 
 ```bash
-lineage --help
-lineage --version
-lineage-dev --help
-lineage-dev --version
+lineage-stable runtime doctor --json
+lineage-preview runtime doctor --json
+npm run lineage:dev -- runtime doctor --json
 ```
 
-Both bins can also run the bundled production server:
+`runtime doctor` fails unless channel, canonical package/checkout root, exact
+version, embedded Git/build fingerprint, install receipt, and installed package
+tree agree. `runtime info` prints the same identity without requiring it to pass
+and is intended for repair diagnostics.
+
+A published package still carries a `lineage-dev` migration stub so old global
+links fail with checkout guidance. It never runs package code as dev.
+
+Start each foreground runtime explicitly:
 
 ```bash
-lineage start
-lineage-dev start
+lineage-stable start --profile team-production
+lineage-preview start --profile team-preview
+npm run lineage:dev -- start --profile team-development
 ```
 
-By default, `lineage start` listens on `lineage.localhost:5197` and stores SQLite state in a stable Lineage runtime directory. `lineage-dev start` listens on `lineage-dev.localhost:5198` and uses a separate development SQLite file. Override those defaults with `--port`, `--host`, `--db`, or `LINEAGE_HOME`:
+Stable defaults to `lineage.localhost:5197`, dev to
+`lineage-dev.localhost:5198`, and preview to
+`lineage-preview.localhost:5199`. Override those defaults with `--port`,
+`--host`, `--db`, or `LINEAGE_HOME`:
 
 ```bash
-lineage start --port 6123 --db ~/.lineage/lineage.sqlite --asset-root /absolute/path/to/asset-repo
+lineage-stable start --profile team-production --port 6123
 ```
 
 `--db` selects the SQLite state file. `--asset-root` (or
@@ -50,17 +71,19 @@ web assets, and public demo fixtures.
 
 ## Runtime Channels and SQLite
 
-Lineage treats app code channels and local SQLite data as separate concerns:
+Lineage treats attested code identity and local SQLite data identity as separate,
+simultaneously required concerns:
 
-- `stable` is npm `latest` and is the daily-use channel.
-- `preview` is the published candidate channel, normally npm `next`.
-- `dev` is a GitHub checkout or local branch before publication.
+- `stable` is the isolated npm `latest` install and daily-use channel.
+- `preview` is the isolated npm `next` candidate.
+- `dev` is the current Git checkout/worktree and may be dirty.
 
-Each channel should use its own default runtime directory and SQLite database.
-Do not point preview or dev code at the stable database unless you are doing an
-intentional, explicit test. Prefer copying a stable snapshot forward when a
-realistic preview/dev dataset is needed. `--db` and `LINEAGE_DB` remain the
-escape hatches for intentionally choosing a database.
+Each channel must use its own code root, runtime directory, and SQLite database.
+Do not point preview or dev code at the stable database. Use the profile clone
+command when a realistic preview/dev dataset is needed; it reads the source
+through SQLite's online backup API and gives the target a fresh non-production
+identity. Direct `--db` and `LINEAGE_DB` selection is diagnostic/read-only
+unless a matching named profile has been selected and its writer lease is held.
 
 For repeatable or multi-session work, prefer a named profile over those legacy
 path defaults. A profile is an immutable identity contract for one Lineage
@@ -71,6 +94,11 @@ service and its data:
   "schema_version": "lineage.profile.v1",
   "profile_id": "team-production",
   "environment": "production",
+  "expected_runtime": {
+    "channel": "stable",
+    "code_origin": "package",
+    "code_fingerprint": "<64-character fingerprint from runtime doctor>"
+  },
   "database_path": "./lineage.sqlite",
   "asset_root": "./media",
   "service_origin": "http://lineage.localhost:5197"
@@ -83,47 +111,101 @@ and asset paths resolve from the manifest directory. Inspect a profile without
 creating or migrating anything:
 
 ```bash
-lineage profile doctor --profile team-production --json
-lineage profile bind --profile team-production --confirm-write --json
-lineage start --profile team-production
+lineage-stable profile doctor --profile team-production --json
+lineage-stable start --profile team-production
 ```
 
 `LINEAGE_PROFILE` is equivalent to `--profile`. Profile commands reject direct
 `--db` and `--asset-root` overrides, and a dev or preview runtime refuses to
 open a production profile. Doctor also requires the existing SQLite database
-to have one matching `lineage_profile_identity` binding; `profile bind` creates
-that identity for a new database or explicitly adopts a legacy database, and
-requires `--confirm-write`. Profile creation and database binding remain
-separate migration operations. A
-command without a profile remains compatible but is labeled `legacy-unbound`.
+to have one matching `lineage_profile_identity` binding, including the profile
+manifest fingerprint. Binding is an explicit migration operation:
+
+```bash
+lineage-stable profile bind --profile team-production --confirm-write --json
+```
+
+The profile must pin the exact verified code origin and fingerprint before it
+can be bound or used for writes. `profile bind` may add a fingerprint to a
+matching legacy identity, but refuses a conflicting identity. An unprofiled
+CLI or service is `legacy-unbound` and read-only; mutating CLI commands and HTTP
+methods fail with a profile-required error instead of creating a database.
+
+To create a realistic preview or development database without copying a live
+SQLite file directly, define a new non-production target profile whose database
+does not exist, then run:
+
+```bash
+lineage-preview profile clone --source-db /path/to/source.sqlite \
+  --target-profile team-preview --confirm-write --json
+npm run lineage:dev -- profile clone --source-db /path/to/source.sqlite \
+  --target-profile team-development --confirm-write --json
+```
+
+Clone refuses production targets, existing target files, source/target path
+reuse, unverified code, and missing confirmation. It writes a local receipt
+under the target profile directory after SQLite integrity and identity checks.
+
+When migrating a legacy installation whose production media still lives under
+a development checkout, stage only database-referenced local files into the
+new profile's nonexistent, dedicated asset root before binding or starting it:
+
+```bash
+lineage-stable profile clone-assets --source-asset-root /path/to/legacy/checkout \
+  --target-profile team-production --confirm-write --json
+```
+
+Asset clone holds the target profile's writer lease, refuses reused or nested
+roots and escaping references, reserves the target without clobbering, verifies
+every copied file by SHA-256, uses owner-only permissions, and writes a compact
+receipt. Missing legacy references are counted rather than silently replaced;
+unreferenced checkout scratch files are not copied. Inspect that count before
+binding the database. The source database and asset tree remain read-only.
 
 A named profile has one cross-process writer lease at
-`<resolved-database-path>.writer.lock`. The managed service holds that lease for its
-lifetime, so a second service is refused while it is running. Named-profile
-mutating CLI commands, including generated claim, heartbeat, link-child, and
-re-roll import handoffs, use an authenticated profile-bound route through that
-service instead of opening SQLite as a competing writer. The request and
-response identities must match the selected profile, environment, channel, and
-configured localhost origin; an unavailable or mismatched service fails closed
-without a direct-write fallback. A CLI data command may hold the same lease
-directly only while the service is offline. Lineage verifies lease ownership
-before opening a named-profile database for writes and configures SQLite with
-WAL journaling and a five-second busy timeout. If an owner was killed, the next
-writer may reclaim the lock only after the recorded PID is no longer alive;
-malformed or mismatched lock metadata is left in place for manual inspection.
-`profile doctor` never acquires or modifies the lease. Legacy-unbound databases
-retain their existing compatibility behavior and also use WAL.
+`<profile-directory>/writer.lock`. The managed service holds that lease for its
+lifetime, so a second service or one-shot CLI writer is refused while it is
+running. A CLI data command may hold the same lease only while the service is
+offline. Lineage verifies lease ownership before opening a named-profile
+database for writes and configures SQLite with WAL journaling and a five-second
+busy timeout. If an owner was killed, the next writer may reclaim the lock only
+after the recorded PID is no longer alive; malformed or mismatched lock metadata
+is left in place for manual inspection. `profile doctor` never acquires or
+modifies the lease. The lease records both the immutable profile ID and manifest
+fingerprint; legacy-unbound access never acquires a writer lease.
 
 Check the active runtime before making changes:
 
 ```bash
-lineage db info --json
-lineage-dev db info --json
+lineage-stable db info --profile team-production --json
+lineage-preview db info --profile team-preview --json
+npm run lineage:dev -- db info --profile team-development --json
 ```
 
+Managed services are profile-scoped. Their receipts record the launcher PID
+and start token, unique service instance, code root/fingerprint, profile and
+database fingerprints, origin, and log path. Start waits for `/api/runtime` to
+match every field before reporting success or opening a browser. Status exits
+nonzero for a stale PID, unreachable service, current-code drift, wrong port,
+or any code/profile/database/instance mismatch:
+
+```bash
+make start-prod-bg LINEAGE_PROD_PROFILE=team-production
+make status-prod LINEAGE_PROD_PROFILE=team-production
+make start-preview-bg LINEAGE_PREVIEW_PROFILE=team-preview
+make start-dev-bg LINEAGE_DEV_PROFILE=team-development
+```
+
+Use the matching `status-*`, `logs-*`, and `stop-*` target with the same profile
+variable. Stable and preview targets execute the service controller from that
+channel's attested, content-addressed package root; only dev executes the
+checkout controller. Stop signals only the process identity recorded for that profile.
+Checkout-backed `start-local-prod` and registration-only launchd/tmux status
+paths are intentionally not supported.
+
 The app shows a persistent environment/profile badge, and Settings includes the
-profile binding, channel, version, Git SHA when available, schema markers, and
-SQLite path.
+profile binding, code origin/root/fingerprint, channel, version, embedded Git
+revision, schema markers, and SQLite path.
 
 ## Agent Claims
 
@@ -242,15 +324,27 @@ whose version or `lineage.version` does not exactly match the resolved Lineage
 package version. The plugin artifact and installer package are released from
 this public repository.
 
+Every Lineage release preflights the current operator skill, packs and checksums
+the exact matching plugin, installs that artifact into a temporary Codex plugin
+root, and attaches both files to the versioned GitHub release before npm publish
+or dist-tag mutation is allowed. Release status reports the local version lock
+and GitHub assets. The installed skill requires isolated channel launchers,
+named profiles, managed service identity status, and profile-only writes.
+
 ## Local Development
 
 ```bash
 npm ci
 npm run dev
 npm run ci
+npm run runtime:oracle
 ```
 
 `npm run dev` starts the local development server from source. `npm run ci` runs the full local verification gate.
+`npm run runtime:oracle` creates three temporary code roots, profiles,
+databases, ports, and managed services, proves their identities are distinct
+while all are live, attacks every cross-channel and stale-identity boundary,
+and then cleans up.
 
 ## Command Shortcuts
 
@@ -260,7 +354,9 @@ verification commands. Run `make` or `make help` to list the available targets.
 ```bash
 make install-prod
 make install-plugin-prod
-make start-prod
+make start-prod LINEAGE_PROD_PROFILE=team-production
+make start-prod-bg LINEAGE_PROD_PROFILE=team-production
+make status-prod LINEAGE_PROD_PROFILE=team-production
 make check
 make smoke
 ```
@@ -287,7 +383,7 @@ npm run release:dry-run -- --tag latest
 npm run release:latest
 ```
 
-The release script verifies package metadata, changelog version coverage, public-readiness scans, install smoke, browser smoke, audit, and package contents before publishing. Promotion also installs the candidate package and runs a claim lifecycle smoke that creates a target claim, proves missing-token writes fail, proves matching-token writes succeed, verifies read surfaces do not expose the raw token, and proves release invalidates the token. GitHub Actions runs CI on pull requests and `main`; publishing is manual through the Release workflow.
+The release script verifies package metadata, changelog version coverage, public-readiness scans, install smoke, browser smoke, audit, package contents, and the version-locked Codex plugin before publishing. The GitHub plugin artifact and checksum must exist before npm publish or dist-tag mutation. Promotion also installs the candidate package and runs a claim lifecycle smoke that creates a target claim, proves missing-token writes fail, proves matching-token writes succeed, verifies read surfaces do not expose the raw token, and proves release invalidates the token. GitHub Actions runs CI on pull requests and `main`; publishing is manual through the Release workflow.
 
 Use the Release workflow operations this way:
 

package/dist/cli/lineage-channel.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+
+// src/cli/lineage-channel.ts
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  writeFileSync
+} from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/shared/runtimeInfoTypes.ts
+var lineageRuntimeBuildSchemaVersion = "lineage.runtime_build.v1";
+var lineageRuntimeInstallSchemaVersion = "lineage.runtime_install.v1";
+
+// src/cli/lineage-channel.ts
+var packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+var packageInfo = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function readOption(args, name) {
+  const inline = args.find((arg) => arg.startsWith(`${name}=`));
+  if (inline) return inline.slice(name.length + 1);
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : void 0;
+}
+function runtimeRoot() {
+  if (process.env.LINEAGE_RUNTIME_ROOT) return resolve(process.env.LINEAGE_RUNTIME_ROOT);
+  if (platform() === "darwin") return join(homedir(), "Library", "Application Support", "Lineage", "runtimes");
+  if (platform() === "win32") return join(process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local"), "Lineage", "runtimes");
+  return join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "lineage", "runtimes");
+}
+function parseChannel(value) {
+  if (value === "stable" || value === "preview") return value;
+  throw new Error("Channel must be stable or preview; dev is checkout-only");
+}
+function packageTreeSha256(root) {
+  const hash = createHash("sha256");
+  const visit = (directory, relativeDirectory = "") => {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))) {
+      const relativePath = relativeDirectory ? join(relativeDirectory, entry.name) : entry.name;
+      const path = join(directory, entry.name);
+      hash.update(relativePath.replaceAll("\\", "/"));
+      hash.update("\0");
+      if (entry.isDirectory()) {
+        hash.update("directory\0");
+        visit(path, relativePath);
+      } else if (entry.isSymbolicLink()) {
+        hash.update("symlink\0");
+        hash.update(readlinkSync(path));
+      } else if (entry.isFile()) {
+        hash.update("file\0");
+        hash.update(readFileSync(path));
+      } else {
+        hash.update("other\0");
+      }
+      hash.update("\0");
+    }
+  };
+  visit(root);
+  return hash.digest("hex");
+}
+function expectedBuildFingerprint(build) {
+  return sha256(JSON.stringify({
+    package_name: build.package_name,
+    package_version: build.package_version,
+    schema_version: build.schema_version,
+    source_dirty: build.source_dirty,
+    source_fingerprint: build.source_fingerprint,
+    source_git_sha: build.source_git_sha
+  }));
+}
+function validateBuild(root, installed) {
+  const path = join(root, "dist", "runtime-build.json");
+  const build = JSON.parse(readFileSync(path, "utf8"));
+  if (build.schema_version !== lineageRuntimeBuildSchemaVersion) throw new Error(`Unsupported build identity schema in ${path}`);
+  if (build.package_name !== installed.name || build.package_version !== installed.version) throw new Error("Embedded build identity does not match installed package.json");
+  if (!/^[a-f0-9]{40}$/i.test(build.source_git_sha)) throw new Error("Embedded build Git revision is invalid");
+  if (!/^[a-f0-9]{64}$/i.test(build.source_fingerprint)) throw new Error("Embedded source fingerprint is invalid");
+  if (build.build_fingerprint !== expectedBuildFingerprint(build)) throw new Error("Embedded build fingerprint does not match its contents");
+  if (build.source_dirty) throw new Error("Refusing stable/preview installation of a dirty-source build");
+  return build;
+}
+function parseRegistryPackageMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("npm metadata was not a JSON object");
+  }
+  const metadata = value;
+  const nestedIntegrity = metadata.dist?.integrity;
+  const flatIntegrity = metadata["dist.integrity"];
+  if (typeof nestedIntegrity === "string" && typeof flatIntegrity === "string" && nestedIntegrity !== flatIntegrity) {
+    throw new Error("npm metadata returned conflicting integrity values");
+  }
+  const integrity = typeof nestedIntegrity === "string" ? nestedIntegrity : flatIntegrity;
+  if (typeof metadata.version !== "string" || !metadata.version || typeof integrity !== "string" || !integrity) {
+    throw new Error("npm metadata did not include exact version and integrity");
+  }
+  return { integrity, version: metadata.version };
+}
+function resolveSpec(spec, allowLocalPackage) {
+  const localPath = resolve(spec.replace(/^file:/, ""));
+  if (existsSync(localPath)) {
+    if (!allowLocalPackage) {
+      throw new Error("Local package paths require --allow-local-package; normal stable/preview installs must resolve from the npm registry");
+    }
+    return {
+      installSpec: localPath,
+      integrity: `sha512-${createHash("sha512").update(readFileSync(localPath)).digest("base64")}`,
+      requestedSpec: spec,
+      source: "local"
+    };
+  }
+  let metadata;
+  try {
+    metadata = parseRegistryPackageMetadata(JSON.parse(execFileSync("npm", ["view", spec, "version", "dist.integrity", "--json"], { encoding: "utf8" })));
+  } catch (error) {
+    throw new Error(`npm metadata for ${spec} did not include exact version and integrity`, { cause: error });
+  }
+  const name = spec.startsWith("@") ? spec.slice(0, spec.indexOf("@", 1)) : spec.split("@")[0];
+  return {
+    installSpec: `${name}@${metadata.version}`,
+    integrity: metadata.integrity,
+    expectedVersion: metadata.version,
+    requestedSpec: spec,
+    source: "registry"
+  };
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function writeShim(path, channel, receiptPath, entrypoint) {
+  const tempPath = `${path}.tmp-${process.pid}`;
+  const script = `#!/bin/sh
+LINEAGE_RUNTIME_RECEIPT=${shellQuote(receiptPath)} LINEAGE_RELEASE_CHANNEL=${shellQuote(channel)} exec ${shellQuote(process.execPath)} ${shellQuote(entrypoint)} "$@"
+`;
+  writeFileSync(tempPath, script, { mode: 493 });
+  chmodSync(tempPath, 493);
+  renameSync(tempPath, path);
+}
+function validateExistingReceipt(receiptPath, channel, expected) {
+  const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+  if (receipt.schema_version !== lineageRuntimeInstallSchemaVersion || receipt.channel !== channel) throw new Error(`Invalid existing ${channel} runtime receipt`);
+  const installed = JSON.parse(readFileSync(join(receipt.package_root, "package.json"), "utf8"));
+  const build = validateBuild(receipt.package_root, installed);
+  if (receipt.package_name !== installed.name || receipt.package_version !== installed.version) throw new Error(`Existing ${channel} receipt does not match package.json`);
+  if (receipt.build_fingerprint !== build.build_fingerprint) throw new Error(`Existing ${channel} receipt does not match embedded build identity`);
+  if (packageTreeSha256(receipt.package_root) !== receipt.package_tree_sha256) throw new Error(`Existing ${channel} runtime package tree has changed`);
+  if (expected && (receipt.package_integrity !== expected.integrity || receipt.package_root !== expected.packageRoot || receipt.package_source !== expected.source || receipt.package_version !== expected.version || receipt.build_fingerprint !== expected.build.build_fingerprint)) {
+    throw new Error(`Existing ${channel} runtime receipt does not match the freshly resolved package`);
+  }
+  return receipt;
+}
+function install(channel, args) {
+  const root = resolve(readOption(args, "--root") || runtimeRoot());
+  const shimDir = resolve(readOption(args, "--shim-dir") || join(root, "bin"));
+  const requestedSpec = readOption(args, "--package") || `${packageInfo.name}@${channel === "stable" ? "latest" : "next"}`;
+  const resolvedSpec = resolveSpec(requestedSpec, args.includes("--allow-local-package"));
+  const channelRoot = join(root, "installs", channel);
+  mkdirSync(channelRoot, { recursive: true });
+  const stagingRoot = mkdtempSync(join(channelRoot, ".staging-"));
+  let keepStaging = false;
+  try {
+    execFileSync("npm", [
+      "install",
+      "--prefix",
+      stagingRoot,
+      "--ignore-scripts",
+      "--no-audit",
+      "--no-fund",
+      "--package-lock=false",
+      resolvedSpec.installSpec
+    ], { stdio: "ignore" });
+    const stagingPackageRoot = join(stagingRoot, "node_modules", ...packageInfo.name.split("/"));
+    const installed = JSON.parse(readFileSync(join(stagingPackageRoot, "package.json"), "utf8"));
+    if (installed.name !== packageInfo.name) throw new Error(`Installed unexpected package ${installed.name}`);
+    if (resolvedSpec.expectedVersion && installed.version !== resolvedSpec.expectedVersion) throw new Error(`Installed ${installed.version}, expected ${resolvedSpec.expectedVersion}`);
+    const build = validateBuild(stagingPackageRoot, installed);
+    const installId = `${installed.version}-${sha256(resolvedSpec.integrity).slice(0, 16)}`;
+    const finalRoot = join(channelRoot, installId);
+    const finalPackageRoot = join(finalRoot, "node_modules", ...packageInfo.name.split("/"));
+    const receiptPath = join(finalRoot, "lineage-runtime-receipt.json");
+    let receipt;
+    if (existsSync(finalRoot)) {
+      receipt = validateExistingReceipt(receiptPath, channel, {
+        build,
+        integrity: resolvedSpec.integrity,
+        packageRoot: finalPackageRoot,
+        source: resolvedSpec.source,
+        version: installed.version
+      });
+    } else {
+      const packageTree = packageTreeSha256(stagingPackageRoot);
+      renameSync(stagingRoot, finalRoot);
+      keepStaging = true;
+      receipt = {
+        build_fingerprint: build.build_fingerprint,
+        channel,
+        installed_at: (/* @__PURE__ */ new Date()).toISOString(),
+        package_integrity: resolvedSpec.integrity,
+        package_name: installed.name,
+        package_root: finalPackageRoot,
+        package_source: resolvedSpec.source,
+        package_spec: resolvedSpec.requestedSpec,
+        package_tree_sha256: packageTree,
+        package_version: installed.version,
+        schema_version: lineageRuntimeInstallSchemaVersion
+      };
+      writeFileSync(receiptPath, `${JSON.stringify(receipt, null, 2)}
+`, { mode: 384 });
+    }
+    mkdirSync(shimDir, { recursive: true });
+    const shim = join(shimDir, channel === "stable" ? "lineage-stable" : "lineage-preview");
+    const entrypoint = join(finalPackageRoot, "dist", "cli", channel === "stable" ? "lineage.js" : "lineage-preview.js");
+    if (!existsSync(entrypoint)) throw new Error(`Installed package is missing ${entrypoint}`);
+    writeShim(shim, channel, receiptPath, entrypoint);
+    const serviceShim = join(shimDir, channel === "stable" ? "lineage-stable-service" : "lineage-preview-service");
+    const serviceEntrypoint = join(finalPackageRoot, "dist", "cli", "managed-service.js");
+    if (!existsSync(serviceEntrypoint)) throw new Error(`Installed package is missing ${serviceEntrypoint}`);
+    writeShim(serviceShim, channel, receiptPath, serviceEntrypoint);
+    const pointerDir = join(root, "channels");
+    mkdirSync(pointerDir, { recursive: true });
+    writeFileSync(join(pointerDir, `${channel}.json`), `${JSON.stringify({ channel, receipt_path: receiptPath, service_shim: serviceShim, shim }, null, 2)}
+`, { mode: 384 });
+    return { ...receipt, receipt_path: receiptPath, service_shim: serviceShim, shim };
+  } finally {
+    if (!keepStaging) rmSync(stagingRoot, { force: true, recursive: true });
+  }
+}
+function status(args) {
+  const root = resolve(readOption(args, "--root") || runtimeRoot());
+  return Object.fromEntries(["stable", "preview"].map((channel) => {
+    const pointerPath = join(root, "channels", `${channel}.json`);
+    if (!existsSync(pointerPath)) return [channel, { installed: false }];
+    try {
+      const pointer = JSON.parse(readFileSync(pointerPath, "utf8"));
+      const receipt = validateExistingReceipt(pointer.receipt_path, channel);
+      if (!existsSync(pointer.shim) || !existsSync(pointer.service_shim)) throw new Error(`Existing ${channel} runtime shims are missing`);
+      return [channel, { installed: true, receipt, receipt_path: pointer.receipt_path, service_shim: pointer.service_shim, shim: pointer.shim }];
+    } catch (error) {
+      return [channel, { error: error instanceof Error ? error.message : String(error), installed: false }];
+    }
+  }));
+}
+function usage() {
+  return `lineage-channel ${packageInfo.version}
+
+Usage:
+  lineage-channel install stable [--root <path>] [--shim-dir <path>] [--package <npm-spec>] [--json]
+  lineage-channel install preview [--root <path>] [--shim-dir <path>] [--package <npm-spec>] [--json]
+  lineage-channel status [--root <path>] [--json]
+
+Stable and preview are installed into separate content-addressed roots. Dev is
+checkout-only and is started with npm run lineage:dev -- <command>. Local
+tarballs are refused unless --allow-local-package is supplied explicitly.`;
+}
+function print(value, json) {
+  if (json) console.log(JSON.stringify(value, null, 2));
+  else if (value && typeof value === "object" && "shim" in value) {
+    const installed = value;
+    console.log(`Installed Lineage ${installed.channel} ${installed.package_version}`);
+    console.log(`Launcher: ${installed.shim}`);
+    console.log(`Service manager: ${installed.service_shim}`);
+  } else console.log(JSON.stringify(value, null, 2));
+}
+function runLineageChannel(args = process.argv.slice(2)) {
+  const json = args.includes("--json");
+  try {
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+      console.log(usage());
+    } else if (args.includes("--version") || args.includes("-v")) {
+      console.log(packageInfo.version);
+    } else if (args[0] === "install") {
+      print(install(parseChannel(args[1] || readOption(args, "--channel")), args.slice(2)), json);
+    } else if (args[0] === "status") {
+      print(status(args.slice(1)), json);
+    } else {
+      throw new Error(`Unknown lineage-channel command: ${args[0]}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (json) console.error(JSON.stringify({ error: message, ok: false }, null, 2));
+    else console.error(`lineage-channel: ${message}`);
+    process.exitCode = 1;
+  }
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) runLineageChannel();
+export {
+  parseRegistryPackageMetadata,
+  runLineageChannel
+};
+//# sourceMappingURL=lineage-channel.js.map