fleetd/bridged/src/main/java/dev/ltms/bridged/peer/PeerLauncher.java

package dev.ltms.bridged.peer;

import java.util.List;
import java.util.Set;

/**
 * SPI for materializing a connected peer — the only way the bridge core creates or tears down
 * a peer process. Every launcher is a first-party, in-tree adapter selected by (future) profile
 * config; today's single adapter is the {@code ClaudeCodeLauncher} / Claude Code over herdr.
 *
 * <p>The core delegates spawn and teardown to this interface without knowing how the peer is set
 * up. Environment variables, CLI flags, subscription guards, transport (herdr tab/pane) layout,
 * and naming conventions are all adapter-private — the core sees only the returned
 * {@link PeerHandle} whose {@code id()} is the registry/routing key.
 *
 * <p>The interface is a superset of what {@code SessionManager} and {@code Bridged.main} call
 * on the concrete launcher today.
 */
public interface PeerLauncher {

    /**
     * The set of {@link Capability capabilities} this launcher declares. A peer whose profile
     * opts into a git-forge token should include {@link Capability#SELF_PR}; the base set for
     * the Claude Code herdr adapter is always {@code MID_TURN_ASK, WORKTREE, ORPHAN_REAP}.
     */
    Set<Capability> capabilities();

    /**
     * {@code profileName}/requestedCwd null/blank → default resolution. Returns after the peer
     * process is live (env + argv + placement complete). Never returns {@code null}.
     *
     * @param req the spawn parameters (profile, requested cwd, caller cwd)
     * @return a handle whose {@link PeerHandle#id()} is the registry/routing key
     * @throws IllegalArgumentException if the profile is unknown and no default is configured
     */
    PeerHandle spawn(SpawnRequest req);

    /**
     * The configured worker profile names — the set of names {@code spawn(profileName)} accepts.
     */
    Set<String> profiles();

    /**
     * The profile a no-argument {@link #spawn(SpawnRequest)} uses, or {@code null} if none is configured.
     */
    String defaultProfile();

    /**
     * Resolve the effective working directory for a spawn {@code req} without actually spawning.
     * Resolution order: requestedCwd → profile cwd → callerCwd → daemon cwd.
     *
     * @return the resolved absolute path, never null/blank
     */
    String effectiveCwd(SpawnRequest req);

    /**
     * The parity-overlay file list for {@code profileName} (default list when unset). Used by
     * worktree provisioning to copy config files into the isolated checkout before spawning.
     */
    List<String> parityOverlay(String profileName);

    /**
     * The set of all agents this launcher currently tracks, transport-specific. Each element
     * exposes at minimum a pane-like {@code id()} matching this launcher's {@link PeerHandle}
     * scheme, plus transport-level status. Callers merge this set with the session registry to
     * build a live roster view.
     */
    List<?> list();

    /**
     * Reap orphaned peers left behind by a prior daemon process. Only peers whose naming scheme
     * matches this launcher's and whose nonce differs from the current process are eligible.
     * Best-effort: a failure to list or to stop any one peer is logged and never aborts startup.
     *
     * @return the number of orphaned peers reaped
     */
    int reapOrphanWorkers();

    /**
     * Tear a peer down by its registry/routing key ({@link PeerHandle#id()}). Tolerates an
     * already-gone peer. Also cleans up launcher-private resources (e.g. empty dedicated tabs)
     * when safe to do so.
     */
    void stop(String id);

    /**
     * Discard the context of the peer identified by {@code id}. Implementations must bypass normal
     * bridge delivery/turn accounting. Unsupported peer kinds return {@code false} without sending
     * a guessed command.
     *
     * @return {@code true} when a reset was sent and its status transition must settle before reuse
     */
    boolean clearContext(String id);
}