@amalgm/shell 0.1.162 → 0.1.164-main.34182640231

package/dist/installation/lease.js

@@ -0,0 +1,28 @@
+import { openFileDatabase } from '../sqlite.js';
+import { dirname } from 'node:path';
+import { ensurePrivateDir } from '../filesystem.js';
+/** An OS-held file lock ends on process exit, survives suspension and cannot
+ * be stolen by age or PID reuse. The file itself is never removed. */
+export function acquireProcessLease(file) {
+    ensurePrivateDir(dirname(file));
+    const database = openFileDatabase(file, { timeout: 0 });
+    try {
+        database.exec('BEGIN EXCLUSIVE');
+    }
+    catch (error) {
+        database.close();
+        if (error.code === 'SQLITE_BUSY')
+            return null;
+        throw error;
+    }
+    return { close() { if (database.open)
+            database.close(); } };
+}
+export function processLeaseHeld(file) {
+    const lease = acquireProcessLease(file);
+    if (!lease)
+        return true;
+    lease.close();
+    return false;
+}
+//# sourceMappingURL=lease.js.map

package/dist/installation/lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../../src/installation/lease.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD;sEACsE;AACtE,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAAC,CAAC;IACzC,OAAO,KAAK,EAAE,CAAC;QACb,QAAQ,CAAC,KAAK,EAAE,CAAC;QACjB,IAAK,KAA2B,CAAC,IAAI,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;QACrE,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,EAAE,KAAK,KAAK,IAAI,QAAQ,CAAC,IAAI;YAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,KAAK,CAAC,KAAK,EAAE,CAAC;IACd,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/installation/ownership.d.ts

@@ -0,0 +1,30 @@
+import { type RuntimeBinding } from '@amalgm/core/identity';
+/** One machine-local ownership ledger, independent of any selected lane.
+ * SQLite serializes competing processes; no polling or idle worker is needed.
+ * Root claims survive shutdown because stopped runtimes still own their data. */
+export declare class InstallationOwnership {
+    private readonly database;
+    private readonly runtimeLeases;
+    private readonly leaseDirectory;
+    readonly installationRoot: string;
+    readonly binding: RuntimeBinding;
+    constructor(input: {
+        home: string;
+        installationRoot: string;
+        binding: RuntimeBinding;
+    });
+    /** Reserve before registration, materialization, Watch or another writer.
+     * Empty scope reserves the installation container, not a user's workspace. */
+    reserve(requestedPath: string, userScope?: string): string;
+    /** Serialize initialization with other claimants before creating a manifest. */
+    initialize<T>(effect: () => T): T;
+    /** An OS-held SQLite write lock is the lease: process exit releases it,
+     * suspension does not, and PID reuse cannot either steal or strand it. */
+    acquireRuntime(userScope: string): void;
+    releaseRuntime(userScope: string): void;
+    /** Contention is bounded setup work, never an idle ownership-recovery poll. */
+    waitForRuntime(userScope: string, timeoutMs?: number): Promise<void>;
+    close(): void;
+}
+/** Resolve existing symlink ancestors even before a new destination exists. */
+export declare function physicalPath(requestedPath: string): string;

package/dist/installation/ownership.js

@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, join, parse, resolve, sep } from 'node:path';
+import { openFileDatabase } from '../sqlite.js';
+import { acquireProcessLease } from './lease.js';
+import { resolveRuntimeBinding, runtimeBindingsMatch, writableRootsOverlap, } from '@amalgm/core/identity';
+/** One machine-local ownership ledger, independent of any selected lane.
+ * SQLite serializes competing processes; no polling or idle worker is needed.
+ * Root claims survive shutdown because stopped runtimes still own their data. */
+export class InstallationOwnership {
+    database;
+    runtimeLeases = new Map();
+    leaseDirectory;
+    installationRoot;
+    binding;
+    constructor(input) {
+        this.binding = resolveRuntimeBinding(input.binding);
+        this.installationRoot = physicalPath(input.installationRoot);
+        const directory = join(input.home, '.amalgm');
+        this.leaseDirectory = join(directory, 'owners');
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        this.database = openFileDatabase(join(directory, 'installation-ownership.sqlite'));
+        this.database.pragma('busy_timeout = 5000');
+        this.database.exec(`
+      CREATE TABLE IF NOT EXISTS writable_roots (
+        path TEXT PRIMARY KEY, installation TEXT NOT NULL, binding TEXT NOT NULL,
+        user_scope TEXT NOT NULL, physical TEXT NOT NULL
+      );
+    `);
+        try {
+            this.reserve(this.installationRoot);
+        }
+        catch (error) {
+            this.database.close();
+            throw error;
+        }
+    }
+    /** Reserve before registration, materialization, Watch or another writer.
+     * Empty scope reserves the installation container, not a user's workspace. */
+    reserve(requestedPath, userScope = '') {
+        const path = physicalPath(requestedPath);
+        const physical = physicalComponents(path);
+        const binding = JSON.stringify(this.binding);
+        this.database.transaction(() => {
+            const claims = this.database.prepare('SELECT * FROM writable_roots').all();
+            for (const claim of claims) {
+                const previous = physicalComponents(claim.path);
+                const recorded = JSON.parse(claim.physical);
+                const overlaps = writableRootsOverlap(pathComponents(path), pathComponents(claim.path))
+                    || writableRootsOverlap(physical, previous)
+                    || writableRootsOverlap(physical, recorded)
+                    || (recorded.at(-1).startsWith('inode:') && physical.includes(recorded.at(-1)))
+                    || (physical.at(-1).startsWith('inode:') && recorded.includes(physical.at(-1)));
+                if (!overlaps)
+                    continue;
+                const sameInstallation = claim.installation === this.installationRoot
+                    && runtimeBindingsMatch(JSON.parse(claim.binding), this.binding);
+                const sameUser = !claim.user_scope || !userScope || claim.user_scope === userScope;
+                if (!sameInstallation || !sameUser) {
+                    throw Object.assign(new Error(`Writable root ${path} overlaps ${claim.path}, owned by another Amalgm installation or user. Use a separate checkout.`), {
+                        code: 'installation_root_conflict',
+                    });
+                }
+            }
+            const existing = this.database.prepare('SELECT * FROM writable_roots WHERE path = ?').get(path);
+            if (!existing) {
+                this.database.prepare('INSERT INTO writable_roots VALUES (?, ?, ?, ?, ?)')
+                    .run(path, this.installationRoot, binding, userScope, JSON.stringify(physical));
+            }
+        }).immediate();
+        return path;
+    }
+    /** Serialize initialization with other claimants before creating a manifest. */
+    initialize(effect) {
+        return this.database.transaction(effect).immediate();
+    }
+    /** An OS-held SQLite write lock is the lease: process exit releases it,
+     * suspension does not, and PID reuse cannot either steal or strand it. */
+    acquireRuntime(userScope) {
+        if (!userScope)
+            throw new Error('Runtime ownership requires a user scope.');
+        if (this.runtimeLeases.has(userScope))
+            return;
+        const scope = createHash('sha256').update(JSON.stringify([this.binding, userScope])).digest('hex');
+        const lease = acquireProcessLease(join(this.leaseDirectory, `${scope}.sqlite`));
+        if (!lease)
+            throw Object.assign(new Error(`Amalgm already has a runtime owner for ${userScope} in this environment. Bind to that runtime.`), {
+                code: 'runtime_already_owned',
+            });
+        this.runtimeLeases.set(userScope, lease);
+    }
+    releaseRuntime(userScope) {
+        const lease = this.runtimeLeases.get(userScope);
+        if (!lease)
+            return;
+        lease.close();
+        this.runtimeLeases.delete(userScope);
+    }
+    /** Contention is bounded setup work, never an idle ownership-recovery poll. */
+    async waitForRuntime(userScope, timeoutMs = 600_000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            try {
+                this.acquireRuntime(userScope);
+                return;
+            }
+            catch (error) {
+                if (error.code !== 'runtime_already_owned' || Date.now() >= deadline)
+                    throw error;
+            }
+            await new Promise((done) => setTimeout(done, 250));
+        }
+    }
+    close() {
+        for (const scope of this.runtimeLeases.keys())
+            this.releaseRuntime(scope);
+        if (this.database.open)
+            this.database.close();
+    }
+}
+/** Resolve existing symlink ancestors even before a new destination exists. */
+export function physicalPath(requestedPath) {
+    let ancestor = resolve(requestedPath);
+    const absent = [];
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            throw new Error(`Cannot resolve physical root ${requestedPath}`);
+        absent.unshift(basename(ancestor));
+        ancestor = parent;
+    }
+    return join(realpathSync.native(ancestor), ...absent);
+}
+function physicalComponents(path) {
+    const root = parse(path).root;
+    const components = [root, ...path.slice(root.length).split(sep).filter(Boolean)];
+    let current = root;
+    return components.map((component, index) => {
+        if (index > 0)
+            current = join(current, component);
+        try {
+            const info = statSync(current);
+            return `inode:${info.dev}:${info.ino}:${info.birthtimeMs}`;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            return `name:${process.platform === 'win32' ? component.toLowerCase() : component}`;
+        }
+    });
+}
+function pathComponents(path) {
+    const absolute = process.platform === 'win32' ? path.toLowerCase() : path;
+    return [parse(absolute).root, ...absolute.slice(parse(absolute).root.length).split(sep).filter(Boolean)];
+}
+//# sourceMappingURL=ownership.js.map

package/dist/installation/ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ownership.js","sourceRoot":"","sources":["../../src/installation/ownership.ts"],"names":[],"mappings":"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"}

package/dist/installation/selection.d.ts

@@ -0,0 +1,8 @@
+import { type RuntimeBinding, type RuntimeLabel } from '@amalgm/core/identity';
+import type { ParsedArguments } from '../cli-arguments.js';
+/** Public command prefixes select the environment, never ambient env vars. */
+export declare function selectRuntimeInvocation(args: readonly string[]): {
+    runtimeLabel: RuntimeLabel;
+    args: readonly string[];
+};
+export declare function resolveInvocationBinding(runtimeLabel: RuntimeLabel, parsed: ParsedArguments): RuntimeBinding;

package/dist/installation/selection.js

@@ -0,0 +1,29 @@
+import { resolveRuntimeBinding } from '@amalgm/core/identity';
+/** Public command prefixes select the environment, never ambient env vars. */
+export function selectRuntimeInvocation(args) {
+    if (args[0] === 'preview')
+        return { runtimeLabel: 'preview', args: args.slice(1) };
+    if (args[0] === 'dev')
+        return { runtimeLabel: 'local', args: args.slice(1) };
+    return { runtimeLabel: 'main', args };
+}
+export function resolveInvocationBinding(runtimeLabel, parsed) {
+    const explicitLabel = stringOption(parsed, 'runtime-label');
+    if (explicitLabel !== undefined && explicitLabel !== runtimeLabel) {
+        throw new Error('The runtime label conflicts with the command prefix. Use amalgm preview … or amalgm dev … to select that environment.');
+    }
+    return resolveRuntimeBinding({
+        runtimeLabel,
+        branch: stringOption(parsed, 'branch'),
+        localSession: stringOption(parsed, 'local-session'),
+    });
+}
+function stringOption(parsed, name) {
+    const value = parsed.options[name];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error(`--${name} requires a value.`);
+    return value;
+}
+//# sourceMappingURL=selection.js.map

package/dist/installation/selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selection.js","sourceRoot":"","sources":["../../src/installation/selection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAA0C,MAAM,uBAAuB,CAAC;AAGtG,8EAA8E;AAC9E,MAAM,UAAU,uBAAuB,CAAC,IAAuB;IAC7D,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK;QAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7E,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,YAA0B,EAAE,MAAuB;IAC1F,MAAM,aAAa,GAAG,YAAY,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC5D,IAAI,aAAa,KAAK,SAAS,IAAI,aAAa,KAAK,YAAY,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CAAC,uHAAuH,CAAC,CAAC;IAC3I,CAAC;IACD,OAAO,qBAAqB,CAAC;QAC3B,YAAY;QACZ,MAAM,EAAE,YAAY,CAAC,MAAM,EAAE,QAAQ,CAAC;QACtC,YAAY,EAAE,YAAY,CAAC,MAAM,EAAE,eAAe,CAAC;KACpD,CAAC,CAAC;AACL,CAAC;AAED,SAAS,YAAY,CAAC,MAAuB,EAAE,IAAY;IACzD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,KAAK,IAAI,oBAAoB,CAAC,CAAC;IACpG,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/machine-host.d.ts

@@ -1,14 +1,14 @@
 import type { ChannelsCommands } from "@amalgm/channels";
 import type { ChatRuntimePort } from "@amalgm/chat";
-import { type JoinMachineInput, type MachineSetupPorts, type ReadyMachine } from "@amalgm/core/identity";
-import { type FilesAddResult } from "@amalgm/live/files";
+import { type JoinMachineInput, type MachineSetupPorts, type ReadyMachine, type RuntimeBinding } from "@amalgm/core/identity";
+import type { FilesAddResult } from "@amalgm/live/files";
 import { type FilesStageObserver } from "./files-observability.js";
 import type { EntityApplyStageEvidence } from "./entity-apply-host.js";
 import { type DeviceKeyStore } from "./authorization/index.js";
 import { type AuthorizationKeyRecoveryResult } from "./authorization/recovery-host.js";
-import { type PlatformProductHostOptions } from "./platform-product-host.js";
+import type { PlatformProductHostOptions } from "./platform-product-host.js";
 import { type RuntimeCommandConnection } from "./runtime-command-host.js";
-import { UserGroundHost, type DetectScanEvidence, type UserGroundCloseOptions, type WorkspaceAddStage } from "./user-ground-host.js";
+import type { UserGroundHost, DetectScanEvidence, UserGroundCloseOptions, WorkspaceAddStage } from "./user-ground-host.js";
 import type { OpenNativeWatch, WatchCoverageEvidence, WatchHealth } from "./watching/index.js";
 export interface MachineHostOptions {
     readonly homedir?: string;
@@ -19,7 +19,11 @@ export interface MachineHostOptions {
     readonly runtimeVersion: string;
     readonly runtimeLabel?: string;
     readonly branch?: string;
+    readonly localSession?: string;
+    /** Explicit local availability; managed installations retain their release selection. */
+    readonly services?: readonly string[];
     readonly proxyUrl?: string;
+    readonly wireUrl?: string;
     /** Hosted product endpoints. Omit in isolated hosts that do not compose them. */
     readonly platformProducts?: Omit<PlatformProductHostOptions, 'authorization'>;
     /** Test/adapter seam; production defaults to the OS-backed device key store. */
@@ -63,6 +67,7 @@ interface MachinePaths {
     readonly status: string;
 }
 export interface MachineStatus {
+    readonly binding: RuntimeBinding;
     readonly user: string;
     readonly deviceId: string | null;
     readonly registration: "absent" | "incomplete" | "ready";
@@ -74,6 +79,14 @@ export interface MachineStatus {
     readonly machineDir: string | null;
     readonly database: string | null;
 }
+type HostJoinInput = Omit<JoinMachineInput, 'appUrl' | 'platform' | 'appVersion' | 'runtimeLabel' | 'branch' | 'localSession'>;
+export interface MachineSetupResult {
+    readonly disposition: 'enrolled' | 'adopted';
+    readonly userEmail: string;
+    readonly userId: string;
+    readonly computerId: string;
+    readonly deviceId: string;
+}
 /** The production effects around Core's machine-setup operation. It does not
  * decide ordering, readiness, or installation selection; those remain Core. */
 export declare class MachineHost {
@@ -82,13 +95,19 @@ export declare class MachineHost {
     readonly amalgmRoot: string;
     readonly deviceFile: string;
     readonly ports: MachineSetupPorts;
+    readonly binding: RuntimeBinding;
+    private readonly ownership;
     private selectedUserEmail;
     private groundHost;
     private running;
     private readonly stages;
     constructor(options: MachineHostOptions);
-    join(input: Omit<JoinMachineInput, "appUrl" | "platform" | "appVersion" | "runtimeLabel" | "branch">): Promise<ReadyMachine>;
+    private approveSetup;
+    join(input: HostJoinInput): Promise<ReadyMachine>;
+    /** Shared, finite UI setup. An existing owner is never disturbed by adoption. */
+    setup(input: HostJoinInput): Promise<MachineSetupResult>;
     resume(): Promise<ReadyMachine>;
+    assertRuntimeCanStart(): void;
     recoverAuthorizationKey(input?: Readonly<{
         setupCode?: string;
     }>): Promise<AuthorizationKeyRecoveryResult>;
@@ -116,6 +135,7 @@ export declare class MachineHost {
      * loopback MCP route. Shell alone reads the local admission capability. */
     channelsCommands(): ChannelsCommands;
     close(options?: UserGroundCloseOptions): Promise<void>;
+    private drainRuntime;
     private ensureInstallationRoot;
     private openChannelsCommands;
     private runtimeCommandAddress;
@@ -124,8 +144,10 @@ export declare class MachineHost {
     private paths;
     private requireSelectedUser;
     private resolveUserForResume;
+    private assertRecordBinding;
     private loadMachine;
     private saveMachine;
+    private acquireRuntimeOwnership;
     private startRuntime;
 }
 export declare function defaultMachineName(): string;