/**
 * Project routine discovery, source tracking, and user-layer sync.
 *
 * Project YAML under `<project>/.agents/routines/*.yml` never fires on its own
 * (a cloned repo must not auto-run agent prompts). A routine has exactly one
 * state — enabled or disabled — owned by this device's `meta.deviceRoutines`
 * list, never by the project YAML's own `enabled:` field. `agents routines
 * enable <name>` materialises the routine into `~/.agents/routines/` with
 * `source:` provenance (so the daemon, which loads only user + system layers,
 * can see it) and flips the device flag on — one action. `discoverProjectRoutines`
 * surfaces not-yet-materialised routines from the user's registered projects so
 * `list` shows them as disabled. `syncProjectRoutines` refreshes materialised
 * copies from their source YAML (also invoked on daemon SIGHUP).
 */
import { type JobConfig, type JobSource } from './scheduling/routines.js';
/** Expand `~/…` and resolve to an absolute path. */
export declare function expandProjectPath(p: string): string;
/** Store paths home-relative when under $HOME so they travel across machines. */
export declare function displayProjectPath(abs: string): string;
/** Resolve the project root (parent of `.agents/`) from a cwd, or null. */
export declare function resolveProjectRoot(cwd?: string): string | null;
/** Git provenance for a project root (best-effort; never throws). */
export declare function readProjectGitSource(projectRoot: string): Pick<JobSource, 'repo' | 'branch' | 'commit'>;
/** List project routine YAML files (name + absolute path). */
export declare function listProjectRoutineFiles(projectRoot: string): Array<{
    name: string;
    path: string;
}>;
export interface SyncProjectResult {
    projectRoot: string;
    synced: string[];
    skipped: Array<{
        name: string;
        reason: string;
    }>;
    removed: string[];
    errors: Array<{
        name: string;
        error: string;
    }>;
}
/**
 * Refresh one project's already-materialised routines from its source YAML.
 * - Overwrites user copies that already carry matching `source.projectPath`
 * - Never clobbers a hand-authored user routine (no source / different source)
 * - Removes user copies from this project whose YAML disappeared
 *
 * Sync NEVER touches the device enable flag: a routine's enabled/disabled state
 * is owned solely by `meta.deviceRoutines` (via `agents routines enable/disable`),
 * never by the project YAML's own `enabled:` field. That is what keeps a cloned
 * repo from auto-firing — refreshing a definition can never turn it on.
 */
export declare function syncProjectRoutines(projectRoot: string): SyncProjectResult;
export interface SyncAllResult {
    projects: SyncProjectResult[];
    /** Project roots that were listed but missing on disk. */
    missing: string[];
}
/** Distinct project roots that already have at least one materialised routine. */
export declare function materialisedProjectRoots(): string[];
/**
 * Refresh every materialised project routine from its source YAML. The set of
 * roots is derived from what the user has already enabled/materialised (their
 * `source.projectPath`), not from any allowlist — enabling a routine is the only
 * thing that brings its project into the refresh set. Also runs on daemon SIGHUP.
 */
export declare function syncAllProjectRoutines(opts?: {
    extraRoots?: string[];
}): SyncAllResult;
/** A project routine available to enable, not yet materialised on this device. */
export interface DiscoveredProjectRoutine {
    name: string;
    projectRoot: string;
    file: string;
    /** Display config for `list` (always disabled — enablement is a local act). */
    config: JobConfig;
}
/**
 * Project routines from registered projects that are NOT already materialised
 * in the user layer. These surface in `agents routines list` as disabled rows so
 * the single enabled/disabled model is visible, and `enable <name>` resolves a
 * name against them. A routine whose name already exists as a user/system
 * routine is omitted (that materialised copy is the live one).
 */
export declare function discoverProjectRoutines(): DiscoveredProjectRoutine[];
/**
 * Resolve a routine name to a project source for `enable <name>`: first the cwd
 * project, then registered projects. Returns null when the name matches no
 * project routine, or throws-by-return when it is ambiguous across projects.
 */
export declare function findProjectRoutine(name: string, cwd?: string): {
    projectRoot: string;
    file: string;
} | {
    ambiguous: string[];
} | null;
/**
 * Materialise one project routine into the user layer WITHOUT enabling it. The
 * caller (`agents routines enable`) flips the device flag separately, so a
 * materialise can never by itself make a routine fire. Returns the written
 * config, or an error string.
 */
export declare function materialiseProjectRoutine(projectRoot: string, name: string): {
    job: JobConfig;
} | {
    error: string;
};
