@serviceme/devtools-core 1.0.0 → 2.0.0

package/dist/index.d.ts

@@ -4,8 +4,8 @@ import * as fs from 'node:fs/promises';
 export { A as AccessCheckResult, a as AccessControl, b as AccessControlOptions, c as AuthCore, d as AuthCoreOptions, e as AuthStateManager, f as AuthStateManagerOptions, C as CancellationCheck, D as DeviceFlowUiCallback, G as GitHubAuthProvider, g as GitHubAuthProviderConfig, I as IAuthProvider, h as IAuthProviderSession, i as IAuthProviderUserInfo, j as InMemoryKeychainAuthTokenStore, K as KeyValueStore, k as KeychainAccountKey, l as KeychainAuthTokenStore, m as KeychainTokenEnvelope, n as KeychainTokenMetadata, o as KeychainUnavailableError, M as MicrosoftAuthProvider, p as MicrosoftProviderNotHostedError, O as OrgMembershipFetcher, P as ProviderRegistry, S as ServiceMeLogger, q as buildGitHubLocalEmail, r as createConsoleLogger, s as isGitHubLocalEmail, t as noopLogger, u as resolvePrimaryEmail } from './index-PD135hlB.js';
 export { AtomicWriteResult, BuildSignedHeadersParams, DEVICE_JSON_SCHEMA_VERSION, DeviceAuthHeaders, DeviceCore, DeviceCoreOptions, DeviceReenrollRequiresAuthError, DeviceRequestSignatureParams, DeviceSecretVersionMismatchError, DeviceSignedHeaders, EnrollRequestFn, EnrollResponse, Enroller, EnrollerOptions, FsIdentityFileBackend, IdentityFileBackend, IdentityStore, IdentityStoreHooks, IdentityStoreOptions, PersistedDeviceIdentity, buildSignedHeaders, createDeviceRequestSignature, deriveInstallationId, fingerprintSource, randomInstallationId } from './device.js';
 import { c as SkillKind, b as SkillFile } from './types-B9gk3dXH.js';
-import { G as GitClient, P as PullResult } from './index-CR1hbAnO.js';
-export { a as GIT_PROXY_PATH_SUFFIX, b as GitError, N as NodeGitSpawner, S as StubGitSpawner, c as SubmitClient, d as SubmitClientOptions, e as SubmitError, f as SubmitOptions, g as SubmitResult, h as buildGitProxyBase, t as toFileUrl } from './index-CR1hbAnO.js';
+import { G as GitClient, P as PullResult } from './index-CymN0x9Z.js';
+export { a as GIT_PROXY_PATH_SUFFIX, b as GitError, N as NodeGitSpawner, S as StubGitSpawner, c as SubmitClient, d as SubmitClientOptions, e as SubmitError, f as SubmitOptions, g as SubmitResult, h as buildGitProxyBase, t as toFileUrl } from './index-CymN0x9Z.js';
 import * as fs$1 from 'node:fs';
 import { z } from 'zod';
 export { BUILTIN_DEFAULT_TOOLS, DefaultToolImmutableError, DefaultToolSeed, FsToolboxFileBackend, PersistedToolbox, ResolvedToolbox, TOOLBOX_JSON_SCHEMA_VERSION, ToolboxCore, ToolboxCoreOptions, ToolboxFileBackend, ToolboxPatch, ToolboxStore, ToolboxStoreHooks, ToolboxStoreOptions, WORKSPACE_TOOLBOX_RELATIVE_PATH, mergeWithDefaults, reindexOrder, sortByRecentFirst, sortByUserOrder, touchLastUsedAt } from './toolbox.js';
@@ -113,6 +113,32 @@ declare class AgentStore {
     writeAgentFiles(agentId: string, scope: "workspace" | "user", files: AgentDownloadFile[]): Promise<void>;
     private listAgentIds;
 }
+/** One legacy content entry reported by {@link migrateLegacyUserContent}. */
+interface LegacyUserContentEntry {
+    /** Legacy agent id derived from the file or directory name. */
+    id: string;
+    /** Absolute path of the legacy content under ~/.agents. */
+    legacyPath: string;
+    /** Target path under ~/.copilot the migration would create. */
+    targetPath: string;
+    /** Always `migration_available` until the user runs the migration. */
+    status: "migration_available";
+}
+interface LegacyUserContentMigrationResult {
+    entries: LegacyUserContentEntry[];
+}
+/**
+ * Detect ~/.agents agent content that can migrate to ~/.copilot.
+ *
+ * Read-only by design: legacy content stays untouched until the user
+ * explicitly invokes the migration, so a detection pass never destroys
+ * anything another tool still depends on.
+ */
+declare function migrateLegacyUserContent(input: {
+    homeDir: string;
+    workspaceDir: string;
+    fileSystem?: AgentStoreFileSystem;
+}): Promise<LegacyUserContentMigrationResult>;
 
 /**
  * Quick auth pre-flight check using `gh auth status`.
@@ -125,6 +151,1104 @@ declare function createCopilotAuthRequiredError(): _serviceme_devtools_protocol.
 
 declare function copilotPrompt(options: CopilotPromptOptions): Promise<CopilotPromptResult>;
 
+/**
+ * Contracts for the declarative Copilot content lifecycle.
+ *
+ * Three layers (see docs/architecture/copilot-content-reconciliation.md):
+ *   1. content sources under ~/.serviceme/repos/<repo-id>
+ *   2. a shared, git-tracked workspace declaration
+ *   3. machine-local materialization state under ~/.serviceme/workspaces
+ */
+/** Artifact kinds a logical plugin can contribute to Copilot. */
+type CopilotArtifactKind = "agent" | "skill" | "instruction" | "prompt" | "hook" | "mcp";
+/** A repository pinned to an exact commit for reproducible restoration. */
+interface WorkspaceManifestRepository {
+    /** Stable id used in on-disk paths and plugin references. */
+    id: string;
+    /** Authoritative cross-machine source identity (HTTPS or git@ URL). */
+    url: string;
+    /** Full 40-character commit SHA; branch names are not allowed. */
+    commit: string;
+}
+/** A Git source in the v2 manifest syntax. */
+interface WorkspaceManifestGitSource extends WorkspaceManifestRepository {
+    type: "git";
+}
+/** An immutable marketplace artifact materialized under ~/.serviceme/repos/<id>. */
+interface WorkspaceManifestCatalogSource {
+    type: "catalog";
+    /** Stable local repository id used for the managed source directory. */
+    id: string;
+    /** Marketplace identity, independent of any transient download URL. */
+    catalogId: string;
+    /** Immutable catalog release selected by the workspace. */
+    revision: string;
+    /** SHA-256 of the complete catalog payload, prefixed with sha256:. */
+    digest: string;
+}
+/** A source that can be restored on each collaborator's machine. */
+type WorkspaceManifestSource = WorkspaceManifestGitSource | WorkspaceManifestCatalogSource;
+/** A logical plugin selection inside the workspace declaration. */
+interface WorkspaceManifestPlugin {
+    /** Referenced repository id. */
+    repository: string;
+    /** Logical plugin id from plugin.json, or the legacy skill/agent name. */
+    id: string;
+    /** Legacy artifact-kind selection, retained for compatible workspace declarations. */
+    artifacts: Partial<Record<CopilotArtifactKind, boolean>>;
+    /** Exact resolver artifact identities selected for this package. */
+    artifactIds?: string[];
+}
+/** A v2 logical plugin selection references any supported source type. */
+interface WorkspaceManifestPluginV2 {
+    /** Referenced source id. */
+    source: string;
+    /** Logical plugin id from plugin.json, or the legacy skill/agent name. */
+    id: string;
+    /** Legacy artifact-kind selection, retained for compatible workspace declarations. */
+    artifacts: Partial<Record<CopilotArtifactKind, boolean>>;
+    /** Exact resolver artifact identities selected for this package. */
+    artifactIds?: string[];
+}
+/** Root shape of .github/serviceme-plugins.json. */
+interface WorkspaceCopilotManifestV1 {
+    version: 1;
+    repositories: WorkspaceManifestRepository[];
+    plugins: WorkspaceManifestPlugin[];
+}
+/** Root v2 shape: sources may be Git checkouts or immutable catalog artifacts. */
+interface WorkspaceCopilotManifestV2 {
+    version: 2;
+    sources: WorkspaceManifestSource[];
+    plugins: WorkspaceManifestPluginV2[];
+}
+/** Root shape of .github/serviceme-plugins.json. */
+type WorkspaceCopilotManifest = WorkspaceCopilotManifestV1 | WorkspaceCopilotManifestV2;
+/** Normalize the versioned source list for consumers that do not care about syntax. */
+declare function getWorkspaceManifestSources(manifest: WorkspaceCopilotManifest): WorkspaceManifestSource[];
+/** Resolve a versioned plugin selection to its source id. */
+declare function getWorkspaceManifestPluginSourceId(manifest: WorkspaceCopilotManifest, plugin: WorkspaceManifestPlugin | WorkspaceManifestPluginV2): string;
+/** Materialization mode used when activating an entry on the current machine. */
+type CopilotLinkMode = "symlink" | "junction" | "generated";
+/** One materialized entry recorded in machine-local state. */
+interface WorkspaceMaterializedEntry {
+    /** Stable identity: repository::plugin::kind[:name]. */
+    identity: string;
+    /** Owning repository id. */
+    repositoryId: string;
+    /** Owning logical plugin id. */
+    pluginId: string;
+    /** Artifact kind of this entry. */
+    kind: CopilotArtifactKind;
+    /** Absolute source path under ~/.serviceme/repos. */
+    sourcePath: string;
+    /** Workspace-relative link path. */
+    linkPath: string;
+    /** Link mode used on this machine. */
+    linkMode: CopilotLinkMode;
+    /** SHA-256 digest of the pinned source content. */
+    digest: string;
+    /** Whether the current machine approved risky content. */
+    approved: boolean;
+}
+/** Machine-local materialization state; never shared through git. */
+interface WorkspaceContentState {
+    version: 1;
+    entries: WorkspaceMaterializedEntry[];
+}
+
+/** One immutable materialization step in a resolved content plan. */
+interface PlannedContentEntry {
+    /** Stable identity: repository::plugin::kind[:name]. */
+    identity: string;
+    /** Owning repository id. */
+    repositoryId: string;
+    /** Owning logical plugin id. */
+    pluginId: string;
+    /** Artifact kind of this entry. */
+    kind: CopilotArtifactKind;
+    /** Absolute source path under the repository root. */
+    sourcePath: string;
+    /** Whether the source is a single file (agent/instruction) or a directory (skill). */
+    sourceIsFile: boolean;
+    /** Copilot-facing name used at the link target. */
+    name: string;
+    /** SHA-256 digest over the source content. */
+    digest: string;
+    /** Whether local approval is required before activation. */
+    requiresApproval: boolean;
+}
+/** Result of resolving a workspace declaration against local repositories. */
+interface WorkspaceContentPlan {
+    entries: PlannedContentEntry[];
+}
+
+interface ResolvedPluginManifest {
+    name: string;
+    description?: string;
+    version?: string;
+    extensions: Record<string, Record<string, unknown>>;
+}
+interface ResolvedPluginEntry extends PlannedContentEntry {
+    /** Stable artifact identifier for consumers that do not need to parse identity. */
+    artifactId: string;
+    /** Stable package identifier for the logical repository/plugin pair. */
+    packageId: string;
+    /** Display metadata for the logical package. */
+    packageDisplayName: string;
+    packageDescription?: string;
+    packageVersion?: string;
+}
+/** Resolve a workspace declaration into an immutable content plan. */
+declare function resolveWorkspaceContentPlan(input: {
+    manifest: WorkspaceCopilotManifest;
+    reposDir: string;
+}): Promise<{
+    entries: ResolvedPluginEntry[];
+}>;
+/**
+ * Lenient variant for CATALOG BROWSING: resolve a single plugin's
+ * declared artifacts, skipping paths that are missing or
+ * unverifiable instead of throwing. Upstream plugin.json files in
+ * the wild carry typos (e.g. declaring `./agents/x.md` for a file
+ * that ships as `x.agent.md`); a strict throw hides the whole
+ * package from browse — while installs still go through the strict
+ * pipeline, so a listing here never guarantees a broken install.
+ *
+ * Only skills/agents/prompts/instructions path arrays are probed
+ * here; mcp.json/hooks stay install-pipeline-only (they materialize
+ * shared config and MUST pass the strict gate).
+ */
+declare function resolvePluginEntriesLenient(input: {
+    repoRoot: string;
+    repositoryId: string;
+    pluginId: string;
+    manifest: ResolvedPluginManifest;
+}): Promise<ResolvedPluginEntry[]>;
+
+/** Personal artifact kinds materialized as managed links into host target directories. */
+declare const allPersonalLinkKinds: readonly ["agent", "skill", "prompt", "instruction"];
+/** One personal link kind. */
+type PersonalLinkKind = (typeof allPersonalLinkKinds)[number];
+/**
+ * Adapter that applies or removes one personal integration entry (mcp/hook)
+ * in host-owned user configuration. Implementations own their config format;
+ * callers own the digest approval rule.
+ */
+interface CopilotIntegrationAdapter {
+    /** Apply one approved integration entry on this machine. */
+    applyEntry(input: {
+        entry: ResolvedPluginEntry;
+    }): Promise<void>;
+    /** Remove a previously applied entry; returns whether anything was removed. */
+    removeEntry(input: {
+        identity: string;
+    }): Promise<boolean>;
+}
+/** Host-verified personal materialization targets and integration adapters. */
+interface CopilotHostCapabilities {
+    /** Absolute, host-verified target directory per personal link kind. */
+    personalTargets: Partial<Record<PersonalLinkKind, string>>;
+    /** Adapter for personal MCP configuration, when the host supports one. */
+    mcpAdapter?: CopilotIntegrationAdapter;
+    /** Adapter for personal hook registration, when the host supports one. */
+    hookAdapter?: CopilotIntegrationAdapter;
+}
+/** Whether the host verified a personal target directory for the kind. */
+declare function supportsPersonalLinkKind(capabilities: CopilotHostCapabilities, kind: PersonalLinkKind): boolean;
+/** Whether the host provides the adapter an integration kind requires. */
+declare function supportsPersonalIntegrationKind(capabilities: CopilotHostCapabilities, kind: "mcp" | "hook"): boolean;
+/**
+ * Conservative production capability provider.
+ *
+ * Only claims targets it can actually verify on this host: the canonical
+ * home '.copilot/agents' and '.copilot/skills' directories when they already
+ * exist. Prompt, instruction, MCP, and hook personal targets stay unclaimed
+ * until a verified provider wires them (Task 9); the reconciler reports those
+ * kinds as unsupported instead of inventing directories.
+ */
+declare function createDefaultCopilotHostCapabilities(options?: {
+    copilotHomeDir?: string;
+}): Promise<CopilotHostCapabilities>;
+
+/** Status of one entry after a reconcile pass. */
+type MaterializeEntryStatus = "restored" | "adopted" | "conflict" | "drifted" | "pending_approval";
+interface MaterializeEntryResult {
+    identity: string;
+    status: MaterializeEntryStatus;
+    /** Secondary machine-local state, e.g. migration_available for legacy links. */
+    message?: string;
+}
+interface MaterializeResult {
+    changed: boolean;
+    entries: MaterializeEntryResult[];
+    /** Updated machine-local state (only successfully materialized entries). */
+    state: WorkspaceContentState;
+}
+/** Create and inspect Copilot links; never overwrite unowned content. */
+declare class CopilotLinkMaterializer {
+    private pendingFailure;
+    /** Test seam: make the next reconcile throw, then clear the failure. */
+    failNext(error: Error): void;
+    /** Materialize planned entries with conflict/drift safety. */
+    reconcile(input: {
+        workspaceDir: string;
+        entries: PlannedContentEntry[];
+        previousState: WorkspaceContentState;
+    }): Promise<MaterializeResult>;
+    /** Adopt a matching legacy link without recreating it. */
+    adoptLegacyLink(input: {
+        workspaceDir: string;
+        entry: PlannedContentEntry;
+    }): Promise<MaterializeEntryResult>;
+    /** Inspect a legacy ~/.agents link; report without deleting. */
+    inspectLegacyUserLink(input: {
+        homeDir: string;
+        entry: PlannedContentEntry;
+    }): Promise<MaterializeEntryResult>;
+    private resolveLinkPath;
+    private createLinkAtomic;
+    private toStateEntry;
+    private toStateLinkPath;
+}
+
+/**
+ * Copilot plugin whole-package registration.
+ *
+ * Installs a plugin.json package by projecting its canonical checkout
+ * into SERVICEME's own registry location
+ * (`~/.serviceme/copilot-plugins/<repoId>:<pluginId>`), enabled through
+ * a path-keyed `chat.pluginLocations` entry (extension-owned).
+ *
+ * The projection is MATERIALIZED (see plugin-materializer.ts): a real
+ * directory whose entries symlink the resolved checkout content and
+ * whose layout matches what VS Code loads (content under the
+ * `com.github.copilot/` namespace, manifest at the root and under
+ * `.plugin/`).
+ *
+ * LOCATION HISTORY — everything under `~/.copilot` turned out to be VS
+ * Code territory whose reconciliation/uninstall flows DELETE
+ * hand-written projections (verified on-machine for both
+ * `installed-plugins/` and `serviceme-plugins/`). The registry therefore
+ * lives under the SERVICEME home, which VS Code never touches, and the
+ * constructor migrates surviving records/projections from the legacy
+ * locations.
+ *
+ * Scope note: plugin packages are PERSONAL-scope only — the
+ * projection is user-level and identical for every caller. The
+ * `scopes` record shape stays for compatibility; an omitted scope
+ * registers as personal.
+ *
+ * `chat.pluginLocations` (VS Code user settings) is intentionally
+ * NOT handled here — it can only be written by the extension layer.
+ */
+interface CopilotPluginRegistrarOptions {
+    /** Projection root. Defaults to `${SERVICEME_HOME}/copilot-plugins`. */
+    pluginsDir?: string;
+    /** `~/.copilot` — migration source only (VS Code owns that tree). */
+    copilotDir?: string;
+}
+interface CopilotPluginRegisterInput {
+    repoId: string;
+    pluginId: string;
+    /** Canonical checkout plugin directory (the whole package root). */
+    pluginDir: string;
+    /** @deprecated Projection root comes from the constructor; ignored. */
+    copilotDir?: string;
+    scope?: "workspace" | "personal";
+    displayName?: string;
+    version?: string;
+}
+interface CopilotPluginRegistration {
+    /** `${repoId}:${pluginId}` — path-safe. */
+    registrationId: string;
+    repoId: string;
+    pluginId: string;
+    pluginDir: string;
+    displayName?: string;
+    version?: string;
+    scopes: Array<"workspace" | "personal">;
+}
+declare class CopilotPluginRegistrar {
+    private readonly pluginsDir;
+    private readonly copilotDir;
+    private migrated;
+    constructor(options?: CopilotPluginRegistrarOptions);
+    /** Registry root — resolved, used as the boundary for all path joins. */
+    private installedDir;
+    /** Projection path for an id, with an explicit containment check. */
+    private linkPath;
+    private registryPath;
+    /**
+     * One-shot migration away from `~/.copilot` (VS Code territory):
+     * carries over registry records and surviving projections from both
+     * legacy layouts and removes the old trees. Self-guarding when the
+     * source and destination coincide; safe to run repeatedly.
+     */
+    private migrateFromCopilotDir;
+    private readRegistry;
+    private writeRegistry;
+    register(input: CopilotPluginRegisterInput): Promise<CopilotPluginRegistration>;
+    unregister(input: {
+        registrationId: string;
+        /** @deprecated Projection root comes from the constructor; ignored. */
+        copilotDir?: string;
+        scope?: "workspace" | "personal";
+    }): Promise<void>;
+    list(_input?: {
+        copilotDir?: string;
+    }): Promise<CopilotPluginRegistration[]>;
+}
+
+type CopilotScope = "workspace" | "personal";
+type CopilotInstallIntent = "available" | "selected" | "moving" | "removing";
+type CopilotMaterializationHealth = "healthy" | "missing" | "drifted" | "conflict" | "source-unavailable" | "unsupported";
+type CopilotLocalGate = "ready" | "approval-required" | "configuration-required";
+type CopilotUserStatus = "healthy" | "action-required" | "blocked" | "not-enabled";
+interface CopilotArtifactState {
+    intent: CopilotInstallIntent;
+    health: CopilotMaterializationHealth;
+    gate: CopilotLocalGate;
+}
+interface CopilotPackageInstallation {
+    packageId: string;
+    scope: CopilotScope;
+    selectedArtifactIds: string[];
+    pinnedVersion?: string;
+}
+interface CopilotArtifactSummary {
+    id: string;
+    packageId: string;
+    kind: CopilotArtifactKind;
+    displayName: string;
+    description?: string;
+    installStrategy: "link" | "generated-config" | "approval-gated";
+    risk: "none" | "review-required";
+}
+declare function deriveCopilotUserStatus(states: CopilotArtifactState[]): CopilotUserStatus;
+
+interface CopilotSourceSummary {
+    id: string;
+    type: "marketplace" | "git" | "local";
+    displayName: string;
+    updateCapability: "pinned" | "live" | "none";
+}
+interface CopilotPackageDefinition {
+    id: string;
+    sourceId: string;
+    displayName: string;
+    description?: string;
+    version?: string;
+    artifacts: CopilotArtifactSummary[];
+    /** Whole-package registrar installation (Copilot-managed, both scopes) —
+     * the home package list shows these; per-artifact v1 manifest plugins
+     * stay in the enabled-content section instead. */
+    wholePackage?: boolean;
+}
+interface CopilotArtifactView {
+    artifact: CopilotArtifactSummary;
+    state: CopilotArtifactState;
+}
+interface CopilotPackageView {
+    definition: CopilotPackageDefinition;
+    installation: CopilotPackageInstallation;
+    artifacts: CopilotArtifactView[];
+    selectedArtifactCount: number;
+    status: CopilotUserStatus;
+}
+interface CopilotSourceView extends CopilotSourceSummary {
+    packages: CopilotPackageView[];
+}
+interface CopilotCustomizationView {
+    scope: CopilotScope;
+    generatedAt: string;
+    sources: CopilotSourceView[];
+    packages: CopilotPackageView[];
+    attention: CopilotArtifactView[];
+    summary: {
+        packageCount: number;
+        enabledArtifactCount: number;
+        attentionCount: number;
+    };
+    legacyMigration?: {
+        count: number;
+        sourceLabel: "~/.agents";
+    };
+}
+interface BuildCustomizationViewInput {
+    scope: CopilotScope;
+    sources: CopilotSourceSummary[];
+    packages: CopilotPackageDefinition[];
+    installations: CopilotPackageInstallation[];
+    statesByArtifactId: Record<string, CopilotArtifactState>;
+    legacyCount?: number;
+    generatedAt?: string;
+}
+declare function buildCopilotCustomizationView(input: BuildCustomizationViewInput): CopilotCustomizationView;
+
+/**
+ * Machine-local disabled marks for per-artifact skills/agents.
+ *
+ * Disable keeps the installation declaration (workspace manifest) or
+ * the user's install decision intact, but removes the materialized
+ * link so neither the Copilot engine nor the renderer can see the
+ * entry. The mark prevents the reconciler from resurrecting the link
+ * on the next restore. Entries are keyed by scope + identity; a
+ * workspace-scope mark only applies to that workspace.
+ */
+interface DisabledContentEntry {
+    scope: "workspace" | "user";
+    repoId: string;
+    name: string;
+    kind: "skill" | "agent";
+    /** Required for workspace-scope marks — disables are per workspace. */
+    workspaceDir?: string;
+}
+interface DisabledContentState {
+    version: 1;
+    entries: DisabledContentEntry[];
+}
+/** Match predicate scoped to one lookup entry. */
+type DisabledContentMatcher = (entry: DisabledContentEntry) => boolean;
+declare class DisabledContentStore {
+    private readonly homeDir;
+    constructor(options?: {
+        homeDir?: string;
+    });
+    /** Absolute store path: SERVICEME_HOME/copilot/disabled-content.json. */
+    path(): Promise<string>;
+    list(): Promise<DisabledContentEntry[]>;
+    has(matcher: DisabledContentMatcher): Promise<boolean>;
+    add(entry: DisabledContentEntry): Promise<void>;
+    remove(entry: DisabledContentEntry): Promise<void>;
+    private write;
+}
+
+/** MCP server definition as authored in a plugin's mcp.json. */
+interface McpServerDefinition {
+    /** Server name used in the generated local configuration. */
+    name: string;
+    /** Transport type: stdio command servers today. */
+    type: string;
+    /** Executable command (validated, never a shell string). */
+    command: string;
+    /** Arguments passed to the command. */
+    args?: string[];
+    /** Environment variable names the server may read. */
+    env?: Record<string, string>;
+    /** Tool allowlist declared by the source. */
+    tools?: string[];
+}
+/** One lifecycle event registration from hooks.json. */
+interface HookEventDefinition {
+    /** Hook executor type; only "command" is supported today. */
+    type: string;
+    /** Relative bash entry referenced after materialization. */
+    bash: string;
+    /** Working directory hint relative to the workspace root. */
+    cwd?: string;
+    /** Environment variable names the hook may read. */
+    env?: Record<string, string>;
+    /** Timeout in seconds. */
+    timeoutSec?: number;
+}
+/** Hook definition as authored in a repo's hooks/<name>/hooks.json. */
+interface HookDefinition {
+    /** Lifecycle event -> registrations. */
+    hooks: Partial<Record<string, HookEventDefinition[]>>;
+}
+/** Result of applying one generated-config entry on this machine. */
+interface IntegrationApplyResult {
+    identity: string;
+    /** Path of the machine-local config the adapter manages. */
+    configPath: string;
+    /** Server or hook names written into the config. */
+    names: string[];
+    changed: boolean;
+}
+/** Machine-local MCP config adapter (generated-config strategy). */
+interface McpConfigAdapter {
+    /** Merge one server definition into the machine-local config. */
+    applyServer(input: {
+        workspaceDir: string;
+        entry: PlannedContentEntry;
+        server: McpServerDefinition;
+    }): Promise<IntegrationApplyResult>;
+    /** Remove servers previously written for this entry. */
+    removeEntry(input: {
+        workspaceDir: string;
+        identity: string;
+    }): Promise<boolean>;
+}
+/** Machine-local hook registration adapter (approval-gated strategy). */
+interface HookConfigAdapter {
+    /** Materialize hook scripts and register lifecycle events. */
+    applyHook(input: {
+        workspaceDir: string;
+        entry: PlannedContentEntry;
+        hook: HookDefinition;
+    }): Promise<IntegrationApplyResult>;
+    /** Remove registrations previously written for this entry. */
+    removeEntry(input: {
+        workspaceDir: string;
+        identity: string;
+    }): Promise<boolean>;
+}
+/** Parse and validate a plugin mcp.json payload. */
+declare function parseMcpJson(raw: string): McpServerDefinition[];
+/** Parse and validate a hooks.json payload. */
+declare function parseHooksJson(raw: string): HookDefinition;
+/** Locate the mcp.json beside a plugin manifest. */
+declare function findPluginMcpJson(repoRoot: string, pluginId: string): Promise<string | null>;
+/** Locate hooks/<name>/hooks.json in a repository. */
+declare function findRepoHooksJson(repoRoot: string, name: string): Promise<string | null>;
+
+/** Adapter merging MCP servers into the workspace-local VS Code config. */
+declare class FileMcpConfigAdapter implements McpConfigAdapter {
+    /** Merge one server definition under its entry identity. */
+    applyServer(input: {
+        workspaceDir: string;
+        entry: PlannedContentEntry;
+        server: McpServerDefinition;
+    }): Promise<IntegrationApplyResult>;
+    /** Remove only servers owned by the given identity. */
+    removeEntry(input: {
+        workspaceDir: string;
+        identity: string;
+    }): Promise<boolean>;
+}
+/** Adapter materializing hook scripts and event registrations. */
+declare class FileHookConfigAdapter implements HookConfigAdapter {
+    /** Copy hook scripts and merge registrations under the entry identity. */
+    applyHook(input: {
+        workspaceDir: string;
+        entry: PlannedContentEntry;
+        hook: HookDefinition;
+    }): Promise<IntegrationApplyResult>;
+    /** Remove registrations owned by the identity and orphaned script copies. */
+    removeEntry(input: {
+        workspaceDir: string;
+        identity: string;
+    }): Promise<boolean>;
+}
+
+/** Machine-local materialization state for personal-scope content. */
+interface PersonalContentState {
+    version: 1;
+    entries: WorkspaceMaterializedEntry[];
+}
+/** Reconcile result: artifact health keyed by artifact id. */
+interface PersonalReconcileResult {
+    statesByArtifactId: Record<string, CopilotArtifactState>;
+}
+/** Resolves the artifact entries a package contributes. */
+type PersonalPackageResolver = (packageId: string) => Promise<ResolvedPluginEntry[]>;
+interface PersonalReconcilerOptions {
+    /** SERVICEME home directory holding intent and machine state. */
+    homeDir?: string;
+    /** Host-verified capabilities; tests inject per-kind presence. */
+    capabilities: CopilotHostCapabilities;
+    /** Resolves package definitions; defaults to no packages. */
+    resolvePackage?: PersonalPackageResolver;
+}
+/** Manage all six personal artifact kinds against host capabilities. */
+declare class PersonalCopilotContentReconciler {
+    private readonly store;
+    private readonly capabilities;
+    private readonly resolvePackage;
+    private readonly statePath;
+    constructor(options: PersonalReconcilerOptions);
+    /** Read current machine state; empty state when not materialized yet. */
+    readState(): Promise<PersonalContentState>;
+    /** Inspect current personal state without materializing anything. */
+    inspect(): Promise<PersonalReconcileResult>;
+    /** Materialize personal intent for all supported kinds on this machine. */
+    reconcile(): Promise<PersonalReconcileResult>;
+    /** Record local approval for integration content, then re-reconcile. */
+    approve(input: {
+        artifactIds: string[];
+    }): Promise<PersonalReconcileResult>;
+    /** Write machine state atomically. */
+    private writeState;
+    private buildPlan;
+    private removeOwnedMaterialization;
+    private projectStates;
+}
+
+/** Persisted personal-scope installation intent. */
+interface PersonalInstallationState {
+    version: 1;
+    installations: CopilotPackageInstallation[];
+}
+/** Atomically persist personal package installation intent under the SERVICEME home. */
+declare class PersonalInstallationStore {
+    private readonly homeDir;
+    private cachedPath;
+    constructor(options?: {
+        homeDir?: string;
+    });
+    /** Absolute intent-file path: SERVICEME_HOME/copilot/personal-installations.json. */
+    path(): Promise<string>;
+    /** Read intent; empty intent when the file does not exist yet. */
+    read(): Promise<PersonalInstallationState>;
+    /** Atomically persist intent. */
+    write(state: PersonalInstallationState): Promise<void>;
+}
+
+/** Statuses surfaced to UI and CLI for each declared entry. */
+type WorkspaceContentStatus = "restored" | "adopted" | "pending_approval" | "missing_source" | "conflict" | "drifted";
+interface WorkspaceContentEntryResult {
+    identity: string;
+    status: WorkspaceContentStatus;
+    message?: string;
+}
+interface WorkspaceContentReconcileResult {
+    changed: boolean;
+    entries: WorkspaceContentEntryResult[];
+}
+interface RepositorySource {
+    ready: boolean;
+    localPath?: string;
+    error?: string;
+}
+/** Orchestrates declaration → pinned source → plan → safe links. */
+declare class WorkspaceCopilotContentReconciler {
+    private readonly workspaceDir;
+    private readonly homeDir;
+    private readonly ensureRepository;
+    constructor(options: {
+        workspaceDir: string;
+        homeDir?: string;
+        /** Injectable repository ensure step (tests avoid real git). */
+        ensureRepository?: (manifest: WorkspaceCopilotManifest) => Promise<Map<string, RepositorySource>>;
+        /** Injectable link materializer (transactions share the test seam). */
+        materializer?: CopilotLinkMaterializer;
+        /** Machine-local disable marks: identities returning true are
+         * treated as NOT declared — their materialization is removed and
+         * never resurrected, while the manifest declaration itself stays. */
+        isDisabled?: (identity: string) => Promise<boolean>;
+    });
+    private readonly materializer;
+    private readonly isDisabled;
+    /** Restore declared content on this machine. */
+    reconcile(): Promise<WorkspaceContentReconcileResult>;
+    /**
+     * Reconcile mcp/hook entries through their generated-config adapters.
+     * Unapproved or digest-changed entries stay pending without touching
+     * host configuration; approved entries are (re)applied; previously
+     * materialized identities that left the declaration are removed.
+     */
+    private reconcileIntegrations;
+    /** Build the machine-local state entry for a generated-config integration. */
+    private toIntegrationStateEntry;
+    /** Record local approval for risky content, then re-reconcile. */
+    approve(input: {
+        identities: string[];
+    }): Promise<WorkspaceContentReconcileResult>;
+    private defaultEnsureRepository;
+}
+
+/** One legacy ~/.agents link considered for migration. */
+interface LegacyMigrationEntry {
+    artifactId: string;
+    name: string;
+    kind: "skill" | "agent";
+    eligible: boolean;
+    sourcePath: string;
+    targetPath: string;
+}
+/** Read-only preview of legacy links; migration happens only on confirmation. */
+interface LegacyMigrationPreview {
+    sourceLabel: "~/.agents";
+    entries: LegacyMigrationEntry[];
+}
+interface CopilotPackageInstallInput {
+    workspaceDir?: string;
+    scope: CopilotScope;
+    sourceId: string;
+    packageId: string;
+    artifactIds: string[];
+    pinnedVersion?: string;
+    localMode?: "live" | "private-workspace-override";
+}
+interface CopilotPackageUpdateInput {
+    workspaceDir?: string;
+    scope: CopilotScope;
+    packageId: string;
+    artifactIds: string[];
+    pinnedVersion?: string;
+}
+interface CopilotPackageUninstallInput {
+    workspaceDir?: string;
+    scope: CopilotScope;
+    packageId: string;
+}
+interface CopilotPackageMoveInput {
+    workspaceDir?: string;
+    packageId: string;
+    from: CopilotScope;
+    to: CopilotScope;
+}
+interface PackageInstallationServiceDeps {
+    personalStore: PersonalInstallationStore;
+    personalReconciler: PersonalCopilotContentReconciler;
+    /** Shared materializer so transaction tests can inject failures. */
+    materializer?: CopilotLinkMaterializer;
+    userHomeDir: string;
+    resolvePackage: (packageId: string) => Promise<ResolvedPluginEntry[]>;
+    resolveWorkspaceSource: (sourceId: string) => Promise<WorkspaceManifestRepository | undefined>;
+    createWorkspaceReconciler: (workspaceDir: string) => WorkspaceCopilotContentReconciler;
+    /** Resolve the local reconciliation state path for transaction rollback. */
+    getWorkspaceStatePath?: (workspaceDir: string) => Promise<string>;
+    readWorkspaceView: (workspaceDir: string) => Promise<CopilotCustomizationView>;
+    /** Exact selected workspace artifact identities for the active workspace. */
+    readWorkspaceInstallations: (workspaceDir: string) => Promise<CopilotPackageInstallation[]>;
+}
+/**
+ * Package lifecycle transactions over the Task 8 personal store /
+ * reconciler and the shared workspace manifest.
+ *
+ * Every mutation follows prepare → activate → commit: destination
+ * intent is validated and materialized first; source intent is
+ * removed only after every destination artifact succeeded. On
+ * activation failure the previous destination intent is restored and
+ * the source intent is left untouched.
+ */
+declare class PackageInstallationService {
+    private readonly deps;
+    /** Last preview shown to the caller; migration re-verifies against it. */
+    private lastPreview;
+    constructor(deps: PackageInstallationServiceDeps);
+    install(input: CopilotPackageInstallInput): Promise<CopilotCustomizationView>;
+    update(input: CopilotPackageUpdateInput): Promise<CopilotCustomizationView>;
+    uninstall(input: CopilotPackageUninstallInput): Promise<CopilotCustomizationView>;
+    move(input: CopilotPackageMoveInput): Promise<CopilotCustomizationView>;
+    private moveIntoWorkspace;
+    private moveIntoPersonal;
+    previewLegacy(): Promise<LegacyMigrationPreview>;
+    migrateLegacy(input: {
+        artifactIds: string[];
+    }): Promise<CopilotCustomizationView>;
+    private readSourceSelection;
+    private assertArtifactsNotActiveElsewhere;
+    private assertArtifactIdsAbsentFromWorkspace;
+    private assertArtifactIdsAbsentFromInstallations;
+    private assertKindNameFree;
+    private writePersonalIntent;
+    private removePersonalIntent;
+    private upsertWorkspaceSelection;
+    private withWorkspaceActivationRollback;
+    private captureWorkspaceActivation;
+    private captureFile;
+    private restoreWorkspaceActivation;
+    private selectedEntries;
+    private selectEntries;
+    private assertNoActivationConflicts;
+    private assertNoActivationConflictsPersonal;
+    private resolveLegacyTarget;
+    private requireWorkspaceDir;
+    private readPersonalView;
+}
+
+/** A git source to enumerate. `id` is the managed repos dir entry name. */
+interface PluginCatalogRepoInput {
+    id: string;
+    enabled?: boolean;
+}
+/**
+ * An installable plugin.json package found in a source — with the
+ * same artifact summaries an installed package would expose, so the
+ * install preview can select artifacts without a second resolution
+ * path.
+ */
+interface PluginCatalogPackage {
+    packageId: string;
+    sourceId: string;
+    displayName: string;
+    description?: string;
+    version?: string;
+    artifacts: CopilotArtifactSummary[];
+}
+/**
+ * Enumerate plugin.json packages across the given git sources.
+ *
+ * Sources resolve under `reposDir/<id>` — the same managed checkout
+ * layout the workspace manifest restore uses — and each source's
+ * plugins are resolved through the shared workspace plan pipeline.
+ * Per-package failures (corrupt manifest, unreadable files) are
+ * skipped, not thrown — the catalog must stay usable when a single
+ * plugin is broken.
+ */
+declare function listPluginCatalog(input: {
+    reposDir: string;
+    repos: PluginCatalogRepoInput[];
+}): Promise<PluginCatalogPackage[]>;
+interface PluginCatalogService {
+    list(input: {
+        reposDir: string;
+        repos: PluginCatalogRepoInput[];
+    }): Promise<PluginCatalogPackage[]>;
+}
+/** Factory: one cache per service instance (tests use fresh instances). */
+declare function createPluginCatalogService(): PluginCatalogService;
+/**
+ * Single source of truth for entry → artifact-summary mapping. The
+ * CLI bridge imports this for installed packages too, so the install
+ * preview's installStrategy/risk can never drift from what the
+ * catalog shows.
+ */
+declare function toArtifactSummary(entry: ResolvedPluginEntry): CopilotArtifactSummary;
+
+/**
+ * Verbatim wire contract for a read-only package update preview.
+ * Field names are pinned by Task 10's brief and shared with the
+ * protocol / webview layers.
+ */
+interface CopilotPackageUpdatePreview {
+    packageId: string;
+    fromVersion?: string;
+    toVersion: string;
+    addedArtifactIds: string[];
+    removedArtifactIds: string[];
+    changedArtifactIds: string[];
+    approvalInvalidatedArtifactIds: string[];
+}
+/** Normalized source record for diagnostics and the source manager UI. */
+interface CopilotSourceRecord {
+    id: string;
+    type: "marketplace" | "git" | "local";
+    displayName: string;
+    updateCapability: "pinned" | "live" | "none";
+    /** Whether the source content is currently materialized on disk. */
+    available: boolean;
+    /** Where this source is declared: "workspace" (manifest), "personal" (intent), or both. */
+    declaredIn: Array<"workspace" | "personal">;
+}
+interface CopilotSourceCatalogDeps {
+    /** SERVICEME home; defaults to the real ~/.serviceme. */
+    homeDir?: string;
+    /** Personal installation intent; consulted by previewUpdate and removeSource. */
+    personalStore: PersonalInstallationStore;
+    /**
+     * Task 9's transaction service owns installations. removeSource
+     * coordinates with it only indirectly: it refuses while any
+     * installation (workspace or personal) still uses the source.
+     */
+    installationService?: PackageInstallationService;
+    /**
+     * Resolves artifacts for a package at a revision; defaults to a
+     * no-content resolver so an unresolvable source yields empty diff
+     * lists rather than a crash.
+     */
+    resolvePackage?: (packageId: string, revision?: string) => Promise<ResolvedPluginEntry[]>;
+    /**
+     * Round 3: workspace declarations enable artifact kinds, not named
+     * artifacts. This predicate reports whether a resolved entry matches a
+     * selection marker produced for an enabled kind. Implementations may
+     * match exact ids or kind prefixes; default behavior matches only
+     * exact ids (personal-intent semantics).
+     */
+    artifactSelected?: (marker: string, artifactId: string) => boolean;
+    /**
+     * Finding 4 honesty: returns the revision actually resolved by
+     * resolvePackage for a given requested revision. When a resolver can
+     * only read the working tree, this lets previewUpdate label toVersion
+     * with what was truly diffed instead of the requested target.
+     */
+    resolveActualRevision?: (packageId: string, revision: string) => Promise<string | undefined>;
+    /** Source ids declared by the workspace manifest for a directory. */
+    listWorkspaceSources: (workspaceDir: string) => Promise<string[]>;
+    /**
+     * Workspace-scope installations for a directory, read through Task 9's
+     * view projection. Both previewUpdate and removeSource honor personal
+     * AND workspace installations; without this a workspace-declared source
+     * with no personal intent could be deleted while still in use.
+     */
+    readWorkspaceInstallations?: (workspaceDir: string) => Promise<CopilotPackageInstallation[]>;
+    /** Classifies a source id as a marketplace catalog source. */
+    isCatalogSource?: (sourceId: string, workspaceDir?: string) => boolean | Promise<boolean>;
+    /**
+     * Task 10 ruling #1: materialize a v2 catalog source under
+     * repos/<sourceId> so availability is a plain directory check.
+     * listSources invokes this for unavailable catalog sources before
+     * reporting diagnostics.
+     */
+    ensureCatalogSource?: (sourceId: string) => Promise<{
+        localPath: string;
+    }>;
+    /**
+     * Round 2 / Minor 2: reports whether a staged catalog directory
+     * actually contains payload. Staging only creates the directory; a
+     * payload check must gate availability so an empty staged dir is
+     * never reported as available.
+     */
+    hasCatalogPayload?: (localPath: string) => Promise<boolean>;
+    /** Classifies a source id as a personal local source. */
+    isLocalSource?: (sourceId: string) => boolean | Promise<boolean>;
+    /**
+     * ReposStore (repos.json) entries on this machine — built-in default
+     * repos plus user-added git repos. The source manager is the single
+     * repository management surface, so every store entry must appear in
+     * the listing even when it is neither workspace-declared nor
+     * personally installed. Entries with an empty declaredIn are
+     * store-only. Also supplies human display names for store sources.
+     */
+    listStoreSources?: () => Promise<Array<{
+        id: string;
+        name?: string;
+        enabled?: boolean;
+    }>>;
+}
+interface CopilotSourceCatalogQuery {
+    workspaceDir?: string;
+    scope?: CopilotScope;
+}
+interface CopilotUpdatePreviewInput {
+    workspaceDir?: string;
+    scope?: CopilotScope;
+    packageId: string;
+    /** Target revision (full 40-char commit for git sources, immutable catalog revision otherwise). */
+    revision: string;
+}
+/**
+ * Normalized Marketplace / Git / local source discovery plus
+ * deterministic, side-effect-free update previews.
+ *
+ * Marketplace sources are identified by an immutable catalog revision
+ * plus digest (see WorkspaceManifestCatalogSource); Git sources by a
+ * validated remote identity plus full commit; personal local sources
+ * may run "live" while workspace local sources require a Git import
+ * or the "private-workspace-override" mode enforced downstream by the
+ * install transaction.
+ */
+declare class CopilotSourceCatalogService {
+    private readonly deps;
+    private readonly reposDir;
+    constructor(deps: CopilotSourceCatalogDeps);
+    /**
+     * List normalized sources for the query: every source declared by
+     * the workspace manifest (when a workspaceDir is given) plus every
+     * source referenced by personal installation intent, plus every
+     * ReposStore entry on this machine (built-in default repos and
+     * user-added git repos) so the source manager can manage them.
+     */
+    listSources(query: CopilotSourceCatalogQuery): Promise<CopilotSourceRecord[]>;
+    /**
+     * Confirms Task 4's materialization assumption for every source
+     * kind: v2 catalog sources materialize under reposDir/<source-id>
+     * exactly like git checkouts, so availability is a directory check.
+     */
+    isSourceAvailable(sourceId: string): Promise<boolean>;
+    /**
+     * Deterministic, side-effect-free update preview: compares the
+     * currently-selected artifacts against what the target revision
+     * resolves to, and reports which approval-gated artifacts would
+     * need re-approval. Never writes intent; the pinned version stays
+     * untouched until the caller runs the update transaction.
+     */
+    previewUpdate(input: CopilotUpdatePreviewInput): Promise<CopilotPackageUpdatePreview>;
+    /**
+     * Remove a source only when nothing references it: no workspace
+     * declaration and no installation (workspace or personal) may still
+     * use it. Refusals match /installed package/i and /workspace/ so
+     * callers can surface distinct remediation paths.
+     */
+    removeSource(sourceId: string, workspaceDir?: string): Promise<void>;
+}
+
+/**
+ * Read the workspace manifest’s declared package selections without resolving
+ * sources. Source resolution can fail (unavailable source, conflict), and
+ * rendered snapshots then fall back to legacy kind maps that erase exact
+ * artifactIds. Reverse-scope conflict checks must still see what the
+ * manifest declares, so they read declarations directly. Corrupted
+ * manifests surface the load error rather than pretending nothing is
+ * declared.
+ */
+declare function readDeclaredWorkspaceInstallations(workspaceDir: string): Promise<CopilotPackageInstallation[]>;
+
+/** Manage the bounded SERVICEME block inside a git worktree's info/exclude. */
+declare class WorkspaceExcludeStore {
+    private readonly workspaceDir;
+    private readonly resolveGitExcludePath;
+    constructor(options: {
+        workspaceDir: string;
+        /** Override exclude-path resolution (tests, linked-worktree handling). */
+        resolveGitExcludePath?: (workspaceDir: string) => Promise<string>;
+    });
+    /** Resolve the worktree-aware exclude file managed by this store. */
+    path(): Promise<string>;
+    /** Replace the managed block so it contains exactly the given paths. */
+    reconcile(paths: string[]): Promise<void>;
+}
+
+/** Location of the shared declaration inside a workspace. */
+declare const WORKSPACE_MANIFEST_RELPATH: string;
+/** Absolute path of the declaration file inside a workspace. */
+declare function getWorkspaceManifestPath(workspaceDir: string): string;
+/** Read and validate the declaration; undefined when absent. */
+declare function loadWorkspaceCopilotManifest(workspaceDir: string): Promise<WorkspaceCopilotManifest | undefined>;
+/** Validate and atomically write the shared declaration. */
+declare function writeWorkspaceCopilotManifest(workspaceDir: string, manifest: WorkspaceCopilotManifest): Promise<void>;
+/**
+ * Atomically replace one package selection with exact resolver artifact IDs.
+ * New selections clear legacy kind maps so future resolution remains stable
+ * if a package adds another artifact of an existing kind.
+ */
+declare function replaceWorkspaceContentSelection(input: {
+    workspaceDir: string;
+    repository: WorkspaceManifestRepository;
+    pluginId: string;
+    artifactIds: string[];
+}): Promise<WorkspaceCopilotManifest>;
+/**
+ * Add or update one artifact-kind selection (any of the six kinds) in the
+ * shared declaration, creating the file when absent. Returns the new manifest.
+ *
+ * The repository entry must already exist (or be provided via
+ * `repository`) with a full pinned commit; this helper only manages
+ * the plugin selection so install flows never race a concurrent write
+ * of unrelated selections.
+ */
+declare function upsertWorkspaceContentSelection(input: {
+    workspaceDir: string;
+    repository: WorkspaceManifestRepository;
+    pluginId: string;
+    kind: CopilotArtifactKind;
+}): Promise<WorkspaceCopilotManifest>;
+/**
+ * Remove one artifact kind from a plugin selection, dropping
+ * the plugin entirely when no artifact kind remains enabled. Returns
+ * the new manifest; a no-op when the selection does not exist.
+ */
+declare function removeWorkspaceContentSelection(input: {
+    workspaceDir: string;
+    repositoryId: string;
+    pluginId: string;
+    kind: CopilotArtifactKind;
+}): Promise<WorkspaceCopilotManifest>;
+
+/** Hash a canonical workspace path into a stable directory segment. */
+declare function hashWorkspaceDir(workspaceDir: string): Promise<string>;
+/** Directory holding machine-local state for one workspace. */
+declare function getWorkspaceStateDir(workspaceDir: string, homeDir?: string): Promise<string>;
+/** Store for machine-local Copilot content state; one file per workspace. */
+declare class WorkspaceContentStateStore {
+    private readonly workspaceDir;
+    private readonly homeDir;
+    private cachedPath;
+    constructor(options: {
+        workspaceDir: string;
+        homeDir?: string;
+    });
+    /** Absolute state-file path for this workspace. */
+    path(): Promise<string>;
+    /** Read state; an empty state when the file does not exist yet. */
+    read(): Promise<WorkspaceContentState>;
+    /** Atomically persist state. */
+    write(state: WorkspaceContentState): Promise<void>;
+}
+
 /**
  * Skill & Agent v2 — Drafts (M4)
  *
@@ -341,6 +1465,8 @@ declare const DRAFTS_SUBDIR = "drafts";
 declare const SKILL_DRAFTS_SUBDIR = "skills";
 declare const AGENT_DRAFTS_SUBDIR = "agents";
 declare const REPOS_CONFIG_FILENAME = "repos.json";
+declare const WORKSPACES_SUBDIR = "workspaces";
+declare const WORKSPACE_CONTENT_STATE_FILENAME = "copilot-content-state.json";
 /** rev.20 — r7 BYOM Server Proxy toggle self-state (read by ext + CLI + server). */
 declare const SERVER_PROXY_GLOBAL_FILENAME = "server-proxy.json";
 /**
@@ -398,6 +1524,8 @@ declare function getAgentDraftsDir(): string;
  * `SERVICEME_HOME` overrides too).
  */
 declare function getReposConfigPath(): string;
+/** `~/.serviceme/workspaces` — machine-local per-workspace state root. */
+declare function getWorkspacesDir(): string;
 /**
  * Convenience helper for callers that need to switch behaviour on platform
  * (e.g. `SkillLinker` chooses symlink vs junction). Exported mostly so tests
@@ -682,8 +1810,8 @@ declare const defaultRepoSchema: z.ZodObject<{
     lastSyncAt: z.ZodOptional<z.ZodString>;
     lastSyncCommitSha: z.ZodOptional<z.ZodString>;
     lastSyncStatus: z.ZodOptional<z.ZodEnum<{
-        ok: "ok";
         error: "error";
+        ok: "ok";
     }>>;
     lastSyncError: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -700,8 +1828,8 @@ declare const userRepoSchema: z.ZodObject<{
     lastSyncAt: z.ZodOptional<z.ZodString>;
     lastSyncCommitSha: z.ZodOptional<z.ZodString>;
     lastSyncStatus: z.ZodOptional<z.ZodEnum<{
-        ok: "ok";
         error: "error";
+        ok: "ok";
     }>>;
     lastSyncError: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -719,8 +1847,8 @@ declare const repoSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     lastSyncAt: z.ZodOptional<z.ZodString>;
     lastSyncCommitSha: z.ZodOptional<z.ZodString>;
     lastSyncStatus: z.ZodOptional<z.ZodEnum<{
-        ok: "ok";
         error: "error";
+        ok: "ok";
     }>>;
     lastSyncError: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
@@ -736,8 +1864,8 @@ declare const repoSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     lastSyncAt: z.ZodOptional<z.ZodString>;
     lastSyncCommitSha: z.ZodOptional<z.ZodString>;
     lastSyncStatus: z.ZodOptional<z.ZodEnum<{
-        ok: "ok";
         error: "error";
+        ok: "ok";
     }>>;
     lastSyncError: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "source">;
@@ -758,8 +1886,8 @@ declare const reposFileSchema: z.ZodObject<{
         lastSyncAt: z.ZodOptional<z.ZodString>;
         lastSyncCommitSha: z.ZodOptional<z.ZodString>;
         lastSyncStatus: z.ZodOptional<z.ZodEnum<{
-            ok: "ok";
             error: "error";
+            ok: "ok";
         }>>;
         lastSyncError: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>, z.ZodObject<{
@@ -775,8 +1903,8 @@ declare const reposFileSchema: z.ZodObject<{
         lastSyncAt: z.ZodOptional<z.ZodString>;
         lastSyncCommitSha: z.ZodOptional<z.ZodString>;
         lastSyncStatus: z.ZodOptional<z.ZodEnum<{
-            ok: "ok";
             error: "error";
+            ok: "ok";
         }>>;
         lastSyncError: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "source">>;
@@ -1130,10 +2258,63 @@ declare class RepoManager {
     pullOne(repoId: string): Promise<PullResult>;
     /** Pull every enabled repo. Per-repo failures don't abort the run. */
     pullAll(): Promise<SyncReport>;
+    /**
+     * Ensure a repository exists locally and is detached at an exact
+     * commit. Used by Copilot content restoration: never pulls to a
+     * branch head, so a declaration always resolves to the reviewed
+     * content on every machine.
+     */
+    ensureAtCommit(input: {
+        repository: Pick<RepoConfig, "id" | "url" | "useProxy">;
+        commit: string;
+    }): Promise<{
+        localPath: string;
+        commit: string;
+    }>;
+    /**
+     * Ensure a v2 catalog source is materialized under repos/<sourceId>
+     * exactly like a git checkout (Task 10, ruling #1).
+     *
+     * The catalog store (repos.json) never held catalog sources, so the
+     * source-lifecycle task owns this path: content arrives from the
+     * provider as an extracted tree, is unpacked under the managed
+     * source directory, and is verified against the immutable digest
+     * before the directory becomes visible to resolvers.
+     *
+     * Callers that only need the directory contract (source availability
+     * is a reposDir/<source-id> directory check) can pass a provider
+     * that stages the tree; the method itself never writes store
+     * entries — marketplace sources stay manifest-only.
+     */
+    ensureCatalogSource(input: {
+        sourceId: string;
+        provider: {
+            /** Stage the catalog payload into the target directory. */
+            materialize: (targetDir: string) => Promise<void>;
+        };
+    }): Promise<{
+        localPath: string;
+    }>;
+    /**
+     * Resolve a unique store id for a repo being added.
+     *
+     * The base id derives from the URL (`owner-repo`). When it is taken
+     * by the SAME url with a DIFFERENT branch — user repo or platform
+     * default alike — derive `base-<branch>` so users can track several
+     * branches of one repository side by side. Genuine duplicates (same
+     * url + same branch) and cross-url id collisions still throw
+     * RepoCloneConflictError.
+     */
+    private resolveUserRepoId;
     /**
      * Validate URL, derive an id, detect the branch via `git ls-remote`,
      * then add the entry to the store and trigger a clone.
      *
+     * The base id derives from the URL. Re-adding the same URL with a
+     * different branch is allowed — it gets a branch-suffixed id
+     * (`owner-repo-<branch>`) so multiple branches of one repository can
+     * be tracked side by side.
+     *
      * Spec §5.3 says "branch detection" happens BEFORE the store write so
      * the resulting `repos.json` is fully populated. The clone is async
      * but the function returns synchronously once the store is updated
@@ -1608,8 +2789,34 @@ declare class SkillStore {
     private migrateLegacyUserSkillMarker;
     writeSkillFiles(skillId: string, scope: "workspace" | "user", files: SkillDownloadFile[]): Promise<void>;
 }
+/** One legacy skill directory reported by {@link migrateLegacyUserSkillContent}. */
+interface LegacyUserSkillEntry {
+    /** Legacy skill id (directory name under ~/.agents/skills). */
+    id: string;
+    /** Absolute path of the legacy skill directory. */
+    legacyPath: string;
+    /** Target directory under ~/.copilot/skills the migration would create. */
+    targetPath: string;
+    /** Always `migration_available` until the user runs the migration. */
+    status: "migration_available";
+}
+interface LegacyUserSkillMigrationResult {
+    entries: LegacyUserSkillEntry[];
+}
+/**
+ * Detect ~/.agents/skills content that can migrate to ~/.copilot/skills.
+ *
+ * Read-only: legacy directories stay in place until the user explicitly
+ * invokes the migration, so detection never breaks tools that still
+ * read the old layout.
+ */
+declare function migrateLegacyUserSkillContent(input: {
+    homeDir: string;
+    workspaceDir: string;
+    fileSystem?: SkillStoreFileSystem;
+}): Promise<LegacyUserSkillMigrationResult>;
 
 declare const unzipFile: (zipPath: string, dest: string) => Promise<void>;
 declare const moveFiles: (sourceDir: string, destDir: string, overwrite?: boolean) => Promise<void>;
 
-export { AGENT_DRAFTS_SUBDIR, type AddUserRepoInput, type AddUserRepoResult, type AgentCatalog, AgentCatalogClient, type AgentCatalogClientOptions, type AgentDownloadFile, type AgentInstallScope, type AgentMutateResult, AgentReconciler, type AgentReconcilerDependencies, AgentStore, type AgentStoreFileSystem, type AgentStoreOptions, type AgentsStateFile, type AnyRepoConfig, type AppendLogInput, type BootstrapPhase5Result, CACHE_SUBDIR, CREDENTIALS_CONFIG_FILENAME, CannotRemoveDefaultRepoError, type CreateTaskInput, FIXED_ADDED_AT as DEFAULT_REPO_FIXED_ADDED_AT, DEFAULT_REPO_ID, DEVICE_JSON_FILENAME, DRAFTS_SUBDIR, DaemonLogger, type DefaultRepoConfig, type DraftDetail, DraftNotFoundError, type DraftSummary, DraftsError, DraftsStore, type EditTaskInput, EnvironmentInspector, type EnvironmentInspectorOptions, type ExecutorResult, type FsWatcherCallbacks, type FsWatcherHandle, GitClient, GithubCopilotCliExecutor, HttpRequestExecutor, ImageTools, type InstalledAgent, InvalidDraftError, InvalidRepoUrlError, type IsoTimestamp, type JsonTools, KNOWN_WORKSPACES_FILENAME, type LoadResult, MACHINE_ID_FILENAME, MIGRATION_FAILURES_FILENAME, type MigrateToGlobalOptions, type MigrationResult, type OutputEventCallback, PROFILES_JSON_FILENAME, PidManager, type ProbeError, type ProbeOptions, type ProbeResult, ProjectTools, REPOS_CONFIG_FILENAME, REPOS_SUBDIR, RepoAlreadyExistsError, RepoCloneConflictError, type RepoConfig, RepoManager, RepoManagerError, type RepoManagerOptions, RepoNotFoundError, RepoNotInStoreError, type RepoSource, type ReposFile, type ReposFileInput, ReposLoader, type ReposLoaderFileSystem, type ReposLoaderOptions, ReposStore, type ReposStoreChange, type ReposStoreFileSystem, type ReposStoreListener, type ReposStoreOptions, SAFE_REPO_ID_PATTERN, SCHEDULED_TASKS_CONFIG_FILENAME, SCHEDULED_TASKS_LOG_FILENAME, SCHEDULER_LOCK_FILENAME, SCHEDULER_LOG_FILENAME, SCHEDULER_PID_FILENAME, SERVER_PROXY_GLOBAL_FILENAME, SERVICEME_DIR_NAME, SERVICEME_HOME_ENV, SKILL_DRAFTS_SUBDIR, type SaveDraftOptions, SchedulerDaemonV2, type SchedulerDaemonV2Options, type ServerProxyGlobalPatch, type ServerProxyGlobalState, ShellExecutor, type SkillCatalog, SkillCatalogClient, type SkillCatalogClientOptions, type SkillDownloadFile, type SkillMutateResult, SkillReconciler, type SkillReconcilerDependencies, SkillStore, type SkillStoreFileSystem, type SkillStoreOptions, type StreamingExecutorHandle, type StreamingTaskExecutor, type SyncReport, type SyncStatus, TOOLBOX_JSON_FILENAME, TOOL_RISK_MAP, TaskConfigManager, type TaskEventListener, TaskExecutionEngine, type TaskExecutor, TaskLogManager, type UserRepoConfig, WorkspaceProbe, repoSchema as anyRepoConfigSchema, assertSafeRepoId, bootstrapDefaults, bootstrapPhase5Placeholders, buildDefaultReposFile, copilotDoctor, copilotPrompt, createCopilotAuthRequiredError, createCopilotNotInstalledError, createImageTools, createJsonTools, createProjectTools, createReposStore, defaultRepoSchema as defaultRepoConfigSchema, ensureDefaultsInstalled, generateDraftId, getAgentDraftsDir, getAllDefaultRepoConfigs, getCacheDir, getCredentialsConfigPath, getDefaultRepoConfig, getDeviceJsonPath, getDraftsDir, getExecutor, getHomeDir, getHomePlatform, getKnownWorkspacesPath, getMachineIdPath, getMigrationFailuresPath, getProfilesJsonPath, getRepoCacheDir, getRepoDir, getReposConfigPath, getReposDir, getScheduledTasksConfigPath, getScheduledTasksLogPath, getSchedulerLockPath, getSchedulerLogPath, getSchedulerPidPath, getServerProxyGlobalPath, getServicemeHome, getSkillDraftsDir, getToolboxJsonPath, isCopilotAuthenticated, isDefaultRepo, isStreamingTaskExecutor, isUserRepo, migrateLegacyServerProxyEnabled, migrateToGlobal, moveFiles, narrowRepoConfig, parseAgentToolPermissions, readServerProxyGlobal, reposFileSchema, resetUserHomeOverrides, resolveDraftDir, resolveTaskExecutionPayload, setUserHomeOverrides, unzipFile, userRepoSchema as userRepoConfigSchema, validateReposFile, validateTaskPayload, writeServerProxyGlobal };
+export { AGENT_DRAFTS_SUBDIR, type AddUserRepoInput, type AddUserRepoResult, type AgentCatalog, AgentCatalogClient, type AgentCatalogClientOptions, type AgentDownloadFile, type AgentInstallScope, type AgentMutateResult, AgentReconciler, type AgentReconcilerDependencies, AgentStore, type AgentStoreFileSystem, type AgentStoreOptions, type AgentsStateFile, type AnyRepoConfig, type AppendLogInput, type BootstrapPhase5Result, type BuildCustomizationViewInput, CACHE_SUBDIR, CREDENTIALS_CONFIG_FILENAME, CannotRemoveDefaultRepoError, type CopilotArtifactKind, type CopilotArtifactState, type CopilotArtifactSummary, type CopilotArtifactView, type CopilotCustomizationView, type CopilotHostCapabilities, type CopilotInstallIntent, type CopilotIntegrationAdapter, CopilotLinkMaterializer, type CopilotLinkMode, type CopilotLocalGate, type CopilotMaterializationHealth, type CopilotPackageDefinition, type CopilotPackageInstallInput, type CopilotPackageInstallation, type CopilotPackageMoveInput, type CopilotPackageUninstallInput, type CopilotPackageUpdateInput, type CopilotPackageUpdatePreview, type CopilotPackageView, type CopilotPluginRegisterInput, CopilotPluginRegistrar, type CopilotPluginRegistrarOptions, type CopilotPluginRegistration, type CopilotScope, type CopilotSourceCatalogDeps, type CopilotSourceCatalogQuery, CopilotSourceCatalogService, type CopilotSourceRecord, type CopilotSourceSummary, type CopilotSourceView, type CopilotUpdatePreviewInput, type CopilotUserStatus, type CreateTaskInput, FIXED_ADDED_AT as DEFAULT_REPO_FIXED_ADDED_AT, DEFAULT_REPO_ID, DEVICE_JSON_FILENAME, DRAFTS_SUBDIR, DaemonLogger, type DefaultRepoConfig, type DisabledContentEntry, type DisabledContentMatcher, type DisabledContentState, DisabledContentStore, type DraftDetail, DraftNotFoundError, type DraftSummary, DraftsError, DraftsStore, type EditTaskInput, EnvironmentInspector, type EnvironmentInspectorOptions, type ExecutorResult, FileHookConfigAdapter, FileMcpConfigAdapter, type FsWatcherCallbacks, type FsWatcherHandle, GitClient, GithubCopilotCliExecutor, type HookConfigAdapter, type HookDefinition, type HookEventDefinition, HttpRequestExecutor, ImageTools, type InstalledAgent, type IntegrationApplyResult, InvalidDraftError, InvalidRepoUrlError, type IsoTimestamp, type JsonTools, KNOWN_WORKSPACES_FILENAME, type LegacyMigrationEntry, type LegacyMigrationPreview, type LegacyUserContentEntry, type LegacyUserContentMigrationResult, type LegacyUserSkillEntry, type LegacyUserSkillMigrationResult, type LoadResult, MACHINE_ID_FILENAME, MIGRATION_FAILURES_FILENAME, type MaterializeEntryResult, type MaterializeEntryStatus, type MaterializeResult, type McpConfigAdapter, type McpServerDefinition, type MigrateToGlobalOptions, type MigrationResult, type OutputEventCallback, PROFILES_JSON_FILENAME, PackageInstallationService, type PackageInstallationServiceDeps, type PersonalContentState, PersonalCopilotContentReconciler, type PersonalInstallationState, PersonalInstallationStore, type PersonalLinkKind, type PersonalPackageResolver, type PersonalReconcileResult, PidManager, type PlannedContentEntry, type PluginCatalogPackage, type PluginCatalogRepoInput, type PluginCatalogService, type ProbeError, type ProbeOptions, type ProbeResult, ProjectTools, REPOS_CONFIG_FILENAME, REPOS_SUBDIR, RepoAlreadyExistsError, RepoCloneConflictError, type RepoConfig, RepoManager, RepoManagerError, type RepoManagerOptions, RepoNotFoundError, RepoNotInStoreError, type RepoSource, type ReposFile, type ReposFileInput, ReposLoader, type ReposLoaderFileSystem, type ReposLoaderOptions, ReposStore, type ReposStoreChange, type ReposStoreFileSystem, type ReposStoreListener, type ReposStoreOptions, type ResolvedPluginEntry, type ResolvedPluginManifest, SAFE_REPO_ID_PATTERN, SCHEDULED_TASKS_CONFIG_FILENAME, SCHEDULED_TASKS_LOG_FILENAME, SCHEDULER_LOCK_FILENAME, SCHEDULER_LOG_FILENAME, SCHEDULER_PID_FILENAME, SERVER_PROXY_GLOBAL_FILENAME, SERVICEME_DIR_NAME, SERVICEME_HOME_ENV, SKILL_DRAFTS_SUBDIR, type SaveDraftOptions, SchedulerDaemonV2, type SchedulerDaemonV2Options, type ServerProxyGlobalPatch, type ServerProxyGlobalState, ShellExecutor, type SkillCatalog, SkillCatalogClient, type SkillCatalogClientOptions, type SkillDownloadFile, type SkillMutateResult, SkillReconciler, type SkillReconcilerDependencies, SkillStore, type SkillStoreFileSystem, type SkillStoreOptions, type StreamingExecutorHandle, type StreamingTaskExecutor, type SyncReport, type SyncStatus, TOOLBOX_JSON_FILENAME, TOOL_RISK_MAP, TaskConfigManager, type TaskEventListener, TaskExecutionEngine, type TaskExecutor, TaskLogManager, type UserRepoConfig, WORKSPACES_SUBDIR, WORKSPACE_CONTENT_STATE_FILENAME, WORKSPACE_MANIFEST_RELPATH, type WorkspaceContentEntryResult, type WorkspaceContentPlan, type WorkspaceContentReconcileResult, type WorkspaceContentState, WorkspaceContentStateStore, type WorkspaceContentStatus, WorkspaceCopilotContentReconciler, type WorkspaceCopilotManifest, type WorkspaceCopilotManifestV1, type WorkspaceCopilotManifestV2, WorkspaceExcludeStore, type WorkspaceManifestCatalogSource, type WorkspaceManifestGitSource, type WorkspaceManifestPlugin, type WorkspaceManifestPluginV2, type WorkspaceManifestRepository, type WorkspaceManifestSource, type WorkspaceMaterializedEntry, WorkspaceProbe, allPersonalLinkKinds, repoSchema as anyRepoConfigSchema, assertSafeRepoId, bootstrapDefaults, bootstrapPhase5Placeholders, buildCopilotCustomizationView, buildDefaultReposFile, copilotDoctor, copilotPrompt, createCopilotAuthRequiredError, createCopilotNotInstalledError, createDefaultCopilotHostCapabilities, createImageTools, createJsonTools, createPluginCatalogService, createProjectTools, createReposStore, defaultRepoSchema as defaultRepoConfigSchema, deriveCopilotUserStatus, ensureDefaultsInstalled, findPluginMcpJson, findRepoHooksJson, generateDraftId, getAgentDraftsDir, getAllDefaultRepoConfigs, getCacheDir, getCredentialsConfigPath, getDefaultRepoConfig, getDeviceJsonPath, getDraftsDir, getExecutor, getHomeDir, getHomePlatform, getKnownWorkspacesPath, getMachineIdPath, getMigrationFailuresPath, getProfilesJsonPath, getRepoCacheDir, getRepoDir, getReposConfigPath, getReposDir, getScheduledTasksConfigPath, getScheduledTasksLogPath, getSchedulerLockPath, getSchedulerLogPath, getSchedulerPidPath, getServerProxyGlobalPath, getServicemeHome, getSkillDraftsDir, getToolboxJsonPath, getWorkspaceManifestPath, getWorkspaceManifestPluginSourceId, getWorkspaceManifestSources, getWorkspaceStateDir, getWorkspacesDir, hashWorkspaceDir, isCopilotAuthenticated, isDefaultRepo, isStreamingTaskExecutor, isUserRepo, listPluginCatalog, loadWorkspaceCopilotManifest, migrateLegacyServerProxyEnabled, migrateLegacyUserContent, migrateLegacyUserSkillContent, migrateToGlobal, moveFiles, narrowRepoConfig, parseAgentToolPermissions, parseHooksJson, parseMcpJson, readDeclaredWorkspaceInstallations, readServerProxyGlobal, removeWorkspaceContentSelection, replaceWorkspaceContentSelection, reposFileSchema, resetUserHomeOverrides, resolveDraftDir, resolvePluginEntriesLenient, resolveTaskExecutionPayload, resolveWorkspaceContentPlan, setUserHomeOverrides, supportsPersonalIntegrationKind, supportsPersonalLinkKind, toArtifactSummary, unzipFile, upsertWorkspaceContentSelection, userRepoSchema as userRepoConfigSchema, validateReposFile, validateTaskPayload, writeServerProxyGlobal, writeWorkspaceCopilotManifest };