/**
 * Projects-root resolution for the `agents run --project <slug>` shorthand.
 *
 * Projects follow a predictable layout — `<root>/<repo>` (e.g.
 * `~/src/github.com/<user>/<repo>`), with git worktrees under
 * `<repo>/.agents/worktrees/<slug>`. The root is auto-inferred from the repo you
 * launch inside (the directory ABOVE the git root) and cached in `agents.yaml`
 * so later runs resolve a bare slug from anywhere. It is stored home-relative
 * (`~/…`) when it sits under `$HOME`, so the SAME value resolves on a remote
 * host whose home differs (`/home/<user>` vs `/Users/<user>`): a `--device` run
 * keeps the `~` and lets the remote login shell expand it (see `remoteCdPrefix`
 * in `hosts/dispatch.ts`), while a local run expands `~` against the local home.
 */
/** Rewrite an absolute path under the local home to a `~/`-relative string; pass others through. */
export declare function toHomeRelative(abs: string): string;
/** Expand a leading `~`/`$HOME` against the LOCAL home. Other paths pass through unchanged. */
export declare function expandLocalHome(p: string): string;
/**
 * Make a `--cwd`/`--project` value portable to a remote host: an absolute path
 * under the LOCAL home (which the local shell already expanded from `~`) becomes
 * `~/…` so the *remote* shell re-roots it at its own home. Paths already anchored
 * at `~`/`$HOME` pass through; other absolute or relative paths are left as-is
 * (used verbatim on the host). Explicit `--remote-cwd` is NOT run through this —
 * it is a literal remote path by contract.
 */
export declare function toRemotePortable(p: string): string;
/**
 * If `p` is anchored at the home dir — a leading `~` or `$HOME` — return the
 * remainder (no leading slash), else null. Callers that want a local-home
 * absolute (`/Users/<me>/x`, from a shell-expanded `--cwd ~/x`) re-rooted at the
 * remote home normalize it to `~/x` first (`toRemotePortable`); explicit
 * `--remote-cwd` is left literal and so is never re-rooted here.
 *
 * The canonical home-anchor stripper — shared by `remoteCdPrefix`,
 * `deriveMirroredCwd`, and the interactive-login shell builder
 * (`devices/connect.ts`), so there is exactly one notion of "the part below the
 * home dir".
 */
export declare function homeRemainder(p: string): string | null;
/**
 * Derive the remote directory to mirror from the local cwd, for a host run the
 * caller gave no `--cwd`/`--remote-cwd` (and for an interactive `agents ssh`
 * login with no command).
 *
 * Without this a `--device` run — or an `agents ssh <device>` login — lands in the
 * remote `$HOME`, so an agent launched from a repo starts with no project
 * context and the user has to `cd` by hand. Only a cwd under the LOCAL home is
 * mirrored — that is the part with a meaningful remote analogue (`~/src/x`
 * re-roots onto the remote home). A path outside home returns undefined:
 * `/opt/thing` on this box says nothing about the target's filesystem, so the
 * run keeps the remote home.
 */
export declare function deriveMirroredCwd(localCwd: string): string | undefined;
/**
 * Build a `cd <dir> && ` prefix that resolves on the REMOTE host.
 *
 * A `~`/`$HOME`-anchored path must resolve against the REMOTE user's home, not
 * the local one (`/home/<me>` vs `/Users/<me>`). We emit an unquoted `"$HOME"`
 * for that segment — the remote login shell expands it — and shell-quote the
 * remainder. Any other path (absolute or relative) is quoted verbatim.
 *
 * `mirror` marks a directory the caller DERIVED from the local cwd rather than
 * one the user asked for (see `deriveMirroredCwd`). The same repo checked out at
 * the same home-relative path on both boxes is the common fleet layout, so
 * mirroring lands the remote agent in the project instead of `$HOME`. It is a
 * best-effort mirror by definition — the host may simply not have that checkout
 * — so a missing directory falls back to the remote home instead of failing the
 * run. An explicit `--cwd`/`--remote-cwd` is never mirrored: the user named that
 * directory, so a missing one must surface as a `cd` error.
 */
export declare function remoteCdPrefix(remoteCwd?: string, opts?: {
    mirror?: boolean;
}): string;
/** The configured projects root (home-relative or absolute), or undefined when unset. */
export declare function getProjectRoot(): string | undefined;
/** Set (override) the cached projects root. Stored home-relative when under `$HOME`. */
export declare function setProjectRoot(rootPath: string): string;
/**
 * Infer the projects root from `cwd`: the directory ABOVE the git repo root
 * (cwd inside `~/src/github.com/user/repo` → `~/src/github.com/user`). Returns a
 * home-relative string when under `$HOME`; undefined when `cwd` is not in a repo.
 */
export declare function inferProjectRoot(cwd: string): Promise<string | undefined>;
/**
 * Resolve the projects root, auto-inferring and caching on first use. Throws an
 * actionable error when it is neither configured nor inferrable from `cwd`.
 */
export declare function ensureProjectRoot(cwd: string): Promise<string>;
export interface ProjectRef {
    slug: string;
    worktree?: string;
}
/** Parse a `--project` value of the form `<slug>[@<worktree>]`. */
export declare function parseProjectRef(ref: string): ProjectRef;
/**
 * Join a root + `--project` ref into a working directory. Pure (no I/O) so the
 * slug/worktree layout is unit-testable. `forRemote` keeps the path
 * home-relative (`~/…`) for the remote shell to expand; otherwise it is expanded
 * against the local home into an absolute path.
 */
export declare function buildProjectPath(root: string, ref: string, forRemote: boolean): string;
/**
 * Resolve a `--project` ref to a working directory, inferring/caching the root.
 *
 * `forRemote: true` returns a home-relative path (`~/…`) so the REMOTE login
 * shell expands `~`/`$HOME` to its own home. `forRemote: false` returns an
 * absolute local path and verifies it exists (so a mistyped slug fails loudly).
 */
export declare function resolveProjectRef(ref: string, opts: {
    forRemote: boolean;
    cwd?: string;
}): Promise<string>;
/**
 * Resolve a `--project` ref to the cwd an agent lands in PLUS the other
 * directories that project binds, so a spawn can grant them.
 *
 * `cwd` is exactly what `resolveProjectRef` returns — this never changes where
 * an agent starts. `extraDirs` is every other `repos[].path`, and is empty for
 * a convention-resolved project (no definition means no bound repos) and for a
 * definition that binds only its primary checkout.
 */
export declare function resolveProjectDirs(ref: string, opts: {
    forRemote: boolean;
    cwd?: string;
}): Promise<{
    cwd: string;
    extraDirs: string[];
}>;
