deepline 0.1.260 → 0.1.261

package/dist/cli/index.mjs

@@ -701,7 +701,7 @@ var SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: "0.1.260",
+  version: "0.1.261",
   apiContract: "2026-07-native-monitor-launch-hard-cutover",
   supportPolicy: {
     minimumSupported: "0.1.53",
@@ -28940,7 +28940,7 @@ import {
   existsSync as existsSync12,
   mkdirSync as mkdirSync10,
   realpathSync as realpathSync3,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   renameSync,
   rmSync as rmSync4,
   unlinkSync,
@@ -28951,7 +28951,7 @@ import { dirname as dirname13, isAbsolute as isAbsolute3, join as join15, relati
 
 // src/cli/commands/skills.ts
 import { spawn as spawn3 } from "child_process";
-import { existsSync as existsSync11, mkdirSync as mkdirSync9, writeFileSync as writeFileSync14 } from "fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync14 } from "fs";
 import { homedir as homedir11 } from "os";
 import { dirname as dirname12, join as join14 } from "path";
 
@@ -29163,10 +29163,13 @@ function buildSkillsPlan(input2) {
     skillNames: input2.skillNames,
     version: input2.version,
     remove: {
-      command: "npx",
+      command: "npm",
       args: [
+        "exec",
         "--yes",
-        "skills@latest",
+        "--package=skills@latest",
+        "--",
+        "skills",
         "remove",
         ...scopeArgs,
         "--agent",
@@ -29176,10 +29179,13 @@ function buildSkillsPlan(input2) {
       ]
     },
     install: {
-      command: "npx",
+      command: "npm",
       args: [
+        "exec",
         "--yes",
-        "skills@latest",
+        "--package=skills@latest",
+        "--",
+        "skills",
         "add",
         skillsIndexUrl(input2.baseUrl),
         "--agent",
@@ -29193,6 +29199,29 @@ function buildSkillsPlan(input2) {
     statePath: skillsStatePathForScope(input2.baseUrl, input2.scope, input2.root)
   };
 }
+function sortedStrings(value) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    return null;
+  }
+  return [...value].sort((a, b) => a.localeCompare(b));
+}
+function isSkillsPlanCurrent(plan, state) {
+  if (!state || state.scope !== plan.scope || state.skillsVersion !== plan.version) {
+    return false;
+  }
+  const installedAgents = sortedStrings(state.agents);
+  const installedSkillNames = sortedStrings(state.skillNames);
+  if (!installedAgents || !installedSkillNames) return false;
+  return installedAgents.join("\0") === [...plan.agents].sort((a, b) => a.localeCompare(b)).join("\0") && installedSkillNames.join("\0") === [...plan.skillNames].sort((a, b) => a.localeCompare(b)).join("\0");
+}
+function readSkillsInstallState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync12(path, "utf8"));
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
 function runProcess(command, args, cwd) {
   return new Promise((resolve15, reject) => {
     const child = spawn3(command, args, {
@@ -29216,7 +29245,7 @@ function runProcess(command, args, cwd) {
     });
   });
 }
-async function runSkillsCommand(options) {
+async function runSkillsCommand(options, dependencies = {}) {
   let scope;
   let root;
   try {
@@ -29238,7 +29267,7 @@ async function runSkillsCommand(options) {
   const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
   let catalog;
   try {
-    catalog = options.dryRun ? { skillNames: [...DEFAULT_SDK_SKILL_NAMES], version: "latest" } : await fetchSkillCatalog(baseUrl);
+    catalog = options.dryRun ? { skillNames: [...DEFAULT_SDK_SKILL_NAMES], version: "latest" } : await (dependencies.fetchCatalog ?? fetchSkillCatalog)(baseUrl);
   } catch (error) {
     printCommandEnvelope(
       {
@@ -29262,6 +29291,37 @@ async function runSkillsCommand(options) {
     );
     return 0;
   }
+  if (isSkillsPlanCurrent(plan, readSkillsInstallState(plan.statePath))) {
+    printCommandEnvelope(
+      {
+        ok: true,
+        status: "current",
+        complete: true,
+        changed: false,
+        skipped: true,
+        skipReason: "skills_version_current",
+        scope,
+        agents,
+        skillsVersion: plan.version,
+        skillCount: plan.skillNames.length,
+        statePath: plan.statePath,
+        render: {
+          sections: [
+            {
+              title: "skills",
+              lines: [
+                `Scope: ${scope}`,
+                `Agents: ${agents.join(", ")}`,
+                `Current: ${plan.skillNames.length}`
+              ]
+            }
+          ]
+        }
+      },
+      { json: options.json }
+    );
+    return 0;
+  }
   if (scope === "local" && root) {
     const managedNames = [
       .../* @__PURE__ */ new Set([...plan.skillNames, ...LEGACY_SKILL_NAMES_TO_REMOVE])
@@ -29279,7 +29339,8 @@ async function runSkillsCommand(options) {
 `
   );
   try {
-    const removeCode = await runProcess(
+    const execute = dependencies.runProcess ?? runProcess;
+    const removeCode = await execute(
       plan.remove.command,
       plan.remove.args,
       root ?? void 0
@@ -29287,7 +29348,7 @@ async function runSkillsCommand(options) {
     if (removeCode !== 0) {
       throw new Error("Could not remove the existing Deepline skills.");
     }
-    const installCode = await runProcess(
+    const installCode = await execute(
       plan.install.command,
       plan.install.args,
       root ?? void 0
@@ -29456,7 +29517,7 @@ function publicNpmFallbackRegistryUrl(hostUrl) {
 }
 function readOptionalText(path) {
   try {
-    return readFileSync12(path, "utf8").trim();
+    return readFileSync13(path, "utf8").trim();
   } catch {
     return "";
   }
@@ -29596,7 +29657,7 @@ function readAutoUpdateFailure(plan) {
   if (!path) return null;
   try {
     const parsed = JSON.parse(
-      readFileSync12(path, "utf8")
+      readFileSync13(path, "utf8")
     );
     if ((parsed.kind === "npm-global" || parsed.kind === "python-sidecar") && typeof parsed.packageSpec === "string" && typeof parsed.failedAt === "string" && typeof parsed.exitCode === "number" && typeof parsed.manualCommand === "string") {
       return parsed;
@@ -29680,7 +29741,7 @@ function installedPackageVersion(versionDir) {
     "package.json"
   );
   try {
-    const parsed = JSON.parse(readFileSync12(packageJsonPath, "utf8"));
+    const parsed = JSON.parse(readFileSync13(packageJsonPath, "utf8"));
     return typeof parsed.version === "string" ? safeVersionSegment(parsed.version) : "";
   } catch {
     return "";
@@ -29993,13 +30054,92 @@ import {
   existsSync as existsSync13,
   lstatSync,
   mkdirSync as mkdirSync11,
-  readFileSync as readFileSync13,
+  readFileSync as readFileSync14,
   realpathSync as realpathSync4,
   rmSync as rmSync5,
   writeFileSync as writeFileSync16
 } from "fs";
 import { homedir as homedir13 } from "os";
 import { dirname as dirname14, join as join16, resolve as resolve14 } from "path";
+var SETUP_PHASE_NAMES = [
+  "cli",
+  "cleanup",
+  "skills",
+  "auth",
+  "verify"
+];
+function initialSetupPhases() {
+  return {
+    cli: { status: "pending" },
+    cleanup: { status: "pending" },
+    skills: { status: "pending" },
+    auth: { status: "pending" },
+    verify: { status: "pending" }
+  };
+}
+function isSetupPhaseStatus(value) {
+  return value === "pending" || value === "in_progress" || value === "complete" || value === "waiting" || value === "failed";
+}
+function parseSetupPhases(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const source = value;
+  const phases = initialSetupPhases();
+  for (const name of SETUP_PHASE_NAMES) {
+    const phase = source[name];
+    if (!phase || typeof phase !== "object" || Array.isArray(phase)) {
+      return null;
+    }
+    const record = phase;
+    if (!isSetupPhaseStatus(record.status)) return null;
+    phases[name] = {
+      status: record.status,
+      ...typeof record.outcome === "string" ? { outcome: record.outcome } : {},
+      ...typeof record.code === "string" ? { code: record.code } : {}
+    };
+  }
+  return phases;
+}
+function phasesFromLegacyStatus(status) {
+  const phases = initialSetupPhases();
+  if (status === "skills_installed" || status === "authorization_pending" || status === "complete") {
+    phases.cli = { status: "complete" };
+    phases.cleanup = { status: "complete" };
+    phases.skills = { status: "complete" };
+  }
+  if (status === "authorization_pending") {
+    phases.auth = { status: "waiting", outcome: "authorization_pending" };
+  } else if (status === "complete") {
+    phases.auth = { status: "complete" };
+    phases.verify = { status: "complete" };
+  }
+  return phases;
+}
+function readSetupState(input2) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync14(
+        setupStatePath(input2.baseUrl, input2.scope, input2.root),
+        "utf8"
+      )
+    );
+    if (parsed.host !== input2.baseUrl || parsed.scope !== input2.scope || parsed.root !== input2.root || typeof parsed.status !== "string") {
+      return null;
+    }
+    return {
+      status: parsed.status,
+      phases: parseSetupPhases(parsed.phases) ?? phasesFromLegacyStatus(parsed.status)
+    };
+  } catch {
+    return null;
+  }
+}
+function selectSetupProgress(previousState) {
+  const resumed = Boolean(previousState && previousState.status !== "complete");
+  return {
+    resumed,
+    phases: resumed ? previousState.phases : initialSetupPhases()
+  };
+}
 function normalizeScope2(value) {
   if (!value || value === "global") return "global";
   if (value === "local") return "local";
@@ -30059,7 +30199,7 @@ function printCapturedAuthorizationUrl(stdout) {
 }
 function safeRead(path) {
   try {
-    return readFileSync13(path, "utf8");
+    return readFileSync14(path, "utf8");
   } catch {
     return "";
   }
@@ -30170,13 +30310,14 @@ function writeSetupState(input2) {
     path,
     `${JSON.stringify(
       {
-        schemaVersion: 1,
+        schemaVersion: 2,
         updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
         cliVersion: SDK_VERSION,
         host: input2.baseUrl,
         scope: input2.scope,
         root: input2.root,
-        status: input2.status
+        status: input2.status,
+        phases: input2.phases
       },
       null,
       2
@@ -30186,6 +30327,24 @@ function writeSetupState(input2) {
   );
   return path;
 }
+function persistSetupProgress(input2) {
+  return writeSetupState({
+    ...input2,
+    status: input2.status ?? "in_progress"
+  });
+}
+function completeSetupPhase(phases, phase, outcome) {
+  phases[phase] = {
+    status: "complete",
+    ...outcome ? { outcome } : {}
+  };
+}
+function beginSetupPhase(phases, phase) {
+  phases[phase] = { status: "in_progress" };
+}
+function failSetupPhase(phases, phase, code) {
+  phases[phase] = { status: "failed", code };
+}
 function rollbackCommand(scope, root) {
   const prefix = scope === "local" && root ? ` --prefix ${JSON.stringify(join16(root, ".deepline", "runtime"))}` : "";
   return `npm install -g${prefix} --no-audit --no-fund --include=optional --allow-scripts=esbuild deepline@${SDK_VERSION}`;
@@ -30197,6 +30356,42 @@ function setupResumeCommand(baseUrl, scope) {
   const hostPrefix = baseUrl === "https://code.deepline.com" ? "" : `DEEPLINE_HOST_URL=${JSON.stringify(baseUrl)} `;
   return `${hostPrefix}deepline setup --scope ${scope} --json`;
 }
+function setupRetry(input2) {
+  return {
+    phase: input2.phase,
+    command: setupResumeCommand(input2.baseUrl, input2.scope),
+    automatic: true
+  };
+}
+function reportSetupPhaseFailure(input2) {
+  failSetupPhase(input2.phases, input2.phase, input2.code);
+  const statePath = persistSetupProgress({
+    baseUrl: input2.baseUrl,
+    scope: input2.scope,
+    root: input2.root,
+    phases: input2.phases,
+    status: "failed"
+  });
+  const retry = setupRetry(input2);
+  printCommandEnvelope(
+    {
+      ok: false,
+      status: "failed",
+      code: input2.code,
+      exitCode: input2.exitCode,
+      scope: input2.scope,
+      message: input2.message,
+      phases: input2.phases,
+      failedPhase: input2.phase,
+      retry,
+      statePath,
+      next: retry.command,
+      ...input2.extra ?? {}
+    },
+    { json: input2.json }
+  );
+  return input2.exitCode;
+}
 async function readAuthStatus(authScope) {
   try {
     const captured = await captureStdout2(
@@ -30216,63 +30411,44 @@ async function readAuthStatus(authScope) {
 }
 function reportSetupAuthStatusFailure(input2) {
   if (!input2.auth.error) return null;
-  printCommandEnvelope(
-    {
-      ok: false,
-      status: "failed",
-      code: "AUTH_STATUS_FAILED",
-      exitCode: 4,
-      scope: input2.scope,
-      message: "Deepline could not verify authorization with the configured host.",
-      next: `Check network access, then rerun: deepline setup --scope ${input2.scope} --json`,
-      authScope: input2.authScope
-    },
-    { json: input2.json }
-  );
-  return 4;
+  return reportSetupPhaseFailure({
+    baseUrl: input2.baseUrl,
+    scope: input2.scope,
+    root: input2.root,
+    phases: input2.phases,
+    phase: "auth",
+    code: "AUTH_STATUS_FAILED",
+    exitCode: 4,
+    message: "Deepline could not verify authorization with the configured host.",
+    json: input2.json,
+    extra: { authScope: input2.authScope }
+  });
 }
-async function runDoctorCommand(options) {
-  let scope;
-  let root;
-  try {
-    scope = normalizeScope2(options.scope);
-    root = resolveScopeRoot(scope);
-  } catch (error) {
-    printCommandEnvelope(
-      {
-        ok: false,
-        status: "failed",
-        code: "INVALID_SETUP_SCOPE",
-        exitCode: 2,
-        message: error instanceof Error ? error.message : String(error)
-      },
-      { json: options.json }
-    );
-    return 2;
-  }
-  const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
-  const skillsStatePath = skillsStatePathForScope(baseUrl, scope, root);
+function buildDoctorAssessment(input2) {
+  const skillsStatePath = skillsStatePathForScope(
+    input2.baseUrl,
+    input2.scope,
+    input2.root
+  );
   const skillsState = parseCapturedJson(safeRead(skillsStatePath));
-  const authScope = authScopeForSetup(scope);
-  const apiKey = scope === "local" ? resolveProjectApiKeyForBaseUrl(baseUrl) : resolveGlobalApiKeyForBaseUrl(baseUrl);
-  const projectAuth = scope === "local" && apiKey ? getResolvedProjectAuthSource(baseUrl, apiKey) : null;
-  const authStatus = await readAuthStatus(authScope);
-  const connected = authStatus.payload?.connected === true;
-  const authScopeOk = scope === "local" ? Boolean(projectAuth) : Boolean(apiKey && !projectAuth);
-  const skillsOk = skillsState?.scope === scope && Array.isArray(skillsState.agents) && skillsState.agents.length > 0;
+  const apiKey = input2.scope === "local" ? resolveProjectApiKeyForBaseUrl(input2.baseUrl) : resolveGlobalApiKeyForBaseUrl(input2.baseUrl);
+  const projectAuth = input2.scope === "local" && apiKey ? getResolvedProjectAuthSource(input2.baseUrl, apiKey) : null;
+  const connected = input2.authStatus.payload?.connected === true;
+  const authScopeOk = input2.scope === "local" ? Boolean(projectAuth) : Boolean(apiKey && !projectAuth);
+  const skillsOk = skillsState?.scope === input2.scope && typeof skillsState.skillsVersion === "string" && Array.isArray(skillsState.agents) && skillsState.agents.length > 0;
   const runningCliPath = process.argv[1] ? resolve14(process.argv[1]) : null;
-  const globalCli = scope === "global" ? inspectGlobalCliAvailability() : null;
+  const globalCli = input2.scope === "global" ? inspectGlobalCliAvailability() : null;
   const pathGlobalCli = globalCli?.path ?? null;
-  const cliPath = scope === "global" ? pathGlobalCli : runningCliPath;
-  const cliScopeOk = scope === "global" ? Boolean(pathGlobalCli) : Boolean(
-    root && runningCliPath?.includes(join16(root, ".deepline", "runtime"))
+  const cliPath = input2.scope === "global" ? pathGlobalCli : runningCliPath;
+  const cliScopeOk = input2.scope === "global" ? Boolean(pathGlobalCli) : Boolean(
+    input2.root && runningCliPath?.includes(join16(input2.root, ".deepline", "runtime"))
   );
   const checks = {
     cli: {
       ok: Boolean(cliPath) && cliScopeOk,
       version: SDK_VERSION,
       path: cliPath,
-      scope
+      scope: input2.scope
     },
     skills: {
       ok: skillsOk,
@@ -30283,16 +30459,48 @@ async function runDoctorCommand(options) {
     auth: {
       ok: connected && authScopeOk,
       scope: projectAuth ? "local" : apiKey ? "global" : null,
-      status: authStatus.payload?.status ?? "not_connected"
+      status: input2.authStatus.payload?.status ?? "not_connected"
     },
     api: {
-      ok: connected && authStatus.exitCode === 0,
-      host: baseUrl,
-      workspace: authStatus.payload?.workspace ?? null,
+      ok: connected && input2.authStatus.exitCode === 0,
+      host: input2.baseUrl,
+      workspace: input2.authStatus.payload?.workspace ?? null,
       providerSpend: false
     }
   };
-  const ok = Object.values(checks).every((check) => check.ok);
+  return {
+    ok: Object.values(checks).every((check) => check.ok),
+    checks
+  };
+}
+async function runDoctorCommand(options) {
+  let scope;
+  let root;
+  try {
+    scope = normalizeScope2(options.scope);
+    root = resolveScopeRoot(scope);
+  } catch (error) {
+    printCommandEnvelope(
+      {
+        ok: false,
+        status: "failed",
+        code: "INVALID_SETUP_SCOPE",
+        exitCode: 2,
+        message: error instanceof Error ? error.message : String(error)
+      },
+      { json: options.json }
+    );
+    return 2;
+  }
+  const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
+  const authScope = authScopeForSetup(scope);
+  const authStatus = await readAuthStatus(authScope);
+  const { ok, checks } = buildDoctorAssessment({
+    baseUrl,
+    scope,
+    root,
+    authStatus
+  });
   const quickstart = setupQuickstartCommand(baseUrl);
   printCommandEnvelope(
     {
@@ -30318,11 +30526,16 @@ async function runDoctorCommand(options) {
   return ok ? 0 : 7;
 }
 function pendingResult(input2) {
+  input2.phases.auth = {
+    status: "waiting",
+    outcome: "authorization_pending"
+  };
   const statePath = writeSetupState({
     baseUrl: input2.baseUrl,
     scope: input2.scope,
     root: input2.root,
-    status: "authorization_pending"
+    status: "authorization_pending",
+    phases: input2.phases
   });
   if (input2.authorizationUrl) {
     process.stderr.write(`Authorize Deepline: ${input2.authorizationUrl}
@@ -30336,6 +30549,14 @@ function pendingResult(input2) {
       scope: input2.scope,
       authorizationUrl: input2.authorizationUrl || null,
       statePath,
+      phases: input2.phases,
+      currentPhase: "auth",
+      resumed: input2.resumed,
+      retry: setupRetry({
+        baseUrl: input2.baseUrl,
+        scope: input2.scope,
+        phase: "auth"
+      }),
       next: `Approve the link, then run: ${setupResumeCommand(input2.baseUrl, input2.scope)}`,
       render: {
         sections: [
@@ -30366,84 +30587,146 @@ async function runSetupCommand(options) {
         status: "failed",
         code: "INVALID_SETUP_SCOPE",
         exitCode: 2,
-        message: error instanceof Error ? error.message : String(error)
+        message: error instanceof Error ? error.message : String(error),
+        phases: {
+          ...initialSetupPhases(),
+          cli: { status: "failed", code: "INVALID_SETUP_SCOPE" }
+        },
+        failedPhase: "cli"
       },
       { json: options.json }
     );
     return 2;
   }
   const baseUrl = autoDetectBaseUrl().replace(/\/$/, "");
-  if (scope === "global") {
-    const globalCli = inspectGlobalCliAvailability();
-    if (!globalCli.ok) {
-      const installedButUnreachable = Boolean(globalCli.persistentPath);
-      printCommandEnvelope(
-        {
-          ok: false,
-          status: "failed",
-          code: installedButUnreachable ? "GLOBAL_CLI_NOT_ON_PATH" : "GLOBAL_CLI_NOT_INSTALLED",
-          exitCode: 7,
+  const previousState = readSetupState({ baseUrl, scope, root });
+  const { resumed, phases } = selectSetupProgress(previousState);
+  if (phases.cli.status !== "complete") {
+    beginSetupPhase(phases, "cli");
+    persistSetupProgress({ baseUrl, scope, root, phases });
+    if (scope === "global") {
+      const globalCli = inspectGlobalCliAvailability();
+      if (!globalCli.ok) {
+        const installedButUnreachable = Boolean(globalCli.persistentPath);
+        const code = installedButUnreachable ? "GLOBAL_CLI_NOT_ON_PATH" : "GLOBAL_CLI_NOT_INSTALLED";
+        return reportSetupPhaseFailure({
+          baseUrl,
           scope,
-          persistentPath: globalCli.persistentPath,
+          root,
+          phases,
+          phase: "cli",
+          code,
+          exitCode: 7,
           message: installedButUnreachable ? `The global Deepline executable is not reachable on PATH: ${globalCli.persistentPath}` : "No persistent global Deepline executable was found.",
-          next: "Use the automatic project-local fallback in https://code.deepline.com/SKILL.md"
-        },
-        { json: options.json }
-      );
-      return 7;
+          json: options.json,
+          extra: {
+            persistentPath: globalCli.persistentPath,
+            fallback: "https://code.deepline.com/INSTALL.md"
+          }
+        });
+      }
     }
-  }
-  const conflict = inspectPathConflict();
-  if (conflict) {
-    printCommandEnvelope(
-      {
-        ok: false,
-        status: "failed",
+    const conflict = inspectPathConflict();
+    if (conflict) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "cli",
         code: "PATH_CONFLICT",
         exitCode: 7,
-        path: conflict,
         message: `An unknown executable named deepline is first on PATH: ${conflict}`,
-        next: "Move or rename that executable, then rerun: deepline setup --json"
-      },
-      { json: options.json }
-    );
-    return 7;
+        json: options.json,
+        extra: { path: conflict }
+      });
+    }
+    completeSetupPhase(phases, "cli", "available");
+    persistSetupProgress({ baseUrl, scope, root, phases });
   }
-  const removedLegacyPaths = removeKnownLegacyPaths(baseUrl);
-  if (removedLegacyPaths.length > 0) {
-    process.stderr.write(
-      `Removed ${removedLegacyPaths.length} known legacy Deepline path(s).
+  if (phases.cleanup.status !== "complete") {
+    beginSetupPhase(phases, "cleanup");
+    persistSetupProgress({ baseUrl, scope, root, phases });
+    try {
+      const removedLegacyPaths = removeKnownLegacyPaths(baseUrl);
+      if (removedLegacyPaths.length > 0) {
+        process.stderr.write(
+          `Removed ${removedLegacyPaths.length} known legacy Deepline path(s).
 `
-    );
+        );
+      }
+      completeSetupPhase(
+        phases,
+        "cleanup",
+        removedLegacyPaths.length > 0 ? "removed_legacy_paths" : "clean"
+      );
+      persistSetupProgress({ baseUrl, scope, root, phases });
+    } catch (error) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "cleanup",
+        code: "LEGACY_CLEANUP_FAILED",
+        exitCode: 5,
+        message: error instanceof Error ? error.message : String(error),
+        json: options.json
+      });
+    }
   }
-  process.stderr.write(`Installing Deepline skills (${scope})...
+  let skillsPayload = null;
+  if (phases.skills.status !== "complete") {
+    beginSetupPhase(phases, "skills");
+    persistSetupProgress({ baseUrl, scope, root, phases });
+    process.stderr.write(`Installing Deepline skills (${scope})...
 `);
-  const skills = await captureStdout2(
-    () => runSkillsCommand({ scope, json: true })
-  );
-  const skillsPayload = parseCapturedJson(skills.stdout);
-  if (skills.exitCode !== 0) {
-    printCommandEnvelope(
-      {
-        ok: false,
-        status: "failed",
+    const skills = await captureStdout2(
+      () => runSkillsCommand({ scope, json: true })
+    );
+    skillsPayload = parseCapturedJson(skills.stdout);
+    if (skills.exitCode !== 0) {
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "skills",
         code: "SKILLS_INSTALL_FAILED",
         exitCode: skills.exitCode,
-        scope,
-        detail: skillsPayload,
-        next: `deepline skills --scope ${scope} --json`
-      },
-      { json: options.json }
+        message: typeof skillsPayload?.message === "string" ? skillsPayload.message : "Deepline skills could not be installed.",
+        json: options.json,
+        extra: { detail: skillsPayload }
+      });
+    }
+    completeSetupPhase(
+      phases,
+      "skills",
+      skillsPayload?.status === "current" ? "current" : "installed"
+    );
+    writeSetupState({
+      baseUrl,
+      scope,
+      root,
+      status: "skills_installed",
+      phases
+    });
+  } else {
+    skillsPayload = parseCapturedJson(
+      safeRead(skillsStatePathForScope(baseUrl, scope, root))
     );
-    return skills.exitCode;
   }
-  writeSetupState({ baseUrl, scope, root, status: "skills_installed" });
   const authScope = authScopeForSetup(scope);
+  beginSetupPhase(phases, "auth");
+  persistSetupProgress({ baseUrl, scope, root, phases });
   let auth = await readAuthStatus(authScope);
   const initialAuthFailure = reportSetupAuthStatusFailure({
     auth,
+    baseUrl,
     authScope,
     scope,
+    root,
+    phases,
     json: options.json
   });
   if (initialAuthFailure !== null) return initialAuthFailure;
@@ -30458,8 +30741,11 @@ async function runSetupCommand(options) {
       auth = await readAuthStatus(authScope);
       const resumedAuthFailure = reportSetupAuthStatusFailure({
         auth,
+        baseUrl,
         authScope,
         scope,
+        root,
+        phases,
         json: options.json
       });
       if (resumedAuthFailure !== null) return resumedAuthFailure;
@@ -30470,7 +30756,9 @@ async function runSetupCommand(options) {
             baseUrl,
             scope,
             root,
+            phases,
             authorizationUrl: stillPending.claimUrl,
+            resumed,
             json: options.json
           });
         }
@@ -30487,24 +30775,30 @@ async function runSetupCommand(options) {
     );
     printCapturedAuthorizationUrl(registered.stdout);
     if (registered.exitCode !== 0) {
-      printCommandEnvelope(
-        {
-          ok: false,
-          status: "failed",
-          code: "AUTH_REGISTER_FAILED",
-          exitCode: registered.exitCode,
-          scope,
-          next: `deepline auth register --auth-scope ${authScope}`
-        },
-        { json: options.json }
-      );
-      return registered.exitCode;
+      return reportSetupPhaseFailure({
+        baseUrl,
+        scope,
+        root,
+        phases,
+        phase: "auth",
+        code: "AUTH_REGISTER_FAILED",
+        exitCode: registered.exitCode,
+        message: "Deepline browser authorization could not be started.",
+        json: options.json,
+        extra: {
+          detail: parseCapturedJson(registered.stdout),
+          authScope
+        }
+      });
     }
     auth = await readAuthStatus(authScope);
     const registeredAuthFailure = reportSetupAuthStatusFailure({
       auth,
+      baseUrl,
       authScope,
       scope,
+      root,
+      phases,
       json: options.json
     });
     if (registeredAuthFailure !== null) return registeredAuthFailure;
@@ -30514,40 +30808,60 @@ async function runSetupCommand(options) {
         baseUrl,
         scope,
         root,
+        phases,
         authorizationUrl: pending?.claimUrl ?? "",
+        resumed,
         json: options.json
       });
     }
   }
-  process.stderr.write("Verifying Deepline setup...\n");
-  const doctor = await captureStdout2(
-    () => runDoctorCommand({ scope, json: true })
-  );
-  const doctorPayload = parseCapturedJson(doctor.stdout);
-  if (doctor.exitCode !== 0) {
-    printCommandEnvelope(
-      {
-        ok: false,
-        status: "failed",
-        code: "DOCTOR_FAILED",
-        exitCode: doctor.exitCode,
-        scope,
+  completeSetupPhase(phases, "auth", "connected");
+  beginSetupPhase(phases, "verify");
+  persistSetupProgress({ baseUrl, scope, root, phases });
+  const assessment = buildDoctorAssessment({
+    baseUrl,
+    scope,
+    root,
+    authStatus: auth
+  });
+  const quickstart = setupQuickstartCommand(baseUrl);
+  const doctorPayload = {
+    ok: assessment.ok,
+    status: assessment.ok ? "complete" : "failed",
+    code: assessment.ok ? "DOCTOR_OK" : "DOCTOR_FAILED",
+    exitCode: assessment.ok ? 0 : 7,
+    checks: assessment.checks,
+    next: assessment.ok ? quickstart : `deepline doctor --scope ${scope} --json`
+  };
+  if (!assessment.ok) {
+    return reportSetupPhaseFailure({
+      baseUrl,
+      scope,
+      root,
+      phases,
+      phase: "verify",
+      code: "DOCTOR_FAILED",
+      exitCode: 7,
+      message: "Deepline setup verification found one or more failed checks.",
+      json: options.json,
+      extra: {
         doctor: doctorPayload,
-        next: "Review the doctor result and choose a repair, then rerun: deepline setup --json"
-      },
-      { json: options.json }
-    );
-    return doctor.exitCode;
+        diagnostic: {
+          command: `deepline doctor --scope ${scope} --json`
+        }
+      }
+    });
   }
+  completeSetupPhase(phases, "verify", "verified");
   const statePath = writeSetupState({
     baseUrl,
     scope,
     root,
-    status: "complete"
+    status: "complete",
+    phases
   });
   const doctorChecks = asRecord2(doctorPayload?.checks);
   const apiCheck = asRecord2(doctorChecks?.api);
-  const quickstart = setupQuickstartCommand(baseUrl);
   printCommandEnvelope(
     {
       ok: true,
@@ -30560,6 +30874,10 @@ async function runSetupCommand(options) {
       rollbackCommand: rollbackCommand(scope, root),
       statePath,
       doctor: doctorPayload,
+      phases,
+      currentPhase: null,
+      failedPhase: null,
+      resumed,
       next: quickstart,
       render: {
         sections: [
@@ -30582,8 +30900,9 @@ function registerSetupCommands(program) {
     "after",
     `
 Notes:
-  Setup is idempotent. Bare setup resumes pending browser authorization.
+  Setup is idempotent. Bare setup resumes the first incomplete or failed phase.
   It installs skills before auth and does not run quickstart.
+  JSON output includes phase status and an exact retry command.
 
 Examples:
   deepline setup --json
@@ -30823,7 +31142,7 @@ import { spawn as spawn6, spawnSync as spawnSync3 } from "child_process";
 import {
   existsSync as existsSync14,
   mkdirSync as mkdirSync12,
-  readFileSync as readFileSync14,
+  readFileSync as readFileSync15,
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync17
 } from "fs";
@@ -30849,7 +31168,7 @@ function readPluginSkillsVersion() {
   const dir = activePluginSkillsDir();
   if (!dir) return "";
   try {
-    return readFileSync14(join17(dir, ".version"), "utf-8").trim();
+    return readFileSync15(join17(dir, ".version"), "utf-8").trim();
   } catch {
     return "";
   }
@@ -30869,7 +31188,7 @@ function readSdkSkillsLocalVersion(baseUrl) {
   const path = existsSync14(sdkSkillsVersionPath(baseUrl)) ? sdkSkillsVersionPath(baseUrl) : legacySdkSkillsVersionPath(baseUrl);
   if (!existsSync14(path)) return "";
   try {
-    return readFileSync14(path, "utf-8").trim();
+    return readFileSync15(path, "utf-8").trim();
   } catch {
     return "";
   }
@@ -30883,7 +31202,7 @@ function writeLocalSkillsVersion(baseUrl, version) {
 function writeUnavailableSkillsNotice(baseUrl, remoteVersion, skillNames) {
   const path = unavailableSkillsNoticePath(baseUrl);
   try {
-    if (existsSync14(path) && readFileSync14(path, "utf-8").trim() === remoteVersion) {
+    if (existsSync14(path) && readFileSync15(path, "utf-8").trim() === remoteVersion) {
       return;
     }
     mkdirSync12(dirname15(path), { recursive: true });