@polderlabs/bizar-omp 0.7.9 → 0.7.10

package/dist/cli/mobile-claim.d.ts

@@ -0,0 +1,143 @@
+import { type Lease } from "../storage/lease.js";
+import { type OmbSessionInfo } from "../omp/omb-sessions.js";
+export interface MobileClaim {
+    readonly claimId: string;
+    readonly session: string;
+    /** The exact generation this claim is bound to. */
+    readonly generation: string;
+    readonly owner: string;
+    /**
+     * The holder's pid, normally the mobile host — never the one-shot CLI that
+     * created the claim. Absent means the claim expires only on its TTL; see
+     * `isClaimStale`.
+     */
+    readonly pid?: number;
+    readonly claimedAt: number;
+}
+export interface ClaimOutcome {
+    readonly claim: MobileClaim;
+    readonly sessionDir: string;
+    readonly nativeId?: string;
+    readonly nativeSessionName?: string;
+    readonly cwd: string;
+    readonly takeover: boolean;
+}
+export declare function mobileClaimsDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * The per-session acquisition lock.
+ *
+ * Named after the session rather than shared, so claims for different sessions
+ * proceed independently — the contention is per ownership, not global.
+ */
+export declare function claimLockPath(session: string, env?: NodeJS.ProcessEnv): string;
+/** Serializes claim acquisition/release with OMB rename, continue and delete. */
+export declare function acquireMobileSessionLease(session: string, env?: NodeJS.ProcessEnv): Lease;
+export declare function claimPath(claimId: string, env?: NodeJS.ProcessEnv): string;
+export declare function writeClaimAtomic(path: string, claim: MobileClaim): void;
+/**
+ * Why a claim record could not be read.
+ *
+ * A claim is ownership metadata, so "I could not read it" and "there is none"
+ * are very different facts and must not share a return value. The previous
+ * implementation returned `undefined` for both, so a torn or truncated record
+ * silently disappeared from the inventory and the next caller saw no owner and
+ * was admitted — the fail-open this enum now makes impossible to express.
+ */
+export type ClaimReadFailure = "malformed" | "unreadable";
+export interface ClaimReadResult {
+    readonly claim: MobileClaim | undefined;
+    readonly failure: ClaimReadFailure | undefined;
+}
+export declare function readClaimResult(claimId: string, env?: NodeJS.ProcessEnv): ClaimReadResult;
+/** Convenience for callers that only care whether a usable claim exists. */
+export declare function readClaim(claimId: string, env?: NodeJS.ProcessEnv): MobileClaim | undefined;
+export interface ClaimInventory {
+    readonly claims: MobileClaim[];
+    /** Claim ids that exist but could not be read, with the reason. */
+    readonly unreadable: readonly {
+        readonly claimId: string;
+        readonly reason: ClaimReadFailure;
+    }[];
+}
+export declare function listClaimsDetailed(env?: NodeJS.ProcessEnv): ClaimInventory;
+export declare function listClaims(env?: NodeJS.ProcessEnv): MobileClaim[];
+/**
+ * A claim is stale only when its holder is provably gone, or it is simply old.
+ *
+ * `pid` is the *holder's* pid — normally the mobile host, supplied by the
+ * caller — and is deliberately not this process. `omb mobile sessions claim` is
+ * a one-shot command that exits immediately, so recording its own pid would
+ * make every claim look abandoned the moment it was created and break mutual
+ * exclusion entirely. A claim with no holder pid therefore expires only on its
+ * TTL, which is the safe direction: an abandoned claim is a nuisance, a claim
+ * that evaporates while its owner is still running is a second writer.
+ */
+export declare function isClaimStale(claim: MobileClaim, now?: number): boolean;
+export declare function releaseClaim(claimId: string, env?: NodeJS.ProcessEnv): void;
+/**
+ * Claims one session for mobile ownership.
+ *
+ * The generation is re-resolved from a live scan rather than trusted from the
+ * caller, then re-checked a second time immediately before the claim is written.
+ * The gap between those two reads is the window a concurrent TUI action could
+ * exploit, and the second read is what closes it.
+ */
+export declare function claimSessionForMobile(input: {
+    cwd: string;
+    name: string;
+    generation: string;
+    owner: string;
+    /** The mobile host's pid, when it knows one. Never this process. */
+    holderPid?: number;
+    env?: NodeJS.ProcessEnv;
+    now?: number;
+}): Promise<ClaimOutcome>;
+/**
+ * Releases a claim, but only while the session still answers to the generation
+ * that was claimed. A session that changed under the claim is reported rather
+ * than silently released, so the caller can decide.
+ */
+export declare function releaseMobileClaim(input: {
+    claimId: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    released: true;
+    claim: MobileClaim;
+    generationHeld: boolean;
+}>;
+export declare function describeClaim(claim: MobileClaim, now?: number): Record<string, unknown>;
+export type { OmbSessionInfo };
+/** A detached tmux client does not prove that its native OMP writer stopped. */
+export declare function assertMobileClaimCandidate(session: Pick<OmbSessionInfo, "state" | "attached" | "authorityKnown" | "processObserved" | "uncertainLiveness" | "nativeId" | "nativeSessionAvailable">): void;
+/** Resolve remote adoption only when the exact name and generation are unique. */
+export declare function findMobileClaimSession<T extends Pick<OmbSessionInfo, "name" | "generation">>(sessions: readonly T[], name: string, generation: string): T;
+/**
+ * Centralized admission check for taking local ownership of a session.
+ *
+ * A claim records that a mobile host has been handed a session, but until this
+ * existed nothing on the local side consulted it: a local command could still
+ * attach to the same journal and become a second writer, which is the one thing
+ * the claim contract exists to prevent. It lives here rather than in a CLI
+ * command so every local ownership path inherits it.
+ *
+ * `generation` is optional and the difference matters:
+ *
+ * - given, only a claim for that exact generation blocks. This is what keeps
+ *   session-name reuse from letting an old claim block a brand-new session.
+ * - omitted, *any* non-stale claim on the name blocks. Conservative on purpose:
+ *   a caller that cannot resolve the current generation must not be allowed to
+ *   start a second writer on a guess.
+ *
+ * Read-only operations never call this, so inventory and status keep working
+ * while a session is claimed.
+ */
+export declare function admitLocalOwnership(session: string, env?: NodeJS.ProcessEnv, generation?: string, now?: number): {
+    admitted: true;
+} | {
+    admitted: false;
+    claim: MobileClaim;
+};
+/** Operator-facing explanation for a refused local attach. */
+export declare function describeOwnershipRefusal(claim: MobileClaim): string;
+//# sourceMappingURL=mobile-claim.d.ts.map

package/dist/cli/mobile-claim.d.ts.map

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

package/dist/cli/mobile-claim.js

@@ -0,0 +1,399 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { ContractError } from "../core/errors.js";
+import { acquireLease } from "../storage/lease.js";
+import { assertOmbSessionGeneration, listOmbSessions, ombSessionDir, } from "../omp/omb-sessions.js";
+/**
+ * Exact-generation mobile ownership claims.
+ *
+ * A claim is the record that a mobile host has been handed one session, so the
+ * TUI does not start a second writer on the same journal. Three rules make it
+ * safe, and all three are enforced here rather than documented and hoped for:
+ *
+ * - **The generation is compared, never the name.** Claiming `bizar-foo` when a
+ *   different journal now answers to that name must fail. That is the whole
+ *   point of `generation`, and a name match is not evidence of anything.
+ * - **A live local owner refuses the claim.** Handing over a session someone is
+ *   attached to is the dual-writer race, so an attached session is not claimable
+ *   without an explicit controlled transition.
+ * - **A crashed claim does not lock a session forever.** The holder's pid is
+ *   recorded; if the process is provably gone the claim is stale and may be taken
+ *   over. Unknown liveness is never treated as gone.
+ */
+const CLAIM_TTL_MS = 24 * 60 * 60 * 1000;
+export function mobileClaimsDir(env = process.env) {
+    const base = env.XDG_STATE_HOME || join(env.HOME || homedir(), ".local", "state");
+    return join(base, "bizar-omp", "mobile-claims");
+}
+/**
+ * The per-session acquisition lock.
+ *
+ * Named after the session rather than shared, so claims for different sessions
+ * proceed independently — the contention is per ownership, not global.
+ */
+export function claimLockPath(session, env = process.env) {
+    if (!/^[A-Za-z0-9-]{1,64}$/.test(session)) {
+        throw new ContractError("session name is not a valid identifier");
+    }
+    const directory = mobileClaimsDir(env);
+    // The lock lives inside the claims directory, which may not exist yet on a
+    // freshly installed host. Created here so every caller of this function gets a
+    // usable path — otherwise the very first claim on a new machine fails with
+    // ENOENT before it can even start.
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    return join(directory, `${session}.lock`);
+}
+/** Serializes claim acquisition/release with OMB rename, continue and delete. */
+export function acquireMobileSessionLease(session, env = process.env) {
+    return acquireLease(claimLockPath(session, env), "another process is changing ownership of this session");
+}
+export function claimPath(claimId, env = process.env) {
+    // The id is generated here, but a caller could pass anything; keep the
+    // filename to a safe alphabet so a claim id can never escape the directory.
+    if (!/^[A-Za-z0-9-]{1,64}$/.test(claimId)) {
+        throw new ContractError("claim id is not a valid identifier");
+    }
+    return join(mobileClaimsDir(env), `${claimId}.json`);
+}
+export function writeClaimAtomic(path, claim) {
+    // Derive the directory from the path itself. Reading it back out of
+    // `process.env` would create a directory that is not the one being written
+    // whenever the caller passed its own environment.
+    const directory = dirname(path);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.tmp`;
+    const fd = openSync(temporary, "wx", 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(claim, null, 2)}\n`, "utf8");
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temporary, path);
+    // The rename itself is not durable until the *directory* entry is synced.
+    // Without this, a claim the CLI has already reported as acquired can vanish
+    // on power loss while the session journal it protects survived — the exact
+    // state where a second writer would be admitted with nothing to detect it.
+    fsyncDirectory(directory);
+}
+/**
+ * Makes a rename durable where the platform supports it.
+ *
+ * Directory fsync is POSIX and is not available on every platform or
+ * filesystem. When the open genuinely cannot be performed, the claim is still
+ * written and this is a no-op — failing here would turn a durability
+ * limitation into an outage, and the file is still correct on the next boot
+ * on any filesystem that journals the rename itself.
+ */
+function fsyncDirectory(directory) {
+    let fd;
+    try {
+        fd = openSync(directory, "r");
+    }
+    catch {
+        // Windows cannot open a directory as a file; EPERM/EISDIR/EACCES/EINVAL all
+        // mean "not supported here" rather than "the claim was not written".
+        return;
+    }
+    try {
+        fsyncSync(fd);
+    }
+    catch {
+        // Some filesystems reject fsync on a directory handle. The rename already
+        // happened; losing the extra barrier is not worth failing the claim over.
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function readClaimResult(claimId, env = process.env) {
+    let raw;
+    try {
+        raw = readFileSync(claimPath(claimId, env), "utf8");
+    }
+    catch (error) {
+        // ENOENT is genuinely absent. Anything else — permissions, a directory, an
+        // I/O error — means the record exists and could not be read, which is not
+        // the same thing at all.
+        const code = error.code;
+        return { claim: undefined, failure: code === "ENOENT" ? undefined : "unreadable" };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            return { claim: undefined, failure: "malformed" };
+        const record = parsed;
+        if (typeof record.claimId !== "string" ||
+            typeof record.session !== "string" ||
+            typeof record.generation !== "string" ||
+            typeof record.owner !== "string" ||
+            typeof record.claimedAt !== "number" ||
+            // `pid` is optional: a claim created by a one-shot CLI has no holder pid.
+            (record.pid !== undefined && typeof record.pid !== "number")) {
+            return { claim: undefined, failure: "malformed" };
+        }
+        return {
+            failure: undefined,
+            claim: {
+                claimId: record.claimId,
+                session: record.session,
+                generation: record.generation,
+                owner: record.owner,
+                ...(typeof record.pid === "number" ? { pid: record.pid } : {}),
+                claimedAt: record.claimedAt,
+            },
+        };
+    }
+    catch {
+        return { claim: undefined, failure: "malformed" };
+    }
+}
+/** Convenience for callers that only care whether a usable claim exists. */
+export function readClaim(claimId, env = process.env) {
+    return readClaimResult(claimId, env).claim;
+}
+export function listClaimsDetailed(env = process.env) {
+    let entries;
+    try {
+        entries = readdirSync(mobileClaimsDir(env));
+    }
+    catch {
+        return { claims: [], unreadable: [] };
+    }
+    const claims = [];
+    const unreadable = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const claimId = entry.slice(0, -".json".length);
+        const result = readClaimResult(claimId, env);
+        if (result.claim !== undefined)
+            claims.push(result.claim);
+        else if (result.failure !== undefined)
+            unreadable.push({ claimId, reason: result.failure });
+    }
+    return { claims, unreadable };
+}
+export function listClaims(env = process.env) {
+    return listClaimsDetailed(env).claims;
+}
+/**
+ * A claim is stale only when its holder is provably gone, or it is simply old.
+ *
+ * `pid` is the *holder's* pid — normally the mobile host, supplied by the
+ * caller — and is deliberately not this process. `omb mobile sessions claim` is
+ * a one-shot command that exits immediately, so recording its own pid would
+ * make every claim look abandoned the moment it was created and break mutual
+ * exclusion entirely. A claim with no holder pid therefore expires only on its
+ * TTL, which is the safe direction: an abandoned claim is a nuisance, a claim
+ * that evaporates while its owner is still running is a second writer.
+ */
+export function isClaimStale(claim, now = Date.now()) {
+    // Liveness is decided before age. The previous order checked the TTL first,
+    // so a mobile host that stayed up for more than 24 hours silently lost its
+    // ownership exclusion while it was demonstrably still running — and a second
+    // writer could then be admitted onto the same journal. Age is a fallback for
+    // claims with nobody to ask, not a way to override a live holder.
+    if (claim.pid === undefined) {
+        // No holder to probe: the TTL is the only evidence available, and
+        // expiring is the safe direction here. An abandoned claim is a nuisance;
+        // the reverse mistake is a second writer.
+        return now - claim.claimedAt > CLAIM_TTL_MS;
+    }
+    if (claim.pid === process.pid)
+        return false;
+    try {
+        // `kill 0` only performs the permission/existence check.
+        process.kill(claim.pid, 0);
+        // Positively alive, whatever the age.
+        return false;
+    }
+    catch (error) {
+        const code = error.code;
+        // EPERM means the process exists but belongs to another user: still alive.
+        // Anything other than a definite ESRCH is unknown liveness, and unknown
+        // is not dead — failing open here is exactly the bug this guards.
+        return code === "ESRCH";
+    }
+}
+export function releaseClaim(claimId, env = process.env) {
+    rmSync(claimPath(claimId, env), { force: true });
+}
+/**
+ * Claims one session for mobile ownership.
+ *
+ * The generation is re-resolved from a live scan rather than trusted from the
+ * caller, then re-checked a second time immediately before the claim is written.
+ * The gap between those two reads is the window a concurrent TUI action could
+ * exploit, and the second read is what closes it.
+ */
+export async function claimSessionForMobile(input) {
+    const env = input.env ?? process.env;
+    const now = input.now ?? Date.now();
+    if (!/^[A-Za-z0-9-]{1,64}$/.test(input.name)) {
+        throw new ContractError("session name is not a valid identifier");
+    }
+    const sessions = await listOmbSessions(input.cwd, env, { includeStopped: true, includeAllStopped: true, requireMultiplexer: true });
+    const session = findMobileClaimSession(sessions, input.name, input.generation);
+    if (!session.authorityKnown) {
+        throw new ContractError("session authority is unavailable");
+    }
+    if (session.generation !== input.generation) {
+        throw new ContractError("session changed externally");
+    }
+    assertMobileClaimCandidate(session);
+    // The existence check and the write that follows it are one serialized
+    // critical section. Previously they were separate steps, so two callers could
+    // both observe "no existing claim" and each write its own file for the same
+    // session and generation — both would report success, and the mutual
+    // exclusion the claim exists to provide was simply absent.
+    //
+    // The lease is Bizar's existing recoverable one, so a crashed holder does not
+    // wedge the session: recovery only rotates the lock when the recorded process
+    // is *provably* gone, and the receipt binds the pid to its process start time
+    // so a recycled pid cannot masquerade as the original owner.
+    const lease = acquireMobileSessionLease(input.name, env);
+    try {
+        // Re-evaluated inside the lock, not before it: this is the read that decides,
+        // and it has to be the read that happens after serialization.
+        const inventory = listClaimsDetailed(env);
+        // Fail closed. A record that exists but cannot be read is not evidence that
+        // nobody owns the session.
+        const blocking = inventory.unreadable.filter((entry) => entry.claimId.startsWith("corrupt-"));
+        if (blocking.length > 0) {
+            throw new ContractError("an existing mobile claim for this session could not be read; repair or quarantine it first", {
+                claimIds: blocking.map((entry) => entry.claimId),
+                reason: blocking[0]?.reason,
+            });
+        }
+        const existing = inventory.claims.find((claim) => claim.session === input.name);
+        if (existing !== undefined && !isClaimStale(existing, now)) {
+            throw new ContractError("session is already claimed for mobile ownership", {
+                claimId: existing.claimId,
+                owner: existing.owner,
+            });
+        }
+        // Re-resolve immediately before writing, still inside the lock, so a
+        // generation change during the wait cannot slip past.
+        const rechecked = await assertOmbSessionGeneration({ name: input.name, generation: input.generation }, input.cwd, env);
+        assertMobileClaimCandidate(rechecked);
+        const claim = {
+            claimId: randomUUID(),
+            session: input.name,
+            generation: input.generation,
+            owner: input.owner,
+            ...(input.holderPid === undefined ? {} : { pid: input.holderPid }),
+            claimedAt: now,
+        };
+        // A stale predecessor is released only once the successor is committed to
+        // disk, so a crash mid-takeover cannot leave the session unowned.
+        writeClaimAtomic(claimPath(claim.claimId, env), claim);
+        if (existing !== undefined)
+            releaseClaim(existing.claimId, env);
+        return {
+            claim,
+            sessionDir: ombSessionDir(rechecked.name, env),
+            cwd: rechecked.cwd,
+            takeover: existing !== undefined,
+            ...(rechecked.nativeId === undefined ? {} : { nativeId: rechecked.nativeId }),
+            ...(rechecked.nativeName === undefined ? {} : { nativeSessionName: rechecked.nativeName }),
+        };
+    }
+    finally {
+        lease.release();
+    }
+}
+/**
+ * Releases a claim, but only while the session still answers to the generation
+ * that was claimed. A session that changed under the claim is reported rather
+ * than silently released, so the caller can decide.
+ */
+export async function releaseMobileClaim(input) {
+    const env = input.env ?? process.env;
+    const claim = readClaim(input.claimId, env);
+    if (claim === undefined) {
+        throw new ContractError("no such claim");
+    }
+    let generationHeld = true;
+    try {
+        await assertOmbSessionGeneration({ name: claim.session, generation: claim.generation }, input.cwd, env);
+    }
+    catch {
+        // The session moved on. The claim is still released, but the caller is told
+        // it was no longer holding the generation it thought it had.
+        generationHeld = false;
+    }
+    releaseClaim(input.claimId, env);
+    return { released: true, claim, generationHeld };
+}
+export function describeClaim(claim, now = Date.now()) {
+    return {
+        claimId: claim.claimId,
+        session: claim.session,
+        generation: claim.generation,
+        owner: claim.owner,
+        claimedAt: claim.claimedAt,
+        stale: isClaimStale(claim, now),
+    };
+}
+/** A detached tmux client does not prove that its native OMP writer stopped. */
+export function assertMobileClaimCandidate(session) {
+    if (!session.authorityKnown)
+        throw new ContractError("session authority is unavailable");
+    if (session.attached)
+        throw new ContractError("session has a live local owner; release it locally first");
+    if (session.state !== "stopped" || session.processObserved || session.uncertainLiveness) {
+        throw new ContractError("session must be stopped and its native OMP process confirmed absent before mobile takeover");
+    }
+    if (!session.nativeSessionAvailable || typeof session.nativeId !== "string" || session.nativeId.length === 0) {
+        throw new ContractError("session has no readable native OMP identity to resume");
+    }
+}
+/** Resolve remote adoption only when the exact name and generation are unique. */
+export function findMobileClaimSession(sessions, name, generation) {
+    const matches = sessions.filter(session => session.name === name && session.generation === generation);
+    if (matches.length !== 1)
+        throw new ContractError(matches.length === 0 ? "no such Bizar session generation" : "session identity is ambiguous");
+    return matches[0];
+}
+/**
+ * Centralized admission check for taking local ownership of a session.
+ *
+ * A claim records that a mobile host has been handed a session, but until this
+ * existed nothing on the local side consulted it: a local command could still
+ * attach to the same journal and become a second writer, which is the one thing
+ * the claim contract exists to prevent. It lives here rather than in a CLI
+ * command so every local ownership path inherits it.
+ *
+ * `generation` is optional and the difference matters:
+ *
+ * - given, only a claim for that exact generation blocks. This is what keeps
+ *   session-name reuse from letting an old claim block a brand-new session.
+ * - omitted, *any* non-stale claim on the name blocks. Conservative on purpose:
+ *   a caller that cannot resolve the current generation must not be allowed to
+ *   start a second writer on a guess.
+ *
+ * Read-only operations never call this, so inventory and status keep working
+ * while a session is claimed.
+ */
+export function admitLocalOwnership(session, env = process.env, generation, now = Date.now()) {
+    for (const claim of listClaimsDetailed(env).claims) {
+        if (claim.session !== session)
+            continue;
+        if (generation !== undefined && claim.generation !== generation)
+            continue;
+        if (isClaimStale(claim, now))
+            continue;
+        return { admitted: false, claim };
+    }
+    return { admitted: true };
+}
+/** Operator-facing explanation for a refused local attach. */
+export function describeOwnershipRefusal(claim) {
+    return (`session ${claim.session} is claimed for mobile ownership by ${claim.owner}` +
+        ` (claim ${claim.claimId}). Release it on the phone, or run: omb mobile sessions release ${claim.claimId}`);
+}
+//# sourceMappingURL=mobile-claim.js.map

package/dist/cli/mobile-claim.js.map

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

package/dist/cli/omb-commands.d.ts

@@ -15,7 +15,7 @@ export interface OmbCommand {
     usage: string;
     run(args: string[], env: NodeJS.ProcessEnv): Promise<number>;
 }
-export declare const HELP_USAGE = "omb help [command]\n\n  Lists every omb command, or prints one command's usage.\n\n  --json   print the command list as { commands: [{ name, names, summary, usage }] }\n\n  Arguments omb does not recognise are passed to OMP, so \"omb --resume\",\n  \"omb <prompt>\", and bare \"omb\" keep working exactly as before. \"omb help\",\n  \"omb --help\" and \"omb -h\" print this table instead; use \"omp --help\" for\n  OMP's own help.";
+export declare const HELP_USAGE = "omb help [command]\n\n  Lists every omb command, or prints one command's usage.\n\n  --json   print public commands and the internal dispatch capabilities\n\n  Arguments omb does not recognise are passed to OMP, so \"omb --resume\",\n  \"omb <prompt>\", and bare \"omb\" keep working exactly as before. \"omb help\",\n  \"omb --help\" and \"omb -h\" print this table instead; use \"omp --help\" for\n  OMP's own help.";
 /** Look up a command by its first token; undefined means "pass through to OMP". */
 export declare function findOmbCommand(token: string): OmbCommand | undefined;
 export declare function renderOmbUsage(): string;

package/dist/cli/omb-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"omb-commands.d.ts","sourceRoot":"","sources":["../../src/cli/omb-commands.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9D;AAED,eAAO,MAAM,UAAU,mbASL,CAAC;AAEnB,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEpE;AAED,wBAAgB,cAAc,IAAI,MAAM,CAavC;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAwBrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,EAiDpC,CAAC"}
+{"version":3,"file":"omb-commands.d.ts","sourceRoot":"","sources":["../../src/cli/omb-commands.ts"],"names":[],"mappings":"AASA;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9D;AAED,eAAO,MAAM,UAAU,saASL,CAAC;AAEnB,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEpE;AAED,wBAAgB,cAAc,IAAI,MAAM,CAavC;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAyBrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,UAAU,EAmEpC,CAAC"}

package/dist/cli/omb-commands.js

@@ -4,11 +4,13 @@ import { DASHBOARD_USAGE, runDashboardCommand } from "./omb-dashboard.js";
 import { RESTART_USAGE, STOP_USAGE, runRestartCommand, runStopCommand } from "./omb-runtime.js";
 import { TRAY_USAGE, runTrayCommand } from "./omb-tray.js";
 import { UPDATE_USAGE, runUpdateCommand } from "./omb-update.js";
+import { SESSIONS_USAGE, runSessionsCommand } from "./omb-sessions.js";
+import { MOBILE_USAGE, PAIR_USAGE, runMobileCommand, runPairCommand } from "./omb-mobile.js";
 export const HELP_USAGE = `omb help [command]
 
   Lists every omb command, or prints one command's usage.
 
-  --json   print the command list as { commands: [{ name, names, summary, usage }] }
+  --json   print public commands and the internal dispatch capabilities
 
   Arguments omb does not recognise are passed to OMP, so "omb --resume",
   "omb <prompt>", and bare "omb" keep working exactly as before. "omb help",
@@ -41,6 +43,7 @@ export function runHelpCommand(args) {
                 summary: command.summary,
                 usage: command.usage,
             })),
+            internalCommands: ["--internal-mobile"],
         }, null, 2)}\n`);
         return 0;
     }
@@ -64,6 +67,18 @@ export function runHelpCommand(args) {
  * the hub needs the cwd its caller was started in, so both are forwarded here.
  */
 export const OMB_COMMANDS = [
+    {
+        names: ["pair"],
+        summary: "Pair the Android app with this host",
+        usage: PAIR_USAGE,
+        run: (args, env) => runPairCommand(args, env),
+    },
+    {
+        names: ["mobile"],
+        summary: "Manage the integrated mobile host and app workspace",
+        usage: MOBILE_USAGE,
+        run: (args, env) => runMobileCommand(args, env),
+    },
     {
         names: ["agents", "hub", "a"],
         summary: "Session hub: attach, start, rename, and stop sessions",
@@ -76,6 +91,12 @@ export const OMB_COMMANDS = [
         usage: DASHBOARD_USAGE,
         run: (args, env) => runDashboardCommand(args, env),
     },
+    {
+        names: ["sessions", "s"],
+        summary: "List Bizar-owned sessions, with machine-readable output",
+        usage: SESSIONS_USAGE,
+        run: (args, env) => runSessionsCommand(process.cwd(), args, env),
+    },
     {
         names: ["daemon"],
         summary: "Detached loopback service behind the dashboard",