@h-rig/contracts 0.0.6-alpha.157 → 0.0.6-alpha.158

package/dist/src/isolation.d.ts

@@ -1,21 +1,213 @@
 /**
- * Pure isolation-backend contract id.
+ * Pure isolation-backend contract vocab.
  *
- * The neutral home for the capability id under which a runtime-isolation backend
- * plugin (e.g. @rig/isolation-plugin: worktree/sandbox provisioning) registers
- * its executable `IsolationBackend` factory. The dumb runtime substrate (the
- * task-runtime-start hook, the default-lifecycle isolation stage) resolves the
- * backend by this id from a plugin host built off the project's rig.config —
- * exactly the seam shape of {@link MEMORY_SERVICE_CAPABILITY_ID} and
- * RUNTIME_INSTRUCTION_SERVICE_CAPABILITY_ID. This module carries no behaviour and
- * imports nothing, so both the substrate and the plugin can reference the id
- * without a substrate->plugin import cycle.
+ * The neutral home for the runtime-isolation backend seam: the capability id, the
+ * `IsolationBackend` service interface, and its provisioning option/data types. A
+ * backend plugin (e.g. @rig/isolation-plugin: worktree/sandbox provisioning)
+ * registers its executable `IsolationBackend` factory under {@link ISOLATION_BACKEND}
+ * (string value {@link ISOLATION_BACKEND_CAPABILITY_ID}); the dumb runtime
+ * substrate (the task-runtime-start hook, the default-lifecycle isolation stage)
+ * resolves it by id from a plugin host built off the project's rig.config via the
+ * `defineCapability` seam — exactly the seam shape of {@link MEMORY} and the
+ * lifecycle capabilities. This module carries no behaviour and imports only pure
+ * contract types, so both the substrate and the plugin can reference it without a
+ * substrate->plugin import cycle.
  *
- * The service interface (`IsolationBackend`) and its option types live in the
- * runtime port module `@rig/runtime/control-plane/isolation-backend-port`,
- * because the provisioning options (AgentRuntime / TaskRecordReader) are
- * runtime-owned types — mirroring how `MemoryService` lives in the runtime port
- * module while only the pure data types live here.
+ * The provisioning data types (`AgentRuntime`, `IsolationMode`, `TaskRecordReader`)
+ * are pure data/structural shapes mirrored here so the option type is contracts-
+ * pure; the runtime re-exports them from its own modules for back-compat.
  */
+import type { CapabilityId } from "./capability-id";
+import type { TaskRecord } from "./task-source";
+import type { IsolationMode } from "./runtime";
 /** Capability id the isolation backend plugin registers its factory under. */
 export declare const ISOLATION_BACKEND_CAPABILITY_ID = "isolation.backend";
+/**
+ * A provisioned, isolated agent runtime: the resolved filesystem layout a backend
+ * hands back. Pure data (all paths/ids), so it lives in contracts as seam vocab;
+ * the runtime re-exports this from `runtime/isolation` for its internal callers.
+ */
+export type AgentRuntime = {
+    id: string;
+    taskId: string;
+    mode: IsolationMode;
+    rootDir: string;
+    workspaceDir: string;
+    homeDir: string;
+    tmpDir: string;
+    cacheDir: string;
+    logsDir: string;
+    stateDir: string;
+    sessionDir: string;
+    claudeHomeDir: string;
+    contextFile: string;
+    binDir: string;
+    createdAt: string;
+};
+/**
+ * The control surface over a running task-run snapshot sidecar. Pure data/handle
+ * type (no impl), so it lives in contracts as seam vocab; both the isolation
+ * plugin (which starts it) and the runtime substrate (agent-wrapper, which holds
+ * the handle) reference it from here without coupling to the impl.
+ */
+export type RuntimeSnapshotSidecar = {
+    cancel: () => Promise<void>;
+    finalize: (command: string[], exitCode: number) => Promise<void>;
+};
+/**
+ * The minimal read surface over task records the provisioner consumes. Structural
+ * contract (only depends on the pure {@link TaskRecord}); the runtime's concrete
+ * reader is assignable to this, mirroring how `MemoryCommandEventSink` keeps the
+ * memory contract free of any runtime/behaviour import.
+ */
+export interface TaskRecordReader {
+    listTasks(): Promise<readonly TaskRecord[]>;
+    getTask(id: string): Promise<TaskRecord | null>;
+}
+/** Options the substrate passes through to provision an isolated runtime. */
+export type EnsureAgentRuntimeOptions = {
+    projectRoot: string;
+    id: string;
+    taskId: string;
+    mode: IsolationMode;
+    provider?: "pi";
+    taskRecordReader?: TaskRecordReader;
+    preserveTaskArtifacts?: boolean;
+};
+/** Options to execute a command inside an already-provisioned agent runtime. */
+export type RunInAgentRuntimeOptions = {
+    projectRoot: string;
+    runtime: AgentRuntime;
+    command: string[];
+    inheritStdio?: boolean;
+};
+/**
+ * The pure filesystem-layout subset a sandbox wrap consumes. Structural data
+ * (all paths/ids), so it lives in contracts as seam vocab; agent-wrapper builds
+ * this from an {@link AgentRuntime} and the backend's wrap impl consumes it. The
+ * provisioned runtime is always `worktree`, but `mode` is the wider
+ * {@link IsolationMode} here so the seam stays assignable from `AgentRuntime`.
+ */
+export type SandboxRuntimeDescriptor = {
+    id: string;
+    mode: IsolationMode;
+    rootDir: string;
+    workspaceDir: string;
+    homeDir: string;
+    tmpDir: string;
+    cacheDir: string;
+    stateDir: string;
+    sessionDir: string;
+    claudeHomeDir: string;
+    binDir: string;
+};
+/** Options the substrate passes to wrap a provider command for sandboxed launch. */
+export type WrapRuntimeSandboxOptions = {
+    projectRoot: string;
+    runtime: SandboxRuntimeDescriptor;
+    command: string[];
+};
+/**
+ * The plan a sandbox-wrap returns: the (possibly rewritten) command plus the
+ * resolved backend metadata. `backend` is an open string union (none/seatbelt/
+ * bwrap/docker/…) kept as `string` so contracts carry no impl-coupled literals.
+ */
+export type RuntimeSandboxPlan = {
+    command: string[];
+    enabled: boolean;
+    backend: string;
+    profilePath?: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+};
+/** Result of executing a command inside an isolated agent runtime. */
+export type RunInAgentRuntimeResult = {
+    exitCode: number;
+    stdout?: string;
+    stderr?: string;
+    sandboxBackend: string;
+    sandboxEnabled: boolean;
+};
+/**
+ * A deterministic fingerprint of the runtime image build inputs. Pure data,
+ * lives in contracts so both isolation-plugin (which computes it) and
+ * cli-surface-plugin (which reads image ops through the ISOLATION_BACKEND
+ * seam) can reference the type without a cross-plugin import.
+ */
+export type RuntimeImageFingerprint = {
+    platform: string;
+    bunVersion: string;
+    nodeVersion: string;
+    claudeVersion: string;
+    runtimeCodeHash: string;
+    policyHash: string;
+    pluginsHash: string;
+    lockfileHashes: Record<string, string>;
+};
+/**
+ * The cohesive isolation surface the runtime substrate depends on: provisioning
+ * (`ensureAgentRuntime`) plus the execution helpers (`runInAgentRuntime`,
+ * `runtimeEnv`, `startRuntimeSnapshotSidecar`) the substrate's queue/agent
+ * executor still invokes. A backend plugin provides a concrete impl (worktree,
+ * sandbox, container, …); the substrate only ever sees this port — it resolves the
+ * port off the plugin host and never imports the backend package, so there is no
+ * substrate->plugin cycle even though the impls now live in @rig/isolation-plugin.
+ */
+export interface IsolationBackend {
+    ensureAgentRuntime(options: EnsureAgentRuntimeOptions): Promise<AgentRuntime>;
+    runInAgentRuntime(options: RunInAgentRuntimeOptions): Promise<RunInAgentRuntimeResult>;
+    runtimeEnv(projectRoot: string, runtime: AgentRuntime): Promise<Record<string, string>>;
+    /**
+     * Enumerate the provisioned runtimes for a project root. Backend-specific
+     * (worktree dirs vs. containers vs. sandboxes), so it belongs on the port —
+     * the `rig agent` group and the host run-loader resolve it here rather than
+     * importing the backend impl.
+     */
+    listAgentRuntimes(projectRoot: string): Promise<AgentRuntime[]>;
+    /**
+     * Tear down a single provisioned runtime by id. Backend-specific cleanup
+     * (remove worktree / kill container), reached through the port.
+     */
+    cleanupAgentRuntime(options: {
+        projectRoot: string;
+        id: string;
+    }): Promise<void>;
+    /**
+     * Persist operator-forwarded secrets beside the runtime so a detached run
+     * process recovers them via {@link runtimeEnv}. Backend-specific because the
+     * secret location is part of the runtime's on-disk/instance layout.
+     */
+    persistRuntimeSecrets(runtimeRoot: string, env: Record<string, string>): void;
+    startRuntimeSnapshotSidecar(runtime: AgentRuntime, options?: {
+        instanceId?: string;
+    }): Promise<RuntimeSnapshotSidecar>;
+    /**
+     * Wrap a provider command for sandboxed launch (seatbelt/bwrap/none). The
+     * substrate's agent-wrapper resolves this through the port and spawns the
+     * returned `command` itself, so the sandbox impl stays plugin-owned.
+     */
+    wrapRuntimeSandbox(options: WrapRuntimeSandboxOptions): Promise<RuntimeSandboxPlan>;
+    /**
+     * Compute the deterministic fingerprint of this project's runtime image build
+     * inputs (Bun/Node/Claude versions, code hashes, policy hash, lockfile hashes).
+     * Exposed on the port so build-time CLI commands (e.g. `rig dist rebuild-agent`)
+     * resolve it through the seam instead of importing isolation-plugin impl directly.
+     */
+    computeRuntimeImageFingerprint(projectRoot: string): Promise<RuntimeImageFingerprint>;
+    /**
+     * Derive a short deterministic image id string from a fingerprint.
+     * Pure function; lives on the port alongside `computeRuntimeImageFingerprint`
+     * so callers only need the seam, not the impl.
+     */
+    computeRuntimeImageId(fp: RuntimeImageFingerprint): string;
+}
+/** The capability `run` shape the plugin registers: a (lazy) backend factory. */
+export type IsolationBackendCapabilityRun = () => IsolationBackend | Promise<IsolationBackend>;
+/**
+ * The typed capability id the isolation backend plugin provides and the substrate
+ * requires. Phantom-typed with {@link IsolationBackend} so
+ * `defineCapability(ISOLATION_BACKEND)` resolves to the backend with no cast
+ * leaking to callers. Its string value is {@link ISOLATION_BACKEND_CAPABILITY_ID},
+ * so it indexes the same host entry.
+ */
+export declare const ISOLATION_BACKEND: CapabilityId<IsolationBackend>;

package/dist/src/isolation.js

@@ -1,6 +1,13 @@
 // @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
 // packages/contracts/src/isolation.ts
 var ISOLATION_BACKEND_CAPABILITY_ID = "isolation.backend";
+var ISOLATION_BACKEND = makeCapabilityId(ISOLATION_BACKEND_CAPABILITY_ID);
 export {
-  ISOLATION_BACKEND_CAPABILITY_ID
+  ISOLATION_BACKEND_CAPABILITY_ID,
+  ISOLATION_BACKEND
 };

package/dist/src/kernel.d.ts

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import type { RigPlugin } from "./plugin";
+import type { CapabilityId } from "./capability-id";
 import { ResolvedPipeline, StageContext, StageDescriptor, StageMutation, StageResult, StageRunOutcome } from "./stage";
 export declare const CapabilityTag: Schema.Literals<readonly ["kernel", "journal", "stage-runner", "transport", "loader-policy"]>;
 export type CapabilityTag = typeof CapabilityTag.Type;
@@ -187,3 +188,13 @@ export interface BootResult {
     capabilityProviderIds: Readonly<Record<CapabilityTag, string>>;
 }
 export type StageExecutor = (ctx: StageContext) => Promise<StageResult> | StageResult;
+/**
+ * The placement-aware run transport capability id.
+ *
+ * @rig/transport-plugin provides this as a host-service capability (its impl
+ * wraps `createPlacementRunTransport`). @rig/run-exec resolves it via
+ * `loadCapabilityForRoot` and passes the result to `adopt()` — the SEAM-ONLY
+ * replacement for importing `createPlacementRunTransport` directly from
+ * @rig/transport-plugin impl (§6.4).
+ */
+export declare const PLACEMENT_RUN_TRANSPORT: CapabilityId<TransportCapability>;

package/dist/src/kernel.js

@@ -39,6 +39,11 @@ var ApprovalRequestId = makeEntityId("ApprovalRequestId");
 var CheckpointRef = makeEntityId("CheckpointRef");
 var RemoteEndpointId = makeEntityId("RemoteEndpointId");
 
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
 // packages/contracts/src/stage.ts
 import { Schema as Schema2 } from "effect";
 var StageKind = Schema2.Literals(["transform", "gate", "observe"]);
@@ -232,8 +237,10 @@ var JournalEvent = Schema3.Struct({
   at: IsoDateTime,
   payload: Schema3.Unknown
 });
+var PLACEMENT_RUN_TRANSPORT = makeCapabilityId("transport.placement-run");
 export {
   PipelineUnresolvable,
+  PLACEMENT_RUN_TRANSPORT,
   MissingCapability,
   KernelResolutionRecord,
   KernelReplacementGrant,

package/dist/src/layout.d.ts

@@ -0,0 +1,49 @@
+/** Directory name for a project's checked-in rig definition (`<root>/rig`). */
+export declare const RIG_DEFINITION_DIRNAME = "rig";
+/** Directory name for rig's per-project state (`<root>/.rig`). */
+export declare const RIG_STATE_DIRNAME = ".rig";
+/** Directory name for run artifacts (`<workspace>/artifacts`). */
+export declare const RIG_ARTIFACTS_DIRNAME = "artifacts";
+export type RigLayout = {
+    projectRoot: string;
+    monorepoRoot: string;
+    definitionRoot: string;
+    runtimeWorkspaceRoot: string;
+    stateRoot: string;
+    artifactsRoot: string;
+    configPath: string;
+    taskConfigPath: string;
+    policyDir: string;
+    policyFile: string;
+    pluginsDir: string;
+    hooksDir: string;
+    toolsDir: string;
+    templatesDir: string;
+    validationDir: string;
+    stateDir: string;
+    logsDir: string;
+    notificationsDir: string;
+    runtimeDir: string;
+    distDir: string;
+    binDir: string;
+    pluginBinDir: string;
+    keybindingsPath: string;
+    controlPlaneEventsFile: string;
+};
+export type RuntimeWorkspaceLayout = {
+    workspaceDir: string;
+    rigRoot: string;
+    stateDir: string;
+    logsDir: string;
+    artifactsRoot: string;
+    runtimeDir: string;
+    homeDir: string;
+    tmpDir: string;
+    cacheDir: string;
+    sessionDir: string;
+    binDir: string;
+    distDir: string;
+    pluginBinDir: string;
+    contextPath: string;
+    controlPlaneEventsFile: string;
+};

package/dist/src/layout.js

@@ -0,0 +1,10 @@
+// @bun
+// packages/contracts/src/layout.ts
+var RIG_DEFINITION_DIRNAME = "rig";
+var RIG_STATE_DIRNAME = ".rig";
+var RIG_ARTIFACTS_DIRNAME = "artifacts";
+export {
+  RIG_STATE_DIRNAME,
+  RIG_DEFINITION_DIRNAME,
+  RIG_ARTIFACTS_DIRNAME
+};

package/dist/src/lifecycle-capabilities.d.ts

@@ -8,16 +8,31 @@
  * `pluginHost.listExecutableCapabilities()`. These pure types are the shared
  * contract for that seam — they carry no behaviour and import nothing.
  */
+import type { CapabilityId } from "./capability-id";
+import type { JournalCapability } from "./kernel";
+import type { RigAutomationConfig, StrictPrGreptileApiOptions } from "./control-plane-types";
+import type { RunCloseoutPhase, RunCloseoutPhaseOutcome } from "./run-journal";
 /** Capability id the bundle registers its `taskVerify` orchestration under. */
 export declare const TASK_VERIFY_CAPABILITY_ID = "default-lifecycle.task-verify";
 /** Capability id the bundle registers the completion-verification gate under. */
 export declare const COMPLETION_VERIFICATION_CAPABILITY_ID = "default-lifecycle.completion-verification";
+/** Capability id the bundle registers its run-worker closeout driver under. */
+export declare const RUN_CLOSEOUT_CAPABILITY_ID = "default-lifecycle.run-closeout";
+/** Capability id the bundle registers its agent-facing git helper surface under. */
+export declare const LIFECYCLE_GIT_AGENT_CAPABILITY_ID = "default-lifecycle.git-agent";
 export interface TaskVerifyCapabilityInput {
     readonly projectRoot: string;
     readonly taskId?: string;
 }
 /** Resolves true when the task is approved, false when verification rejects. */
 export type TaskVerifyCapabilityRun = (input: TaskVerifyCapabilityInput) => Promise<boolean>;
+/**
+ * The typed capability id the bundle provides its task-verify run under, phantom-
+ * typed with {@link TaskVerifyCapabilityRun} so `defineCapability(TASK_VERIFY_CAPABILITY)`
+ * resolves to the run function with no cast leaking to callers. Its string value
+ * is {@link TASK_VERIFY_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const TASK_VERIFY_CAPABILITY: CapabilityId<TaskVerifyCapabilityRun>;
 export interface CompletionVerificationCapabilityInput {
     readonly projectRoot: string;
     readonly taskId?: string;
@@ -27,3 +42,87 @@ export interface CompletionVerificationCapabilityResult {
     readonly ok: boolean;
 }
 export type CompletionVerificationCapabilityRun = (input: CompletionVerificationCapabilityInput) => Promise<CompletionVerificationCapabilityResult>;
+/**
+ * The typed capability id the bundle provides its completion-verification gate
+ * under, phantom-typed with {@link CompletionVerificationCapabilityRun}. Its
+ * string value is {@link COMPLETION_VERIFICATION_CAPABILITY_ID}, so it indexes
+ * the same host entry.
+ */
+export declare const COMPLETION_VERIFICATION_CAPABILITY: CapabilityId<CompletionVerificationCapabilityRun>;
+export type LifecycleGitCommitOptions = {
+    projectRoot: string;
+    taskId?: string;
+    target: "monorepo" | "project" | "both";
+    message?: string;
+    allowEmpty: boolean;
+    scoped?: boolean;
+};
+export type LifecycleGitOpenPrOptions = {
+    projectRoot: string;
+    taskId?: string;
+    target?: "monorepo" | "project";
+    reviewer?: string;
+    base?: string;
+    title?: string;
+    body?: string;
+    draft?: boolean;
+};
+export type LifecycleGitOpenPrResult = {
+    url: string;
+    reviewer?: string;
+    reviewerSource?: "flag" | "task-config" | "changed-files" | "env";
+    target: "monorepo" | "project";
+    repoLabel: string;
+    branch: string;
+    base: string;
+};
+export type LifecycleGitAgentService = {
+    shouldScopeGitCommit(args: string[], hasTaskContext: boolean): boolean;
+    gitStatus(projectRoot: string, taskId?: string): void;
+    gitChanged(projectRoot: string, taskId: string | undefined, scoped: boolean): string[];
+    gitPreflight(projectRoot: string, taskId: string | undefined, strict: boolean): boolean;
+    gitSyncBranch(projectRoot: string, taskId?: string, targetRepo?: "monorepo" | "project"): void;
+    gitCommit(options: LifecycleGitCommitOptions): void;
+    gitSnapshot(projectRoot: string, taskId?: string, outputPath?: string): string;
+    gitOpenPr(options: LifecycleGitOpenPrOptions): LifecycleGitOpenPrResult;
+};
+export declare const LIFECYCLE_GIT_AGENT: CapabilityId<LifecycleGitAgentService>;
+export type RunTaskSourceReflectStatus = "under_review" | "ci_fixing" | "merging" | "closed" | "needs_attention";
+export type RunCloseoutResultStatus = "merged" | "opened" | "skipped" | "needs-attention";
+export type RunCloseoutResult = {
+    status: RunCloseoutResultStatus;
+    prUrl?: string;
+    iterations: number;
+    feedback: readonly string[];
+};
+export type RunCloseoutValidationInput = {
+    projectRoot: string;
+    taskId: string;
+};
+export type RunCloseoutValidationRunner = (input: RunCloseoutValidationInput) => Promise<boolean> | boolean;
+export type RunCloseoutInput = {
+    projectRoot: string;
+    runId: string;
+    taskId: string;
+    branch: string;
+    workspace: string;
+    artifactRoot?: string | null;
+    config?: RigAutomationConfig | null;
+    sourceTask?: Record<string, unknown> | null;
+    steerPi: (message: string) => Promise<void>;
+    greptileApi?: StrictPrGreptileApiOptions;
+    runValidation?: RunCloseoutValidationRunner;
+    onValidationStart?: () => Promise<void> | void;
+    kernelJournal?: JournalCapability | null;
+    journalPhase: (phase: RunCloseoutPhase, outcome: RunCloseoutPhaseOutcome, detail?: string | null) => Promise<void> | void;
+    reflect: (status: RunTaskSourceReflectStatus, summary: string, options?: {
+        errorText?: string | null;
+    }) => Promise<void> | void;
+};
+export type RunCloseoutCapabilityRun = (input: RunCloseoutInput) => Promise<RunCloseoutResult>;
+/**
+ * The typed capability id the bundle provides its run-worker closeout driver
+ * under, so @rig/run-worker can close out by resolving the lifecycle capability
+ * instead of importing the lifecycle plugin implementation.
+ */
+export declare const RUN_CLOSEOUT_CAPABILITY: CapabilityId<RunCloseoutCapabilityRun>;

package/dist/src/lifecycle-capabilities.js

@@ -1,8 +1,25 @@
 // @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
 // packages/contracts/src/lifecycle-capabilities.ts
 var TASK_VERIFY_CAPABILITY_ID = "default-lifecycle.task-verify";
 var COMPLETION_VERIFICATION_CAPABILITY_ID = "default-lifecycle.completion-verification";
+var RUN_CLOSEOUT_CAPABILITY_ID = "default-lifecycle.run-closeout";
+var LIFECYCLE_GIT_AGENT_CAPABILITY_ID = "default-lifecycle.git-agent";
+var TASK_VERIFY_CAPABILITY = makeCapabilityId(TASK_VERIFY_CAPABILITY_ID);
+var COMPLETION_VERIFICATION_CAPABILITY = makeCapabilityId(COMPLETION_VERIFICATION_CAPABILITY_ID);
+var LIFECYCLE_GIT_AGENT = makeCapabilityId(LIFECYCLE_GIT_AGENT_CAPABILITY_ID);
+var RUN_CLOSEOUT_CAPABILITY = makeCapabilityId(RUN_CLOSEOUT_CAPABILITY_ID);
 export {
   TASK_VERIFY_CAPABILITY_ID,
-  COMPLETION_VERIFICATION_CAPABILITY_ID
+  TASK_VERIFY_CAPABILITY,
+  RUN_CLOSEOUT_CAPABILITY_ID,
+  RUN_CLOSEOUT_CAPABILITY,
+  LIFECYCLE_GIT_AGENT_CAPABILITY_ID,
+  LIFECYCLE_GIT_AGENT,
+  COMPLETION_VERIFICATION_CAPABILITY_ID,
+  COMPLETION_VERIFICATION_CAPABILITY
 };

package/dist/src/managed-repos.d.ts

@@ -1,23 +1,17 @@
 /**
- * Pure managed-repo contract types + the managed-repo service capability id.
+ * Pure managed-repo and repo-operation contract types + capability ids.
  *
- * The neutral home for the managed-repo (registry / layout / mirror) domain.
- * The implementation lives in `@rig/repos-plugin`, which registers an
- * executable `ManagedRepoService` factory under {@link MANAGED_REPO_SERVICE_CAPABILITY_ID}
- * on `contributes.capabilities[].run`. The dumb runtime substrate (plugin-host
- * boot wiring, the pre-run monorepo sync, native repo-ops pin recording, and the
- * state-sync tracker-path resolver) resolves the service by this id from a
- * plugin host built off the project's rig.config — exactly the seam shape of
- * {@link MEMORY_SERVICE_CAPABILITY_ID} / ISOLATION_BACKEND_CAPABILITY_ID. This
- * module carries no behaviour and imports only pure sibling types, so both the
- * substrate and the plugin can reference these without a substrate->plugin
- * import cycle.
+ * `@rig/repos-plugin` owns the concrete implementations. It contributes:
+ * - `ManagedRepoService` under {@link MANAGED_REPO_SERVICE_CAPABILITY_ID} for
+ *   registry/layout/mirror state, and
+ * - `RepoOperationsService` under {@link REPO_OPERATIONS_CAPABILITY_ID} for
+ *   task repo pinning, baseline reset, and project-main pre-run sync.
  *
- * The service interface (`ManagedRepoService`) itself lives in the runtime port
- * module `@rig/runtime/control-plane/managed-repo-service-port`, mirroring how
- * `MemoryService` lives in the runtime port while only the pure data types live
- * here.
+ * This module carries no behaviour and imports only pure sibling types, so
+ * consumers resolve typed ids through `@rig/core` without importing the provider
+ * plugin or the old kernel repo-ops facades.
  */
+import type { CapabilityId } from "./capability-id";
 import type { RepoSourceRegistration } from "./plugin";
 export type ManagedRepoId = string;
 export type ManagedRepoAlias = string;
@@ -69,5 +63,74 @@ export interface RepoRegistry {
     getById(id: string): RepoEntry | undefined;
     list(): readonly RepoEntry[];
 }
+/**
+ * The cohesive set of managed-repo operations the runtime substrate depends on.
+ * The plugin provides a concrete impl (statically checked against this interface
+ * via `defineCapability(MANAGED_REPO_SERVICE_CAPABILITY).provide`); the substrate
+ * only ever sees this port, resolved by id off a plugin host with no cast.
+ */
+export interface ManagedRepoService {
+    /** Replace the managed-repo singleton with the given entries (boot wiring). */
+    setManagedRepos(entries: readonly ManagedRepoRegistryEntry[]): void;
+    /** List the currently registered managed-repo entries. */
+    listManagedRepoEntries(): ManagedRepoRegistryEntry[];
+    /** Resolve a managed-repo id from its alias, or null when unknown. */
+    resolveManagedRepoIdByAlias(alias: string): ManagedRepoId | null;
+    /**
+     * Convert a plugin-contributed RepoSourceRegistration into the managed-repo
+     * entry shape; null for pure-listing registrations (no defaultBranch).
+     */
+    repoRegistrationToManagedEntry(reg: RepoSourceRegistration): ManagedRepoRegistryEntry | null;
+    /** Build an immutable id-indexed registry from repo source registrations. */
+    createRepoRegistry(entries: readonly RepoSourceRegistration[]): RepoRegistry;
+    /** Resolve a managed repo's on-disk layout by alias, or null when unknown. */
+    resolveManagedRepoLayoutByAlias(projectRoot: string, alias: string): ManagedRepoLayout | null;
+    /** Resolve the primary monorepo layout; throws when no managed repos exist. */
+    resolveMonorepoRepoLayout(projectRoot: string): ManagedRepoLayout;
+    /** Refresh + sync a managed repo's mirror, returning the resulting head. */
+    syncManagedRepo(projectRoot: string, repoId: ManagedRepoId): ManagedRepoSyncResult;
+}
+export type RepoPins = Record<string, string>;
+export type ProjectMainPreRunSyncResult = {
+    status: "disabled";
+} | {
+    status: "skipped_not_main";
+    branch: string;
+} | {
+    status: "up_to_date";
+} | {
+    status: "local_ahead";
+    localAhead: number;
+} | {
+    status: "updated";
+    remoteAhead: number;
+};
+export type ProjectMainPreRunSyncOptions = {
+    projectRoot: string;
+    disabled?: boolean;
+    runBootstrap: () => Promise<void>;
+    syncMonorepo?: (projectRoot: string) => void | Promise<void>;
+};
+export interface RepoOperationsService {
+    repoEnsure(projectRoot: string, taskId?: string): void;
+    repoPins(projectRoot: string, taskId?: string): RepoPins;
+    repoVerify(projectRoot: string, taskId?: string): boolean;
+    repoDiscover(projectRoot: string, taskId?: string): RepoPins;
+    repoBaseline(projectRoot: string, refresh?: boolean): RepoPins;
+    resetBaseline(projectRoot: string, keepTaskStatus: boolean): void;
+    ensureProjectMainFreshBeforeRun(options: ProjectMainPreRunSyncOptions): Promise<ProjectMainPreRunSyncResult>;
+}
+export declare const REPO_OPERATIONS_CAPABILITY_ID = "repos.operations";
+export declare const REPO_OPERATIONS_CAPABILITY: CapabilityId<RepoOperationsService>;
+/** The capability `run` shape the plugin registers: a (lazy) service factory. */
+export type ManagedRepoServiceCapabilityRun = () => ManagedRepoService | Promise<ManagedRepoService>;
 /** Capability id the managed-repo service plugin registers its factory under. */
 export declare const MANAGED_REPO_SERVICE_CAPABILITY_ID = "managed-repos.service";
+/**
+ * The typed capability id the repos plugin provides and consumers require.
+ * Phantom-typed with {@link ManagedRepoService} so
+ * `defineCapability(MANAGED_REPO_SERVICE_CAPABILITY).resolve(host)` returns a
+ * `ManagedRepoService` with no cast leaking to callers. Its string value is
+ * {@link MANAGED_REPO_SERVICE_CAPABILITY_ID}, so it indexes the same host entry.
+ */
+export declare const MANAGED_REPO_SERVICE_CAPABILITY: CapabilityId<ManagedRepoService>;

package/dist/src/managed-repos.js

@@ -1,6 +1,17 @@
 // @bun
+// packages/contracts/src/capability-id.ts
+function makeCapabilityId(id) {
+  return id;
+}
+
 // packages/contracts/src/managed-repos.ts
+var REPO_OPERATIONS_CAPABILITY_ID = "repos.operations";
+var REPO_OPERATIONS_CAPABILITY = makeCapabilityId(REPO_OPERATIONS_CAPABILITY_ID);
 var MANAGED_REPO_SERVICE_CAPABILITY_ID = "managed-repos.service";
+var MANAGED_REPO_SERVICE_CAPABILITY = makeCapabilityId(MANAGED_REPO_SERVICE_CAPABILITY_ID);
 export {
-  MANAGED_REPO_SERVICE_CAPABILITY_ID
+  REPO_OPERATIONS_CAPABILITY_ID,
+  REPO_OPERATIONS_CAPABILITY,
+  MANAGED_REPO_SERVICE_CAPABILITY_ID,
+  MANAGED_REPO_SERVICE_CAPABILITY
 };