@serviceme/devtools-core 0.1.8 → 0.2.0

package/dist/index.d.mts

@@ -1,6 +1,15 @@
 import * as _serviceme_devtools_protocol from '@serviceme/devtools-protocol';
-import { AgentMarketplaceEntry, AgentMutationRequest, AgentPermissionSummary, CopilotDoctorResult, CopilotPromptOptions, CopilotPromptResult, EnvironmentCheckResult, KnownEnvironmentTool, ToolCheckResult, ServiceMeImageValidationResult, ServiceMeImageInfo, ServiceMeImageCompressOptions, ServiceMeImageCompressResult, JsonSortOptions, JsonValidationResult, AgentToolRiskLevel, AgentToolPermission, ServiceMeProjectExtractTemplateInput, ServiceMeProjectExtractTemplateResult, ServiceMeProjectInstallDepsResult, ServiceMeProjectMakeScriptsExecutableResult, ServiceMeProjectGitInitResult, ServiceMeProjectScaffoldPruneResult, TaskExecutionStatus, ScheduledTaskType, TaskPayload, ScheduledTasksConfig, ScheduledTask, TaskStartedEventParams, TaskOutputEventParams, TaskCompletedEventParams, TaskFailedEventParams, TaskCancelledEventParams, TaskExecutionSnapshot, RunningTaskInfo, TaskExecutionLog, SkillMarketplaceEntry, SkillMutationRequest } from '@serviceme/devtools-protocol';
+import { AgentMarketplaceEntry, AgentMutationRequest, AgentPermissionSummary, CopilotDoctorResult, CopilotPromptOptions, CopilotPromptResult, EnvironmentCheckResult, KnownEnvironmentTool, ToolCheckResult, ServiceMeImageValidationResult, ServiceMeImageInfo, ServiceMeImageCompressOptions, ServiceMeImageCompressResult, JsonSortOptions, JsonValidationResult, AgentToolRiskLevel, AgentToolPermission, ServiceMeProjectExtractTemplateInput, ServiceMeProjectExtractTemplateResult, ServiceMeProjectInstallDepsResult, ServiceMeProjectMakeScriptsExecutableResult, ServiceMeProjectGitInitResult, ServiceMeProjectScaffoldPruneResult, TaskExecutionStatus, ScheduledTaskType, TaskPayload, TaskWorkspaceRef, ScheduledTasksConfig, ScheduledTask, TaskExecutionLog, TaskStartedEventParams, TaskOutputEventParams, TaskCompletedEventParams, TaskFailedEventParams, TaskCancelledEventParams, TaskExecutionSnapshot, RunningTaskInfo, SkillMarketplaceEntry, SkillMutationRequest } from '@serviceme/devtools-protocol';
 import * as fs from 'node:fs/promises';
+export { AccessCheckResult, AccessControl, AccessControlOptions, AuthCore, AuthCoreOptions, AuthStateManager, AuthStateManagerOptions, CancellationCheck, DeviceFlowUiCallback, GitHubAuthProvider, GitHubAuthProviderConfig, IAuthProvider, IAuthProviderSession, IAuthProviderUserInfo, InMemoryKeychainAuthTokenStore, KeyValueStore, KeychainAccountKey, KeychainAuthTokenStore, KeychainTokenEnvelope, KeychainTokenMetadata, KeychainUnavailableError, MicrosoftAuthProvider, MicrosoftProviderNotHostedError, OrgMembershipFetcher, ProviderRegistry, buildGitHubLocalEmail, isGitHubLocalEmail, resolvePrimaryEmail } from './auth.mjs';
+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.mjs';
+import { c as SkillKind, b as SkillFile } from './types-B9gk3dXH.mjs';
+import { G as GitClient, P as PullResult } from './index-Dmyy4urr.mjs';
+export { a as GitError, N as NodeGitSpawner, S as StubGitSpawner, b as SubmitClient, c as SubmitClientOptions, d as SubmitError, e as SubmitOptions, f as SubmitResult, t as toFileUrl } from './index-Dmyy4urr.mjs';
+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.mjs';
+import 'node:child_process';
 
 type AgentInstallScope = "workspace" | "user";
 interface InstalledAgent {
@@ -91,6 +100,13 @@ declare class AgentStore {
     listWorkspaceAgentIds(): Promise<string[]>;
     listUserAgentIds(): Promise<string[]>;
     readState(): Promise<AgentsStateFile | null>;
+    /**
+     * One-time migration: the workspace agents state file used to be named
+     * `.github/.ms-devtools-agents.yml`. If the new `.serviceme-agents.yml`
+     * doesn't exist yet but the legacy file does, copy its content forward
+     * so existing installed-agent state isn't silently lost.
+     */
+    private migrateLegacyState;
     writeState(state: AgentsStateFile): Promise<void>;
     addInstalledAgent(entry: InstalledAgent): Promise<void>;
     removeInstalledAgent(agentId: string): Promise<void>;
@@ -109,6 +125,107 @@ declare function createCopilotAuthRequiredError(): _serviceme_devtools_protocol.
 
 declare function copilotPrompt(options: CopilotPromptOptions): Promise<CopilotPromptResult>;
 
+/**
+ * Skill & Agent v2 — Drafts (M4)
+ *
+ * Drafts are offline WIP copies of skills/agents that the user is
+ * editing locally before submitting. They live under
+ * `~/.serviceme/drafts/{skills,agents}/<draft-id>/` and have the same
+ * file layout as a published entry: SKILL.md (or AGENT.md) plus any
+ * extra files. The `SubmitClient` (also M4) reads a draft's files and
+ * sends them to the server's validate endpoint before pushing.
+ *
+ * Draft ids are short random hex strings (16 hex chars / 8 bytes of
+ * entropy) — long enough to be globally unique, short enough to be
+ * pasteable. They are NOT user-meaningful; clients surface a `name`
+ * from the draft's frontmatter instead.
+ *
+ * Persistence is atomic per-file (write to `.tmp-xxx` + rename).
+ * The whole draft directory is never partially committed — failed
+ * writes leave a `.tmp-xxx` orphan that the next save/cleanup can
+ * sweep.
+ *
+ * @see docs/architecture/skill-agent-v2-repo.md §2.1 (drafts layout),
+ *      §5.7 SubmitClient (consumer).
+ */
+interface DraftSummary {
+    /** Random id (16 hex chars). */
+    id: string;
+    kind: SkillKind;
+    /** Path to the manifest file (SKILL.md or AGENT.md). */
+    manifestPath: string;
+    /** Path to the directory containing the draft's files. */
+    dir: string;
+    /** Best-effort name from the frontmatter (empty string when absent). */
+    name: string;
+    /** Best-effort description from the frontmatter (empty string when absent). */
+    description: string;
+    /** ISO timestamp of the manifest file's mtime. */
+    modifiedAt: string;
+}
+interface DraftDetail extends DraftSummary {
+    files: SkillFile[];
+}
+interface SaveDraftOptions {
+    kind: SkillKind;
+    /** Existing draft id; omit to create a new draft. */
+    id?: string;
+    /** Files to write. Must include a manifest (SKILL.md or AGENT.md). */
+    files: SkillFile[];
+}
+/** Sentinel errors. */
+declare class DraftsError extends Error {
+    constructor(message: string);
+}
+declare class DraftNotFoundError extends DraftsError {
+    readonly kind: SkillKind;
+    readonly id: string;
+    constructor(kind: SkillKind, id: string);
+}
+declare class InvalidDraftError extends DraftsError {
+    constructor(message: string);
+}
+/**
+ * Generate a short random hex id. Uses Node's `crypto.randomBytes` so
+ * the output is unpredictable. 8 bytes = 16 hex chars = 64 bits of
+ * entropy. We don't promise uniqueness (collisions exist with
+ * astronomically low probability) — callers must treat ids as opaque.
+ */
+declare function generateDraftId(): string;
+/**
+ * Resolve the on-disk directory for a draft of a given kind + id.
+ * Exported for tests + the SubmitClient which writes the committed
+ * files into the repo.
+ */
+declare function resolveDraftDir(kind: SkillKind, id: string): string;
+/**
+ * Persistent draft store backed by the local filesystem. Pure local —
+ * no network, no git, no DB.
+ */
+declare class DraftsStore {
+    /**
+     * List every draft of the given kind. Returns [] when the drafts
+     * directory doesn't exist (cold start, never-saved state).
+     */
+    list(kind: SkillKind): Promise<DraftSummary[]>;
+    /** Single draft summary (manifest + metadata). Returns null when missing. */
+    tryReadSummary(kind: SkillKind, id: string): Promise<DraftSummary | null>;
+    /** Single draft detail (summary + all files). Throws when missing. */
+    get(kind: SkillKind, id: string): Promise<DraftDetail>;
+    /** All files in a draft (manifest + extras), recursively. */
+    getFiles(kind: SkillKind, id: string): Promise<SkillFile[]>;
+    /**
+     * Create-or-update a draft. Returns the (possibly new) draft id.
+     * Throws `InvalidDraftError` when the file list does not include
+     * a manifest.
+     */
+    save(opts: SaveDraftOptions): Promise<string>;
+    /** Delete a draft. ENOENT is silently ignored (idempotent). */
+    delete(kind: SkillKind, id: string): Promise<void>;
+    /** Best-effort cleanup of `.tmp-*` orphan files in the draft dir. */
+    private sweepTmp;
+}
+
 interface RunCommandOptions {
     args?: string[];
     cwd?: string;
@@ -190,9 +307,173 @@ interface ServiceMeLogger {
 declare const noopLogger: ServiceMeLogger;
 declare function createConsoleLogger(prefix?: string): ServiceMeLogger;
 
+/**
+ * SERVICEME user home directory helpers.
+ *
+ * All paths resolve under {@link getServicemeHome}, which is either the
+ * `SERVICEME_HOME` environment variable (when set and non-empty) or
+ * `$HOME/.serviceme` on POSIX / `%USERPROFILE%\.serviceme` on Windows.
+ *
+ * Tests inject `homeDir` and `servicemeHomeEnv` overrides via
+ * {@link setUserHomeOverrides} / {@link resetUserHomeOverrides} so they can
+ * exercise the path logic without touching the real user environment.
+ */
+/** Layout constants — kept in one place so other modules can reuse them. */
+declare const SERVICEME_DIR_NAME = ".serviceme";
+declare const REPOS_SUBDIR = "repos";
+declare const CACHE_SUBDIR = "cache";
+declare const DRAFTS_SUBDIR = "drafts";
+declare const SKILL_DRAFTS_SUBDIR = "skills";
+declare const AGENT_DRAFTS_SUBDIR = "agents";
+declare const REPOS_CONFIG_FILENAME = "repos.json";
+/**
+ * Repo id regex — used to validate any `repoId` argument before it is joined
+ * into a filesystem path. Keeps path traversal attempts out and gives us a
+ * predictable on-disk shape.
+ */
+declare const SAFE_REPO_ID_PATTERN: RegExp;
+/** Environment variable that overrides the user-home root directory. */
+declare const SERVICEME_HOME_ENV = "SERVICEME_HOME";
+/**
+ * Test seam: lets unit tests inject deterministic values for `os.homedir()`
+ * and the `SERVICEME_HOME` env override without actually mutating
+ * `process.env` (which would leak into other tests).
+ */
+interface UserHomeOverrides {
+    homeDir?: string | undefined;
+    servicemeHomeEnv?: string | undefined;
+    platform?: NodeJS.Platform | undefined;
+}
+declare function setUserHomeOverrides(overrides: UserHomeOverrides): void;
+declare function resetUserHomeOverrides(): void;
+declare function assertSafeRepoId(repoId: string): string;
+/**
+ * The raw OS home directory (`os.homedir()`), honoring test overrides
+ * ({@link setUserHomeOverrides}). Exported for callers that need a
+ * home-relative path *outside* of `~/.serviceme` — e.g. the
+ * `~/.agents/{skills,agents}` convention used by `SkillLinker` for
+ * user-scope links.
+ */
+declare function getHomeDir(): string;
+/**
+ * Root directory for all SERVICEME user-level state. Resolves to
+ * `${SERVICEME_HOME}` when that env var is set, otherwise `${HOME}/.serviceme`
+ * (POSIX) or `%USERPROFILE%\.serviceme` (Windows via `os.homedir`).
+ */
+declare function getServicemeHome(): string;
+/** `$HOME/.serviceme/repos` (or `${SERVICEME_HOME}/repos`). */
+declare function getReposDir(): string;
+/** `$HOME/.serviceme/repos/<repoId>` — validates `repoId` first. */
+declare function getRepoDir(repoId: string): string;
+/** `$HOME/.serviceme/cache` — generic per-user cache. */
+declare function getCacheDir(): string;
+/** `$HOME/.serviceme/cache/<repoId>` — per-repo sync state lives here. */
+declare function getRepoCacheDir(repoId: string): string;
+/** `$HOME/.serviceme/drafts` — local edits not yet pushed upstream. */
+declare function getDraftsDir(): string;
+/** `$HOME/.serviceme/drafts/skills` — local skill drafts. */
+declare function getSkillDraftsDir(): string;
+/** `$HOME/.serviceme/drafts/agents` — local agent drafts. */
+declare function getAgentDraftsDir(): string;
+/**
+ * `$HOME/.serviceme/repos.json` — the single config entry point for repo
+ * metadata. Always under the resolved home root (i.e. follows
+ * `SERVICEME_HOME` overrides too).
+ */
+declare function getReposConfigPath(): string;
+/**
+ * Convenience helper for callers that need to switch behaviour on platform
+ * (e.g. `SkillLinker` chooses symlink vs junction). Exported mostly so tests
+ * can pin the value without touching `process.platform` directly.
+ */
+declare function getHomePlatform(): NodeJS.Platform;
+/** Layout constants for scheduled-tasks files. Kept here so other modules
+ * can reuse them and the names stay in sync with the design doc. */
+declare const SCHEDULED_TASKS_CONFIG_FILENAME = "scheduled-tasks.json";
+declare const SCHEDULED_TASKS_LOG_FILENAME = "scheduled-tasks-log.json";
+declare const SCHEDULER_PID_FILENAME = "scheduler.pid";
+declare const SCHEDULER_LOCK_FILENAME = "scheduler.lock";
+declare const SCHEDULER_LOG_FILENAME = "scheduler.log";
+declare const MIGRATION_FAILURES_FILENAME = "migration-failures.json";
+declare const KNOWN_WORKSPACES_FILENAME = "known-workspaces.json";
+/** `~/.serviceme/scheduled-tasks.json` — the global v2 task list. */
+declare function getScheduledTasksConfigPath(): string;
+/** `~/.serviceme/scheduled-tasks-log.json` — the global execution log (200 LRU). */
+declare function getScheduledTasksLogPath(): string;
+/** `~/.serviceme/scheduler.pid` — global daemon PID file. */
+declare function getSchedulerPidPath(): string;
+/** `~/.serviceme/scheduler.lock` — global daemon startup flock. */
+declare function getSchedulerLockPath(): string;
+/** `~/.serviceme/scheduler.log` — global daemon log (daemon lifecycle, not task execution). */
+declare function getSchedulerLogPath(): string;
+/** `~/.serviceme/migration-failures.json` — diagnostics for failed v1→v2 imports. */
+declare function getMigrationFailuresPath(): string;
+/** `~/.serviceme/known-workspaces.json` — workspace list the extension has seen. */
+declare function getKnownWorkspacesPath(): string;
+/** Layout constants for the Phase 5 client-side state files. The server
+ * already has the corresponding routes (`/api/v1/auth/...`,
+ * `/api/v1/device/...`, etc.) — the client just needs the on-disk
+ * file paths + a first-run bootstrap so the auth/device/toolbox
+ * services can open + read them without a per-call existence check. */
+declare const CREDENTIALS_CONFIG_FILENAME = "credentials.json";
+declare const DEVICE_JSON_FILENAME = "device.json";
+declare const TOOLBOX_JSON_FILENAME = "toolbox.json";
+declare const MACHINE_ID_FILENAME = "machine-id";
+declare const PROFILES_JSON_FILENAME = "profiles.json";
+/** `~/.serviceme/credentials.json` — better-auth session tokens + refresh state (client-side cache). */
+declare function getCredentialsConfigPath(): string;
+/** `~/.serviceme/device.json` — device enrollment payload (id, public key fingerprint, claimed-by). */
+declare function getDeviceJsonPath(): string;
+/** `~/.serviceme/toolbox.json` — local toolbox state (installed tool refs, per-user prefs). */
+declare function getToolboxJsonPath(): string;
+/** `~/.serviceme/machine-id` — opaque stable per-install id (uuid v4 string, no JSON wrapper). */
+declare function getMachineIdPath(): string;
+/** `~/.serviceme/profiles.json` — cached projection of server-side profile rows; refresh on demand. */
+declare function getProfilesJsonPath(): string;
+
 declare const TOOL_RISK_MAP: Record<string, AgentToolRiskLevel>;
 declare function parseAgentToolPermissions(content: string): AgentToolPermission[];
 
+/**
+ * Spec §11.12 — Phase 5 client-side state bootstrap.
+ *
+ * The server already exposes the Phase 5 surface (better-auth session
+ * endpoints, device enrollment routes, toolbox + profile API). The
+ * client (extension + CLI) needs the on-disk files to exist on first
+ * run so that subsequent code can `readFile()` without an existence
+ * check, and so the user can grep `~/.serviceme/` and see the
+ * expected layout instead of an empty directory.
+ *
+ * Strategy: idempotently write the empty / default JSON for every
+ * Phase 5 file that doesn't already exist. Existing files are
+ * left untouched so the bootstrap can re-run on every extension
+ * activation without overwriting user state.
+ *
+ * All writes are `mkdir -p` + `writeFile` (no race), and failures
+ * are surfaced but never thrown — Phase 5 is auxiliary; the
+ * extension / CLI should keep working even if the user's home
+ * directory is read-only.
+ *
+ * @see docs/architecture/skill-agent-v2-repo.md §11.12
+ */
+interface BootstrapPhase5Result {
+    /** Files that were created by this run (already-existing files excluded). */
+    created: string[];
+    /** Files that were already present and left untouched. */
+    skipped: string[];
+    /** Files where the write attempt failed (e.g. read-only home). */
+    failed: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+/**
+ * Idempotently create the Phase 5 placeholder files under
+ * `~/.serviceme/`. Safe to call on every extension activation —
+ * existing files are detected via `access` and skipped.
+ */
+declare function bootstrapPhase5Placeholders(): Promise<BootstrapPhase5Result>;
+
 declare class ProjectTools {
     extractTemplate(zipPath: string, workspacePath: string, tempExtractDir: string, input: ServiceMeProjectExtractTemplateInput): Promise<ServiceMeProjectExtractTemplateResult>;
     installDependencies(workspacePath: string, command?: string): Promise<ServiceMeProjectInstallDepsResult>;
@@ -207,17 +488,890 @@ declare class ProjectTools {
 }
 declare function createProjectTools(): ProjectTools;
 
+/**
+ * `repos.json` schema — mirrors §3 of docs/architecture/skill-agent-v2-repo.md.
+ *
+ * The on-disk file lives at `${SERVICEME_HOME}/repos.json` (see
+ * `paths/userHome.getReposConfigPath`). It holds the user-visible catalog of
+ * skill/agent repositories (default + user-added) plus the currently-selected
+ * default.
+ *
+ * Two flavours of repo:
+ *   - `DefaultRepoConfig` — hardcoded by SERVICEME; can only be disabled, not
+ *     removed.
+ *   - `UserRepoConfig` — added by the user via the "Add repository" flow;
+ *     can be removed freely.
+ *
+ * Both extend `RepoConfig` and add a `source` discriminant so consumers can
+ * branch on `repo.source === 'default' | 'user'` without sniffing free-form
+ * fields.
+ */
+/** ISO 8601 timestamp. */
+type IsoTimestamp = string;
+/** Per-repo sync health — surfaced in the UI alongside the repo entry. */
+type SyncStatus = "ok" | "error";
+/** Discriminant on `RepoConfig.source` — narrow with a literal check. */
+type RepoSource = "default" | "user";
+/**
+ * Common shape shared by both default and user-added repos. Source lives on
+ * the type so we can keep the loader schema flat while still letting
+ * `DefaultRepoConfig` carry a `description`.
+ */
+interface RepoConfig {
+    /** Stable id used in on-disk paths (must match `SAFE_REPO_ID_PATTERN`). */
+    id: string;
+    /** Display name shown in UI. */
+    name: string;
+    /** Upstream git URL (typically github.com/<owner>/<repo>.git). */
+    url: string;
+    /** Default branch to track (e.g. "v2", "main"). */
+    branch: string;
+    /** Whether this repo participates in scheduled syncs. */
+    enabled: boolean;
+    /** Whether the user is allowed to push back to this repo. */
+    writeEnabled: boolean;
+    /** When the user (or first-run installer) added this repo. */
+    addedAt: IsoTimestamp;
+    /** Last successful sync timestamp. */
+    lastSyncAt?: IsoTimestamp;
+    /** Commit SHA at the time of the last successful sync. */
+    lastSyncCommitSha?: string;
+    /** Result of the most recent sync attempt. */
+    lastSyncStatus?: SyncStatus;
+    /** Error message from the most recent sync attempt (when `lastSyncStatus === 'error'`). */
+    lastSyncError?: string;
+    /** Whether this repo is a default or a user-added repo. */
+    source: RepoSource;
+}
+/** A default (bundled) repo — has a UI-facing description, cannot be removed. */
+interface DefaultRepoConfig extends RepoConfig {
+    source: "default";
+    description: string;
+}
+/** A user-added repo — can be added, removed, disabled freely. */
+interface UserRepoConfig extends RepoConfig {
+    source: "user";
+}
+/** Any repo, regardless of source. */
+type AnyRepoConfig = DefaultRepoConfig | UserRepoConfig;
+/**
+ * Root shape of `repos.json`. `version` lets us evolve the schema later
+ * without colliding with hand-edited files.
+ */
+interface ReposFile {
+    version: 1;
+    /** Id of the repo currently surfaced as the default selection in the UI. */
+    defaultRepoId: string;
+    repos: AnyRepoConfig[];
+}
+/**
+ * Convenience type-guard — narrows to `DefaultRepoConfig`. Useful when callers
+ * want to render `repo.description` or reject `removeRepo(repo)` for defaults.
+ */
+declare function isDefaultRepo(repo: RepoConfig): repo is DefaultRepoConfig;
+/** Convenience type-guard — narrows to `UserRepoConfig`. */
+declare function isUserRepo(repo: RepoConfig): repo is UserRepoConfig;
+
+declare const defaultRepoSchema: z.ZodObject<{
+    source: z.ZodLiteral<"default">;
+    description: z.ZodString;
+    id: z.ZodString;
+    name: z.ZodString;
+    url: z.ZodString;
+    branch: z.ZodString;
+    enabled: z.ZodBoolean;
+    writeEnabled: z.ZodBoolean;
+    addedAt: z.ZodString;
+    lastSyncAt: z.ZodOptional<z.ZodString>;
+    lastSyncCommitSha: z.ZodOptional<z.ZodString>;
+    lastSyncStatus: z.ZodOptional<z.ZodEnum<["ok", "error"]>>;
+    lastSyncError: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    description: string;
+    source: "default";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}, {
+    name: string;
+    id: string;
+    description: string;
+    source: "default";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}>;
+declare const userRepoSchema: z.ZodObject<{
+    source: z.ZodLiteral<"user">;
+    id: z.ZodString;
+    name: z.ZodString;
+    url: z.ZodString;
+    branch: z.ZodString;
+    enabled: z.ZodBoolean;
+    writeEnabled: z.ZodBoolean;
+    addedAt: z.ZodString;
+    lastSyncAt: z.ZodOptional<z.ZodString>;
+    lastSyncCommitSha: z.ZodOptional<z.ZodString>;
+    lastSyncStatus: z.ZodOptional<z.ZodEnum<["ok", "error"]>>;
+    lastSyncError: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    source: "user";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}, {
+    name: string;
+    id: string;
+    source: "user";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}>;
+declare const repoSchema: z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
+    source: z.ZodLiteral<"default">;
+    description: z.ZodString;
+    id: z.ZodString;
+    name: z.ZodString;
+    url: z.ZodString;
+    branch: z.ZodString;
+    enabled: z.ZodBoolean;
+    writeEnabled: z.ZodBoolean;
+    addedAt: z.ZodString;
+    lastSyncAt: z.ZodOptional<z.ZodString>;
+    lastSyncCommitSha: z.ZodOptional<z.ZodString>;
+    lastSyncStatus: z.ZodOptional<z.ZodEnum<["ok", "error"]>>;
+    lastSyncError: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    description: string;
+    source: "default";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}, {
+    name: string;
+    id: string;
+    description: string;
+    source: "default";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}>, z.ZodObject<{
+    source: z.ZodLiteral<"user">;
+    id: z.ZodString;
+    name: z.ZodString;
+    url: z.ZodString;
+    branch: z.ZodString;
+    enabled: z.ZodBoolean;
+    writeEnabled: z.ZodBoolean;
+    addedAt: z.ZodString;
+    lastSyncAt: z.ZodOptional<z.ZodString>;
+    lastSyncCommitSha: z.ZodOptional<z.ZodString>;
+    lastSyncStatus: z.ZodOptional<z.ZodEnum<["ok", "error"]>>;
+    lastSyncError: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    source: "user";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}, {
+    name: string;
+    id: string;
+    source: "user";
+    url: string;
+    branch: string;
+    enabled: boolean;
+    writeEnabled: boolean;
+    addedAt: string;
+    lastSyncAt?: string | undefined;
+    lastSyncCommitSha?: string | undefined;
+    lastSyncStatus?: "ok" | "error" | undefined;
+    lastSyncError?: string | undefined;
+}>]>;
+declare const reposFileSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    defaultRepoId: z.ZodString;
+    repos: z.ZodArray<z.ZodDiscriminatedUnion<"source", [z.ZodObject<{
+        source: z.ZodLiteral<"default">;
+        description: z.ZodString;
+        id: z.ZodString;
+        name: z.ZodString;
+        url: z.ZodString;
+        branch: z.ZodString;
+        enabled: z.ZodBoolean;
+        writeEnabled: z.ZodBoolean;
+        addedAt: z.ZodString;
+        lastSyncAt: z.ZodOptional<z.ZodString>;
+        lastSyncCommitSha: z.ZodOptional<z.ZodString>;
+        lastSyncStatus: z.ZodOptional<z.ZodEnum<["ok", "error"]>>;
+        lastSyncError: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        description: string;
+        source: "default";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    }, {
+        name: string;
+        id: string;
+        description: string;
+        source: "default";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    }>, z.ZodObject<{
+        source: z.ZodLiteral<"user">;
+        id: z.ZodString;
+        name: z.ZodString;
+        url: z.ZodString;
+        branch: z.ZodString;
+        enabled: z.ZodBoolean;
+        writeEnabled: z.ZodBoolean;
+        addedAt: z.ZodString;
+        lastSyncAt: z.ZodOptional<z.ZodString>;
+        lastSyncCommitSha: z.ZodOptional<z.ZodString>;
+        lastSyncStatus: z.ZodOptional<z.ZodEnum<["ok", "error"]>>;
+        lastSyncError: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        id: string;
+        source: "user";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    }, {
+        name: string;
+        id: string;
+        source: "user";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    }>]>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    repos: ({
+        name: string;
+        id: string;
+        description: string;
+        source: "default";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    } | {
+        name: string;
+        id: string;
+        source: "user";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    })[];
+    defaultRepoId: string;
+}, {
+    version: 1;
+    repos: ({
+        name: string;
+        id: string;
+        description: string;
+        source: "default";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    } | {
+        name: string;
+        id: string;
+        source: "user";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    })[];
+    defaultRepoId: string;
+}>, {
+    version: 1;
+    repos: ({
+        name: string;
+        id: string;
+        description: string;
+        source: "default";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    } | {
+        name: string;
+        id: string;
+        source: "user";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    })[];
+    defaultRepoId: string;
+}, {
+    version: 1;
+    repos: ({
+        name: string;
+        id: string;
+        description: string;
+        source: "default";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    } | {
+        name: string;
+        id: string;
+        source: "user";
+        url: string;
+        branch: string;
+        enabled: boolean;
+        writeEnabled: boolean;
+        addedAt: string;
+        lastSyncAt?: string | undefined;
+        lastSyncCommitSha?: string | undefined;
+        lastSyncStatus?: "ok" | "error" | undefined;
+        lastSyncError?: string | undefined;
+    })[];
+    defaultRepoId: string;
+}>;
+/** Inferred Zod type — identical to our hand-written `ReposFile`. */
+type ReposFileInput = z.infer<typeof reposFileSchema>;
+/** Result of a load attempt — either a parsed file or a recovery notice. */
+interface LoadResult {
+    /** Parsed + validated repos file (always populated, even on recovery). */
+    config: ReposFile;
+    /**
+     * Non-null when the existing file on disk was unreadable / invalid and
+     * was moved aside as a `.bak`. The store can use this to surface a
+     * warning in the UI.
+     */
+    recoveredFromBackup: string | null;
+}
+/** Dependencies — defaults to the real fs, tests inject a fake. */
+interface ReposLoaderFileSystem {
+    readFile: typeof fs.readFile;
+    writeFile: typeof fs.writeFile;
+    rename: typeof fs.rename;
+    mkdir: typeof fs.mkdir;
+    stat: typeof fs.stat;
+    unlink?: typeof fs.unlink;
+}
+interface ReposLoaderOptions {
+    /** Absolute path of the `repos.json` file. */
+    configPath: string;
+    /** Custom time provider — defaults to `() => new Date().toISOString()`. */
+    now?: () => string;
+    /** Random suffix provider for atomic-write temp files. */
+    randomSuffix?: () => string;
+    /** Filesystem shim for tests. */
+    fileSystem?: ReposLoaderFileSystem;
+}
+declare class ReposLoader {
+    private readonly configPath;
+    private readonly now;
+    private readonly randomSuffix;
+    private readonly fileSystem;
+    constructor(options: ReposLoaderOptions);
+    /** Absolute path of the file this loader reads/writes. */
+    getConfigPath(): string;
+    /**
+     * Read + validate the on-disk config. When the file is missing, returns a
+     * sentinel empty config (no backup is taken — that's expected on first
+     * run). When the file is corrupted, moves it to `<name>.<ts>.bak` and
+     * returns an empty config with `recoveredFromBackup` populated.
+     */
+    load(): Promise<LoadResult>;
+    /**
+     * Write the config to disk atomically. Writes to
+     * `<target>.tmp-<random>` then `rename`s over the target. The parent
+     * directory is created on demand.
+     */
+    save(config: ReposFile): Promise<void>;
+    /**
+     * Move the existing file to a timestamped `.bak` sibling and return the
+     * backup path. Used when we detect a corrupted / unparseable file and
+     * need to make room for a fresh write.
+     */
+    private quarantine;
+    /**
+     * Empty config used when no file exists or the existing file is corrupt.
+     * The caller (e.g. `ensureDefaultsInstalled`) is expected to populate the
+     * real default repo set before persisting.
+     */
+    private buildEmptyConfig;
+}
+
+/** Helper: parse + validate a config object (e.g. freshly built in memory). */
+declare function validateReposFile(input: unknown): ReposFile;
+/** Helper: discriminate a `RepoConfig` between default and user flavours. */
+declare function narrowRepoConfig(repo: AnyRepoConfig): DefaultRepoConfig | UserRepoConfig;
+
+/**
+ * In-memory CRUD store for `repos.json`.
+ *
+ * Responsibilities:
+ *   - Hold the authoritative `ReposFile` state in memory.
+ *   - Re-load on `fs.watch` events so external writes (CLI edit, user edit)
+ *     propagate to in-process consumers (extension UI, bridge calls).
+ *   - Emit `change` events so consumers can re-render without polling.
+ *   - Validate every write through {@link ReposLoader} so a programmatic
+ *     `addRepo` cannot smuggle in a malformed entry.
+ *
+ * The store deliberately does **not** own `fs.watch` resources by default.
+ * Callers opt in via {@link ReposStore.startWatching} / {@link stopWatching}
+ * so tests can run without lingering watchers.
+ */
+/** Mutating event from the store. */
+type ReposStoreChange = {
+    kind: "load";
+    config: ReposFile;
+} | {
+    kind: "add";
+    repo: AnyRepoConfig;
+} | {
+    kind: "update";
+    repo: AnyRepoConfig;
+} | {
+    kind: "remove";
+    repoId: string;
+} | {
+    kind: "default-change";
+    defaultRepoId: string;
+} | {
+    kind: "error";
+    error: Error;
+};
+/** Subscriber callback. */
+type ReposStoreListener = (change: ReposStoreChange) => void;
+/** Dependencies — defaults to the real fs, tests inject a fake. */
+interface ReposStoreFileSystem {
+    watch: typeof fs$1.watch;
+}
+interface ReposStoreOptions {
+    /** Use an explicit loader (defaults to one wrapping the resolved configPath). */
+    loader?: ReposLoader;
+    /** File-system watch implementation — defaults to `fs.watch`. */
+    fileSystem?: ReposStoreFileSystem;
+    /** Time provider for `addedAt` stamping. */
+    now?: () => string;
+    /**
+     * Debounce window for `fs.watch` callbacks. Editors sometimes emit
+     * multiple `change` events for a single logical write — coalesce them.
+     * Defaults to 50ms.
+     */
+    debounceMs?: number;
+    /**
+     * Watch implementation factory — defaults to a no-deps wrapper around
+     * `fs.watch`. Tests inject a fake watcher here. The store wires the
+     * returned handle to its own schedule/error flow via the supplied
+     * callbacks.
+     */
+    createFsWatcher?: (configPath: string, callbacks: FsWatcherCallbacks) => FsWatcherHandle;
+}
+/**
+ * Minimal subset of `fs.FSWatcher` that the store depends on. Defining our
+ * own type lets tests inject a fake without dragging in real fs handles.
+ */
+interface FsWatcherHandle {
+    close(): void;
+}
+/**
+ * Callbacks the store wires to a watcher. The default `fs.watch` factory
+ * uses these to forward events into `scheduleReload` / `error` emission;
+ * tests can ignore them when they only care about lifecycle.
+ */
+interface FsWatcherCallbacks {
+    onChange?: () => void;
+    onRename?: () => void;
+    onError?: (err: Error) => void;
+}
+declare class ReposStore {
+    private readonly loader;
+    private readonly fileSystem;
+    private readonly now;
+    private readonly debounceMs;
+    private readonly createFsWatcher;
+    private config;
+    private readonly emitter;
+    private watcher;
+    private reloadTimer;
+    private lastLoadResult;
+    constructor(options?: ReposStoreOptions);
+    /** Currently held config, or `null` if `load()` has not been called yet. */
+    getConfig(): ReposFile | null;
+    /** Path of the underlying `repos.json` file (via the loader). */
+    getConfigPath(): string;
+    /** Subscribe to store mutations. Returns an unsubscribe function. */
+    subscribe(listener: ReposStoreListener): () => void;
+    /**
+     * Read the config from disk (delegating to the loader) and seed the
+     * in-memory state. Safe to call repeatedly.
+     */
+    load(): Promise<LoadResult>;
+    /** Convenience getter — wraps `load()` and returns the config. */
+    ensureLoaded(): Promise<ReposFile>;
+    /** The most recent `LoadResult`, useful for surfacing recovery warnings. */
+    getLastLoadResult(): LoadResult | null;
+    /**
+     * Start watching the config file for external changes. Subsequent writes
+     * (or edits from another process) trigger a debounced re-load.
+     *
+     * No-op when already watching.
+     */
+    startWatching(): void;
+    /** Stop watching and release any pending reload timers. */
+    stopWatching(): void;
+    list(): AnyRepoConfig[];
+    listDefault(): AnyRepoConfig[];
+    listUser(): UserRepoConfig[];
+    get(repoId: string): AnyRepoConfig | undefined;
+    /**
+     * Add a user repo. Throws when the id already exists. The `addedAt`
+     * timestamp defaults to `now()` when not provided. Persists to disk.
+     */
+    addUserRepo(input: Omit<UserRepoConfig, "source">): Promise<UserRepoConfig>;
+    /**
+     * Update an existing repo by id (partial). Throws when not found.
+     * Persists to disk.
+     */
+    updateRepo(repoId: string, patch: Partial<RepoConfig>): Promise<AnyRepoConfig>;
+    /**
+     * Remove a user repo. Throws when the repo is a default or does not exist.
+     * Persists to disk.
+     */
+    removeUserRepo(repoId: string): Promise<void>;
+    /**
+     * Disable a repo (any source). Useful for the "Disable" button on default
+     * repos. Persists to disk.
+     */
+    disableRepo(repoId: string): Promise<AnyRepoConfig>;
+    /** Inverse of {@link disableRepo}. */
+    enableRepo(repoId: string): Promise<AnyRepoConfig>;
+    /** Change which repo the UI surfaces as the default. Persists to disk. */
+    setDefaultRepoId(repoId: string): Promise<void>;
+    getDefaultRepoId(): string | null;
+    /** Returns the configured `now` provider — exposed for `bootstrapDefaults`. */
+    getNow(): () => string;
+    /**
+     * Replace the in-memory config and persist it. Used by helpers like
+     * `bootstrapDefaults` that build a new config wholesale (rather than
+     * mutating a single field).
+     */
+    replaceConfig(next: ReposFile): Promise<ReposFile>;
+    private mutate;
+    private emit;
+    /**
+     * Default `fs.watch` adapter. Public so tests can wrap a real watcher
+     * with a debounce trampoline if they need to.
+     */
+    private defaultCreateFsWatcher;
+    private scheduleReload;
+}
+/** Factory: creates a `ReposStore` bound to a specific config path. */
+declare function createReposStore(configPath: string, options?: Omit<ReposStoreOptions, "loader">): ReposStore;
+/** Error: tried to add a repo whose id already exists. */
+declare class RepoAlreadyExistsError extends Error {
+    readonly repoId: string;
+    constructor(repoId: string);
+}
+/** Error: looked up a repo id that isn't present in the current config. */
+declare class RepoNotFoundError extends Error {
+    readonly repoId: string;
+    constructor(repoId: string);
+}
+/** Error: tried to remove a default repo (defaults are disable-only). */
+declare class CannotRemoveDefaultRepoError extends Error {
+    readonly repoId: string;
+    constructor(repoId: string);
+}
+/**
+ * Bootstrap helper — invokes `ensureDefaultsInstalled` on the store to
+ * guarantee that the 4 default repos are present. Returns the resulting
+ * config. Lives here (not in `default-repos.ts`) to keep the default-repo
+ * module free of store concerns.
+ */
+declare function bootstrapDefaults(store: ReposStore): Promise<ReposFile>;
+
+/**
+ * Skill & Agent v2 — Client RepoManager (M3)
+ *
+ * RepoManager is the orchestrator for local git repo management. It
+ * composes:
+ *   - {@link ReposStore} (in-memory CRUD over `~/.serviceme/repos.json`)
+ *   - {@link GitClient} (spawns `git` against the server proxy)
+ *   - the filesystem (clone targets live under `~/.serviceme/repos/<id>/`)
+ *
+ * Lifecycle responsibilities:
+ *   - **Bootstrap**: on first launch, clone all enabled default repos.
+ *   - **Sync**: pullOne / pullAll for periodic updates.
+ *   - **User repos**: addUserRepo validates URL, probes branch via
+ *     `git ls-remote`, writes the entry, and triggers an async clone.
+ *   - **Cleanup**: removeUserRepo deletes both the local clone AND the
+ *     `repos.json` entry. disableRepo / enableRepo only flip a flag.
+ *
+ * Default repos (`source === 'default'`) cannot be removed — only
+ * disabled. The Store enforces this; RepoManager propagates the error.
+ *
+ * @see docs/architecture/skill-agent-v2-repo.md §5.3 RepoManager
+ */
+interface RepoManagerOptions {
+    store: ReposStore;
+    gitClient: GitClient;
+    /** Override the clock for deterministic tests. */
+    now?: () => string;
+    /** Skip the actual git clone (used by tests). When true, the
+     *  filesystem-side mkdir is the only side effect. */
+    skipClone?: boolean;
+}
+interface AddUserRepoInput {
+    /** Upstream URL the user pasted in. */
+    url: string;
+    /** Branch to track. Auto-detected from upstream when omitted. */
+    branch?: string;
+    /** Optional display name (defaults to id). */
+    name?: string;
+}
+interface AddUserRepoResult {
+    repo: UserRepoConfig;
+    branch: string;
+    cloned: boolean;
+}
+/** Snapshot of a sync run, suitable for UI rendering. */
+interface SyncReport {
+    pulls: Array<{
+        repoId: string;
+        status: "ok" | "error";
+        result?: PullResult;
+        error?: string;
+    }>;
+}
+/** Sentinel errors. */
+declare class RepoManagerError extends Error {
+    constructor(message: string);
+}
+declare class InvalidRepoUrlError extends RepoManagerError {
+}
+declare class RepoCloneConflictError extends RepoManagerError {
+}
+declare class RepoNotInStoreError extends RepoManagerError {
+}
+declare class RepoManager {
+    private readonly store;
+    private readonly git;
+    private readonly now;
+    private readonly skipClone;
+    constructor(opts: RepoManagerOptions);
+    /**
+     * Clone every enabled default repo that doesn't have a local clone
+     * yet. Failures on individual repos are recorded in `lastSyncStatus`
+     * but do NOT abort the loop — the UI surfaces per-repo state and the
+     * user can retry.
+     *
+     * Per spec §3.1: 4 default repos; the loop honors `enabled=false` and
+     * disables (rather than removes) repos the user has turned off.
+     */
+    ensureDefaults(): Promise<SyncReport>;
+    /**
+     * Pull a single repo. Updates `lastSync*` fields on success or failure.
+     * Returns the raw `PullResult` so callers can surface fetch progress.
+     */
+    pullOne(repoId: string): Promise<PullResult>;
+    /** Pull every enabled repo. Per-repo failures don't abort the run. */
+    pullAll(): Promise<SyncReport>;
+    /**
+     * Validate URL, derive an id, detect the branch via `git ls-remote`,
+     * then add the entry to the store and trigger a clone.
+     *
+     * 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
+     * (cloning happens via `ensureDefaults`-style background fire).
+     *
+     * For tests with `skipClone: true`, the clone is skipped entirely.
+     */
+    addUserRepo(input: AddUserRepoInput): Promise<AddUserRepoResult>;
+    /**
+     * Remove a user-added repo. Throws when:
+     *   - the repo is unknown
+     *   - the repo is a default (use `disableRepo` instead — store enforces)
+     *
+     * The local clone is deleted via `fs.rm`. If the local dir is
+     * already gone we silently succeed (idempotent re-remove).
+     */
+    removeUserRepo(repoId: string): Promise<void>;
+    disableRepo(repoId: string): Promise<AnyRepoConfig>;
+    enableRepo(repoId: string): Promise<AnyRepoConfig>;
+    /** `true` when `~/.serviceme/repos/<id>/` exists on disk. */
+    hasLocalClone(repoId: string): Promise<boolean>;
+    /** Force-create the SERVICEME home directory tree (idempotent). */
+    ensureHome(): Promise<void>;
+    private pathExists;
+}
+
+/**
+ * Hard-coded catalog of repositories SERVICEME ships with. The id, URL and
+ * branch are pinned by the design doc (§12) and **must not** change without
+ * an owner-approved migration. The order here mirrors the on-disk
+ * `repos.json` order (§3.1) which the UI relies on.
+ */
+declare const DEFAULT_REPO_ID = "medalsoftchina-ms-skills";
+declare const FIXED_ADDED_AT = "2026-06-29T00:00:00.000Z";
+/** Returns a deep-ish clone of every default repo with a fresh `addedAt`. */
+declare function getAllDefaultRepoConfigs(now?: () => string): DefaultRepoConfig[];
+/** Returns a single default repo by id, or `undefined` when not in the catalog. */
+declare function getDefaultRepoConfig(id: string, now?: () => string): DefaultRepoConfig | undefined;
+/**
+ * Idempotent: returns a fresh `ReposFile` containing the default set, or —
+ * when `existing` already has all four — returns it untouched (still cloned
+ * to keep callers from accidentally mutating shared state).
+ */
+declare function buildDefaultReposFile(now?: () => string, existing?: ReposFile): ReposFile;
+/**
+ * `ensureDefaultsInstalled(existing)` — pure helper that returns either
+ * `existing` (when defaults are already present) or a merged copy that
+ * appends the missing defaults. The companion `ensureDefaultsInstalledInStore`
+ * below is the mutating, store-bound counterpart.
+ */
+declare function ensureDefaultsInstalled(existing: ReposFile, now?: () => string): {
+    config: ReposFile;
+    installed: string[];
+};
+
 declare class DaemonLogger {
     private readonly logPath;
-    constructor(workspacePath: string);
+    constructor(workspacePath: string, options?: {
+        logPath?: string;
+    });
     getLogPath(): string;
     log(level: "info" | "warn" | "error", message: string): void;
     private rotateIfNeeded;
 }
 
+interface PidManagerOptions {
+    /**
+     * Override the on-disk PID path. Defaults to
+     * `<workspacePath>/.serviceme/scheduler.pid` for backward compat.
+     * V2 callers pass an absolute path (e.g. `getSchedulerPidPath()`)
+     * to read the global daemon PID file.
+     */
+    pidPath?: string;
+}
 declare class PidManager {
     private readonly pidPath;
-    constructor(workspacePath: string);
+    constructor(workspacePath: string, options?: PidManagerOptions);
     getPidPath(): string;
     writePid(pid: number): void;
     readPid(): number | null;
@@ -269,6 +1423,12 @@ interface SchedulerDaemonOptions {
      */
     getExecutor?: typeof getExecutor;
 }
+/**
+ * @deprecated v1 per-workspace daemon. Superseded by `SchedulerDaemonV2` in
+ * `daemon/SchedulerDaemonV2.ts` for the global single-instance model. Kept
+ * temporarily so callers can roll back to v1 behaviour during the M1.5
+ * transition. New code should use SchedulerDaemonV2.
+ */
 declare class SchedulerDaemon {
     private readonly workspacePath;
     private readonly configManager;
@@ -310,6 +1470,7 @@ interface CreateTaskInput {
     schedule: string;
     taskType: ScheduledTaskType;
     payload: TaskPayload;
+    workspace: TaskWorkspaceRef;
     enabled?: boolean;
 }
 interface EditTaskInput {
@@ -319,13 +1480,45 @@ interface EditTaskInput {
     schedule?: string;
     taskType?: ScheduledTaskType;
     payload?: TaskPayload;
+    workspace?: TaskWorkspaceRef;
     enabled?: boolean;
 }
+interface TaskConfigManagerOptions {
+    /**
+     * Override the on-disk config path. Defaults to the global
+     * `~/.serviceme/scheduled-tasks.json`. Tests use this to point at a tmp
+     * directory; production code should leave it unset.
+     */
+    configPath?: string;
+    /**
+     * Workspace context used when a legacy v1 config is read. v1 tasks had no
+     * per-task workspace, so the manager needs a fallback to attach when
+     * auto-migrating. Required only if the underlying file might still be v1.
+     */
+    workspaceContext?: TaskWorkspaceRef;
+    /**
+     * Override the path where malformed-config diagnostic entries are appended.
+     * Defaults to `~/.serviceme/migration-failures.json`. Tests can point at a
+     * tmp file to assert failures were recorded.
+     */
+    migrationFailuresPath?: string;
+    /**
+     * Inject a logger for the manager's recovery / migration warnings. Defaults
+     * to `console.warn`. Tests pass a `vi.fn`/`mock.fn` to assert the warnings
+     * were emitted.
+     */
+    logger?: (message: string) => void;
+}
 declare class TaskConfigManager {
     private readonly configPath;
-    constructor(workspacePath: string);
+    private readonly workspaceContext?;
+    private readonly migrationFailuresPath?;
+    private readonly logger?;
+    constructor(options?: TaskConfigManagerOptions);
     getConfigPath(): string;
     readConfig(): ScheduledTasksConfig;
+    private warn;
+    private recordMalformedConfigFailure;
     private writeConfig;
     listTasks(): ScheduledTask[];
     getTask(id: string): ScheduledTask | undefined;
@@ -336,27 +1529,6 @@ declare class TaskConfigManager {
     toggleTask(id: string, enabled: boolean): ScheduledTask;
 }
 
-interface TaskEventListener {
-    onStarted(params: TaskStartedEventParams): void;
-    onOutput(params: TaskOutputEventParams): void;
-    onCompleted(params: TaskCompletedEventParams): void;
-    onFailed(params: TaskFailedEventParams): void;
-    onCancelled(params: TaskCancelledEventParams): void;
-}
-declare function resolveTaskExecutionPayload(taskType: ScheduledTaskType, payload: TaskPayload, workspacePath: string): TaskPayload;
-declare class TaskExecutionEngine {
-    private readonly getExecutor;
-    private readonly running;
-    private readonly taskExecutions;
-    private listener;
-    constructor(getExecutor: (taskType: string) => TaskExecutor);
-    setListener(listener: TaskEventListener): void;
-    execute(snapshot: TaskExecutionSnapshot): Promise<void>;
-    cancel(executionId: string): boolean;
-    listRunning(): RunningTaskInfo[];
-    dispose(): void;
-}
-
 interface AppendLogInput {
     taskId: string;
     taskName: string;
@@ -366,9 +1538,17 @@ interface AppendLogInput {
     output?: string;
     error?: string;
 }
+interface TaskLogManagerOptions {
+    /**
+     * Override the on-disk log path. Defaults to the global
+     * `~/.serviceme/scheduled-tasks-log.json`. Tests use this to point at a
+     * tmp directory; production code should leave it unset.
+     */
+    logPath?: string;
+}
 declare class TaskLogManager {
     private readonly logPath;
-    constructor(workspacePath: string);
+    constructor(options?: TaskLogManagerOptions);
     getLogPath(): string;
     private readLogFile;
     private backupCorruptedFile;
@@ -384,6 +1564,164 @@ declare class TaskLogManager {
     clearLogs(taskId?: string): number;
 }
 
+interface SchedulerDaemonV2Options {
+    /**
+     * Override the executor factory. Production callers should leave this
+     * undefined; tests inject a fake to drive the execution branch without
+     * spawning real subprocesses.
+     */
+    getExecutor?: typeof getExecutor;
+    /** Override the config manager. Tests inject a fake pointing at a tmp dir. */
+    configManager?: TaskConfigManager;
+    /** Override the log manager. */
+    logManager?: TaskLogManager;
+    /** Override the PID manager. */
+    pidManager?: PidManager;
+    /** Override the daemon logger (for tests; the default writes to ~/.serviceme/scheduler.log). */
+    logger?: DaemonLogger;
+    /** Override the startup lock acquisition (tests use this to inject "lock held" / "lock free"). */
+    tryAcquireLock?: () => boolean;
+    /** Override the startup lock release. */
+    releaseLock?: () => void;
+    /**
+     * Override the PID file existence + process liveness check. Production
+     * reads PID file + `process.kill(pid, 0)`; tests inject a stub.
+     */
+    getRunningPid?: () => number | null;
+}
+declare class SchedulerDaemonV2 {
+    private readonly configManager;
+    private readonly logManager;
+    private readonly pidManager;
+    private readonly logger;
+    private readonly getExecutor;
+    private readonly tryAcquireLock;
+    private readonly releaseLock;
+    private readonly getRunningPid;
+    private tickTimer;
+    private running;
+    private readonly sigtermHandler;
+    private readonly sigintHandler;
+    private startTime;
+    private lastRun;
+    private workspaceLocks;
+    constructor(options?: SchedulerDaemonV2Options);
+    start(): void;
+    stop(): void;
+    private tick;
+    private disableTaskForMissingWorkspace;
+    private shouldRun;
+    private executeTask;
+    getStatus(): {
+        running: boolean;
+        pid: number;
+        uptimeSeconds: number | null;
+        tasksRegistered: number;
+        tasksEnabled: number;
+        pidFile: string;
+    };
+}
+
+interface MigrateToGlobalOptions {
+    /**
+     * Workspace paths to scan for legacy v1 files. May include the current
+     * workspace + any persisted in `~/.serviceme/known-workspaces.json`.
+     */
+    workspacePaths: string[];
+    /**
+     * Workspace context to apply to each scanned file. The scanner calls the
+     * probe for each candidate path to populate path/name/git metadata.
+     * Tests can inject a stub that returns synthetic data.
+     */
+    probe?: (workspacePath: string) => Promise<TaskWorkspaceRef> | TaskWorkspaceRef;
+    /**
+     * Override the global config path. Tests use this; production should
+     * leave it unset to get the standard ~/.serviceme/scheduled-tasks.json.
+     */
+    globalConfigPath?: string;
+    /**
+     * Override the migration-failures path. Same convention.
+     */
+    migrationFailuresPath?: string;
+}
+interface MigrationResult {
+    /** Number of v1 files successfully migrated into the global config. */
+    migrated: number;
+    /** Number of v1 files that failed to parse / migrate. */
+    failed: number;
+    /** Task names that had to be disambiguated because they appeared in multiple workspaces. */
+    conflicts: string[];
+    /** Soft issues surfaced by migrateV1ToV2 (e.g. unknown taskType). */
+    issues: string[];
+}
+declare class MigrateToGlobal {
+    /**
+     * Run the migration. Idempotent: each v1 file is deleted after processing,
+     * so re-running this method on a partially-migrated state is safe (the
+     * already-migrated files no longer exist; only the remainder is processed).
+     */
+    static run(options: MigrateToGlobalOptions): Promise<MigrationResult>;
+}
+
+interface TaskEventListener {
+    onStarted(params: TaskStartedEventParams): void;
+    onOutput(params: TaskOutputEventParams): void;
+    onCompleted(params: TaskCompletedEventParams): void;
+    onFailed(params: TaskFailedEventParams): void;
+    onCancelled(params: TaskCancelledEventParams): void;
+}
+declare function resolveTaskExecutionPayload(taskType: ScheduledTaskType, payload: TaskPayload, workspacePath: string): TaskPayload;
+declare class TaskExecutionEngine {
+    private readonly getExecutor;
+    private readonly running;
+    private readonly taskExecutions;
+    private listener;
+    constructor(getExecutor: (taskType: string) => TaskExecutor);
+    setListener(listener: TaskEventListener): void;
+    execute(snapshot: TaskExecutionSnapshot): Promise<void>;
+    cancel(executionId: string): boolean;
+    listRunning(): RunningTaskInfo[];
+    dispose(): void;
+}
+
+/** Result of probing a single workspace. */
+interface ProbeResult {
+    /** Always populated; empty fields are left undefined. */
+    workspace: TaskWorkspaceRef;
+    /** null on success; one of the {@link ProbeError} tags on failure. */
+    error: ProbeError | null;
+}
+type ProbeError = "path-not-found" | "not-a-git-repo" | "git-timeout" | "git-error";
+interface ProbeOptions {
+    /** Timeout for each git invocation in ms. Default: 2000. */
+    timeoutMs?: number;
+    /** Override the git binary (default: 'git'). Tests inject a stub. */
+    gitBinary?: string;
+    /**
+     * Override the underlying runner. Receives the args + cwd and returns
+     * { stdout, stderr, code } on success, or throws on timeout. The default
+     * implementation spawns `gitBinary` with the given args.
+     */
+    runGit?: (args: string[], cwd: string) => Promise<{
+        stdout: string;
+        stderr: string;
+        code: number;
+    }>;
+}
+/**
+ * Probes a workspace for git metadata. Returns a {@link ProbeResult} with
+ * `error: null` on success and an error tag on failure — the workspace
+ * descriptor is always populated so callers can still surface a partial
+ * record.
+ */
+declare class WorkspaceProbe {
+    private readonly timeoutMs;
+    private readonly gitBinary;
+    private readonly runGitFn;
+    constructor(options?: ProbeOptions);
+    probe(workspacePath: string): Promise<ProbeResult>;
+}
+
 interface SkillDownloadFile {
     path: string;
     content: string;
@@ -465,10 +1803,17 @@ declare class SkillStore {
     listUserSkillIds(): Promise<string[]>;
     writeManagedUserSkillMarker(skillId: string): Promise<void>;
     isManagedUserSkill(skillId: string): Promise<boolean>;
+    /**
+     * One-time migration: the user-scope skill marker used to be named
+     * `.ms-devtools-skill.json`. If the new `.serviceme-skill.json` doesn't
+     * exist yet but the legacy marker does, copy it forward so an existing
+     * skill doesn't lose its "managed" status.
+     */
+    private migrateLegacyUserSkillMarker;
     writeSkillFiles(skillId: string, scope: "workspace" | "user", files: SkillDownloadFile[]): Promise<void>;
 }
 
 declare const unzipFile: (zipPath: string, dest: string) => Promise<void>;
 declare const moveFiles: (sourceDir: string, destDir: string, overwrite?: boolean) => Promise<void>;
 
-export { type AgentCatalog, AgentCatalogClient, type AgentCatalogClientOptions, type AgentDownloadFile, type AgentInstallScope, type AgentMutateResult, AgentReconciler, type AgentReconcilerDependencies, AgentStore, type AgentStoreFileSystem, type AgentStoreOptions, type AgentsStateFile, type AppendLogInput, type CreateTaskInput, DaemonLogger, type EditTaskInput, EnvironmentInspector, type EnvironmentInspectorOptions, type ExecutorResult, GithubCopilotCliExecutor, HttpRequestExecutor, ImageTools, type InstalledAgent, type JsonTools, type OutputEventCallback, PidManager, ProjectTools, SchedulerDaemon, type ServiceMeLogger, ShellExecutor, type SkillCatalog, SkillCatalogClient, type SkillCatalogClientOptions, type SkillDownloadFile, type SkillMutateResult, SkillReconciler, type SkillReconcilerDependencies, SkillStore, type SkillStoreFileSystem, type SkillStoreOptions, type StreamingExecutorHandle, type StreamingTaskExecutor, TOOL_RISK_MAP, TaskConfigManager, type TaskEventListener, TaskExecutionEngine, type TaskExecutor, TaskLogManager, copilotDoctor, copilotPrompt, createConsoleLogger, createCopilotAuthRequiredError, createCopilotNotInstalledError, createImageTools, createJsonTools, createProjectTools, getExecutor, isCopilotAuthenticated, isStreamingTaskExecutor, matchesCron, moveFiles, noopLogger, parseAgentToolPermissions, parseIntervalMs, resolveTaskExecutionPayload, unzipFile, validateTaskPayload };
+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, MigrateToGlobal, 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, SERVICEME_DIR_NAME, SERVICEME_HOME_ENV, SKILL_DRAFTS_SUBDIR, type SaveDraftOptions, SchedulerDaemon, SchedulerDaemonV2, type SchedulerDaemonV2Options, type ServiceMeLogger, 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, createConsoleLogger, 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, getServicemeHome, getSkillDraftsDir, getToolboxJsonPath, isCopilotAuthenticated, isDefaultRepo, isStreamingTaskExecutor, isUserRepo, matchesCron, moveFiles, narrowRepoConfig, noopLogger, parseAgentToolPermissions, parseIntervalMs, reposFileSchema, resetUserHomeOverrides, resolveDraftDir, resolveTaskExecutionPayload, setUserHomeOverrides, unzipFile, userRepoSchema as userRepoConfigSchema, validateReposFile, validateTaskPayload };