/**
 * InstarWorktreeManager — Layer 1 of the Agent Worktree Convention.
 *
 * Creates git worktrees of the shared instar repository inside the agent's
 * own home directory (`~/.instar/agents/<agent>/.worktrees/`). This is the
 * only location the macOS sandbox cannot revoke mid-session.
 *
 * Spec: docs/specs/AGENT-WORKTREE-CONVENTION-SPEC.md (status: approved).
 *
 * The CLI subcommand `instar worktree create <branch>` is a thin shim over
 * this manager. All validation, resolution, and audit-trail logic lives
 * here so it can be unit-tested without spawning a CLI process.
 */
/** Default allowlist of remote-origin URLs for the canonical instar repo.
 *  Operators can extend via `worktree.repoUrlAllowlist` in `.instar/config.json`. */
export declare const DEFAULT_INSTAR_REPO_URL_ALLOWLIST: ReadonlyArray<string>;
export interface ResolveAgentHomeOptions {
    /** Override `process.env`. */
    env?: NodeJS.ProcessEnv;
    /** Override `process.cwd()`. */
    cwd?: string;
    /** Override the instar home root (defaults to `~/.instar`). */
    instarHome?: string;
    /** Override registry lookup (for tests). Returns the set of registered agent names. */
    registryLookup?: () => Set<string>;
    /** Override registry entries lookup (for tests). Returns name + recorded
     *  home path pairs — the legacy-home acceptance path matches the candidate
     *  against these recorded paths. */
    registryEntriesLookup?: () => ReadonlyArray<{
        name: string;
        path?: string;
    }>;
}
export interface ResolvedAgentHome {
    /** Absolute, real (symlink-resolved) path to the agent home directory. */
    agentHome: string;
    /** Agent name extracted from the trailing path segment. */
    agentName: string;
}
export interface ResolveInstarRepoOptions {
    env?: NodeJS.ProcessEnv;
    /** Override `process.cwd()` for current-checkout discovery. */
    cwd?: string;
    /** Path to user config (defaults to `~/.instar/config.json`). */
    configPath?: string;
    /** Override the URL allowlist entirely (skipping the default + config merge). */
    urlAllowlist?: ReadonlyArray<string>;
    /** Override the fallback chain order (for tests). */
    fallbackChain?: ReadonlyArray<string>;
    /** Override the home directory used for default fallbacks. */
    homeDir?: string;
}
export interface ResolvedInstarRepo {
    /** Absolute, real path to a validated instar repo. */
    repoPath: string;
    /** The allowlisted remote url that validated the repo (url or pushurl). */
    remoteUrl: string;
    /** Name of the remote that won the allowlist check (e.g. 'origin', 'JKHeadley'). */
    remoteName: string;
    /** True when the match was the remote's FETCH url — its refs mirror
     *  canonical instar and are safe as a worktree base. A pushurl-only match
     *  proves trust but NOT ref provenance: on fleet agent homes origin fetches
     *  the personal fork (backup-sync of agent-home files) while pushing to
     *  canonical — its refs must never be used as a code base. */
    remoteFetchesCanonical: boolean;
}
export interface CreateWorktreeOptions {
    /** Branch name to check out / create. */
    branch: string;
    /** Optional override for the worktree directory slug. Defaults to branch with `/` → `-`. */
    slug?: string;
    /** Default true (current bash-helper behavior). Pass false to skip the node_modules symlink. */
    shareNodeModules?: boolean;
    /** Override agent-home resolution (mainly for tests). */
    resolveAgentHomeOpts?: ResolveAgentHomeOptions;
    /** Override instar-repo resolution (mainly for tests). */
    resolveInstarRepoOpts?: ResolveInstarRepoOptions;
    /** Override the base for new branches. If omitted, resolves to origin/HEAD. */
    baseBranch?: string;
    /** Audit-mirror state directory (defaults to `<agent_home>/.instar`). */
    stateDir?: string;
}
export interface CreateWorktreeResult {
    worktreePath: string;
    branch: string;
    slug: string;
    agentHome: string;
    agentName: string;
    instarRepo: string;
    instarRepoSha: string;
    shareNodeModules: boolean;
    /** True if a new branch was created; false if an existing branch was checked out. */
    createdBranch: boolean;
}
export declare function resolveAgentHome(opts?: ResolveAgentHomeOptions): ResolvedAgentHome;
export declare function resolveInstarRepo(opts?: ResolveInstarRepoOptions): ResolvedInstarRepo;
export declare function defaultSlugFor(branch: string): string;
export declare function validateSlug(slug: string, existingSlugsLower: ReadonlySet<string>): void;
export declare function validateBranchName(branch: string, repoPath: string): void;
export declare function createWorktree(opts: CreateWorktreeOptions): Promise<CreateWorktreeResult>;
export declare function resolveBaseBranch(repoPath: string, override?: string, allowlistedRemote?: string): Promise<string>;
export declare function ensureHuskyHooksActive(worktreePath: string): void;
export declare function hasRunnableHookShim(shimHookPath: string): boolean;
/**
 * Drop a `.metadata_never_index` marker at the `.worktrees/` container root so
 * macOS Spotlight (mds_stores) + mediaanalysisd skip indexing every worktree
 * beneath it. Worktrees are throwaway full source trees; re-indexing dozens of
 * them is a top OS-level CPU consumer (measured: mediaanalysisd ~80% CPU under a
 * ~120-worktree backlog). The marker is honored recursively for the whole
 * subtree, lives at the container (not inside any worktree, so no git noise),
 * is a harmless no-op on non-macOS, and is idempotent. Returns true if it
 * created the marker, false if it already existed or could not be written.
 *
 * Part of the Responsible Resource Usage standard — OS resource hygiene.
 */
export declare function ensureWorktreeSpotlightExclusion(worktreesDir: string): boolean;
/**
 * Drop a `.metadata_never_index` marker at this agent's Claude Code transcript
 * directory (`<claudeHome>/projects/<encoded-agent-home>`) so macOS Spotlight
 * (mds_stores) stops re-indexing the constantly-appended JSONL session
 * transcripts. These are the single largest Spotlight churn source on a busy
 * agent: every assistant/user turn appends to them and an active home accumulates
 * many GB (measured ~18GB on a busy fleet box), which Spotlight re-indexes on
 * every change — pinning mds_stores at 60-90% of a core. instar already READS
 * these transcripts (TokenLedger / CompactionSentinel), so excluding them from
 * indexing is the matching OS hygiene; nothing usefully Spotlight-searches a
 * Claude JSONL transcript. Claude encodes the project dir by mapping every
 * non-alphanumeric char to '-' (`/Users/justin/.instar/agents/echo` ->
 * `-Users-justin--instar-agents-echo`); we mirror that. Graceful no-op when the
 * transcript dir doesn't exist yet (no sessions run) or on non-macOS; idempotent.
 * Returns true iff it created the marker.
 *
 * Part of the Responsible Resource Usage standard — OS resource hygiene.
 */
export declare function ensureClaudeTranscriptSpotlightExclusion(agentHome: string, claudeHome?: string): boolean;
/**
 * Drop a `.metadata_never_index` marker in each high-churn subdir of the agent's
 * runtime data dir (`<stateDir>`) so macOS Spotlight (mds_stores) + mediaanalysisd
 * stop re-indexing the agent's own constantly-mutating images / databases / logs /
 * state. This closes the gap left by the worktree, node_modules, and transcript
 * exclusions — the agent's own `.instar/` data was the remaining unexcluded churn
 * source (measured: mediaanalysisd ~72-78% CPU + mds_stores ~28-48% on a busy box
 * whose ~/.instar was never excluded). Markers sit INSIDE each subdir (gitignored
 * runtime trees → no git noise), are honored recursively, are harmless on
 * non-macOS, and idempotent. Returns the list of subdir names where a marker was
 * newly created (empty if all already present or none exist).
 *
 * Part of the Responsible Resource Usage standard — OS resource hygiene.
 */
export declare function ensureAgentDataSpotlightExclusion(stateDir: string): string[];
export interface LedgerEntry {
    ts: string;
    agent: string;
    branch: string;
    slug: string;
    worktreePath: string;
    instarRepo: string;
    instarRepoSha: string;
    shareNodeModules: boolean;
}
export declare function appendLedgerEntry(worktreesDir: string, stateDir: string, entry: LedgerEntry): void;
/** Stable hash for a worktree path — used by the (deferred) Layer 4 detector
 *  as the AttentionQueue dedupe key. Exposed here so detector code and tests
 *  cannot drift. */
export declare function worktreeDedupeKey(worktreePath: string): string;
//# sourceMappingURL=InstarWorktreeManager.d.ts.map